Re: Documenting a set of functions with -man

[Anton Shepelev]

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)