|
From: engelbert g. <gr...@us...> - 2026-05-13 19:02:12
|
one problem is the manpage writer does not know it is man page reference, it is only marked as emphasize
second
~~~
*groff_man_style*\(7)
is a reference to the *groff* *man* macro language, with much advice
for document authors.
~~~
is
~~~
<definition_list_item>
<term>
<emphasis>
groff_man_style
(7)
<definition>
~~~
and defintionlistitems are typeset BOLD
admittedly a decision i simply made without asking
problem one would require the manpage writer to lex/parse
---
**[bugs:#482] manpage: section numbers wrongly in boldface in "See also" section**
**Status:** open
**Labels:** manpage writer
**Created:** Wed Mar 27, 2024 01:22 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 11:16 AM UTC
**Owner:** engelbert gruber
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.
---
Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/
To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |