G. Branden Robinson:
> 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.)
I dislike long lines in code as well as in documentation,
which made me ponder a tabular approach, where each function
is presented and documented in parts, e.g:
char *strtok
<describe the fucntion and what it returns>
char *restrict str,
<describe the `str' argument>
const char *restrict delim
<describe the delim argument>
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 */
);
> 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.
Glad to see Doug still around and about this list.
> You'd declare a function like this.
>
> FILE *freopen(filename, type, stream);
> char *filename, *type;
> FILE *stream;
Yes, and the K&R style is good at least in that it is
"bookish" -- tall and narrow.
> 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!
> > 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
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.
> > 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 ->
I meant the standard `man' package without the GNU
extension, and specifically not `mdoc', which seems more
advanced.
> -> 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. ;-)
Thank you.
> [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.
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. Yes, typesetting the
arguments in italics is a good idea both esthetically and
syntatically.
> [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. AFAIK,
the `man' package is unaware of it as well, save the example
macro, but it is an extension.
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:
[/.../ denotes italic]
void* a_newl(/elem_sz/, /len/)
create a new array of length /len/ and with elements
of size /elem_sz/.
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 have a dedicated macro .AR to format argument
documentation, which also relies on .TP . I mean
parameters, and will rename the macro accordingly.
____________________
1. or `were'? (pray pardon mine English)
