API documentation format

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.

Any and all suggestions welcome.

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.

Yea, I thought about that. I figured by the time I actually learned DocBook, I could be done with the whole thing writing in another format.

findinglisp wrote:I figured by the time I actually learned DocBook, I could be done with the whole thing writing in another format.

It turns out I was thinking of Texinfo anyway.

findinglisp wrote: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.

When I think of API documentation, I think of tools like Tinaa. If you want to go the texinfo route though, take a look at the SBCL documentation or the Portable CLX documentation for examples.

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 .