If you were going to hack out a document describing a Lisp API, which documentation format would you use? I'm thinking about one of the following: xhtml, tex, or texinfo. I'd like something that could be used to create a printed manual or an online doc.

I have written a lot of xhtml and tex over the years, but not so much texinfo. If anybody suggests texinfo, can you tell me which Emacs mode you use for editing it? I notice that the official texinfo manual documents one mode, but it seems like AUCTeX also has some support for editing texinfo, and I have used AUCTeX previously for doing some TeX editing.

findinglisp wrote:If you were going to hack out a document describing a Lisp API, which documentation format would you use? [...] Any and all suggestions welcome.

I've never used it, but lots of people seem to like DocBook. I vaguely recall that it can be transformed to text. pdf, html, man page (!!) and various other formats. Their FAQ lists < http://www.dpawson.co.uk/docbook/reference.html#d17e133 > lots of computer-y projects that use it.

I haven't used Texinfo before, but if you haven't used it before, I'm not sure if it has any relevant advantage over TeX now. I, for one, am perfectly content with HTML documentation generated by tth or latex2html which I can browse from an Emacs session (the wonders of w3m ).

You may also want to consider some inline documentation tools if you're documenting API that you are writing just now. I'm considering one as well, trying out various tools listed at http://www.cliki.net/Documentation%20tool .