At 2018-11-04T02:25:37+0100, Bertrand Garrigues wrote:
> Apologies for my long silence; due to personal problems I wasn't able to
> work on groff these last months.

Hi Bertrand,

I hope things are getting better for you!

> Version 1.22.4.rc2 no longer build on my environment (Archlinux) because
> of glibc 2.28 (fixed by 1c8c0210bded9e78c2748753c17fc9d9b07b0089) so
> I've just made a 1.22.4.rc3 version.  I need to check the issue on
> 'contrib/hdtbl' pointed out by Branden before pushing an official
> release.

I'd like to propose resolving the following 4 issues before going final.

1. Resolve this compiler warning:

../src/roff/troff/input.cpp: In function ‘void macro_source()’:
../src/roff/troff/input.cpp:7716:11: warning: ‘char* strncat(char*, const 
char*, size_t)’ specified bound depends on the length of the source argument 
[-Wstringop-overflow=]
    strncat(s, fn, strlen(fn) - sizeof(MACRO_POSTFIX) + 1);
    ~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
../src/roff/troff/input.cpp:7716:25: note: length computed here
    strncat(s, fn, strlen(fn) - sizeof(MACRO_POSTFIX) + 1);
                   ~~~~~~^~~~

2. Revert the 3 changes Ingo made to hdtbl in August; unfortunately they
had bad side-effects, producing warnings and causing some documents to
not generate correctly.  (It may be better to think of
contrib/hdtbl/examples as contrib/hdtbl/test-suite.)

3. Resolve Savannah #40967.  I told Dave K. I'd work on this back on
February but I let it drop.  It is not a big patch, and only affects the
"me" macro package documentation.  Maybe we can even get a French
translation before 1.22.4 final (it's only a few words).

https://savannah.gnu.org/bugs/?40967

I'll work on this first as it requires no research.

4. Apply the final pass of my groff_man.7 overhaul.  IIRC I sent this
privately to you and Ingo a few months ago; I have tweaked it very
little sense, so I reckon I'm happy with it.  All it needs now is a
commit message and ChangeLog entry.

Please find it attached.

-- 
Regards,
Branden
diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man
index 1ce14033..12c655fc 100644
--- a/tmac/groff_man.7.man
+++ b/tmac/groff_man.7.man
@@ -53,7 +53,7 @@ groff_man \- GNU roff macro package for formatting man pages
 .\" ====================================================================
 .
 The
-.B man
+.I man
 macro package for
 .I groff
 is used to produce manual pages
@@ -81,28 +81,28 @@ Macro	Meaning	Subsection
 .T&
 lB l l.
 _
-\&.B	Boldface	Font face macros
-\&.BI	Boldface, italic alternating	Font face macros
-\&.BR	Boldface, roman alternating	Font face macros
+\&.B	Bold	Font style macros
+\&.BI	Bold, italic alternating	Font style macros
+\&.BR	Bold, roman alternating	Font style macros
 \&.EE	Example end	Document structure macros
 \&.EX	Example begin	Document structure macros
-\&.I	Italic	Font face macros
-\&.IB	Italic, boldface alternating	Font face macros
+\&.I	Italic	Font style macros
+\&.IB	Italic, bold alternating	Font style macros
 \&.IP	Indented paragraph	Paragraph macros
-\&.IR	Italic, roman alternating	Font face macros
+\&.IR	Italic, roman alternating	Font style macros
 \&.LP	(Left) paragraph	Paragraph macros
 \&.ME	Mail-to end	Hyperlink and email macros
 \&.MT	Mail-to start	Hyperlink and email macros
 \&.OP	(Command-line) option	Command synopsis macros
 \&.P	Paragraph	Paragraph macros
 \&.PP	Paragraph	Paragraph macros
-\&.RB	Roman, boldface alternating	Font face macros
+\&.RB	Roman, bold alternating	Font style macros
 \&.RE	Relative-indent end	Document structure macros
-\&.RI	Roman, italic alternating	Font face macros
+\&.RI	Roman, italic alternating	Font style macros
 \&.RS	Relative-indent start	Document structure macros
-\&.SB	Small boldface	Font face macros
+\&.SB	Small bold	Font style macros
 \&.SH	Section heading	Document structure macros
-\&.SM	Small	Font face macros
+\&.SM	Small	Font style macros
 \&.SS	Subection heading	Document structure macros
 \&.SY	Synopsis start	Command synopsis macros
 \&.TH	Title heading	Document structure macros
@@ -156,10 +156,10 @@ exceptions are noted.
 .PP
 Bear in mind that
 .I groff
-is fundamentally a programming language for typesetting.
+is fundamentally a programming system for typesetting.
 .
 Consequently,
-the verb \(lqset\(rq is frequently used below in the sense of \(lqto
+the verb \(lqto set\(rq is frequently used below in the sense \(lqto
 typeset\(rq.
 .
 .
@@ -172,15 +172,16 @@ group of macros.
 .
 .B .TH
 (title heading) identifies the document as a man page and defines
-fundamental information enabling its indexing by
-.BR mandb (8).
+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,
-facilitate quick location of relevant information by the reader and aid
-the man page writer to comprehensively discuss all essential aspects of
-the topic.
+facilitate quick location of relevant material by the reader and aid
+the man page writer to discuss all essential aspects of the topic.
 .
 Subsections
 .RB ( .SS )
@@ -205,154 +206,227 @@ macros.
 .
 .
 .TP
-.BI .TH " title section \fR[\fPextra1\fR]\fP \fR[\fPextra2\fR]\fP \fR[\fPextra3\fR]"
-Set the title of the man page to
+.BI .TH " title section"\c
+.RI " [" footer-middle ]\c
+.RI " [" footer-outside ]\c
+.RI " [" header-middle ]
+Define the title of the man page as
 .I title
-and the section to
-.IR section ,
-which must take on a value between 1 and\~8.
+and the section as
+.IR section .
 .
-The value
-.I section
-may also have a string appended, e.g.\& \[oq]pm\[cq], to indicate a
-specific subsection of the man pages.
+See
+.IR man (1)
+for details on the section numbers and suffixes applicable to your
+system.
 .
-Both
 .I title
 and
 .I section
-are positioned at the left and right in the header line (with
+are positioned together at the left and right in the header line
+(with
 .I section
 in parentheses immediately appended to
-.IR title .
+.IR title ).
 .
-.I extra1
-is positioned in the middle of the footer line.
+.I footer-middle
+is centered in the footer line.
 .
-.I extra2
+.I footer-outside
 is positioned at the left in the footer line (or at the left on
 even pages and at the right on odd pages if double-sided printing is
 active).
 .
-.I extra3
+.I header-middle
 is centered in the header line.
 .
+If
+.I section
+is a simple integer between 1 and\~9 (inclusive),
+or is exactly \(lq3p\(rq,
+there is no need to specify
+.IR header-middle ;
+the macro package will supply text for it.
+.
 .
 .IP
 For HTML output, headers and footers are completely suppressed.
 .
 .
 .IP
-Additionally, this macro starts a new page; the new line number is\~1
-again (except if the \[oq]\-rC1\[cq] option is given on the command
-line).
+Additionally, this macro starts a new page; the page number is reset
+to\~1
+(unless the \(lq\-rC1\(rq option is given on the command line).
+.
+This feature is intended only for formatting multiple man pages.
+.
+.
+.IP
+A man page should contain exactly one
+.B .TH
+call at or near the beginning of the file,
+prior to any other macro calls.
 .
-This feature is intended only for formatting multiple man pages;
-a single man page should contain exactly one
-.B TH
-macro at the beginning of the file.
+.
+.IP
+By convention,
+.I footer-middle
+is the most recent modification date of the man page source document,
+and
+.I footer-outside
+is the name and version or release of the project providing it.
 .
 .
 .TP
-.BI .SH " \fR[\fPtext for a heading\fR]\fP"
-Set up an unnumbered section heading sticking out to the left.
+.BR .SH " ["\c
+.IR heading-text ]
+Set
+.I heading-text
+as a section heading flush left.
 .
-Prints out all the text following
+The text following
+.B .SH
+up to the end of the line,
+or the text on the next input line if
 .B .SH
-up to the end of the line (or the text in the next input line if there
-is no argument to
-.BR .SH )
-in bold face
-(or the font specified by the string
-.BR HF ),
-one size larger than the base document size.
+is given no arguments,
+is set in bold
+(or the font specified by the string register
+.BR HF )
+slightly larger than the base font size.
 .
-Additionally, the left margin and the indentation for the following
-text is reset to the default values.
+Additionally,
+the left margin and indentation affecting subsequent text are reset to
+their default values.
 .
+Text on input lines after
+.I heading-text
+is set as a normal paragraph
+.RB ( .PP ).
 .
-.TP
-.BI .SS " \fR[\fPtext for a heading\fR]\fP"
-Set up a secondary, unnumbered section heading.
 .
-Prints out all the text following
+.IP
+The content of
+.I heading-text
+and ordering of sections has been standardized by common practice,
+as has much of the layout of material within sections.
+.
+For example,
+a section called \(lqName\(rq or \(lqNAME\(rq must exist,
+must be the first section after the
+.B .TH
+call,
+and must contain only a line of the form
+.RS \" Invisibly move left margin to current .IP indent.
+.RS \" Now indent further, visibly.
+.IR page-topic [\c
+.BR , " \&.\|.\|.\&]"
+.B \e\-\ \c
+.I summary-description
+.RE \" Move left margin back to .IP indentation.
+for a man page to be properly indexed.
+.
+See
+.IR man (7)
+for the conventions prevailing on your system.
+.RE \" Move left margin back to standard position.
+.
+.
+.TP
+.BR .SS " ["\c
+.IR subheading-text ]
+Set
+.I subheading-text
+as a subsection heading indented (by default) partway between a section
+heading and a normally-indented paragraph
+.RB ( .PP ).
+.
+The text following
+.B .SS
+up to the end of the line,
+or the text on the next input line if
 .B .SS
-up to the end of the line (or the text in the next input line if there
-is no argument to
-.BR .SS )
-in bold face
-(or the font specified by the string
-.BR HF ),
-at the same size as the base document size.
+is given no arguments,
+is set in bold
+(or the font specified by the string register
+.BR HF )
+at the base font size.
+.
+Additionally,
+the left margin and indentation affecting subsequent text are reset to
+their default values.
 .
-Additionally, the left margin and the indentation for the following
-text is reset to the default values.
+Text on input lines after
+.I subheading-text
+is set as a normal paragraph
+.RB ( .PP ).
 .
 .
 .TP
 .B .EX
 .TQ
 .B .EE
-Example/End Example.
+Begin and end example.
 .
 After
 .BR .EX ,
-filling is disabled and the font is set to constant-width.
+filling and hyphenation are disabled and a constant-width (monospaced)
+font is selected.
 .
-This is useful for formatting code, command, and configuration-file
-examples.
+Calling
+.B .EE
+enables filling and restores the previous hyphenation setting and font.
 .
-The
-.B EE
-macro restores filling and restores the previous font.
+.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.IP
+Example regions are useful for formatting code,
+shell sessions,
+and text file contents.
 .
 .
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
 .IP
 These macros are defined on many (but not all) legacy Unix systems
-running classic troff.
+running classic
+.IR troff .
 .
 To be certain your page will be portable to those systems, copy
 their definitions from the
 .I \%an\-ext.tmac
 file of a
-.BR groff
+.I groff
 installation.
 .
 .
 .TP
-.BI .RS " \fR[\fPnnn\fR]\fP"
-This macro moves the left margin to the right by the value
-.I nnn
-if specified (default unit is \[oq]n\[cq]); otherwise it is set to the
-previous indentation value specified with
-.BR .TP ,
-.BR .IP ,
-or
-.B .HP
-(or to the default value if none of them have been used yet).
-.
-The indentation value is then set to the default.
+.BR .RS " ["\c
+.IR indent ]
+Move the left margin to the right by the value
+.IR indent ,
+if specified,
+and by a default amount otherwise;
+see subsection \(lqHorizontal and vertical spacing\(rq,
+below.
 .
+Calls to
+.B .RS
+can be nested;
+each call increments by\~1 the indentation level used by
+.BR .RE .
 .
-.IP
-Calls to the
-.B RS
-macro can be nested.
+The indentation level prior to any
+.B .RS
+calls is\~1.
 .
 .
 .TP
-.BI .RE " \fR[\fPnnn\fR]\fP"
-This macro moves the left margin back to level
-.IR nnn ,
-restoring the previous left margin.
+.BR .RE " ["\c
+.IR level ]
+Move the left margin back to that corresponding to indentation level
+.IR level .
 .
-If no argument is given, it moves one level back.
-.
-The first level (i.e., no call to
-.B .RS
-yet) has number\~1, and each call to
-.B .RS
-increases the level by\~1.
+If no argument is given, move the left margin one level back.
 .
 .
 .\" ====================================================================
@@ -361,7 +435,8 @@ increases the level by\~1.
 .
 A typical paragraph
 .RB ( .PP )
-is set at the current left margin.
+is set at the current left margin,
+which by default is indented from the left margin of the output device.
 .
 In man pages and other technical literature,
 definition lists are frequently encountered;
@@ -386,52 +461,54 @@ or to present an itemized or ordered list.
 .B .PP
 .TQ
 .B .P
-These macros are mutual aliases.
+Begin a new paragraph;
+these macros are synonymous.
 .
-Any of them causes a line break at the current position, followed by a
-vertical space downwards by the amount specified by the
+They break the output line at the current position,
+followed by a vertical space downward by a default amount
+(which can be changed by the deprecated
 .B PD
-macro.
+macro).
 .
-The font size and shape are reset to the default value (normally 10pt
-Roman).
+The font size and style are reset to defaults;
+see subsection \(lqFont style macros\(rq,
+below.
 .
-Finally, the current left margin and the indentation is reset to the
-default values.
+Finally, the left margin and indentation are reset to default values.
 .
 .
 .TP
-.BI .TP " \fR[\fPnnn\fR]\fP"
-Set up an indented paragraph with label.
+.BR .TP " ["\c
+.IR indent ]
+Set a tagged, indented paragraph.
 .
-The indentation is set to
-.I nnn
-if that argument is supplied (the default unit is \[oq]n\[cq] if omitted),
-otherwise it is set to the previous indentation value specified with
-.BR .TP ,
-.BR .IP ,
-or
-.B .HP
-(or to the default value if none of them have been used yet).
+The input line following this macro,
+known as the
+.IR tag ,
+is printed at the current left margin.
 .
+Subsequent text is indented by
+.IR indent ,
+if specified,
+and by a default amount otherwise;
+see subsection \(lqHorizontal and vertical spacing\(rq,
+below.
 .
-.IP
-The first input line of text following this macro is interpreted as a
-string to be printed flush-left, as it is appropriate for a label.
-.
-It is not interpreted as part of a paragraph, so there is no attempt
-to fill the first line with text from the following input lines.
 .
-Nevertheless, if the label is not as wide as the indentation the
-paragraph starts at the same line (but indented), continuing on the
-following lines.
+.IP
+If the tag is not as wide as the indentation,
+the paragraph starts on the same line as the tag,
+at the applicable indentation,
+and continues on the following lines.
 .
-If the label is wider than the indentation the descriptive part of the
-paragraph begins on the line following the label, entirely indented.
+Otherwise,
+the descriptive part of the paragraph begins on the line following the
+tag,
+entirely indented.
 .
-Note that neither font shape nor font size of the label is set to a
-default value; on the other hand, the rest of the text has default
-font settings.
+The line containing the tag can include a macro call,
+for instance to set the tag in bold with
+.BR .B .
 .
 .
 .IP
@@ -445,161 +522,193 @@ the subsequent ones.
 .
 .TP
 .B .TQ
-The
-.B TQ
-macro sets up header continuation for a
-.B TP
-macro.
+Set an additional tag for a paragraph tagged with
+.BR .TP .
 .
-With it, you can stack up any number of labels (such as in a
-glossary, or list of commands) before beginning the indented
-paragraph.
+The pending output line is broken.
 .
-For an example, look up the documentation of the
-.BR LP ,
-.BR PP ,
-and
-.BR P
-macros.
+The tag on the input line following this macro and subsequent lines are
+handled as with
+.BR .TP .
 .
 .
 .IP
 This macro is not defined on legacy Unix systems running classic
-troff.
+.IR troff .
 .
 To be certain your page will be portable to those systems,
 copy its definition from the
 .I \%an\-ext.tmac
 file of a
-.BR groff
+.I groff
 installation.
 .
 .
+.IP
+The descriptions of
+.BR .LP ,
+.BR .PP ,
+and
+.BR .P
+above were written using
+.B .TP
+and
+.BR .TQ .
+.
+.
 .TP
-.BI .IP " \fR[\fPdesignator\fR]\fP \fR[\fPnnn\fR]\fP"
-Set up an indented paragraph, using
-.I designator
-as a tag to mark its beginning.
+.BR .IP " ["\c
+.IR tag "] "\c
+.RI [ indent ]
+Set an indented paragraph with an optional tag.
 .
-The indentation is set to
-.I nnn
-if that argument is supplied (the default unit is \[oq]n\[cq] if
-omitted), otherwise it is set to the previous indentation value
-specified with
+The
+.I tag
+and
+.I indent
+arguments,
+if present,
+are handled as with
 .BR .TP ,
-.BR .IP ,
-or
-.B .HP
-(or to the default value if none of them have been used yet).
-.
-Font size and face of the paragraph (but not the designator) are reset
-to its default values.
+with the exception that the
+.I tag
+argument to
+.B .IP
+cannot include a macro call.
 .
 .
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
 .IP
-To start an indented paragraph with a particular indentation but
-without a designator, use \[oq]""\[cq] (two doublequotes) as the
-first argument.
-.
+Two convenient use cases for
+.B .IP
+are
 .
-.IP
-For example, the following paragraphs were all set up with bullets as
-the designator, using \[oq].IP\ \e(bu\ 4\[cq].
 .
-The whole block has been enclosed with
-.B .RS
+.RS \" Invisibly move left margin to current .IP indent.
+.RS \" Now indent further, visibly.
+.IP (1) 4n
+to start a new paragraph with the same indentation as the previous
+.B .IP
+or
+.B .TP
+paragraph,
+if no
+.I indent
+argument is given;
 and
-.B .RE
-to set the left margin temporarily to the current indentation value.
 .
 .
-.RS
-.IP \(bu 4
-.B IP
-is one of the three macros used in the
-.B man
-package to format lists.
+.IP (2)
+to set a paragraph with a short
+.I tag
+that is not semantically important,
+such as a bullet (\(bu)\(emobtained with the \(oq\e(bu\(cq character
+escape\(emor list enumerator,
+as seen in this very paragraph.
+.RE \" Move left margin back to .IP indentation.
+.RE \" Move left margin back to standard position.
 .
 .
-.IP \(bu 4
-.B HP
-is another.
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" ====================================================================
+.SS "Command synopsis macros"
+.\" ====================================================================
 .
-This macro produces a paragraph with a left hanging indentation.
+Command synopses are a staple of section\~1 and\~8 man pages.
 .
+These macros aid you to construct one that has the classical Unix
+appearance.
 .
-.IP \(bu 4
-.B TP
-is another.
+Furthermore,
+some tools are able to interpret these macros semantically and treat
+them appropriately for localization and/or presentation.
 .
-This macro produces an unindented label followed by an indented
-paragraph.
-.RE
+A command synopsis is wrapped in
+.BR .SY / .YS
+calls,
+with command-line options of some formats indicated by
+.BR .OP .
 .
 .
-.\" ====================================================================
-.SS "Command synopsis macros"
-.\" ====================================================================
-.
-The following macros are not defined on legacy Unix systems
-running classic troff.
+.PP
+These macros are not defined on legacy Unix systems running classic
+.IR troff .
 .
-To be certain your page will be portable to those systems, copy their
-definitions from the
+To be certain your page will be portable to those systems, copy
+their definitions from the
 .I \%an\-ext.tmac
 file of a
-.BR groff
+.I groff
 installation.
 .
 .
-.PP
-These macros are a convenience for authors.
-.
-Together, they produce the traditional look of a Unix command synopsis.
-.
-They also assist automated translation tools and help browsers in
-recognizing command synopses and treating them differently from
-running text.
-.
-.
 .TP
 .BI .SY " command"
 Begin synopsis.
 .
-Takes a single argument, the name of a command.
+Hyphenation is turned off.
 .
-Text following, until closed by
-.BR .YS ,
-is set with a hanging indentation of the width of
+The
 .I command
-plus a space.
+argument is set in bold.
 .
-Hyphenation is turned off.
+The output line is filled as normal,
+but if a break is required,
+subsequent output lines are indented by the width of
+.I command
+plus a space.
 .
 .
 .TP
 .BI .OP " option-name"\/\c
 .RI " [" option-argument ]
 Indicate an optional command parameter called
-.IR option-name .
+.IR option-name ,
+which is set in bold.
 .
 If the option takes an argument, specify
 .I option-argument
 using a noun, abbreviation, or hyphenated noun phrase.
 .
+If present,
+.I option-argument
+is preceded by a space and set in italics.
+.
+Square brackets (in roman) surround both arguments.
+.
 .
 .TP
 .B .YS
 End synopsis.
 .
-Restores indentation and hyphenation to previous values.
+Restore indentation and hyphenation to previous values.
+.
+.
+.PP
+Multiple
+.B .SY/.YS
+blocks can be specified,
+for instance to distinguish differing modes of operation of a complex
+command like
+.IR tar (1);
+each will be separated by a paragraph space.
+.
+.
+.PP
+.B .SY
+can also be repeated multiple times before a closing
+.BR .YS ,
+which is useful to indicate synonymous ways of invoking a particular
+mode of operation.
 .
 .
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
 .PP
 For example,
 .
 .
 .IP
+.\" from src/roff/groff/groff.1.man
 .EX
 \&.SY groff
 \&.OP \e\-abcegiklpstzCEGNRSUVXZ
@@ -621,6 +730,16 @@ For example,
 \&.RI [ file
 \e&.\e|.\e|.\e&]
 \&.YS
+\&.
+\&.SY groff
+\&.B \e\-h
+\&.SY groff
+\&.B \e\-\e\-help
+\&.YS
+.
+.
+.IP
+
 .EE
 .
 .
@@ -650,35 +769,40 @@ produces the following output.
 .RI [ file
 \&.\|.\|.\&]
 .YS
+.
+.SY groff
+.B \-h
+.SY groff
+.B \-\-help
+.YS
 .RE
 .
 .
 .PP
-Multiple
-.B .SY/.YS
-blocks can be specified,
-for instance to distinguish differing modes of operation of a complex
-command like
-.BR tar (1);
-each will be separated by a paragraph space.
+Several features of the above example are of note.
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" TODO: Some of the normative discussion below can go there, too.
 .
-If necessary, you can use a
-.B br
-request to insert a mandatory line break.
 .
+.IP \(bu
+The empty request (.),
+which does nothing,
+is used for vertical spacing in the input file for readability by the
+document maintainer.
 .
-.PP
-Several features of the above example are of note.
+Do not put empty lines in a
+.I roff
+source document.
 .
 .
 .IP \(bu
 The command and option names are presented in
-.B boldface
+.B bold
 to cue the user that they should be input literally.
 .
 .
 .IP \(bu
-Option dashes are specified with the \(lq\e\-\(rq escape sequence;
+Option dashes are specified with the \(oq\e\-\(cq escape sequence;
 this is an important practice to make them clearly visible and to
 facilitate cut-and-paste from the rendered man page to a shell prompt or
 text file.
@@ -693,7 +817,7 @@ to cue the user that they must be replaced with appropriate text.
 .
 .IP \(bu
 Symbols that are neither to be typed literally nor simply replaced
-appear in plain (roman) style;
+appear in the roman style;
 brackets surround optional arguments,
 and an ellipsis indicates that the previous syntactical element may be
 repeated arbitrarily.
@@ -702,7 +826,7 @@ repeated arbitrarily.
 .IP
 Some man pages use a brace-and-pipe notation such as
 .RB \(lq{ \-\-diff | \-\-compare }\(rq
-to indicate that one and only one of the \(lq|\(rq-separated items
+to indicate that one and only one of the \(oq|\(cq-separated items
 within the braces must be input.
 .
 If this braced construct is furthermore surrounded by square brackets,
@@ -711,229 +835,511 @@ it means that at most one of the items is accepted.
 .
 .IP
 Authors of man pages should note the use of the zero-width space
-escape sequence \(lq\e&\(rq on both sides of the ellipsis;
+escape sequence \(oq\e&\(cq on both sides of the ellipsis;
 this is a good practice to avoid surprises in the event the ellipsis
-gets reflowed in your text editor.
+gets refilled in your text editor.
 .
 See \(lqPortability\(rq, below.
 .
 The morbidly curious may consult
-.BR groff (7)
-regarding the narrow-space escape sequence \(lq\e|\(rq.
+.IR groff (7)
+regarding the narrow-space escape sequence \(oq\e|\(cq.
 .
 .
 .\" ====================================================================
 .SS "Hyperlink and email macros"
 .\" ====================================================================
 .
-The following macros are not defined on legacy Unix systems
-running classic troff.
+Email addresses are bracketed with
+.BR .MT / .ME
+and URL hyperlinks with
+.BR .UR / .UE .
+.
+.
+.PP
+These macros are not defined on legacy Unix systems running classic
+.IR troff .
 .
 To be certain your page will be portable to those systems, copy
 their definitions from the
 .I \%an\-ext.tmac
 file of a
-.B groff
+.I groff
 installation.
 .
 .
-.PP
-Using these macros helps ensure that you get hyperlinks when your
-manual page is rendered in a browser or other program that is
-Web-enabled.
-.
-.
 .TP
 .BI .MT " address"
 .TQ
-.BI .ME " \fR[\fPpunctuation\fR]\fP"
-Wrap an email address.
-.
-The argument of
-.B .MT
-is the address; text following, until
-.BR .ME ,
-is a name to be associated with the address.
+.BR .ME " ["\c
+.IR punctuation ]
+Identify
+.I address
+as an RFC 6068
+.I addr-spec
+for a \(lqmailto:\(rq URI with the text between the two macro
+calls as the link text.
+.
+A
+.I punctuation
+argument to
+.B .ME
+is placed at the end of the link text without intervening space.
 .
-Any argument to the
-.B ME
-macro is pasted to the end of the link text.
+Note that
+.I address
+may not be visible in the output text,
+particularly if the man page is being viewed as HTML.
 .
 On a device that is not a browser,
+.I address
+is set in angle brackets after the link text and before
+.IR punctuation .
 .
 .
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.IP
+When rendered by
+.I groff
+to a TTY or PostScript output device,
 .RS
 .IP
 .EX
-contact
+Contact
 \&.MT fred.foonly@\e:fubar.net
 Fred Foonly
 \&.ME
-for more information
+for more information.
 .EE
 .RE
 .
 .
 .IP
-usually displays like this: \[lq]contact Fred Foonly
-<fred.foonly@\:fubar.net> for more information\[rq].
+displays as: \(lqContact Fred Foonly
+\(lafred.foonly@\:fubar.net\(ra for more information.\(rq.
 .
 .
 .IP
-The use of
-.B \e:
-to insert hyphenless breakpoints is a groff extension and can
-be omitted.
+The use of \(oq\e:\(cq to insert hyphenless discretionary breaks is a
+.I groff
+extension and can be omitted.
 .
 .
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
 .TP
 .BI .UR " URL"
 .TQ
-.BI .UE " \fR[\fPpunctuation\fR]\fP"
-Wrap a World Wide Web hyperlink.
-.
-The argument to
-.B .UR
-is the URL; thereafter, lines until
+.BR .UE " ["\c
+.IR punctuation ]
+Identify
+.I URL
+as an RFC 3986 URI hyperlink with the text between the two macro calls
+as the link text.
+.
+A
+.I punctuation
+argument to
 .B .UE
-are collected and used as the link text.
+is placed at the end of the link text without intervening space.
 .
-Any argument to the
-.B UE
-macro is pasted to the end of the text.
+Note that
+.I URL
+may not be visible in the output text,
+particularly if the man page is being viewed as HTML.
 .
 On a device that is not a browser,
+.I URL
+is set in angle brackets after the link text and before
+.IR punctuation .
 .
 .
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.IP
+When rendered by
+.I groff
+to a TTY or PostScript output device,
 .RS
 .IP
 .EX
-this is a link to
-\&.UR http://\e:randomsite.org/\e:fubar
-some random site
-\&.UE ,
-given as an example
+The GNU Project of the Free Software Foundation hosts the
+\&.UR https://\e:www.gnu.org/\e:software/\e:groff/
+Groff home page
+\&.UE .
 .EE
 .RE
 .
 .
 .IP
-usually displays like this: \[lq]this is a link to some random
-site \[la]http://\:randomsite.org/\:fubar\[ra], given as an
-example\[rq].
+displays as: \(lqThe GNU Project of the Free Software Foundation hosts
+the Groff home page
+\(lahttps://\:www.gnu.org/\:software/\:groff/\(ra.\(rq.
 .
 .
 .IP
-The use of
-.B \e:
-to insert hyphenless breakpoints is a groff extension and can be
-omitted.
+The use of \(oq\e:\(cq to insert hyphenless discretionary breaks is a
+.I groff
+extension and can be omitted.
 .
 .
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
 .\" ====================================================================
-.SS "Font face macros"
+.SS "Font style macros"
 .\" ====================================================================
 .
+The
+.I man
+macro package is limited in its font styling options,
+offering only
+.BR bold \~( .B ),
+.I italic\c
+.RB \~( .I ),
+and roman (the default).
+.
+Italic text is usually set underscored instead on terminals and other
+classical
+.IR nroff -style
+output devices.
+.
+The
+.B .SM
+and
+.B .SB
+macros set text in roman or bold, respectively, at a smaller point size;
+these differ visually from regular-sized roman or bold text only on
+.IR troff -style
+output devices.
+.
+The foregoing macros cause word breaks before and after their arguments,
+but it is often necessary to set text in different styles without
+intervening whitespace.
+.
+The macros
+.BR .BI ,
+.BR .BR ,
+.BR .IB ,
+.BR .IR ,
+.BR .RB ,
+and
+.BR .RI ,
+where \(oqB\(cq, \(oqI\(cq, and \(oqR\(cq indicate bold, italic, and
+roman, respectively,
+set their odd- and even-numbered arguments in alternating styles,
+with no whitespace separating them.
+.
+.
+.PP
+Because font styles are presentational rather than semantic,
+conflicting traditions have arisen regarding which font styles should be
+used to mark file or path names,
+environment variables,
+in-line literals,
+and even man page cross-references.
+.
+.
+.PP
 The default font size and family (for
 .I troff
 output devices)
 is 10-point Times.
 .
-The default face is roman.
+The default style is roman.
 .
 .
 .TP
-.BI .B " \fR[\fPtext\fR]\fP"
-Causes
+.BR .B \~[\c
+.IR text ]
+Set
 .I text
-to appear in bold face.
+in bold.
+.
+If the macro is given no arguments,
+the text of the next input line is set in bold.
+.
+.
+.\" BEGIN USAGE (TODO: move to tutorial/style guide when we have it)
+.IP
+Use bold
+for literal portions of syntax synopses,
+for command-line options in running text,
+and for literals that are major topics of the subject under discussion;
+for example,
+this page uses bold for macro and register names.
+.
+In
+.BR .EX / .EE
+examples of interactive I/O (such as a shell session),
+set only the user-typed input in bold.
 .
-If no text is present on the line where the macro is called the text
-of the next input line appears in bold face.
 .
 .
+.\" END USAGE (TODO: move to tutorial/style guide when we have it)
 .TP
-.BI .I " \fR[\fPtext\fR]\fP"
-Causes
+.BR .I \~[\c
+.IR text ]
+Set
 .I text
-to appear in italic.
+in italics.
 .
-If no text is present on the line where the macro is called the text
-of the next input line appears in italic.
+If the macro is given no arguments,
+the text of the next input line is set in italics.
 .
 .
-.TP
-.BI .SM " \fR[\fPtext\fR]\fP"
-Causes the text on the same line or the text on the next input line to
-appear in a font that is one point size smaller than the default font.
+.\" BEGIN USAGE (TODO: move to tutorial/style guide when we have it)
+.IP
+Use italics
+for file and path names,
+for environment variables,
+for enumeration or preprocessor constants in C,
+for variable (user-determined) portions of syntax synopses,
+for the first occurrence only of a technical concept being introduced,
+for names of works of software
+(including commands and functions,
+.\" The following is an interesting exception that seems to have arisen
+.\" organically and nearly universally.
+but excluding names of operating systems or their kernels),
+and anywhere a parameter requiring replacement by the user is
+encountered.
+.
+An exception involves file or path names with variable components;
+in such cases,
+follow the convention of mathematical typography:
+set the file or path name in italics as usual
+(see
+.B .IR
+below),
+but use roman for the variable part,
+and italics again in running roman text when referring to the variable.
+.
+.
+.\" END USAGE (TODO: move to tutorial/style guide when we have it)
+.TP
+.BR .SM \~[\c
+.IR text ]
+Set
+.I text
+one point size smaller that the default size.
 .
+If the macro is given no arguments,
+the text of the next input line is set smaller.
 .
-.TP
-.BI .SB " \fR[\fPtext\fR]\fP"
-Causes the text on the same line or the text on the next input line to
-appear in boldface font, one point size smaller than the default font.
 .
+.IP
+.IR Note :
+.IR nroff -style
+output devices,
+such as terminals,
+will render
+.I text
+at the normal font size instead.
+.
+Do not rely upon
+.B .SM
+to communicate semantic information distinct from using roman style at
+the normal size;
+it will be hidden from readers using such devices.
 .
-.TP
-.BI ".BI " text
-Causes text on the same line to appear alternately in bold face and
-italic.
 .
-The text must be on the same line as the macro call.
+.TP
+.BR .SB \~[\c
+.IR text ]
+Set
+.I text
+in bold,
+one point size smaller that the default size.
 .
-Thus
+If the macro is given no arguments,
+the text of the next input line is set smaller and in bold.
 .
 .
-.RS
 .IP
-\&.BI this "word and" that
+.IR Note :
+.IR nroff -style
+output devices,
+such as terminals,
+will render
+.I text
+in bold at the normal font size instead.
+.
+Do not rely upon
+.B .SB
+to communicate semantic information distinct from using bold style at
+the normal size;
+it will be hidden from readers using such devices.
+.
+.
+.\" BEGIN USAGE (TODO: move to tutorial/style guide when we have it)
+.PP
+Note what is
+.I not
+prescribed for setting in bold or italics above:
+elements of \(lqsynopsis language\(rq such as ellipses and brackets
+around options;
+proper names and adjectives;
+titles of anything other than works of literature or software;
+identifiers for standards documents or technical reports such as
+CSTR\~#54,
+RFC\~1918,
+Unicode\~11.0,
+or
+POSIX.1-2017;
+acronyms;
+and occurrences after the first of a technical term or piece of jargon.
+.
+Again,
+the names of operating systems and their kernels are,
+by practically universal convention,
+set in roman.
 .
 .
 .PP
-would cause \[oq]this\[cq] and \[oq]that\[cq] to appear in bold face,
-while \[oq]word and\[cq] appears in italics.
+Be frugal with the use of italics for emphasis,
+and particularly with the use of bold.
+.
+Brief runs of literal text,
+such as references to individual characters or short strings,
+are suitable objects for quotation;
+see the
+\(oq\e(lq\(cq,
+\(oq\e(rq\(cq,
+\(oq\e(oq\(cq,
+and
+\(oq\e(cq\(cq
+escapes in the subsection \(lqPortability\(rq,
+below.
+.
+.
+.\" END USAGE (TODO: move to tutorial/style guide when we have it)
+.PP
+Unlike the above font style macros,
+the font alternation macros below accept only arguments on the same
+line as the macro call.
+.
+If whitespace is required within one of the arguments,
+first consider whether the same result could be achieved with as much
+clarity by using the single-style macros on separate input lines.
+.
+When it cannot,
+double-quote an argument with one or more embedded space characters.
+.
+Setting all three different styles within one whitespace-delimited word
+presents challenges;
+it is possible with the \(oq\ec\(cq and/or \(oq\ef\(cq escapes,
+but see subsection \(lqPortability\(rq below for caveats.
+.
+.
+.TP
+.BI .BI " bold-text italic-text"\c
+\~\&.\|.\|.\&
+Set each argument in bold and italics, alternately.
+.
+.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.RS
+.IP
+.\" from src/roff/troff/troff.1.man
+.EX
+\&.BI \e\-r name = n
+.EE
 .RE
 .
 .
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
 .TP
-.BI ".BR " text
-Causes text on the same line to appear alternately in bold face and
-roman.
+.BI .BR " bold-text roman-text"\c
+\~\&.\|.\|.\&
+Set each argument in bold and roman, alternately.
 .
-The text must be on the same line as the macro call.
+.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.RS
+.IP
+.\" from tmac/groff_ms.7.man
+.EX
+Any such change becomes effective with the first use of
+\&.BR .NH ,
+\&.I after
+the new alias is defined.
+.EE
+.RE
 .
 .
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
 .TP
-.BI ".IB " text
-Causes text to appear alternately in italic and bold face.
+.BI .IB " italic-text bold-text"\c
+\~\&.\|.\|.\&
+Set each argument in italics and bold, alternately.
 .
-The text must be on the same line as the macro call.
+.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.RS
+.IP
+.\" from man/groff_tmac.5.man
+.EX
+All macro package files must be named
+\&.IB name .tmac
+to fully use the
+\&.I tmac
+mechanism.
+.EE
+.RE
 .
 .
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
 .TP
-.BI ".IR " text
-Causes text on the same line to appear alternately in italic and
-roman.
+.BI .IR " italic-text roman-text"\c
+\~\&.\|.\|.\&
+Set each argument in italics and roman, alternately.
+.
 .
-The text must be on the same line as the macro call.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.RS
+.IP
+.\" from man/groff_out.5.man
+.EX
+This is the first command of the
+\&.IR prologue .
+.EE
+.RE
 .
 .
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
 .TP
-.BI ".RB " text
-Causes text on the same line to appear alternately in roman and bold
-face.
+.BI .RB " roman-text bold-text"\c
+\~\&.\|.\|.\&
+Set each argument in roman and bold, alternately.
 .
-The text must be on the same line as the macro call.
+.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.RS
+.IP
+.\" from src/preproc/eqn/eqn.1.man
+.EX
+Also, the statement
+\&.RB \e(oq "delim on" \e(cq
+is not handled specially.
+.RE
+.EE
 .
 .
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
 .TP
-.BI ".RI " text
-Causes text on the same line to appear alternately in roman and
-italic.
+.BI .RI " roman-text italic-text"\c
+\~\&.\|.\|.\&
+Set each argument in roman and italics, alternately.
+.
 .
-The text must be on the same line as the macro call.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.RS
+.IP
+.\" from contrib/mm/groff_mm.7.man
+.EX
+\&.RI [ file
+\e&.\e|.\e|.\e&]
+.EE
+.RE
 .
 .
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
 .\" ====================================================================
 .SS "Horizontal and vertical spacing"
 .\" ====================================================================
@@ -973,7 +1379,7 @@ or (2)
 .BR .SS ,
 or
 .B .PP
-or its synonyms is made;
+or its synonyms is called;
 these clear the indent entirely.
 .
 .
@@ -999,10 +1405,10 @@ is 7.2n in
 .I troff
 mode and 7n in
 .I nroff
-mode,
-except for
-.BR grohtml ,
-which ignores indentation.
+mode.
+.
+The HTML output device is an exception;
+it ignores indentation completely.
 .
 This same indentation is used again (additively) for the defaults of
 .BR .IP ,
@@ -1032,23 +1438,29 @@ check,
 or which is developed in the future.
 .
 The table preprocessor
-.BR tbl (1)
+.IR @g@tbl (@MAN1EXT@)
 can likely meet your needs.
 .
 .
 .PP
 The following macros cause a line break with the
 insertion of vertical space:
-.BR SH ,
-.BR SS ,
-.BR TP ,
-.BR TQ ,
-.B LP
-.RB ( PP ,
-.BR P ),
-.BR IP ,
+.BR .SH ,
+.BR .SS ,
+.BR .TP ,
+.BR .TQ ,
+.B .PP
+(and its synonyms),
+.BR .IP ,
 and the deprecated
-.BR HP .
+.BR .HP .
+.
+The default inter-section and inter-paragraph spacing is 1\~line in
+.I nroff
+mode,
+and 0.4v in
+.I troff
+mode.
 .
 (The deprecated macro
 .B .PD
@@ -1056,50 +1468,64 @@ can change this vertical spacing,
 but its use is discouraged.)
 .
 The macros
-.BR RS ,
-.BR RE ,
-.BR EX ,
+.BR .RS ,
+.BR .RE ,
+.BR .EX ,
 and
-.B EE
+.B .EE
 also cause a break but no insertion of vertical space.
 .
 .
 .\" ====================================================================
+.SS "Number registers"
+.\" ====================================================================
+.
+Number registers are described in section \(lqOPTIONS\(rq, below.
+.
+.
+.\" ====================================================================
 .SS "String registers"
 .\" ====================================================================
 .
-The following strings are defined:
+The following strings are defined.
 .
 .
 .TP
 .B \e*R
-The \[oq]registered\[cq] sign.
+expands to the character escape for the \(lqregistered sign\(rq glyph,
+\(oq\e(rg\(cq,
+if available,
+and \(lq(Reg.)\(rq otherwise.
+.
 .
 .
 .TP
 .B \e*S
-Switch back to the default font size.
+expands to an escape setting the font size to the document default.
 .
 .
 .TP
-.B \e*(lq
-.TQ
-.B \e*(rq
-Left and right quote.
+.B \e*(HF
+expands to the font identifier used to print headings and subheadings.
 .
-This is equal to \[oq]\e(lq\[cq] and \[oq]\e(rq\[cq], respectively.
+The default is \(oqB\(cq.
 .
 .
 .TP
-.B \e*(HF
-The typeface used to print headings and subheadings.
-.
-The default is \[oq]B\[cq].
+.B \e*(lq
+.TQ
+.B \e*(rq
+expand to the character escapes for left and right double-quotation
+marks,
+\(oq\e(lq\(cq and \(oq\e(rq\(cq, respectively.
 .
 .
 .TP
 .B \e*(Tm
-The \[oq]trademark\[cq] sign.
+expands to the character escape for the \(lqtrade mark sign\(rq glyph,
+\(oq\e(tm\(cq,
+if available,
+and \(lq(TM)\(rq otherwise.
 .
 .
 .\" ====================================================================
@@ -1117,7 +1543,7 @@ of a man page look like this:
 .
 .PP
 .RS
-.BI \(aq\e"\  word
+.BI "\(aq\e\(dq " word
 .RE
 .
 .
@@ -1128,13 +1554,13 @@ and that a single space character follows the double quote.
 The
 .I word
 consists of one letter for each needed preprocessor:
-\[oq]e\[cq] for
-.BR @g@eqn ,
-\[oq]r\[cq] for
-.BR @g@refer ,
+\(oqe\(cq for
+.IR @g@eqn ,
+\(oqr\(cq for
+.IR @g@refer ,
 and
-\[oq]t\[cq] for
-.BR @g@tbl .
+\(oqt\(cq for
+.IR @g@tbl .
 .
 Modern implementations of the
 .I man
@@ -1162,49 +1588,51 @@ output devices are extremely limited in presentation of mathematical
 equations.
 .
 .
+.\" TODO BEGIN: move subsection to tutorial/style guide when we have it
 .\" ====================================================================
 .SS Portability
 .\" ====================================================================
 .
-Since the
-.B man
-macros consist of groups of
-.I groff
-requests, one can, in principle, supplement the functionality of the
-.B man
-macros with individual
-.I groff
-requests where necessary.
+The two major syntactical categories of
+.I roff
+languages are requests and escapes.
 .
-See the
+Since the
+.I man
+macros are implemented in terms of
 .I groff
-info pages for a complete reference of all requests.
+requests and escapes,
+one can,
+in principle,
+supplement the functionality of
+.I man
+with these lower-level elements where necessary.
 .
 .
 .PP
-Note, however, that using raw troff requests is likely to make your
-page render poorly on the class of viewers that transform it to HTML.
+Note,
+however,
+that using raw
+.I groff
+requests is likely to make your page render poorly on the class of
+viewers that transform it to HTML.
 .
-Troff requests make implicit assumptions about things like character
-and page sizes that may break in an HTML environment; also, many of
-these viewers don't interpret the full troff vocabulary, a problem
-that can lead to portions of your text being silently dropped.
+Some requests make implicit assumptions about things like character
+and page sizes that may not hold in an HTML environment;
+also,
+many of these viewers don't interpret the full
+.I groff
+vocabulary,
+a problem that can lead to portions of your text being silently dropped.
 .
 .
 .PP
-For portability to modern viewers, it is best to write your page
-entirely in the requests described on this page.
-.
-Further, it is best to completely avoid those we have described as
-\[oq]presentation-level\[cq]
-.RB ( .HP ,
-.BR .PD ,
-and
-.BR .DT )
-in \(lqDeprecated features\(rq, below.
-.
+For portability to modern viewers,
+it is best to write your page entirely with the macros described in this
+page
+(except for the ones identified as deprecated,
+which should be avoided entirely).
 .
-.PP
 The macros we have described as extensions
 .RB ( .EX / .EE ,
 .BR .SY / .OP / .YS ,
@@ -1214,43 +1642,63 @@ and
 should be used with caution, as they may not yet be built in to
 some viewer that is important to your audience.
 .
-If in doubt, copy the implementation onto your page.
+If in doubt, copy the implementation into your page\(emafter the
+.B .TH
+call and the \(lqName\(rq section,
+to accommodate timid
+.I mandb
+implementations.
 .
 .
 .PP
-In a way similar to using
-.I groff
-requests, it is possible to use the facilities documented in the
-ESCAPE SEQUENCES section of the
-.BR groff (7)
-manual page and in the
-.BR groff_char (7)
-manual page.
-.
-Regarding portability, similar caveats apply as with respect to
-.I groff
-requests.
+Similar caveats apply to escapes.
 .
 Some escape sequences are however required for correct typesetting
-even in manual pages and usually do not cause portability problems:
+even in man pages and usually do not cause portability problems:
+.
 .
 .TP
-.RB \(dq \e\  \(dq
-Unpaddable non-breaking space character.
+.B \e\(dq
+Comment.
+.
+Everything after the double-quote to the end of the input line is
+ignored.
 .
-(The double-quotes are to make the presence of the space character
-clear in this document, and are not necessary in the input file.)
+Whole-line comments are frequently placed immediately after the empty
+request \(oq.\(cq.
+.
+.
+.TP
+.BI \e newline
+Join the next input line to the current one.
+.
+Except for the update of the input line counter (used for diagnostic
+messages and related purposes),
+a series of lines ending in backslash-newline is transparent to
+.IR groff .
+.
+Use this escape to break excessively input long lines for document
+maintenance.
+.
+.
+.TP
+.B \e\(ti
+Adjustable, non-breaking space character.
+.
+Use this escape to prevent a break inside a short phrase or between a
+numerical quantity and its corresponding unit(s).
 .
-Useful for preventing breaking between a numerical quantity and its
-corresponding unit(s), for instance:
 .
 .RS
 .IP
 .EX
-There are 2.54\e\ cm in an inch, and 1,024\e\ bytes in 1\e\ kiB.
+Before starting the motor, set the output speed to\e\(ti1.
+There are 1,024\e\(tibytes in 1\e\(tikiB.
+CSTR\e\(ti#8 documents the B language.
 .EE
 .RE
 .
+.
 .TP
 .B \e&
 Zero-width space.
@@ -1262,14 +1710,16 @@ beginning of a
 .I roff
 request.
 .
+.
 .TP
 .B \e(aq
 ASCII apostrophe.
 .
-Useful for syntax elements of programming languages because some
+Use for syntax elements of programming languages because some
 output devices might replace unescaped apostrophes with right single
 quotation marks.
 .
+.
 .TP
 .B \e(oq
 Opening single quotation mark.
@@ -1278,17 +1728,20 @@ Opening single quotation mark.
 .B \e(cq
 Closing single quotation mark.
 .
+.
 .IP
 Use these for paired directional single quotes, \(oqlike this\(cq.
 .
+.
 .TP
 .B \e(dq
 ASCII double-quote.
 .
-Sometimes needed on macro lines to prevent the interpretation of the
+Sometimes needed after macro calls to prevent the interpretation of the
 ASCII quotation mark character \(oq\(dq\(cq as the beginning or end
 of a macro argument.
 .
+.
 .TP
 .B \e(lq
 Left double quotation mark.
@@ -1297,58 +1750,67 @@ Left double quotation mark.
 .B \e(rq
 Right double quotation mark.
 .
+.
 .IP
 Use these for paired directional double quotes, \(lqlike this\(rq.
 .
+.
 .TP
 .B \e(em
 Em-dash.
 .
-Used as a punctuation mark for an interruption in a sentence\(emlike
-in this one.
+Use for an interruption in a sentence\(emsuch as this one.
+.
 .
 .TP
 .B \e(en
 En-dash.
 .
-Used to separate the two ends of a range, in particular between
-numbers, for example: the digits 1\(en9.
+Use to separate the two ends of a range,
+in particular between numbers,
+for example: the digits 1\(en9.
+.
 .
 .TP
 .B \e(ga
 ASCII grave accent.
 .
-Useful for syntax elements of programming languages, for example
-shell command substitutions, because some output devices might
-replace unescaped grave accents with left single quotation marks.
+Use for syntax elements of programming languages,
+for example shell command substitutions,
+because some output devices might replace unescaped grave accents with
+left single quotation marks.
+.
 .
 .TP
 .B \e(ha
 ASCII circumflex accent.
 .
-Useful for syntax elements of programming languages because some
-output devices might replace unescaped circumflex accents with
-non-ASCII glyphs like the Unicode U+02C6 modifier letter circumflex.
+Use for syntax elements of programming languages because some output
+devices might replace unescaped circumflex accents with non-ASCII glyphs
+like the Unicode U+02C6 modifier letter circumflex.
+.
 .
 .TP
 .B \e(ti
 ASCII tilde.
 .
-Useful for syntax elements of programming languages because some
-output devices might replace unescaped tildes with non-ASCII glyphs
-like the Unicode U+02DC small tilde.
+Use for syntax elements of programming languages because some output
+devices might replace unescaped tildes with non-ASCII glyphs like the
+Unicode U+02DC small tilde.
+.
 .
 .TP
-.B \e-
+.B \e\-
 Minus sign.
 .
 Also use this to display syntax elements that require the ASCII
-hyphen-minus character, for example command-line options and C
-language operators.
+hyphen-minus character,
+for example command-line options and C language operators.
 .
 The unescaped \(oq\-\(cq input character is not appropriate for
 these cases because it may render as a hyphen on some output devices.
 .
+.
 .TP
 .B \ec
 .
@@ -1357,30 +1819,33 @@ space is inserted between the last glyph on it and the first glyph
 resulting from the next input line.
 .
 This is occasionally useful when three different fonts are needed
-in a single word, for example:
+in a single word.
+.
 .
 .RS
 .IP
+.\" contrib/pdfmark/pdfroff.1.man
 .EX
-\&.BR "dd if" =\ec
-\&.I file
+Normally, the final output file should be named
+\&.IB file .pdf\ec
+\e&.
 .EE
 .RE
 .
+.
 .IP
 Note that when using this trick with the
 .B .BI
 or
 .B .RI
 macros, you will need to manually add an italic correction escape
-.B \e/
-before the
-.B \ec
-due to way macros expand their arguments.
+\(oq\e/\(cq before the \(oq\ec\(cq due to way macros expand their
+arguments.
 .
 .
 .RS
 .IP
+.\" from contrib/mom/groff_mom.7.man
 .EX
 Files processed with
 \&.B groff \e\-mom
@@ -1392,16 +1857,15 @@ Files processed with
 .
 .
 .IP
-Alternatively, and perhaps with better portability, the
-.B \ef
-font escape sequence can be used; see below.
+Alternatively,
+and perhaps with better portability,
+the \(oq\ef\(cq font escape sequence can be used;
+see below.
 .
-Attempting to use
-.B \ec
-to include the output from more than one macro line into the next-line
-argument of a
+Using \(oq\ec\(cq to include the output from more than one input line
+into the next-line argument of a
 .B .TP
-macro will misrender with
+macro will render incorrectly with
 .I groff
 1.22.3,
 .I mandoc
@@ -1409,45 +1873,46 @@ macro will misrender with
 older versions of these programs,
 and perhaps with some other formatters.
 .
+.
 .TP
 .B \ee
-Widely used in manual pages to represent a backslash output glyph.
+Widely used in man pages to represent a backslash output glyph.
 .
 It works reliably as long as the
 .B .ec
-request is not used, which should never happen in manual pages, and
-it is slightly more portable than the more exact
-.B \e(rs
-(\[lq]reverse solidus\[rq])
-escape sequence.
+request is not used,
+which should never happen in man pages,
+and it is slightly more portable than the more exact \(oq\e(rs\(cq
+(\(lqreverse solidus\(rq) escape sequence.
+.
 .
 .TP
 .BR \efB ,\  \efI ,\  \efR ,\  \efP
 Switch to bold, italic, roman, or back to the previous font,
 respectively.
 .
-This is needed when three different fonts are required on a single
-input line, for example:
+Either these or \(oq\ec\(cq is needed when three different fonts are
+required in a single whitespace-delimited word.
+.
 .
 .RS
 .IP
+.\" second example from contrib/pdfmark/pdfroff.1.man
 .EX
-\&.TP
-\efBif\efP=\efIfile\efP
+\&.RB [ \e\-\e\-reference\e\-dictionary=\efI\e,name\e/\efP ]
+.IP
+\&.RB [ \e\-\e\-reference\e\-dictionary=\ec
+\&.IR name ]
 .EE
 .RE
 .
+.
 .IP
-It can also be used if three different fonts are needed in a
-single word.
-It may be more portable than
-.BR \ec .
+Font escapes may be more portable than \(oq\ec\(cq.
 .
-It is up to you to account for italic corrections with
-.B \e/
-and
-.BR \e, ,
-which are themselves
+As shown above,
+it is up to you to account for italic corrections with \(oq\e/\(cq and
+\(oq\e,\(cq, which are themselves
 .I groff
 extensions,
 if desired and if supported by your implementation.
@@ -1456,16 +1921,17 @@ if desired and if supported by your implementation.
 .IP
 As long as at most two fonts are needed in any one whitespace-delimited
 word,
-using font alternation macros like
+font alternation macros like
 .B .BR
-usually results in more readable source code.
+usually result in more readable source code than \(oq\ef\(cq escapes.
 .
 .
 .PP
 For maximum portability, escape sequences and special characters
-not listed above are better avoided in manual pages.
+not listed above are better avoided in man pages.
 .
 .
+.\" TODO END: move subsection to tutorial/style guide when we have it
 .\" ====================================================================
 .SS "Deprecated features"
 .\" ====================================================================
@@ -1474,19 +1940,53 @@ Use of the following is discouraged.
 .
 .
 .TP
-.BI .AT " \fR[\fPsystem \fR[\fPrelease\fR]]\fP"
-Alter the footer for use with AT&T man pages.
+.BR .AT " ["\c
+.IR system "] [" release ]
+Alter the footer for use with AT&T man pages,
+overriding any definition of the
+.I footer-outside
+argument to
+.BR .TH .
 .
 This macro exists only for compatibility; don't use it.
 .
-See the
-.I groff
-info manual for more.
+.
+.IP
+The first argument
+.I system
+can be:
+.
+.
+.RS \" Invisibly move left margin to current .IP indent.
+.RS \" Now indent further, visibly.
+.TP
+3
+7th edition
+.I (default)
+.
+.
+.TP
+4
+System III
+.
+.
+.TP
+5
+System V
+.RE \" Move left margin back to .IP indentation.
+.RE \" Move left margin back to standard position.
+.
+.
+.IP
+The optional second argument
+.I release
+specifies the release number,
+such as in \(lqSystem V Release 3\(rq.
 .
 .
 .TP
 .B .BT
-Print the footer string.
+Set the page footer.
 .
 Redefine this macro to get control of the footer.
 .
@@ -1496,7 +1996,7 @@ Redefine this macro to get control of the footer.
 Set tabs every 0.5\~inches.
 .
 Since this macro is always called during a
-.B TH
+.B .TH
 macro, it makes sense to call it only if the tab positions have been
 changed.
 .
@@ -1513,44 +2013,21 @@ to express are likely to be lost.
 .
 If you feel tempted to use it, you should probably be composing a
 table using
-.BR @g@tbl (@MAN1EXT@)
+.IR @g@tbl (@MAN1EXT@)
 markup instead.
 .
 .
 .TP
-.BI .HP " \fR[\fPnnn\fR]\fP"
-Set up a paragraph with hanging left indentation.
+.BR .HP " ["\c
+.IR indent ]
+Set up a paragraph with a hanging left indentation.
 .
-The indentation is set to
-.I nnn
-if that argument is supplied (the default unit is \[oq]n\[cq] if
-omitted), otherwise it is set to the previous indentation value
-specified with
-.BR .TP ,
-.BR .IP ,
-or
-.B .HP
-(or to the default value if none of them have been used yet).
-.
-Font size and face are reset to its default values.
-.
-The following paragraph illustrates the effect of this macro with
-hanging indentation set to\~4 (enclosed by
-.B .RS
-and
-.B .RE
-to set the left margin temporarily to the current indentation):
-.
-.
-.RS
-.HP 4
-This is a paragraph following an invocation of the
-.B HP
-macro.
-.
-As you can see, it produces a paragraph where all lines but the first
-are indented.
-.RE
+The
+.I indent
+argument,
+if present,
+is handled as with
+.BR .TP .
 .
 .
 .IP
@@ -1566,25 +2043,18 @@ indentation may be lost.
 .
 .
 .TP
-.BI .PD " \fR[\fPnnn\fR]\fP"
-Adjust the empty space before a new paragraph or section.
+.BR .PD " ["\c
+.IR vertical-space ]
+Define the vertical space between paragraphs or (sub)sections.
 .
-The optional argument gives the amount of space (default unit is
-\[oq]v\[cq]); without parameter, the value is reset to its default
-value (1\~line in nroff mode, 0.4v\~otherwise).
+The optional argument
+.I vertical-space
+specifies the amount of space;
+the default scaling is \(oqv\(cq).
 .
-This affects the macros
-.BR SH ,
-.BR SS ,
-.BR TP ,
-.B LP
-(resp.\&
-.B PP
-and
-.BR P ),
-.BR IP ,
-and
-.BR HP .
+Without an argument,
+the spacing is reset to its default value;
+see \(lqHorizontal and vertical spacing\(rq above.
 .
 .
 .IP
@@ -1600,61 +2070,135 @@ to express are likely to be lost.
 .
 .TP
 .B .PT
-Print the header string.
+Set the page header.
 .
 Redefine this macro to get control of the header.
 .
 .
 .TP
-.BI .UC " \fR[\fPversion\fR]\fP"
-Alter the footer for use with BSD man pages.
+.BR .UC " ["\c
+.IR version ]
+Alter the footer for use with BSD man pages,
+overriding any definition of the
+.I footer-outside
+argument to
+.BR .TH .
 .
 This macro exists only for compatibility; don't use it.
 .
-See the
-.I groff
-info manual for more.
+.
+.IP
+The argument
+.I version
+can be:
 .
 .
+.RS \" Invisibly move left margin to current .IP indent.
+.RS \" Now indent further, visibly.
+.TP
+3
+3rd Berkeley Distribution
+.I (default)
+.
+.
+.TP
+4
+4th Berkeley Distribution
+.
+.
+.TP
+5
+4.2 Berkeley Distribution
+.
+.
+.TP
+6
+4.3 Berkeley Distribution
+.
+.
+.TP
+7
+4.4 Berkeley Distribution
+.RE \" Move left margin back to .IP indentation.
+.RE \" Move left margin back to standard position.
+.
+.
+.\" ====================================================================
+.SS "History"
+.\" ====================================================================
+.
+According to its own
+.IR man (7)
+page,
+Version 7 Unix (1979) supported all of the macros described in this page
+not listed as GNU extensions,
+except
+.BR .P ,
+.BR .SB ,
+.BR .SS ,
+and the deprecated
+.BR .AT ,
+.BR .BT ,
+.BR .PT ,
+and
+.BR .UC .
+.
+The only string registers defined were
+.B R
+and
+.BR S;
+no number registers were documented.
 .
 .
 .\" ====================================================================
 .SH OPTIONS
 .\" ====================================================================
 .
-The
-.B man
-macros understand the following command-line options (which define
-various registers).
+The following
+.I groff
+options set number registers recognized and used by the
+.I man
+macro package.
 .
 .
 .TP
 .B \-rcR=1
-This option (the default if in nroff mode) creates a single, very
-long page instead of multiple pages.
+Continuous rendering.
+.
+Create a single,
+very long page instead of multiple pages.
+.
+This is the default in
+.I nroff
+mode.
 .
-Say
+Use
 .B \-rcR=0
 to disable it.
 .
 .
 .TP
 .B \-rC1
-If more than one manual page is given on the command line, number the
+Number pages continuously.
+.
+If more than one man page is given on the command line, number the
 pages continuously, rather than starting each at\~1.
 .
 .
 .TP
 .B \-rD1
-Double-sided printing.
+Enable double-sided printing.
 .
 Footers for even and odd pages are formatted differently.
 .
 .
 .TP
-.BI \-rFT= dist
-Set distance of the footer relative to the bottom of the page if
-negative or relative to the top if positive.
+.BI \-rFT= footer-distance
+Set distance of the footer,
+relative to the bottom of the page if negative or relative to the top if
+positive,
+to
+.IR footer-distance .
 .
 The default is \-0.5i.
 .
@@ -1663,14 +2207,18 @@ The default is \-0.5i.
 .BI \-rHY= flags
 Set hyphenation flags.
 .
-Possible values are 1\~to not hyphenate the first and last character
-of a word, 2\~to not hyphenate the last word on a page, 4\~to not
-hyphenate the last two characters of a word, 8\~to not hyphenate the
-first two characters of a word, 16\~to enable hyphenation before the
-last character of a word, and 32 to enable hyphenation after the
-first character of a word.
+Possible values of
+.I flags
+are 1\~to not hyphenate the first and last character of a word,
+2\~to not hyphenate the last word on a page,
+4\~to not hyphenate the last two characters of a word,
+8\~to not hyphenate the first two characters of a word,
+16\~to enable hyphenation before the last character of a word,
+and
+32\~to enable hyphenation after the first character of a word.
 .
-These values are additive; the default is\~6.
+These values are additive;
+the default is\~6.
 .
 Values 4 and\~16 can't be used together since they contradict each
 other;
@@ -1678,19 +2226,18 @@ the same holds for values 8 and\~32.
 .
 .
 .TP
-.BI \-rIN= width
-Set body text indentation to
-.IR width .
+.BI \-rIN= indent
+Set the body text indentation (for normal paragraphs) to
+.IR indent .
 .
-The default is 7n for
-.IR nroff ,
-7.2n for
-.IR troff .
+See \(lqHorizontal and vertical spacing\(rq above for the default
+indentation value.
 .
 For
 .IR nroff ,
-this value should always be an integer multiple of unit \[oq]n\[cq] to
-get consistent indentation.
+.I indent
+should always be an integer multiple of unit \(oqn\(cq to get consistent
+indentation.
 .
 .
 .TP
@@ -1698,10 +2245,12 @@ get consistent indentation.
 Set line length.
 .
 If this option is not given, the line length is set to respect any
-value set by a prior \[oq].ll\[cq] request (which
+value set by a prior \(lq.ll\(rq request (which
 .I must
-be in effect when the \[oq].TH\[cq] macro is invoked),
-if this differs from the built\-in default for the formatter;
+be in effect when the
+.B .TH
+macro is invoked),
+if this differs from the built-in default for the formatter;
 otherwise it defaults to 78n in
 .I nroff
 mode and 6.5i in
@@ -1710,25 +2259,29 @@ mode.
 .
 .
 .IP
-Note that the use of a \[oq].ll\[cq] request to initialize the line
+Note that the use of a \(lq.ll\(rq request to initialize the line
 length is supported for backward compatibility with some versions of
 the
-.B man
+.I man
 program;
-direct initialization of the \[oq]LL\[cq] register should
+direct initialization of the
+.B LL
+register should
 .I always
 be preferred to the use of such a request.
 .
-In particular, note that a \[oq].ll\ 65n\[cq] request does
+In particular, note that a \(lq.ll\~65n\(rq request does
 .I not
 preserve the normal
 .I nroff
 default line length,
 (the
-.B man
-default initialization to 78n prevails), whereas, the
-\[oq]\-rLL=65n\[cq] option, or an equivalent \[oq].nr\ LL\ 65n\[cq]
-request preceding the use of the \[oq]TH\[cq] macro,
+.I man
+default initialization to 78n prevails),
+whereas the \(lq\-rLL=65n\(rq option,
+or an equivalent \(lq.nr\~LL\~65n\(rq request preceding the use of the
+.B .TH
+macro,
 .I does
 set a line length of 65n.
 .
@@ -1742,40 +2295,44 @@ length.
 .
 .
 .TP
-.BI \-rP nnn
-Enumeration of pages start with
-.I nnn
-rather than with\~1.
+.BI \-rP n
+Start enumeration of pages at
+.I n
+rather than\~1.
 .
 .
 .TP
-.BI \-rS xx
-Base document font size is
-.I xx
-points
-.RI ( xx
-can be 10, 11, or\~12) rather than 10\~points.
+.BI \-rS point-size
+Use
+.I point-size
+as the base document font size.
+.
+Acceptable values are 10, 11, or 12.
+.
+See subsection \(lqFont style macros\(rq above for the default.
 .
 .
 .TP
-.BI \-rSN= width
-Set sub-subheading indentation to
-.IR width .
-The default is 3n.
+.BI \-rSN= subsection-indent
+Set subsection indentation to
+.IR subsection-indent .
+.
+See \(lqHorizontal and vertical spacing\(rq above for the default
+indentation value.
 .
 .
 .TP
-.BI \-rX nnn
-After page\~\c
-.IR nnn ,
+.BI \-rX p
+After
+.RI page " p" ,
 number pages as
-.IR nnn a,
-.IR nnn b,
-.IR nnn c,
-etc.
+.IR p a,
+.IR p b,
+.IR p c,
+and so forth.
 .
-For example, the option \[oq]\-rX2\[cq] produces the following page
-numbers: 1, 2, 2a, 2b, 2c, etc.
+For example, the option \(lq\-rX2\(rq produces the following page
+numbers: 1, 2, 2a, 2b, 2c, and so on.
 .
 .
 .\" ====================================================================
@@ -1897,7 +2454,10 @@ and the deprecated
 .BR .HP .
 .
 If you need to start an indent relative to an indented paragraph,
-give
+call
+.B .RS
+repeatedly until an acceptable indentation is achieved,
+or give
 .B .RS
 an indentation argument that is at least as much as the paragraph's
 indentation amount relative to an adjacent
@@ -1959,6 +2519,7 @@ have no effect.
 .\" ====================================================================
 .SH AUTHORS
 .\" ====================================================================
+.
 The GNU version of the
 .I man
 macro package was written by James Clark and contributors.
@@ -1979,21 +2540,52 @@ This document was originally written for the Debian GNU/Linux system by
 Susan G.\& Kleinmann
 .ME .
 .
-It was corrected and updated by Werner Lemberg.
+It was corrected and updated by Werner Lemberg and G.\& Branden
+Robinson.
 .
 The extension macros were documented by Eric S.\& Raymond;
-he also originated the portability advice.
+he also originated the portability section,
+to which Ingo Schwarze contributed most of the material on escape
+sequences.
 .
 .
 .\" ====================================================================
 .SH "SEE ALSO"
 .\" ====================================================================
-.BR @g@tbl (@MAN1EXT@),
-.BR @g@eqn (@MAN1EXT@),
-.BR @g@refer (@MAN1EXT@),
-.BR man (1),
-.BR man (7),
-.BR groff_mdoc (7)
+.
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is the main
+.I groff
+documentation.
+.
+You can browse it interactively with \(lqinfo groff\(rq.
+.
+.
+.PP
+.IR @g@tbl (@MAN1EXT@),
+.IR @g@eqn (@MAN1EXT@),
+and
+.IR @g@refer (@MAN1EXT@)
+are preprocessors used with man pages.
+.
+.
+.PP
+.IR man (1)
+describes the man page formatter on your system.
+.
+.
+.PP
+.IR groff_mdoc (@MAN7EXT@)
+describes the
+.I groff
+version of the BSD-originated alternative macro package for man pages.
+.
+.
+.PP
+.IR groff (@MAN7EXT@),
+.IR groff_char (@MAN7EXT@),
+.IR man (7)
 .
 .
 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
@@ -2004,5 +2596,6 @@ he also originated the portability advice.
 .\" ### Emacs settings:
 .\" Local Variables:
 .\" mode: nroff
+.\" fill-column: 72
 .\" End:
-.\" vim: set filetype=groff:
+.\" vim: set filetype=groff textwidth=72:

Attachment: signature.asc
Description: PGP signature

Reply via email to