[armedbear-devel] Manual format

[Mark Evenson]

On Oct 22, 2011, at 04:16 , Blake McBride wrote:

> 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.

I deliberately chose LaTeX over Texinfo after considering the arguments you mention.  That after two manuals, you would still recommend Texinfo over LaTeX is another opinion to consider. 

To recap my arguments:

1.  One can always create a simplified "domain specific" macro layer to separate markup from presentation.  'abel.sty' starts to do that for source listings.

2.  I want to be able to include pictures and tables, dammit!

3.  I find all the Texinfo to HTML conversion tools so aesthetically challenged that I am willing to write my own translator out of "ABCL" tex (i.e. that defined in abel.sty) to HTML.

4.  I want to be able to fiddle the printed layout at a fundamental level

I guess we're gonna need to discuss this a bit,
Mark