Re: Documenting a set of functions with -man

[G. Branden Robinson]

Hi Anton,

...returning to this after a digression on alignment/adjustment...

At 2024-06-18T02:01:24+0300, Anton Shepelev wrote:
> G. Branden Robinson:
> In my sources, I tend to format the declarations of my
> functions in similar manner, e.g.:
> 
>    void sort
>    (    void * data, /* pointer to data to sort         */
>         int    len,  /* length of data to sort          */
>         comp_f comp, /* comparison function             */
>         swap_f swap, /* swap function                   */
>         void * extra /* user-supplied parameter to comp */
>    );

That's a salutary practice.  To get it to show up like that in a page
would require tbl(1), though, or an EX/EE region (an extension).

> Glad to see Doug still around and about this list.

Me too!  :D

> > It took a decade for ANSI C function prototypes to become
> > standard,[2] and much, much longer than that for "old-
> > style", "K&R" function declarations to fade away.
> 
> What with the varous new modifiers in addition to types!

One of my favorite examples from the C standard, somewhere between C89
and C23:

void f(double a[static 10], float b[const restrict 20], int [*][*]);

> As an occasional visitor rather than a regular reader, I did not see
> that post.  Thanks.  I will give my (belated) comments in a follow-up
> to it.

I'm curious to hear what you think.

> > I'm not sure what you mean by "classic" here ->
> 
> I meant the standard `man' package without the GNU extension, and
> specifically not `mdoc', which seems more advanced.

Okay.  I'm not sure I'd concede "more advanced".  "More complicated",
sure.  ;-)

> I thought you were typesetting your e-mails in `groff' (as I
> do, in -mm, with macros for nested quotations), but having
> failed to find the source of this footnote, I concluded you
> are[1] using a WYSWYG editor directly.

Just good old vim(1).

> > [2] I observe that London and Reiser explicitly lobbied
> >     for them in July 1978; see their UNIX/32V paper.
> >
> >     https://lists.gnu.org/archive/html/groff/2024-06/msg00022.html
> 
> Advocacy by example?  I see they have program names and C
> functions in italic, inline assembly intructions, C macros,
> and C types in bold, and never use monospace font.

Yes, but I wouldn't try to map that usage pattern directly on to man
pages without further consideration.  The lack of a monospaced font is,
I suspect, due either to physical limitations of the C/A/T
phototypesetter[1] or fiscal limitations--no budget in that department
to buy photographic plates for Courier.  Printing costs money; people
keep track of that.

> AFAIK, the `man' package is unaware of it as well, save the example
> macro, but it is an extension.

Right.  For the same reason(s), I think.

> What I have come up with so far does not use .SY either:
> 
>    .FN void* a_newl elem_sz len
>    create a new array of length \*(a2
>    and with elements of size \*(a1.
> 
> My .FN macro uses .TP internally to format the above as:

This won't work if the formatter you're using isn't powerful enough to
interpret macro definitions.  (String definitions run a similar risk.)
As mandoc(1) maintainer Ingo Schwarze would point out, you run a risk of
your function synopsis being discarded entirely, because one of *roff's
interpretation rules is that unrecognized macros are no-ops.

Deliberately misspell your macro name when calling it to simulate this
failure mode.

This used to be a huge problem with the many "man2html" converters in
existence.  I'm not sure how much of a problem it still is.

>    [/.../ denotes italic]
> 
>    void* a_newl(/elem_sz/, /len/)
>           create a new array of length /len/ and with elements
>           of size /elem_sz/.

I have no objection to this formatting; the question is how to achieve
it.

You didn't say if "void *", "a_newl", and the punctuation are in bold or
roman.  Assuming bold, here's how you format the foregoing without
needing to define your own macro, or use escape sequences.

$ cat /tmp/anton.man
.TH anton 3 2024-06-24 "groff test suite"
.TP
.BI "void* anewl(" elem_sz ", " len )
create a new array of length
.I len
and with elements of size
.IR elem_sz .

$ nroff -r LL=65 -man -P -cbou /tmp/anton.man
anton(3)             Library Functions Manual            anton(3)

     void* anewl(elem_sz, len)
            create a new array of length len and with elements of
            size elem_sz.

groff test suite            2024‐06‐24                   anton(3)

> It is not aligned by return type (yet, I might fix that) and
> deliberately omits types, because they are introduced in a
> preceding section:
> 
>    Since the majority of parameters are common to the
>    majority of functions, we shall describe them below
>    to avoid repetition:
> 
>    void* /a/
>           Pointer to a dymamic array, henceforwared referred
>           to as the array, for each function operates on a
>           single array.
> 
>    ptrdiff_t /len/
>           Array length.
> 
>    size_t /elem_sz/
>           The size of an array element, in bytes.

I wouldn't necessarily write a section 3 man page this way, but the
questions for debate here are matters of style and preference, and will
vary by author and project, not *roff syntax or portability, so I'll
leave them aside for now.

> I have a dedicated macro .AR to format argument
> documentation, which also relies on .TP .  I mean
> parameters, and will rename the macro accordingly.

You might end up with unhappy readers if they use mandoc(1).

> 1. or `were'? (pray pardon mine English)

Either is correct depending on whether you were referring to the editor
I used to compose that specific mail, or the one I use on an ongoing
basis.  Worry not!  Your usage of English is excellent.

Regards,
Branden

[1] As I understand it, the C/A/T came in two configurations: the CAT-4
    with four slots in its mounting carousel for photographic font
    plates, and the CAT-8 with--you guessed it--8.  The 4 fonts that
    Unix V7 troff expected were R, I, B, and S (in that order).  No room
    for Helvetica or Courier in any style.  You will observe that the
    case charging number on page 1 of 32vscan.pdf is in a typewriter
    font that has poor registration with the rest of the document.  My
    supposition is that this datum was added to the document with an
    actual typewriter.  Youngsters of today may not remember that this
    is one of the ways "compositing" was done in the days before the
    desktop publishing revolution--and I'm only barely old enough to
    have gotten any exposure to such methods myself.

    After Kernighan refactored troff for device-independence, documents
    enjoyed more flexibility.  But that had not happened yet.

signature.asc
Description: PGP signature