[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 01/09: groff_man(7): Pick style nits.
From: |
G. Branden Robinson |
Subject: |
[groff] 01/09: groff_man(7): Pick style nits. |
Date: |
Sat, 8 Aug 2020 08:48:17 -0400 (EDT) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 01/09: groff_man(7): Pick style nits.,
G. Branden Robinson <=