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

This is a multi-part message in MIME format.
--===============2613438670529017998==
Content-Type: multipart/related; boundary="===============6313166282659055886=="

This is a multi-part message in MIME format.
--===============6313166282659055886==
Content-Type: multipart/alternative; boundary="===============4601841709930491600=="
MIME-Version: 1.0

--===============4601841709930491600==
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit

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 [email protected] 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.
--===============4601841709930491600==
MIME-Version: 1.0
Content-Type: text/html; charset="us-ascii"
Content-Transfer-Encoding: 7bit

<div class="markdown_content"><p>one problem is the manpage writer does not know it is man page reference, it is only marked as emphasize</p>
<p>second</p>
<div class="codehilite"><pre><span></span><code>*groff_man_style*\(7)
  is a reference to the <span class="gs">*groff*</span> *man* macro language, with much advice
  for document authors.
</code></pre></div>

<p>is</p>
<div class="codehilite"><pre><span></span><code>        &lt;definition_list_item&gt;
            &lt;term&gt;
                &lt;emphasis&gt;
                    groff_man_style
                (7)
            &lt;definition&gt;
</code></pre></div>

<p>and defintionlistitems are typeset BOLD <br/>
admittedly a decision i simply made without asking</p>
<p>problem one would require the manpage writer to lex/parse</p>
<hr/>
<p><strong><a class="alink" href="https://sourceforge.net/p/docutils/bugs/482/">[bugs:#482]</a> manpage: section numbers wrongly in boldface in "See also" section</strong></p>
<p><strong>Status:</strong> open<br/>
<strong>Labels:</strong> manpage writer <br/>
<strong>Created:</strong> Wed Mar 27, 2024 01:22 AM UTC by G. Branden Robinson<br/>
<strong>Last Updated:</strong> Wed Mar 27, 2024 11:16 AM UTC<br/>
<strong>Owner:</strong> engelbert gruber</p>
<p>The parenthesized section number of a man page document should be rendered upright at normal weight, not in boldface.</p>
<p>This appears to be an unintentional defect in the manpage writer.  Here's a snippet of <em>rst2man</em> output.</p>
<div class="codehilite"><pre><span></span><code>.<span class="k">SH</span> <span class="s">SEE</span> <span class="s">ALSO</span>
.<span class="k">INDENT</span> <span class="m">0</span><span class="s">.0</span>
.<span class="k">TP</span>
.<span class="k">B</span> <span class="se">\fI</span><span class="s">groff_man_style\fP(7)</span>
is a reference to the <span class="se">\fI</span>groff<span class="se">\fP</span> <span class="se">\fI</span>man<span class="se">\fP</span> macro language, with much advice
for document authors.
.<span class="k">TP</span>
.<span class="k">B</span> <span class="se">\fI</span><span class="s">mandoc\fP(1)</span>
is a non<span class="se">\-\fI</span>roff<span class="se">\fP\-</span>based system for formatting man pages.
.<span class="k">UNINDENT</span>
</code></pre></div>

<p>It's pretty confusing to humans to mix font selection escape sequences with <em>man</em> 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.)</p>
<p>Here's what I propose when formatting a man page cross reference, in case you're doing any pattern matching to detect them.</p>
<div class="codehilite"><pre><span></span><code>.<span class="k">TP</span>
.<span class="k">B</span> <span class="se">\fI</span><span class="s">groff_man_style\fP\R(7)\fP</span>
</code></pre></div>

<p>If you're <em>not</em> doing pattern matching to detect man page cross references, the problem may be harder.</p>
<p>Here's my rST input for the foregoing.</p>
<div class="codehilite"><pre><span></span><code><span class="gh">See also</span>
<span class="gh">========</span>

<span class="ge">*groff_man_style*</span>\(7)
  is a reference to the <span class="ge">*groff*</span> <span class="ge">*man*</span> macro language, with much advice
  for document authors.

<span class="ge">*mandoc*</span>\(1)
  is a non-<span class="ge">*roff*</span>-based system for formatting man pages.
</code></pre></div>

<p>It appears to me that the decision to set the paragraph tag (definition list headword) in bold was <em>rst2man</em>'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 <code>B</code> call may just be getting in the way.</p>
<hr/>
<p>Sent from sourceforge.net because [email protected] is subscribed to <a href="https://sourceforge.net/p/docutils/bugs/">https://sourceforge.net/p/docutils/bugs/</a></p>
<p>To unsubscribe from further messages, a project admin can change settings at <a href="https://sourceforge.net/p/docutils/admin/bugs/options.">https://sourceforge.net/p/docutils/admin/bugs/options.</a>  Or, if this is a mailing list, you can unsubscribe from the mailing list.</p></div>
--===============4601841709930491600==--

--===============6313166282659055886==--


--===============2613438670529017998==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline


--===============2613438670529017998==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline