[armedbear-devel] Manual format

[Blake McBride]

Greetings,

I was looking at the ABCL manual for ABCL 1.0 under the 'manual'
directory.  I noticed that it is in LaTeX format.  I have been using
TeX, LaTeX and Texinfo for many years.  Among many other things, I
have written two longish user manuals in Texinfo. They are located
(including source) at:

        http://blake.mcbride.name/software/dynace/downloads.html

under the 'manual' directory.  With the experience I've had with TeX,
LaTeX, and Texinfo, I feel very strongly that these are unbelievably
great tools, and, in fact, the right tools for the job.  However, I
also feel strongly that Texinfo is the better format for the
particular task of a manual on ABCL.  I use LaTeX pretty often, but I
have found Texinfo better suited for user manuals of computer topics
for several reasons.  First, the macros defined are more natural for
the topic.  Second, Texinfo supplies much better index creation tools
for functions, variables, classes, etc..  Lastly, if you use Texinfo,
you get online documentation for free!  Texinfo is specifically
designed for exactly this kind of technical document.  LaTeX is
equally good, but at writing non-technical books.  Latex is not a
natural fit for technical documents in my opinion.

So, in conclusion:

1.  I recommend switching to Texinfo.  It would be especially easy at
this early juncture.

2.  The manuals I wrote come out, IMO, nicely.  These documents could
be used as templates.

3.  My time is a real problem but I think I can convert the existing
document so that you'd have it all setup to continue with if that is
desired.

I welcome your thoughts.

Blake McBride