The parenthesized section number of a man page document should be rendered upright at normal weight, not in boldface.
This appears to be an unintentional defect in the manpage writer. Here's a snippet of rst2man output.
.SH SEE ALSO
.INDENT 0.0
.TP
.B \fIgroff_man_style\fP(7)
is a reference to the \fIgroff\fP \fIman\fP macro language, with much advice
for document authors.
.TP
.B \fImandoc\fP(1)
is a non\-\fIroff\fP\-based system for formatting man pages.
.UNINDENT
It's pretty confusing to humans to mix font selection escape sequences with man font macros. (I also think that macros should be used in preference to formatter requests or escape sequences wherever possible, but I acknowledge that this is a much bigger challenge for document format conversion programs than for human writers.)
Here's what I propose when formatting a man page cross reference, in case you're doing any pattern matching to detect them.
.TP
.B \fIgroff_man_style\fP\R(7)\fP
If you're not doing pattern matching to detect man page cross references, the problem may be harder.
Here's my rST input for the foregoing.
See also
========
*groff_man_style*\(7)
is a reference to the *groff* *man* macro language, with much advice
for document authors.
*mandoc*\(1)
is a non-*roff*-based system for formatting man pages.
It appears to me that the decision to set the paragraph tag (definition list headword) in bold was rst2man's; it was not derived from any formatting in the rST source document. I humbly suggest reconsidering that choice, and let rST document authors select whatever degree of typographic emphasis for the paragraph tag/definition list headword they desire. In fact it appears to be that they can already do so, so the B
call may just be getting in the way.
Here's a message from 2022 where Ingo mentions that he'll be changing mandoc(1) to no longer warn about mixed case. It produces these warnings only with the
-Tlint
option in the first place; using mixed case for man page identifiers and section headings will not cause any formatter known to me to produce diagnostic messages when simply formatting a document.https://lists.gnu.org/archive/html/groff/2022-08/msg00014.html
Last edit: G. Branden Robinson 2024-03-27
this is disruptive
a manpage is not a webpage , getting fonts uniform helps (just like
uppercase titles)
but from rST-source point it is clearer if the importance is marked there ...
might require a lot of changes in rST files ...
till after 0.21
Last edit: Günter Milde 2024-03-29