API reference manual generation ?

[Stefan Seefeld <seefeld@sympatico.ca>]

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 ?
(Both, input, as well as output are attached.)


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.e. something akin to, say,
http://boost.org/libs/python/doc/v2/class.html ?


Thanks,
		Stefan

-- 

      ...ich hab' noch einen Koffer in Berlin...
<section>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;stdio.h&gt;
</funcsynopsisinfo>
<funcprototype>
  <funcdef>int <function>printf</function></funcdef>
  <paramdef>const char *<parameter>format</parameter></paramdef>
  <paramdef>...</paramdef>
</funcprototype>

<funcprototype>
  <funcdef>int <function>fprintf</function></funcdef>
  <paramdef>FILE *<parameter>strm</parameter></paramdef>
  <paramdef>const char *<parameter>format</parameter></paramdef>
  <paramdef>...</paramdef>
</funcprototype>

<funcprototype>
  <funcdef>int <function>sprintf</function></funcdef>
  <paramdef>char *<parameter>s</parameter></paramdef>
  <paramdef>const char *<parameter>format</parameter></paramdef>
  <paramdef>...</paramdef>
</funcprototype>
</funcsynopsis>
</section>

---

#include <stdio.h>

int printf(	format,
	);

const char *	format;
	;

int fprintf(	strm,
	format,
	);

FILE *	strm;
const char *	format;
	;

int sprintf(	s,
	format,
	);

char *	s;
const char *	format;
	;