[Chicken-users] Documentation status

[Peter Bex]

Hello all,

Here's a status report on the documentation situation:

After the Hackathon I've continued to wikify all oldskool HTML egg
documentation.  This has been completed now.

Now the discussion about what we should do with the remaining eggs
can start :)  To get some more info, I've made a list of "weird"
eggs with their documentation type/lack of documentation.
The following lists are based ONLY on release/3 and only trunk versions
of the eggs.

For a few eggs I have removed the old docs if they were marked
(doc-from-wiki).  I think it's important to have EITHER docs from wiki
OR docs from the egg itself.  Otherwise docs can get out of synch,
and that helps nobody.

Also, PEOPLE: if you mark an egg as using doc-from-wiki, you DON'T
include the html output in the egg itself.  The scripts on Galinha
will take care of that.  I'm not 100% sure, but I think that these
scripts will not clobber the HTML file you include in svn, which means
that changes on the wiki will not be reflected in the egg docs.
If they are clobbered, there's no point in having the HTML files in
the svn tree either.

Now that's out of the way, here's a list of eggs that have NO
documentation and are _not_ marked (hidden) in the meta-file:

stream-flash
glfw
dbus
lmm
apr

Here's a list of eggs that are using some "special" documentation.
Special includes anything that's not wiki or eggdoc.

combinators - wiki syntax, but not available as chicken.wiki.br/combinators
fmt - mistie
metakit - docutils
mysql - mole (yes, mole _and_ eggdoc)
sedna - TeX4ht
caketext - mole (but also using wiki)

Here's a list of eggs that have eggdoc, but where the eggdoc sources
from which the html is generated are missing.  This is *bad*, and I
urge the developers of these eggs to add the eggdoc sources to the
source repository as well.

doctype
dpfw
lirc-client
pipeline
stream-sections
vector-lib

All eggs not listed above are either using the wiki or eggdoc.

Cheers,
Peter
-- 
http://sjamaan.ath.cx
--
"The process of preparing programs for a digital computer
 is especially attractive, not only because it can be economically
 and scientifically rewarding, but also because it can be an aesthetic
 experience much like composing poetry or music."
                                                        -- Donald Knuth

pgpcIUhZAwFA0.pgp
Description: PGP signature