[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 02/12: groff_man*(7): Fix style nits.
G. Branden Robinson
[groff] 02/12: groff_man*(7): Fix style nits.
Mon, 24 Aug 2020 08:15:36 -0400 (EDT)
gbranden pushed a commit to branch master
in repository groff.
Author: G. Branden Robinson <firstname.lastname@example.org>
AuthorDate: Sat Aug 22 12:15:03 2020 +1000
groff_man*(7): Fix style nits.
* tmac/groff_man.7.man.in (Description/Horizontal and vertical spacing)
[style]: Stop referring to an indentation amount as "ordinary". The
word "ordinary" is used in this page only to distinguish .LP/.PP/.P
paragraphs from the other kinds.
(Description/Number registers): Rename...
(Description/Registers): ...to this. And similarly through the rest
of the page. *roff registers have been returning string values since
the 1970s (\n(.F, \n(.z). "Number register" might be mnemonic for the
".nr" request (though I'm doubtful, and itching to make this same
change in more general groff documentation), but the man(7)-only groff
audience has no need of that device.
(Description/Portability) [style] <\c>: My recent sentence describing
what \c does after explaining the normal semantics of a newline works
even better as the initial description of the escape. Replace the
latter with the former. Put explanation of normal semantics in
parentheses so it is more clear when we switch back to describing \c
(Description/Hooks): Recast and rearrange, mainly to avoid the
misleading implication that because .BT and .PT are GNU extensions,
they should not be used in man pages (though doubtless some people
feel that way). No, they shouldn't be used in man pages because
they're hooks. Make that more clear.
(Options) <-dAD>: Fix bad macro call causing a mis-set comma.
(Options) <-rHY>: Explicitly tell reader how to disable hyphenation
since that's popular.
(general): Don't set slash in bold in constructions like ".EX/.EE".
tmac/groff_man.7.man.in | 61 ++++++++++++++++++++++++++++---------------------
1 file changed, 35 insertions(+), 26 deletions(-)
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 35973e7..0b31e39 100644
@@ -20,7 +20,7 @@ _endif
These man pages serve multiple goals, one of which is to serve as a
-model for good man page writing by people who examine its source.
+model for good man page writing by people who examine their sources.
After processing by m4, both child pages in the above case will carry \c
escapes followed by text lines starting with punctuation one normally
@@ -30,7 +30,7 @@ to be protected from interpretation as a control line).
This is ugly, fragile, and unnecessary; all of these traits are
offensive to good pedagogy.
-Consequently, it is better to repeat a small amount of material than
+Consequently, it is better to repeat a small amount of material than
write a man page that looks like the output of docbook-to-man.
@@ -196,11 +196,9 @@ _ifstyle()dnl
.\" TODO: Write an introduction for non-typographers. Cover the
-.\" word (delimited by spaces or newlines)
-.\" sentence (including end-of-sentence detection)
-.\" filling, hyphenation, breaking, adjustment (elsewhere:
+.\" filling, hyphenation, breaking, adjustment (elsewhere known as
-.\" font (family, style [elsewhere: face])
+.\" font (family, style [elsewhere known as face])
.\" point size
.\" typesetter (troff device, PostScript, PDF)
.\" terminal (nroff device, emulator, typewriter, TTY)
@@ -213,7 +211,12 @@ Man pages should be encoded using Unicode basic Latin code
and employ the Unix line-ending convention
+.\" What about rare English words that require diacritics, and
+.\" proper names that require more than basic Latin?
.\" text lines vs. control lines (macro calls)
+.\" word (delimited by spaces or newlines)
+.\" sentence (including end-of-sentence detection)
.\" The above distinction works well with filling.
.\" Don't fill your input text yourself; let groff do the work.
.\" Also good for diffs.
@@ -934,7 +937,7 @@ _ifstyle()dnl
+.BR .SY / .YS
blocks can be specified,
for instance to distinguish differing modes of operation of a complex
@@ -1789,7 +1792,7 @@ to change it.
This paragraph is affected both by the moved left margin
.RB ( .RS )
-and ordinary indentation
.RB ( .IP ).
@@ -1901,10 +1904,10 @@ also cause a break but no insertion of vertical space.
-.SS "Number registers"
-Number registers are described in section \(lqOptions\(rq below.
+Registers are described in section \(lqOptions\(rq below.
They can be set not only on the command line but in the site
@@ -2342,9 +2345,11 @@ or similar.
-Suppress break at the end of the input line.
+End an input line without inserting space or attempting a break.
+.\" TODO: When we explain what a "sentence" is, move this parenthetical
the end of an input line is treated like a space;
.\" end-of-sentence detection is performed, and...
an output line
@@ -2355,11 +2360,8 @@ an adjustable space is inserted)
be broken there in
-examples.\" i.e., no-fill mode
-This escape ends an input line without inserting space or attempting a
+.BR .EX / .EE
+examples.)\" i.e., no-fill mode
@@ -2374,7 +2376,7 @@ The next line is interpreted as usual and can `include' a
This escape is useful when three different font styles are needed in a
single word or on a single line in
+.BR .EX / .EE
@@ -2550,9 +2552,11 @@ _endif()dnl
-Two macros called internally by the
+both GNU extensions,\" from groff 1.19
+are called internally by the
.I groff man
-package to format page headers and footers can be redefined by the
+package to format page headers and footers and can be redefined by the
administrator in a site's
@@ -2562,11 +2566,12 @@ The default headers and footers are documented in the
-These macros are GNU extensions and it makes no sense for a man page
-to call them.
+Because these macros are hooks for
+.I groff man
+man pages have no reason to call them.
-.\" both from groff 1.19
Set the page footer
@@ -2783,7 +2788,7 @@ The only strings defined were
.BR S ;
-no number registers were documented.
+no registers were documented.
appeared in 3BSD (1980) and
@@ -2847,7 +2852,7 @@ macro package.
.BI \-dAD= adjustment-mode
Set line adjustment to
-.I adjustment-mode ,
+.IR adjustment-mode ,
which is typically
.RB \[lq] b \[rq]
for adjustment to both margins
@@ -2953,11 +2958,15 @@ See
-.BI \-rHY= mode
+.BI \-rHY= hyphenation-mode
Set hyphenation mode,
as documented in section \(lqHyphenation\(rq of
.IR groff (@MAN7EXT@).
+to disable hyphenation.
The default is\~4 if continuous rendering is enabled
.RB ( \-rcR=1
|[Prev in Thread]
||[Next in Thread]|
- [groff] 02/12: groff_man*(7): Fix style nits.,
G. Branden Robinson <=