[armedbear-devel] Manual format

[Blake McBride]

Nothing is perfect, but I thought Texinfo was better suited to the
task, easier to use, and good enough.  I'm not stuck on it though.

(The online ability I was referring to was using 'info' rather than an
html converter.)

Thanks.

Blake

On Sat, Oct 22, 2011 at 2:21 AM, Mark Evenson <evenson.not.org at gmail.com> wrote:
>
> 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