Re: Documenting a set of functions with -man

[G. Branden Robinson]

Hi Anton,

At 2024-06-13T01:27:42+0300, Anton Shepelev wrote:
> What is the covenstional way of documenting a set of C functions with
> -man?

There isn't one.  As usual I'll offer some historical background.

As far as I know, the community has never converged on a recommended
best practice.  Page authors took a variety of approaches suiting their
ambitions and levels of skill with man(7) and *roff itself.

People frequently run into trouble because they usually don't want the
text of function prototypes filled, but the prototypes can also get
lengthy, and they don't know how to make the text adapt to the available
terminal width in the absence of filling.  (Short answer: you don't.)

My guess is that this didn't seem like a problem when Doug McIlroy
designed man(7) in about 1977, because C function prototypes didn't yet
exist.  You'd declare a function like this.

FILE *freopen(filename, type, stream);
char *filename, *type;
FILE *stream;

In the Seventh Edition Manual, the first to use man(7), this was all set
in undifferentiated bold, and as you can see, without data types
adjacent to the formal parameter names, the declarations were unlikely
to grow lengthy.

Two notorious boundary-pushers had not yet arisen: mmap(2) didn't exist
yet, and neither did bsearch(3).

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.  I think it is only with the just-released
C23 that the old style is no longer syntactically valid, though some
compilers have been stricter, by option or default, for years.

> The .SY macro does not seem to work well for C, because its function
> declarations start with the return type.

Funny you should mention that.

Just 2 months ago I proposed a revision to groff man(7) to solve this
very problem.

https://lists.gnu.org/archive/html/groff/2024-04/msg00115.html

I've since committed the change and it is expected in groff 1.24.

https://git.savannah.gnu.org/cgit/groff.git/tree/NEWS?id=06821158e81af2d7707d59c83113341e2cf41cd1#n150

> Have you any recommendations or examples about typesetting function
> declaraions, their return types and aruguments in a classic man-page?

I'm not sure what you mean by "classic" here, but my recommendation
would be to employ the solution I proffered above.  It survived Alex
Colomar's peer review, and he's familiar with one or two man pages.  ;-)

If you don't want to wait for groff 1.24 to be released or propagate
into deployments, your pages can copy the macro definitions from
tmac/an-ext.tmac.  `SY` is a little long, so I understand if people have
trepidation about doing so.

https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/an-ext.tmac?id=06821158e81af2d7707d59c83113341e2cf41cd1#n56

Regards,
Branden

[1] I would have set the formal argument names in italics to break up
    the tedium and emphasize that the name of a parameter was a matter
    of the user's discretion.

[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

signature.asc
Description: PGP signature