[groff] 01/09: groff_man(7): Pick style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit b2b7a35442cd7a218286dee5ba05849c7dbf6b7a
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Aug 1 18:36:13 2020 +1000

    groff_man(7): Pick style nits.
    
    * (Description/Macro reference preliminaries): Mark another region as
      being for the tutorial/style guide.
    * (Description/Font style macros): Use different idiom for the
      three-font problem in paragraph tags, using less \~ in favor of more
      (quoted) regular spaces on the previous line.
    * (Description/Portability): Add .TQ to list of GNU extensions.
    * Add comments to note cases where falling back to 1991 AT&T troff
      portability would produce hideous outcomes.  (CSTR #54 does not
      admit \(aq or \(dq.)
    * Stop suppressing a break between "AT&T" and "troff".  The Texinfo
      manual doesn't do it and I intend to stop doing it in man pages.  The
      potential for misreading is lower than the risk of ugly adjustment.
    * Use inter-sentence empty requests more consistently.
---
 tmac/groff_man.7.man | 41 ++++++++++++++++++++++++-----------------
 1 file changed, 24 insertions(+), 17 deletions(-)

diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man
index 31e1342..2bc499e 100644
--- a/tmac/groff_man.7.man
+++ b/tmac/groff_man.7.man
@@ -226,6 +226,7 @@ An empty macro argument can be specified with a pair of 
double-quotes
 but the
 .I man
 package is designed such that this should seldom be necessary.
+.\" BEGIN STYLE
 .
 Unused macro arguments are more often simply omitted,
 .\" antipattern: '.TP ""' (just '.TP' will do)
@@ -244,6 +245,7 @@ superfluous.
 .\"     .B one "two " three
 .\"     .B one two " three"
 .\"     .B one two\~ three
+.\" END STYLE
 .
 Most macro arguments are strings that will be output as text;
 exceptions are noted.
@@ -274,7 +276,6 @@ information enabling its indexing by
 .IR mandb (8)
 or a similar tool.
 .
-.
 Sections
 .RB ( .SH ),
 one of which is mandatory and many of which are standardized,
@@ -1413,8 +1414,8 @@ but see subsection \(lqPortability\(rq below for caveats.
 .
 .
 .TP
-.BI .BI " bold-text italic-text"\c
-\~\&.\|.\|.\&
+.BI .BI " bold-text italic-text "\c
+\&.\|.\|.\&
 Set each argument in bold and italics,
 alternately.
 .
@@ -1431,8 +1432,8 @@ alternately.
 .
 .\" END STYLE
 .TP
-.BI .BR " bold-text roman-text"\c
-\~\&.\|.\|.\&
+.BI .BR " bold-text roman-text "\c
+\&.\|.\|.\&
 Set each argument in bold and roman,
 alternately.
 .
@@ -1453,8 +1454,8 @@ the new alias is defined.
 .
 .\" END STYLE
 .TP
-.BI .IB " italic-text bold-text"\c
-\~\&.\|.\|.\&
+.BI .IB " italic-text bold-text "\c
+\&.\|.\|.\&
 Set each argument in italics and bold,
 alternately.
 .
@@ -1475,8 +1476,8 @@ mechanism.
 .
 .\" END STYLE
 .TP
-.BI .IR " italic-text roman-text"\c
-\~\&.\|.\|.\&
+.BI .IR " italic-text roman-text "\c
+\&.\|.\|.\&
 Set each argument in italics and roman,
 alternately.
 .
@@ -1494,8 +1495,8 @@ This is the first command of the
 .
 .\" END STYLE
 .TP
-.BI .RB " roman-text bold-text"\c
-\~\&.\|.\|.\&
+.BI .RB " roman-text bold-text "\c
+\&.\|.\|.\&
 Set each argument in roman and bold,
 alternately.
 .
@@ -1515,8 +1516,8 @@ is not handled specially.
 .
 .\" END STYLE
 .TP
-.BI .RI " roman-text italic-text"\c
-\~\&.\|.\|.\&
+.BI .RI " roman-text italic-text "\c
+\&.\|.\|.\&
 Set each argument in roman and italics,
 alternately.
 .
@@ -1889,6 +1890,8 @@ of a man page look like this:
 .PP
 .RS
 .BI "\(aq\e\(dq " word
+.\" AT&T: .BI "'\e"" " word
+.\" ...and good luck with that "'".
 .RE
 .
 .
@@ -1896,6 +1899,7 @@ of a man page look like this:
 Note that the line starts with an apostrophe (\(aq),
 not a dot,
 and that a single space character follows the double quote.
+.
 The
 .I word
 consists of one letter for each needed preprocessor:
@@ -1984,6 +1988,7 @@ which should be avoided).
 The macros we have described as extensions
 .RB ( .EX / .EE ,
 .BR .SY / .OP / .YS ,
+.BR .TQ ,
 .BR .UR / .UE ,
 and
 .BR .MT / .ME )
@@ -2090,6 +2095,7 @@ Insert at the beginning of an input line to prevent a dot 
or apostrophe
 from being interpreted as the beginning of a
 .I roff
 request.
+.
 Append to an end-of-sentence punctuation sequence to keep it from being
 recognized as such.
 .
@@ -2149,7 +2155,9 @@ Basic Latin double-quote.
 .
 Use in macro calls to prevent
 .RB \(oq \(dq \(rq
-from being interpreted as beginning a quoted argument.
+.\" AT&T: .RB ` """'
+from being interpreted as beginning a quoted argument,
+or simply for readability.
 .
 .
 .RS
@@ -2226,7 +2234,6 @@ or similar.
 .
 .TP
 .B \ec
-.
 Suppress break at the end of the input line.
 .
 Normally,
@@ -2971,8 +2978,8 @@ The extension macro definitions for
 and
 .BR .MT / .ME
 are contained in this file,
-which is written to be compatible with
-.RI AT&T\~ troff
+which is written to be compatible with AT&T
+.I troff
 and permissively licensed\(emnot copylefted.
 .
 Man page authors concerned about portability to legacy Unix systems are