gbranden pushed a commit to branch master
in repository groff.
commit 2da1c38209325a7fe8667f12df6630788786d9e4
Author: G. Branden Robinson <[email protected]>
AuthorDate: Thu Aug 10 00:04:23 2023 -0500
groff_man*(7): Revise.
Content:
* [style] Introduce distinction between "terminals" and "typesetters".
* Drop discussion of "left margin" concept, instead using "inset" and
"indentation" amounts (and one mention of "page offset") instead.
* [style] Add forward cross reference to "Portability" subsection when
cautioning reader in `EX`/`EE` description about formatting ', -, \,
^, `, and ~.
* Document register defaults exclusively in "Registers" section rather
than placing some in "Horizontal and vertical spacing" subsection.
* [style] Drop examples of warning diagnostics when `RE` is misused;
their language is subject to change. (And man-db man(1) users who use
only that program to preview their pages, and don't tell it to enable
warnings, won't see them anyway.)
Style:
* Collect more discussion of horizontal spacing in "Horizontal and
vertical spacing" subsection, relocating it from macro descriptions.
* Reorganize same subsection, for clarity (I hope).
* Coalesce some brief paragraphs.
* Adjust dead-tree pagination with poor man's keeps.
* Arrange "Research Ninth Edition Unix" in canonical order.
* Tighten wording.
---
tmac/groff_man.7.man.in | 267 +++++++++++++++++++++++-------------------------
1 file changed, 130 insertions(+), 137 deletions(-)
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index ad1ddf0ec..6e59cdd3a 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -129,8 +129,6 @@ It is used to produce manual pages
(\(lqman\~pages\(rq)
like the one you are reading.
.
-.
-.P
This document presents the macros thematically;
for those needing only a quick reference,
the following table lists them alphabetically,
@@ -283,6 +281,13 @@ option).
.MR roff @MAN7EXT@
details these processes.
.
+Output is prepared for
+.I terminal
+devices,
+or for more capable
+.I typesetting
+devices that can change the type size and font family.
+.
.
.P
An input line that starts with a dot (.\&)
@@ -345,11 +350,11 @@ macro description).
.\" small (mandoc, Kerrisk's man7.org, manpages.debian.org, non-expert
.\" humans).
.\" possibly exhibit a horrorshow docbook-to-man example
-_endif()dnl
.
.
.br
.ne 6v
+_endif()dnl
.\" ====================================================================
.SS "Macro reference preliminaries"
.\" ====================================================================
@@ -362,10 +367,6 @@ as with
and
.BR .EE .
.
-.
-.br
-.ne 2v
-.P
_ifstyle()dnl
Optional macro arguments are indicated by surrounding them with square
brackets.
@@ -568,11 +569,11 @@ text on the next line
becomes
.I heading-text.
.
-The left margin is reset to zero to set the heading text in bold
+The heading text is set in bold
(or the font specified by the string
.BR HF ),
and,
-on typesetting devices,
+on typesetters,
slightly larger than the base type size.
.
If the heading font
@@ -638,9 +639,7 @@ text on the next line
becomes
.I subheading-text.
.
-The left margin is reset to the value of the
-.B SN
-register to set the heading text in bold
+The subheading text is set in bold
(or the font specified by the string
.BR HF ).
.
@@ -692,9 +691,11 @@ glyphs for
.BR \(ha ,
.BR \(ga ,
and
-.BR \(ti ,
-and sentence endings are still detected and additional inter-sentence
-space applied.
+.B \(ti
+(see subsection \(lqPortability\(rq below).
+.
+Sentence endings are still detected and additional inter-sentence space
+applied.
.
If the amount of additional inter-sentence spacing is altered,
the rendering of,
@@ -713,7 +714,7 @@ before the spaces.
_endif()dnl
.IP
.\" Also see subsection "History" below...
-These macros are extensions introduced in Ninth Edition Research Unix.
+These macros are extensions introduced in Research Ninth Edition Unix.
.
Systems running that
.IR troff , \" AT&T Research Unix
@@ -739,7 +740,7 @@ installation.
.IR inset-amount ]
Start a new relative inset level.
.
-The position of the left margin is saved,
+The current inset amount is saved,
then moved right by
.I inset-amount,
if specified,
@@ -781,7 +782,7 @@ An ordinary paragraph
_ifstyle()dnl
like this one
_endif()dnl
-is set without a first-line indentation at the current left margin.
+is set with all output lines indented the same amount.
.
In man pages and other technical literature,
definition lists are frequently encountered;
@@ -831,8 +832,14 @@ see subsection \(lqFont style macros\(rq below.
Begin a new paragraph;
these macros are synonymous.
.
-The indentation is reset to the default value;
-the left margin,
+Any indentation from use of
+.BR .IP ,
+.BR .TP ,
+or the deprecated
+.B .HP
+is cleared.
+.
+The inset amount,
as affected by
.B .RS
and
@@ -850,7 +857,7 @@ A one-line input trap is planted;
text on the next line,
which can be formatted with a macro,
becomes the tag,
-which is placed at the current left margin.
+which is set without indentation.
.
The tag can be extended with the
.B \(rsc
@@ -983,13 +990,13 @@ _endif()dnl
.SS "Command synopsis macros"
.\" ====================================================================
.
+Use
.B .SY
and
.B .YS
-aid you to construct a command synopsis that has the classical Unix
-appearance.
+to summarize syntax using familiar Unix conventions.
.
-They break the output line.
+These macros break the output line.
.
.\" TODO: Determine whether this (is still? was ever?) true.
.\" Furthermore,
@@ -998,7 +1005,10 @@ They break the output line.
.
.
.P
-These macros are GNU extensions not defined on systems running
+.B .SY
+and
+.B .YS
+are GNU extensions not defined on systems running
AT&T,
Plan\~9,
or
@@ -1013,7 +1023,7 @@ in section \(lqFiles\(rq below.
.BI .SY " command"
Begin synopsis.
.
-A new paragraph begins at the left margin
+A new paragraph begins at the current inset amount
_ifstyle()dnl
(as with
.BR .P )
@@ -1277,9 +1287,7 @@ Text may be hyperlinked to email addresses with
or other URIs with
.BR .UR / .UE .
.
-Hyperlinked text is supported on HTML
-.\", PDF,
-and terminal output devices;
+Hyperlinked text is not supported on all output devices;
terminals and pager programs must support ECMA-48 OSC\~8 escape
sequences
(see
@@ -1560,12 +1568,11 @@ offering only
.RB \~( .I ),
and roman.
.
-Italic text is usually set underscored instead on terminal devices.
+Italic text is usually set underscored instead on terminals.
.
-The
.B .SM
-macro sets text at a smaller type size;
-it differs visually from regular-sized text only on typesetting devices.
+sets text at a smaller type size,
+which differs visually from regular-sized text only on typesetters.
.
It is often necessary to set text in different styles without
intervening space.
@@ -1601,8 +1608,7 @@ _endif()dnl
.br
.ne 2v
.P
-The default type size and family for typesetting devices is 10-point
-Times,
+The default type size and family for typesetters is 10-point Times,
except on the
.B \%X75\-12
and
@@ -1695,7 +1701,7 @@ _endif()dnl
.IR text ]
Set
.I text
-one point smaller than the default type size on typesetting devices.
+one point smaller than the default type size on typesetters.
.
If no argument is given,
a one-line input trap is planted;
@@ -1754,6 +1760,10 @@ escape sequences in subsection \(lqPortability\(rq below.
.
.
_endif()dnl
+_ifnotstyle()dnl
+.br
+.ne 2c
+_endif()dnl
.P
Unlike the above font style macros,
the font style alternation macros below set no input traps;
@@ -1908,17 +1918,47 @@ _endif()dnl
.SS "Horizontal and vertical spacing"
.\" ====================================================================
.
+All text is rendered with respect to the
+.I "page offset;"
+see register
+.B PO
+in section \[lq]Options\[rq] below.
+.
+Headers,
+footers
+(both set with
+.BR .TH ),
+and section headings
+.RB ( .SH )
+are set with no further indentation.
+.
+Subsection headings
+.RB ( .SS )
+are indented by the amount in the
+.B SN
+register.
+.
+.
+.P
+Ordinary paragraphs not within an
+.BR .RS / .RE
+inset region are indented by the amount stored in the
+.B BP
+register;
+see section \[lq]Options\[rq] below.
+.
The
-.I indentation
-argument accepted by
+.B IN
+register configures the default indentation amount used by
+.B .RS
+(as the
+.IR inset-amount ),
.BR .IP ,
.BR .TP ,
and the deprecated
-.B .HP
-is a number plus an optional scaling unit,
-as is
-.BR .RS 's
-.IR inset-amount .
+.BR .HP ;
+an overriding argument
+is a number plus an optional scaling unit.
.
If no scaling unit is given,
the
@@ -1952,52 +1992,16 @@ or
.B .P
or its synonyms is called;
these clear the indentation entirely.
-.
-.
-.P
-The left margin used by ordinary paragraphs set with
-.B .P
-(and its synonyms)
-not within an
-.BR .RS / .RE
-relative inset
-.\" TODO: future: BP or BI register ("base paragraph indentation")
-is 7.2n for typesetting devices
-and 7n for terminal devices
-(but see the
-.B \-rIN
-option).
-.
-Headers,
-footers
-(both set with
-.BR .TH ),
-and section headings
-.RB ( .SH )
-are set at the page offset
-(see
-.MR groff @MAN7EXT@ )
-and subsection headings
-.RB ( .SS )
-indented from it by 3n
-(but see the
-.B \-rSN
-option).
-.
.\" XXX: This is not true, but they do handle it badly.
+.\"
.\" HTML output devices ignore indentation.
_ifstyle()dnl
.
.
.P
-It may be helpful to think of the left margin and indentation as related
-but distinct concepts;
-.IR groff 's
-implementation of the
-.I man
-macro package tracks them separately.
+The inset amount and indentation are related but distinct concepts.
.
-The left margin is manipulated by
+The former is manipulated by
.B .RS
and
.B .RE
@@ -2037,14 +2041,15 @@ paragraph is not in a relative inset nor does it
possess an indentation.
.
.RS
.P
-Now we have created a relative inset
-(in other words,
-moved the left margin)
-with
+Now we have created a relative inset with
.B .RS
and started another ordinary paragraph with
.BR .P .
.
+If the paragraph is lengthy,
+we can tell that every line of it is inset;
+contrast with a first-line indentation.
+.
.
.TP
.B tag
@@ -2068,23 +2073,23 @@ because
re-uses the previous paragraph's indentation unless given an argument
to change it.
.
-This paragraph is affected both by the moved left margin
+Both the inset amount
.RB ( .RS )
and indentation
-.RB ( .IP ).
+.RB ( .IP )
+affect this paragraph.
.
.TS
box;
l.
This table is affected both by
-the left margin and indentation.
+the inset amount and indentation.
.TE
.
.
.IP \(bu
This indented paragraph has a bullet for a tag,
-making it more obvious that the left margin and indentation are
-distinct;
+contrasting the inset amount and the indentation;
only the former affects the tag,
but both affect the text of the paragraph.
.
@@ -2095,13 +2100,13 @@ but both affect the text of the paragraph.
This ordinary
.RB ( .P )
paragraph resets the indentation,
-but the left margin is still inset.
+but the inset amount is unchanged.
.
.TS
box;
l.
This table is affected only
-by the left margin.
+by the inset amount.
.TE
.RE
.
@@ -2114,7 +2119,7 @@ which
(because we used only one
.BR .RS / .RE
pair)
-has reset the left margin to the default.
+has restored the inset amount to its initial value.
.
This is an ordinary
.B .P
@@ -2129,13 +2134,13 @@ tab characters or the indentation arguments to
.BR .RS ,
or the deprecated
.BR .HP ;
-the result may not render comprehensibly on an output device you fail to
+the result may not be comprehensible on an output device you fail to
check,
or which is developed in the future.
.
-The table preprocessor
+Consider the table preprocessor
.MR @g@tbl @MAN1EXT@
-can likely meet your needs.
+instead.
_endif()dnl
.
.
@@ -2151,15 +2156,15 @@ and the deprecated
.BR .HP .
.
The default inter-section and inter-paragraph spacing is
-is 1v for terminal devices
+is 1v for terminals
_ifstyle()dnl
-and 0.4v for typesetting devices
+and 0.4v for typesetters
(\(lqv\(rq is a unit of vertical distance,
where 1v is the distance between adjacent text baselines in a
single-spaced document).
_endif()dnl
_ifnotstyle()dnl
-and 0.4v for typesetting devices.
+and 0.4v for typesetters devices.
_endif()dnl
.
(The deprecated macro
@@ -2249,8 +2254,8 @@ None of the above is necessary in a contemporary man page.
.
.B \e*S
is superfluous,
-since type size changes are invisible on terminal devices and macros
-that change it restore its original value afterward.
+since type size changes are invisible on terminals and macros that
+change it restore its original value afterward.
.
Better alternatives exist for the rest;
simply use the
@@ -2532,7 +2537,7 @@ a non-breaking space.
.
Used primarily in ellipses
(\(lq.\e|.\e|.\(rq)\&
-to space the dots more pleasantly on typesetting devices like
+to space the dots more pleasantly on typesetters like
.BR dvi ,
.BR pdf ,
and
@@ -3113,7 +3118,7 @@ to express are likely to be lost.
Set
.I text
in bold and
-(on typesetting devices)
+(on typesetters)
one point smaller than the default type size.
.
If no argument is given,
@@ -3297,7 +3302,7 @@ and
.
.\" Per Doug McIlroy in
.\" <https://lists.gnu.org/archive/html/groff/2019-07/msg00038.html>...
-Ninth Edition Research Unix (1986) introduced
+Research Ninth Edition Unix (1986) introduced
.B .EX
and
.BR .EE .
@@ -3406,7 +3411,7 @@ This is the default for terminal and HTML devices.
.
Use
.B \-rcR=0
-to disable it on terminal devices;
+to disable it on terminals;
on HTML devices,
it cannot be disabled.
.
@@ -3507,21 +3512,17 @@ Set the default indentation amount used by
and the deprecated
.BR .HP .
.
-See subsection \(lqHorizontal and vertical spacing\(rq above for the
-default.
+The default is 7n on terminals and 7.2n on typesetters.
.
-For
-terminal devices,
-.I standard-indentation
-should always be an integer multiple of unit \(lqn\(rq to get consistent
+Use only integer multiples of unit \(lqn\(rq on terminals for consistent
indentation.
.
.
.TP
.BI \-rLL= line-length
Set line length;
-the default is 78n for terminal devices
-and 6.5i for typesetting devices.
+the default is 78n on terminals
+and 6.5i on typesetters.
.
.
.TP
@@ -3574,8 +3575,8 @@ The default is\~1.
.TP
.BI \-rPO= page-offset
Set page offset;
-the default is 0 for terminal devices
-and 1i for typesetting devices.
+the default is 0 on terminals
+and 1i on typesetters.
.
.
.TP
@@ -3595,8 +3596,7 @@ See subsection \(lqFont style macros\(rq above for the
default.
Set indentation of subsection headings to
.I subsection-indentation.
.
-See subsection \(lqHorizontal and vertical spacing\(rq above for the
-default.
+The default is 3n.
.
.
.br
@@ -3963,24 +3963,24 @@ which can be overlooked in source and rendered forms.
.
The
.B .RS
-macro sets the left margin;
-that is,
+macro determines the
+.I "inset amount,"
the position at which an
.I ordinary
paragraph
.RB ( .P
and its synonyms)
-will be set.
+will be set,
+the value of the
+.B IN
+register determines its default amount.
.
+This register also determines
+the default indentation used by
.BR .IP ,
.BR .TP ,
and the deprecated
-.B .HP
-use the same default indentation.
-.
-If not given an argument,
-.B .RS
-moves the left margin by this same amount.
+.BR .HP .
.
To create an inset relative to an indented paragraph,
call
@@ -4017,15 +4017,6 @@ to end the indented region before starting the next
tagged paragraph
.
.TP
.RB \(bu " .RE" " doesn't move the inset back to the expected level."
-.TQ
-\(bu warning: scaling unit invalid in context
-.TQ
-\(bu warning: register \(aqan\-saved\-margin\c
-.IR n "\(aq not defined"
-.TQ
-\(bu warning: register \(aqan\-saved\-prevailing\-indent\c
-.IR n "\(aq not defined"
-.
The
.B .RS
macro takes an
@@ -4242,7 +4233,7 @@ macro. \" all 1.23 except where noted
.
.
Except for
-.BR .SB , \" Clark, as noted above
+.BR SB , \" Clark, as noted above
the extension macros were written by
Lemberg,
.MT esr@\:thyrsus\:.com
@@ -4273,6 +4264,8 @@ contributed most of the material on escape sequences.
_endif()dnl
.
.
+.br
+.ne 4v
.\" ====================================================================
.SH "See also"
.\" ====================================================================
_______________________________________________
Groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
