Re: Documenting a set of functions with -man

[Bjarni Ingi Gislason]

On Fri, Jun 21, 2024 at 02:52:22PM +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.

> .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

  There are two issues here,

1) wrong use of the adjustment requests

2) still not fixed bug #55579 (patch in bug #59795).

About

1) '.ad' only works with '.na' so the right use is

.na\" instead of '.ad l'
...
.ad

2) the fix in item 1 does not work if the adjustment before '.na' is 'left',
as the adjustment is then switched to 'both'.

  The patch in #59795 (comment #0) is simple enough to apply it with an
editor.