[armedbear-devel] Manual format

[Ole Arndt]

to revive an older thread...


Mark Evenson writes:

> On Oct 22, 2011, at 04:16 , Blake McBride wrote:
>
>> [...]
>> So, in conclusion:
>> 
>> 1.  I recommend switching to Texinfo.  It would be especially easy at
>> this early juncture.

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

I would also prefer the Texinfo format, if only for the ease of
accessing info files from Emacs. 

There are also tools used by other lisp projects, such as stumpwm, to
extract documentation from the docstrings and insert them into the
documentation.

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

Texinfo does images and tables.
See (Info-goto-node "(texinfo) Images")
and (Info-goto-node "(texinfo) Lists and Tables")

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

The HTML generated by makeinfo is indeed pretty plain, but 
much can be done with some CSS stylesheets.

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

Ok, if you need that, texinfo is not the right choice. But I think the
uniformity of texinfo manuals is a good thing, that helps the reader to
quickliy find what shes looking for.

-- 
Ole Arndt                     http://www.sugarshark.com