[groff] 10/14: groff_man*(7): Fix content and style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 0a111a916ee344d5046e244dcc95b4d3f49c352d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Nov 1 11:46:48 2021 +1100

    groff_man*(7): Fix content and style nits.
    
    Content:
    * <TH>: Attempt to clarify the meaning of the "section" (manual volume).
    * <TH>: Remove use of passive voice to make it clear that the package
      will perform any necessary abbreviation of `TH` parameters.
    * (Hyperlink macros): Advise reader that arguments to `MR`, `MT`, and
      `UR` should be prepared for typesetting (meaning: use escapes for the
      hyphen-minus, apostrophe, double quote, grave accent, caret,
      backslash, and tilde, though apart from the first, many of those are
      doubtless uncommon or invalid in their remote contexts).
    * (Hyperlink macros): Soften guidance regarding URI breaking; discretion
      is warranted.  Thanks to Ralph Corderoy for the suggestion.
    * (Deprecated features): Explicitly annotate `OP` macro as an extension.
    
    Style:
    * Spell "PostScript" with StudlyCaps.
---
 tmac/groff_man.7.man.in | 34 +++++++++++++++++++++++++---------
 1 file changed, 25 insertions(+), 9 deletions(-)

diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 74282fd..09b912f 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -348,7 +348,7 @@ macros.
 .RI " [" header-middle ]
 Define the title of the man page as
 .I title
-and the section of the manual volume as
+and the volume of the manual to which it belongs as
 .IR section .
 _ifstyle()dnl
 .
@@ -405,13 +405,15 @@ If
 is a simple integer between 1 and\~9 (inclusive),
 there is no need to specify
 .IR header-middle ;
-the macro package will supply text for it.
+.I an.tmac
+will supply text for it.
 .
+The macro package may also abbreviate
 .I title
 and
 .I footer-inside
-may each be abbreviated with an ellipsis if they overrun the space
-available in the header and footer,
+with an ellipsis if they overrun the space available in the header and
+footer,
 respectively.
 .
 For HTML output,
@@ -1180,10 +1182,24 @@ Plan\~9
 .I troff \" Plan 9
 implements
 .BR .MR .
-_ifstyle()dnl
 .
 .
 .P
+The arguments to
+.BR .MR ,
+.BR .MT ,
+and
+.B .UR
+should be prepared for typesetting since they can appear in the
+output.
+.
+Use special character escape sequences to encode Unicode basic Latin
+characters where necessary,
+particularly the hyphen-minus.
+_ifstyle()dnl
+.
+(See section \[lq]Portability\[rq] below.)
+.
 URIs can be lengthy;
 rendering them can result in jarring adjustment or variations in line
 length,
@@ -1197,7 +1213,7 @@ after each slash
 (or series thereof),
 and before each dot
 (or series thereof)
-is recommended.
+is recommended as a rule of thumb.
 .
 The former practice avoids forcing a trailing slash in a URI onto a
 separate output line,
@@ -1250,13 +1266,13 @@ _ifstyle()dnl
 .EX
 The output driver
 \&.MR grops @MAN1EXT@
-produces Postscript from
+produces PostScript from
 \&.I troff
 output.
 \&.
 The Ghostscript program (\[rs]c
 \&.MR gs 1 )
-interprets Postscript and PDF.
+interprets PostScript and PDF.
 .EE
 .RE
 _endif()dnl
@@ -2880,7 +2896,7 @@ Square brackets in roman surround both arguments.
 .IP
 Use of this quasi-semantic macro,
 .\" https://github.com/n-t-roff/DWB3.3/blob/master/macros/man/an.sr#L37
-originating in Documenter's Workbench
+an extension originating in Documenter's Workbench
 .IR troff ,\" DWB
 is deprecated.
 .