API documentation format

Discussion of programming Lisps using Emacs, including SLIME and other tools

API documentation format

Postby 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/
findinglisp
 
Posts: 440
Joined: Sat Jun 28, 2008 7:49 am
Location: Austin, TX

Re: API documentation format

Postby 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.
theclapp
 
Posts: 17
Joined: Wed Jul 16, 2008 11:05 am

Re: API documentation format

Postby 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/
findinglisp
 
Posts: 440
Joined: Sat Jun 28, 2008 7:49 am
Location: Austin, TX

Re: API documentation format

Postby 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. :)
theclapp
 
Posts: 17
Joined: Wed Jul 16, 2008 11:05 am

Re: API documentation format

Postby 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.
mmmk
 
Posts: 8
Joined: Sat Jun 28, 2008 11:37 pm

Re: API documentation format

Postby 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 .
donkey
 
Posts: 11
Joined: Sun Jun 29, 2008 11:05 am


Return to Emacs

Who is online

Users browsing this forum: No registered users and 3 guests

cron