Re: [Chicken-hackers] single egg documentation format

[Ivan Raikov]

  I think we have visited that issue before, and I will again vigorously
oppose getting rid of eggdoc, on the grounds that it is far more
technically superior than the wiki format, and the tool to automatically
convert eggdoc documentation to wiki is limited. I still find
eggdoc-generated HTML to be more aesthetically appealing than that of
stream-wiki; eggdoc does a much better job at delineating the sections
and highlighting the procedure headers, formatting the code examples and
the license text.

  Furthermore, eggdoc relies on the rather general and flexible SXML
libraries, and as a result it easily supports extensions and different
backends. Porting it to Chicken 4 was trivial once the SXML-related eggs
were ported. In contrast, stream-wiki has yet to be ported to Chicken 4,
not to mention that svnwiki relies on a bunch of other eggs that are not
so easy to port either.

  The complexity of stream-wiki is such that I would even argue that if
nobody is willing to put in the necessary time and effort to maintain
it, the Chicken documentation itself should be moved to an SXML-based
format. Currently, it is only possible to generate HTML from wiki
content in Chicken 4 and only by means of the horrible hack of a script
that is wiki2html. Because there is no way to generate a Texinfo variant
of the manual, I still use the Chicken 3 manual. In contrast, generating
Texinfo, LaTeX and even OpenOffice content from SXML is trivial. Please
do not get rid of eggdoc and seriously consider either finding someone
to maintain the wiki software, or using a better source format for the
manual. 


   -Ivan
  

felix winkelmann <address@hidden> writes:

> Hi!
>
>
> Here is a possibly somewhat controversial proposal: let's get rid of eggdoc,
> and use svnwiki format exclusively for egg documentation.
>
> What do you think?
>
>
> cheers,
> felix