I'm looking at the possibility of converting to docbook
for a project I work on, where the documentation
includes descriptions for lots of functions with long
argument lists and long function and type names. (No
comments, please, on the wisdom or lack thereof in
setting up such an API.)
In some of my tests, I find that the function
prototypes generated for html and dvi documentation
(the only outputs I've tried) does nice things with
fonts, but the declarations are sometimes several lines
long, and filled like paragraphs, with line breaks at
any convenient whitespace, and continuation lines
starting at the left margin.
There are a lot of different styles used for readable
function declarations, varying in where the
continuation lines start, how to decide whether to put
a line break between certain arguments, whether the
return type, function name, and argument list are
separated by line breaks, etc. But I don't know of
anyone who likes arbitrary line breaks and first-column
I sent email a year or so ago to nwalsh describing
this, and including a hacked-up style sheet that
generated an html table for the function prototype,
putting one argument on each line and causing them to
line up vertically; didn't get a response. It was kind
of a hack, though it mostly worked. I've no idea how
to fix it for TeX or other formats. I'd guess that TeX
could be encouraged to put line breaks after the commas
instead of at other whitespace, perhaps treating each
argument as a box instead of free-form text, and I'm
pretty sure the indentation could be dealt with too;
I'm just not familiar enough with TeX to do it.
I'm using these packages on Debian:
ii docbook 4.1.99really4. SGML DTD for au...
ii docbook-dsssl 1.76-1 Modular DocBoo...
ii docbook-utils 0.6.9-12 Convert Docbook...
ii docbook-xml 4.1.99really4. XML DTD for D...
ii jade 1.2.1-28 James Clark's DSS...
ii jadetex 3.12-2 LaTeX macros for ...
I took a look at docbook-dsssl-1.78 and it looked like
the html generation code hadn't changed that much in
Log in to post a comment.