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
