[bug #62926] [mdoc] align styling of titles and man page cross references with man(7)

[G. Branden Robinson]

Follow-up Comment #5, bug #62926 (project groff):

> Yikes.  Are you aware that the mdoc(7) language API does not contain a
single user-visible register yet?

> Very grudgingly, yes, if you must pollute the API with \*(MF.

I would also add that your use of "API" here is open to equivocation.

There are two materially relevant interfaces here.

1. That between the man page author and the macro package.
2. That between the man page reader and the macro package.

Man page authors are explicitly discouraged from using `MF`, as they are _all
other_ strings and registers.


.\" ====================================================================
.SS Registers
.\" ====================================================================
.
Registers are described in section \(lqOptions\(rq below.
.
They can be set not only on the command line but in the site
.I man.local
file as well;
see section \(lqFiles\(rq below.
.
.
.\" ====================================================================
.SS Strings
.\" ====================================================================
.
The following strings are defined for use in man pages.
.
_ifnotstyle()dnl
None of these is necessary in a contemporary man page;
see
.MR groff_man_style @MAN7EXT@ .
_endif()dnl
.
Others are supported for configuration of rendering parameters;
see section \(lqOptions\(rq below.
[...]
_ifstyle()dnl
.
.
.P
None of the above is necessary in a contemporary man page.
.
.B \e*S
is superfluous,
since type size changes are invisible on terminal devices and macros
that change it restore its original value afterward.
.
Better alternatives exist for the rest;
simply use the
.BR \(rs(rg , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9, Solaris
.BR \(rs(lq , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9
.BR \(rs(rq , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9
and
.B \(rs(tm \" Heirloom Doctools, mandoc, neatmkfn, Plan 9
special character escape sequences directly.
.
Unless a man page author is aiming for a pathological level of
portability,
such as the composition of pages for consumption on simulators of 1980s
Unix systems
(or Solaris
.IR troff ,
though even it supports
.BR \(rs(rg ),
the above strings should be avoided.
[...]
.\" ====================================================================
.SH Options
.\" ====================================================================
.
The following
.I groff
options set registers
(with
.BR \-r )
and strings
(with
.BR \-d )
recognized and used by the
.I man
macro package.
.
To ensure rendering consistent with output device capabilities and
reader preferences,
man pages should never manipulate them.


There is therefore no reason to catastrophize the addition of `MF` to a set
that already includes (strings) `AD` and `HF` and registers `cR`, `C`, `CS`,
`CT`, `D`, `FT`, `HY`, `IN`, `LL`, `LT`, `P`, `S`, `SN`, `U`, and `X`.

groff mdoc does not yet support all of these, but I would like it if it did. 
These are _all_ rendering options, and if an implementation wants to remove
these degrees of freedom, it can do so without impacting how man pages using
either package are _written_.


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?62926>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/