[Openmcl-devel] ccl manual (was Re: trace on recursive functions)

[Robert Goldman]

Liam Healy wrote:
> Sorry to go a bit off-topic here, but I'm contemplating how to do
> documentation for projects of my own.  I too was put off by the
> complexity (and unfamiliarity) of docbook and its tools.  On the other
> hand, (La)TeX, though I'm very familiar with it, doesn't seem very
> oriented toward documentation and code.  Someone recommended texinfo
> to me; it is appealing in that it is made for documentation, is quite
> simple, and you can generate many different formats from it, including
> DocBook.   Has anyone tried it?  What are your experiences?
> 

I have tried it for the ASDF manual (and another manual for an in-house
bit of software).

It does the job, but it's really very crude --- texinfo is much closer
to tex than to latex, if that helps.

I found that I had to do a shocking amount of layout by hand.  Stuff
like laying out and populating hypertext nodes and tables of contents.
If you use latex, you'll be used to having that done for you.

As a Latex user, I would have found the level of hand-tweaking
unbearable, but it turns out that the emacs texinfo mode really lifts
the burden.

I'm torn about the advice I'd give.  Latex is /much/ more slick, and
does a lot more for you.  However, it's not primarily aimed at writing
documentation, and it doesn't produce info files (as far as I know,
anyway), which are really great if you're an emacs user.

HtH,

r