[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. 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]