Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

#19 function prototypes shouldn't be filled like paragraphs

open
nobody
None
5
2009-04-27
2003-04-25
Ken Raeburn
No

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

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

Discussion

  • Ken Raeburn
    Ken Raeburn
    2003-04-25

    doc with long fn prototypes

     
    Attachments
  • Ken Raeburn
    Ken Raeburn
    2003-04-25

    Logged In: YES
    user_id=79109

    BTW, that email last year was to ndw@nwalsh.com, last
    February. I can dig up a copy if anyone wants the hacked
    html handling.

     
  • Logged In: YES
    user_id=178336

    Please provide more concrete information on how you would
    like the rendering to change. While the current implementation
    might not be ideal, it doesn't appear outright broken.

     
    • milestone: 112684 --> 447636
    • status: open --> pending
     
  • Ken Raeburn
    Ken Raeburn
    2005-06-16

    Logged In: YES
    user_id=79109

    > Please provide more concrete information on how you would like the
    rendering to change.

    You mean, what format I'd like to see? I guess, line breaks should be
    avoided in any argument description, permitted only after the comma
    between arguments; the continuation lines should be indented so that the
    text starts where the text for the first argument started. (Obviously, "to the
    extent possible" should apply to everything.) An optional line break
    between the return type and function name would allow the layout process
    to give more horizontal space to argument descriptions. If the function
    name plus one argument description is too long for a line (in hardcopy
    formatting), then perhaps the argument list should start on the line after the
    function name, to make more horizontal space available.

    > While the current implementation might not be ideal, it doesn't appear
    outright broken.

    Well, no, not in a "that information isn't correct" type of way, just in a
    "maybe I want to look at other doc tools" kind of way. The projects I'm
    interested in using docbook for tend to have these annoyingly long
    prototypes, and while the current doc systems are unpleasant and poorly
    (if at all) maintained by hand, their output is more readable than I got from
    docbook when I filed this bug.

     
  • Ken Raeburn
    Ken Raeburn
    2005-06-16

    • status: pending --> open
     
  • Robert Stayton
    Robert Stayton
    2009-04-27

    • labels: 321158 -->
    • milestone: 447636 -->