Hi Mark,
Mark Kettenis wrote on Mon, May 20, 2013 at 01:42:14PM -0600:
> CVSROOT: /cvs
> Module name: src
> Changes by: kette...@cvs.openbsd.org 2013/05/20 13:42:14
>
> Modified files:
> share/man/man9 : uvm.9
>
> Log message:
> Wrap list of prototypes in a .nr nS 1/0 pair just like all the others. No
> cluse what this is supposed to do, but it is consistent with what happens
> elsewhere in this man page and fixes the obvious formatting problems.
To answer your question, as i guess few people know this quirk:
$ man 7 roff | grep -A14 -B1 'Define a register'
nr
Define a register. A register is an arbitrary string value
that defines some sort of state, which influences parsing
and/or formatting. Its syntax is as follows:
.nr name value
The value may, at the moment, only be an integer. So far,
only the following register name is recognised:
nS If set to a positive integer value, certain mdoc(7)
macros will behave in the same way as in the SYNOPSIS
section. If set to 0, these macros will behave in the
same way as outside the SYNOPSIS section, even when
called within the SYNOPSIS section itself. Note that
starting a new mdoc(7) section with the Sh macro will
reset this register.
So .nr is one of the few roff(7) requests implemented in mandoc(1).
The register "nS" is special to the old (pre-groff-1.17) groff
implementation of mdoc(7), it is neither supported by modern groff
nor (i suppose) by other, non-groff mdoc(7) implementations, so it's
utterly non-portable.
As OpenBSD never used anything but old groff to build manuals,
this hack just worked for us and got used extensively in kernel
manuals, wherever any page needed to split the SYNOPSIS into parts.
Consequently, i made it work in mandoc(1) as well.
It is still a non-portable hack, but since there is no portable
way to split a SYNOPSIS in mdoc(7), i don't know how to improve
the situation. Inventing new mdoc(7) syntax for this end would
only make matters worse by being even less portable and causing
a make-work project to adjust existing manuals.
Hope that helps,
Ingo
P.S.
If you want a free commit, feel free to fix the INITIALISATION
section in the same way.
