Re: Documenting a set of functions with -man

[G. Branden Robinson]

Hi Lennart,

At 2024-06-21T14:52:22+0000, Lennart Jablonka wrote:
> Quoth Anton Shepelev:
> > What is the covenstional way of documenting a set of C
> > functions with -man?  Have you any recommendations or
> > examples about typesetting function declaraions, their
> > return types and aruguments in a classic man-page?  The .SY
> > macro does not seem to work well for C, because its function
> > declarations start with the return type.
> 
> Do take a look at .SY, but also note that it’s possible to do
> something like this.

I advise against part of this pattern, because it can override user
preferences.

Let me illustrate by way of a slight expansion.

.TH MMAP 2
.SH NAME
mmap \- map pages of memory
.SH SYNOPSIS
.ad l
#include <sys/mman.h>
.HP
void *mmap(\
void\ *addr,
size_t\ len,
int\ prot,
int\ flags,
int\ filedes,
off_t\ off);
.HP "\w'void *mmap('u"
void *mmap(\
void\ *addr,
size_t\ len,
int\ prot,
int\ flags,
int\ filedes,
off_t\ off);
.ad
.SH DESCRIPTION
I wanted adjustment off for this,
because I'm the sort of person who hates seeing it on a terminal.
I wanted adjustment off for this,
because I'm the sort of person who hates seeing it on a terminal.

Say someone is using groff's man.local mechanism or something similar
(an old-schooler might even hack up their "tmac.an" file) to turn off
adjustment just as you did.

.ad l

Or perhaps like this:

.if n .ad l

Your ".ad l" call will be redundant in such circumstances, but that's
fine.

Where things go wrong is here.

.ad

This will cause undesired results for those who wanted adjustment off in
general when reading man pages.

$ nroff -r LL=72n -man -T ascii -P -cbou /tmp/branden/mmap-gbr1.man
MMAP(2)                    System Calls Manual                   MMAP(2)

NAME
     mmap - map pages of memory

SYNOPSIS
     #include <sys/mman.h>

     void *mmap(void *addr, size_t len, int prot, int flags,
            int filedes, off_t off);

     void *mmap(void *addr, size_t len, int prot, int flags,
                int filedes, off_t off);

DESCRIPTION
     I  wanted  adjustment  off for this, because I'm the sort of person
     who hates seeing it on a terminal.  I  wanted  adjustment  off  for
     this,  because I'm the sort of person who hates seeing it on a ter-
     minal.

                                                                 MMAP(2)

A fairly shrewd man(7) writer might then ask:

"Ah, right, because '.ad' by itself restores the previous alignment and
adjustment setting, which I clobbered with my '.ad l', right?"

No, it only behaves that way if the previous mode _wasn't_ left
alignment with no adjustment.

It's a painful, unorthogonal design, and inconsistent with much else
of *roff, which retains a one-item deep memory of many formatting
parameters.  `.ft` without arguments goes back to the previous font
selection for example, `.ll` does that for the line length, `.in` for
the indentation, and so on.

Unfortunately, two of the most commonly manipulated formatting
parameters, the adjustment/alignment mode and the automatic hyphenation
mode, don't follow the same rules as the others.

But on the bright side, few people ever seem to use '.ad c' or '.ad r'.
_Especially_ in man pages.

So I'm contemplating a reform to `ad` request behavior.  I'll start a
new thread for that.  And there is always compatibility mode for legacy
documents.

Regards,
Branden

mmap-gbr1.man
Description: Unix manual page

signature.asc
Description: PGP signature