API documentation format

Discussion of programming Lisps using Emacs, including SLIME and other tools
Post Reply
findinglisp
Posts: 447
Joined: Sat Jun 28, 2008 7:49 am
Location: Austin, TX
Contact:

API documentation format

Post by findinglisp » Thu Jul 24, 2008 5:43 pm

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.
Cheers, Dave
Slowly but surely the world is finding Lisp. http://www.findinglisp.com/blog/

theclapp
Posts: 17
Joined: Wed Jul 16, 2008 11:05 am

Re: API documentation format

Post by theclapp » Thu Jul 24, 2008 6:45 pm

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.

findinglisp
Posts: 447
Joined: Sat Jun 28, 2008 7:49 am
Location: Austin, TX
Contact:

Re: API documentation format

Post by findinglisp » Thu Jul 24, 2008 9:00 pm

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. :D
Cheers, Dave
Slowly but surely the world is finding Lisp. http://www.findinglisp.com/blog/

theclapp
Posts: 17
Joined: Wed Jul 16, 2008 11:05 am

Re: API documentation format

Post by theclapp » Fri Jul 25, 2008 4:10 am

findinglisp wrote:I figured by the time I actually learned DocBook, I could be done with the whole thing writing in another format. :D
It turns out I was thinking of Texinfo anyway. :)

mmmk
Posts: 8
Joined: Sat Jun 28, 2008 11:37 pm

Re: API documentation format

Post by mmmk » Fri Jul 25, 2008 2:28 pm

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.

donkey
Posts: 11
Joined: Sun Jun 29, 2008 11:05 am

Re: API documentation format

Post by donkey » Thu Jul 31, 2008 6:54 am

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 .

Post Reply