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

[Stefan Seefeld <seefeld@sympatico.ca>]

Mauritz Jeanson wrote:

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

Definitely. (Isn't it about time to switch to ANSI by default ? ;-) )

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

Thanks for these suggestions, I will definitely try them out.

To put this in perspective, I'm presently looking into adding a 'DocBook
backend' to Synopsis (http://synopsis.fresco.org), which is a
source-code documentation tool. As such, it introspects source code of
various languages (IDL, C, C++, Python, ...), builds a common internal
representation, and then formats it in various way.

I'm thus wondering what DocBook markup to (auto-)generate to represent
both, the source artifacts, as well as the documentation embedded into
the source code.
It turns out that the existing stylesheets (xsl-docbook) don't support
Python, so, at least when formatting Python APIs, I can't use
classsynopsis, funcsynopsis, etc., but need to fall back to using the
much simpler synopsis element.

Also, as I autogenerate documentation, I do want to represent much more
than just functions, classes, and variables. (Arbitrary type
definitions, constants, macros, template parameters, etc., etc.)), so
I'm a little afraid the limited model that DocBook provides of source
code gets into the way, instead of helping.

(When I'm in dream-mode I'm thinking that much of this OO model that is
part of DocBook could move into an extension module, and expanded to
model more and better the various programming language artifacts. I do
understand Norm's preference not to put more programing language
modeling into the core of DocBook.)

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

I'm looking for guidelines on how to complement a synopsis (which, as
far as I understand, merely reproduces a piece of language-specific
syntax) with documentation. And, I'm looking for suggestions on how to
generate (potentially rather big) sets of such items, that are, on the
language level, part of a hierarchy. (I'm thinking about namespaces /
modules, nested classes, etc., etc.)

Thanks,
		Stefan

-- 

      ...ich hab' noch einen Koffer in Berlin...