RE: [docbook-apps] API reference manual generation ?

["Mauritz Jeanson" <mj@johanneberg.com>]

> -----Original Message-----
> From: Stefan Seefeld 
> 
> I'm once again trying to understand how to generate an API reference
> manual (for various languages) in docbook.
> 
> I started by copying directly from
> http://docbook.org/tdg/en/html/ch02.html#making-refentry, 
> then processed
> with the 1.72 XSL stylesheets. Looking at the generated html, I'm not
> sure what to make of what I see. It looks neither 
> syntactically correct,
> nor does it look suitable for a reference manual. Is this output
> expected / correct ?


I agree that the output is not the prettiest, but it can be improved.

1. The example from TDG that you used is a little old.
<paramdef>...</paramdef> is used to indicate a variable number of arguments.
This is actually what <varargs/> is for, but a restriction on the content
model of <funcprototype> in DocBook prior to version 4.3 made it impossible
to use <varargs/> in this case. 

If you replace <paramdef>...</paramdef> with <varargs/> in the example, the
ellipses (...) will be rendered in the output, as they should.

2. There are two output styles for funcsynopses, K&R (default) and ANSI.
Maybe you'll like the ANSI one better.

http://docbook.sourceforge.net/release/xsl/current/doc/html/funcsynopsis.sty
le.html
http://docbook.sourceforge.net/release/xsl/current/doc/pi/dbhtml_funcsynopsi
s-style.html

3. By setting the funcsynopsis.decoration parameter to 0, text decorations
such as italics and bold are disabled.

4. There is a variable in synop.xsl called tabular-p that controls whether
the output is rendered using tables or not. I don't know why this is not a
parameter. Try setting tabular-p to false() and see if you prefer the output
resulting from that.


> But more to my actual question: what is the best markup to use for a
> function for which I'd like to document
> 
> - general usage (requirements, effects, results)
> - arguments


I don't know any other source of information about this than TDG
(http://docbook.org/tdg5/en/html/funcsynopsis.html). Do you think that there
is information missing here?


/MJ