OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

> -----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.


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?


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]