Re: [Chicken-users] local egg documentation (experimental)

[Jim Ursetto]

Hi Matt.

On Apr 2, 2013, at 4:13 PM, Matt Gushee wrote:

> I wonder if there is a program that converts Markdown to Chicken Wiki format?

There is not, mostly because markdown is not really extensible and doesn't 
support marking up procedure identifiers and so on (without terrible hacks).  
There's also the issue of markdown dialects, for example 
https://help.github.com/articles/github-flavored-markdown.  Everybody handles 
syntax highlighting in a different way, like via ```ruby (github) or :::python 
(pymarkdown).  Python does have a fully-fleshed out extension API, which of 
course only works with Python.  Finally, it's somewhat difficult to maintain N 
different X->wiki converters, and I am reluctant to open that box yet.

[Copied from another message:]
> But how about this for a utopian vision: some future version of
> chicken-install has the ability to find the documentation for whatever
> version of an egg you are installing, and downloads it and
> automatically updates your Chickadee repo with the new doc? If we
> could do that I'd feel a lot better about the whole thing.

It is technically possible now to keep your (svnwiki format) documentation 
inside your egg source.  I only recommend doing this for unofficial or 
experimental eggs, though; in other words eggs that are not globally 
installable by chicken-install.  Details are at 
http://api.call-cc.org/doc/chicken-doc-admin#sec:Locally_installed_egg_documentation,
 but briefly:

You can put a wiki doc in /eggname.wiki and install it by adding it to the 
install-extension clause in your .setup file.  After installing it, the user 
can (manually) call "chicken-doc-admin -H" to scan for and update 
locally-installed documentation.  This is experimental right now and could 
change.  We can't really have chicken-install do this step because 
chicken-doc-admin is typically not installed and also chicken-install is part 
of the core and won't be updated until the next major release.

One interesting possibility is to include the chicken-doc-admin call at the end 
of your .setup file.  For example,

 (install-extension
   'inane
    '("inane.so" "inane.import.so" "inane.wiki")     ;; add wiki doc here
    '((version "nan.0")))
 (system "chicken-doc-admin -H inane")

This will not cause an error if chicken-doc-admin fails, you just get a warning 
message on the console.

Alternatively, you could invoke chicken-doc-admin directly on the file in the 
egg source, instead of installing it.  Disadvantage is it won't be there if the 
user wipes out his or her repo, installs chicken-doc later, etc.:

 (install-extension
   'inane
    '("inane.so" "inane.import.so")                  ;; no wiki doc
    '((version "nan.0")))
 (system "chicken-doc-admin -E inane.wiki")

The overall problem with local egg documentation is that NO ONE is using 
chicken-doc-admin except possibly you and me.  Everybody else just pulls the 
database tarball from my homepage, and this will not contain your local docs; 
neither will the wiki or api.call-cc.org.  This is why I recommend using this 
only for unofficial, private or experimental eggs; official eggs should go in 
the wiki for now.

Jim