Re: [Chicken-users] egg documentation

[Elf]

putting in my two cents (sorry for the delay, i didnt read the list today yet)
...
i am working on a documentation system to replace eggdocs, straight-wiki, and
chicken-man simultaneously.  this is not to say or imply in any way that there
wont be web files on callcc!  the goal of the system is to be able to generate
the documentation for chicken in any form, searchable via net or within the
interpreter or as a pdf or texi or WHATEVER, while enforcing some consistency
in presentation.  this will (hopefully) make it easier to a) document both 
eggs and core, b) keep the documentation up to date, c) reduce duplication of 
effort, and d) reduce the learning curve.  this is NOT a replacement for the
wiki, however; certain things can and SHOULD be wikiised.

a full (semi)formal specification will follow, hopefully later tonight.  the
specification is intended as an rfc, not as an elf-says-so-its-set-in-stone,
obviously.

-elf

On Tue, 12 Feb 2008, Graham Fawcett wrote:

> Ivan raised a good point on the Hackathon1 page (where he asks that
> people don't move his egg documentation out of the egg and into the
> wiki, because it's a pain to deal with eggs that don't have a copy of
> their docs in the egg directory itself).
>
> It's good to have the wiki docs, and especially so with Toby's
> excellent callcc.org site as a search interface. But it doesn't
> address "local" documentation very well. We've done some work on
> wiki->texi conversion, which is good, but it's not integrated with
> chicken-setup in any way, and that's a drawback.
>
> One can imagine pushing local docs into the wiki upon releasing a new
> egg version; or adding an "include" mechanism to the wiki to pull in
> external docs (though that would make search-indexing harder if not
> done properly). Since the wiki is stored in the svn repository, there
> are opportunities for svn-commit hooks to do some of the work, as well
> as opportunities for a decent inclusion mechanism.
>
> Before we venture too far into 'wikifying' all of the egg
> documentation, if that's a hackathon goal, we should probably ensure
> that we have a consistent documentation plan that ensures a local copy
> of the docs is preserved in some form.
>
> Personally, I'd love to have texi documentation, and (optionally) have
> chicken-setup do the necessary work to pull egg docs into the 'info'
> system. I'd never have to leave Emacs to look something up, and that
> would (for me) be more efficient than keeping a callcc.org browser
> open.
>
> Graham
>
>
> _______________________________________________
> Chicken-users mailing list
> address@hidden
> http://lists.nongnu.org/mailman/listinfo/chicken-users