Re: [Chicken-users] ideas

[Panagiotis Vossos]

"Perry E. Metzger" <address@hidden> writes:

> felix <address@hidden> writes:
>
> > That would be great. Would you say texinfo is the right format?
> > (I never used it, I just know plain text and HTML).
> 
> Texinfo is certainly a *popular* format. Whether it is a *good* format
> is another story entirely. :)
> 
> I'd say texinfo is pretty good for an overall manual for someone who
> has never used something before. For reference purposes, I prefer
> things like man pages.

Some people use docbook, man pages or even latex for their project's
documentation, but I strongly feel that texinfo is the best choice for
software manuals.  The basic reasons are:

1) There are info readers for all types of terminals and html
renderers for all types of graphic displays.  That means that you can
read the manual over a telnet connection as well as in mozilla.

2) Info manuals are nicely hyperlinked *and* can be navigated
effectively with keyboard shortcuts.  This is very important; it means
you can search for a particular keyword with a single keypress,
without ever reaching out for the mouse to hunt down the index.

3) texinfo is easy to write.  Someone can probably start from the GNU
hello manual as a guide and read the documentation only to look
something up.

4) makeinfo is available in every GNU-like system.  That's not the
case with the docbook/sgml/xml framework, which I find pretty
impossible to install correctly on my compiled-from-scratch system.

For these reasons, I think that rewriting the manual in anything other
than texinfo is a waste of time.

regards,
panagiotis