docutils-develop

[Docutils-develop] [docutils:bugs] #482 manpage: section numbers wrongly in boldface in "See also" section

[G. B. R. <br...@us...>]

---

**[bugs:#482] manpage: section numbers wrongly in boldface in "See also" section**

**Status:** open
**Created:** Wed Mar 27, 2024 01:22 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 01:22 AM UTC
**Owner:** nobody


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.

[Docutils-develop] [docutils:bugs] #482 manpage: section numbers wrongly in boldface in "See also" section

[engelbert g. <gr...@us...>]

- **labels**:  --> manpage writer
- **assigned_to**: engelbert gruber



---

**[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 01:29 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.

[Docutils-develop] [docutils:bugs] #482 manpage: section numbers wrongly in boldface in "See also" section

[G. B. R. <br...@us...>]

Here's a message from 2022 where Ingo mentions that he'll be changing _mandoc_(1) to no longer warn about mixed case.  Note that it only produces these warnings 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.

https://lists.gnu.org/archive/html/groff/2022-08/msg00014.html


---

**[bugs:#482] manpage: section numbers wrongly in boldface in "See also" section**

**Status:** open
**Created:** Wed Mar 27, 2024 01:22 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 01:22 AM UTC
**Owner:** nobody


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.

[Docutils-develop] [docutils:bugs] Re: #482 manpage: section numbers wrongly in boldface in "See also" section

[engelbert g. <gr...@us...>]

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

On Wed, 27 Mar 2024 at 02:29, G. Branden Robinson
<br...@us...> wrote:
>
> Here's a message from 2022 where Ingo mentions that he'll be changing mandoc(1) to no longer warn about mixed case. Note that it only produces these warnings 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.
>
> https://lists.gnu.org/archive/html/groff/2022-08/msg00014.html
>
> ________________________________
>
> [bugs:#482] manpage: section numbers wrongly in boldface in "See also" section
>
> Status: open
> Created: Wed Mar 27, 2024 01:22 AM UTC by G. Branden Robinson
> Last Updated: Wed Mar 27, 2024 01:22 AM UTC
> Owner: nobody
>
> 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 you indicated interest in https://sourceforge.net/p/docutils/bugs/482/
>
> To unsubscribe from further messages, please visit https://sourceforge.net/auth/subscriptions/


---

**[bugs:#482] manpage: section numbers wrongly in boldface in "See also" section**

**Status:** open
**Created:** Wed Mar 27, 2024 01:22 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 01:29 AM UTC
**Owner:** nobody


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.