[groff] 02/02: groff_man(7): Correct error regarding hyphenation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit dab09420d5e40c5774d1c0cff111709f96eca968
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Jul 12 12:22:46 2020 +1000

    groff_man(7): Correct error regarding hyphenation.
    
    ...but mostly make style fixes.
    
    Add comments outlining my plans for the content to be included in the
    separate tutorial and style guide page.  Update boundaries of this
    material for easy conversion into m4 macros.  The idea is to produce
    both groff_man.7.man and groff_man_tutorial.7.man pages from the same
    source.
    
    Generally:
    * Refer to "typesetter", not "troff-style output" devices or "troff
      mode".
    * Refer to "terminal" devices instead of "terminals and other classical
      nroff‐style output" (whew!) or "nroff mode".
    * Revert to "point size" term in preference to "font size".
    * Describe strings simply as "strings", not "string registers".  The
      syntax is different and the word "register" buys us nothing.
    * Do not use quotation marks with escape sequences; they are already
      boldfaced and are also not ambiguous with English syntax (so they're
      still intelligible even if the output device doesn't support bold).
    * Use (directional) double quotes for quotations; this is an en_US
      document.
    * Eliminate references to the ASCII character encoding in favor of
      "(Unicode) Basic Latin".  Unicode has now been around longer than
      ASCII had been when Unicode was first promulgated (cf. 1964, 1991).
    * Refer to subsections as such when quoting their names in
      cross-references.
    * Stop using a comma before directional indicator on a page-internal
      "see" reference.
    * Tweak English style, either to tighten wording or be more precise.
    
    * (Description): Delete phrase "to aid learners".  I don't think
      thematic organization benefits only that group.
    * Summarize .TQ even more briefly in table; this gets the width down to
      71 characters.
    * Add (in comments) list of concepts to be covered in tutorial/style
      guide.
    
    * (Description/Macro reference preliminaries): Add paragraph describing
      macro call syntax (tutorial/style material).
    * Drop usage of jargony "whitespace" in favor of more precise language
      in explanation of when macro arguments require quotation.
    * Explain that empty macro arguments are seldom necessary.
    
    * (Description/Document structure macros/.SH): Make synopsis-style
      syntax of "Name" section content more scrupulously correct.
    * (.SS): Add forward reference for default indentation amount of
      subsection headings.  Remove redundant language about point size used.
    * (.EX, .EE): Fix error; refer to "initial hyphenation setting" instead
      of "previous hyphenation mode".  Incidentally, this fact points out
      why putting ".hy 0" or ".nh" in your man page is futile.  Refer to
      "AT&T troff" instead of "classic troff".
    
    * (Description/Paragraph macros): Note lack of first-line indent in
      ordinary paragraphs.  Refer to "leftmost position", not "left margin"
      of output device, since "left margin" is elsewhere used to refer to
      internal state in the macro package.  Describe more precisely how
      paragraph macros (except for .TQ) handle breaks and vertical space.
      Add forward reference for default indentation amount of subsection
      headings.
    * (.TQ): Note lack of support on AT&T and Plan 9 troffs (Heirloom
      Doctools has a copy of our an-ext.tmac, albeit from 2014, and neatroff
      does not supply any macro packages).
    * (.IP): Refer to *roff special characters as such.
    
    * (Description/Command synopsis macros): Delete sentence about tools
      with semantic or localization sensitivity to the man(7) language; I
      don't know of any that are actively maintained or have an impact.  The
      tutorial/style guide can easily accommodate specific references to
      these if/when they turn up.
    * Note absence of these macros from AT&T and Plan 9 troffs.
    * (.YS): Fix error; refer to "initial hyphenation setting" instead of
      "previous hyphenation mode".  Incidentally, this fact points out why
      putting ".hy 0" or ".nh" in your man page is futile.
    * (example): Eliminate paragraph regarding brace-and-pipe notation; it's
      seldom seen and redundant with existing "[foo|bar]" synopsis language.
      Do we need an operator precedence chart for synopsis language?  People
      seem to understand "[-d|-r]" analogously to "(foo|bar)" in POSIX EREs,
      so perhaps not.
    * (example): Moderate my recommendation about using \& with ellipses a
      bit in favor of more carefully explaining how it is actually useful.
      End-of-sentence recognition is one of the topics noted above to be
      covered in the tutorial/style guide.
    * (example): Drop comment about \| escape; it's now in the Portability
      section.
    
    * (Description/Hyperlink and email macros): Note absence of these macros
      from AT&T and Plan 9 troffs.
    * (.ME, .UE): Refer to "terminal", not "TTY".  Remove spurious colon.
      Refer to "GNU", not "groff" extensions.  Like GNU extensions to the C
      language and its compiler command-line interface, they've been adopted
      elsewhere.
    
    * (Description/Font style macros): Refer to what gets alternated by the
      font-related macros is the _style_, not the font in general.
    * (.B): Note that the page uses bold for string names as well.
    
    * (Description/Horizontal and vertical spacing): Tighten cross-reference
      to "Numerical Expressions" section in groff(7).  Note placement of
      headers and footers.  Add reference to -SN option when discussing .SS.
      Refer to to "horizontal tab characters" without reference to the ASCII
      character encoding.
    
    * (Description/Portability): Slightly recast material about HTML
      converters.  Explain the problem inexperienced man page authors
      frequently encounter when using the apostrophe, dash, caret, grave
      accent, and tilde.  This is also facilitates the removal of some
      repeated language in \- and special character escape descriptions.
    * (\newline): Recase to avoid the word "transparent", which is used to
      mean several different things in groff 1.22.4 documentation, rendering
      the meaning rather opaque.  (I'm slowly cleaning them up.)
    * (\|): New; document this escape.  It's portable all the way back to
      CSTR #54 1976, used in the canonical ellipsis idiom, which in turn is
      ubiquitous in our own man pages and appears in an example in this very
      page.
    * (\-): Relocate to be the first of the special character escapes
      listed, instead of the last.  Every subsequent escape is
      "alphabetical" (\(xx, \c, or \f).
    * (\dq): Slightly clarify: a bare '"' will only be misinterpreted by
      groff as the _beginning_ if a macro argument.  Supply example.
    * (\em): Use slightly more idiomatic example; a sentence interrupted
      with an em-dashed phrase or clause is typically resumed (though I have
      introduced a counterexample in \c with this commit--nobody's perfect).
    * (\c): Recast description a bit, particularly to make the lead sentence
      describe what it does instead of build up background.
    * (\f): Refer simply to "style" escapes and macros when the font context
      is clear.
    
    * (Description/Deprecated features): Clarify that deprecation is with
      respect to publicly-distributed man pages.  Deprecation does not apply
      to site-local configuration files, which is why .BT and .PT, for
      example, were written and documented in the first place.
    * (.BT, .PT): Call out the foregoing point.
    * (.DT): Say "tab stops" instead of "tabs" or "tab positions", and
      "tabulation" instead of the less formal "tabbing".
    
    * (Options/-rcR): Refer to "terminal and HTML devices" rather than
      "nroff mode".
    * (-rHY): Refer to hyphenation "mode" rather than "flags", in line with
      recent updates to hyphenation documentation.
    * (-rLT): Describe what the title length is used for (headers and
      footers).
---
 ChangeLog            |    7 +
 tmac/groff_man.7.man | 1013 ++++++++++++++++++++++++++++++++------------------
 2 files changed, 655 insertions(+), 365 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index c7a7af0..18ce4eb 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2020-07-12  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * tmac/groff_man.7.man (.EE, .YS): Fix error; refer to "initial
+       hyphenation setting" instead of "previous hyphenation mode".
+       Incidentally, this fact points out why putting ".hy 0" or ".nh"
+       in your man page is futile.
+
 2020-06-28  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * man/groff.7.man (Requests/Request short reference): Fix error
diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man
index 254e185..75ae5f8 100644
--- a/tmac/groff_man.7.man
+++ b/tmac/groff_man.7.man
@@ -64,12 +64,29 @@ like the one you are reading.
 .
 .
 .PP
-This document presents the macros thematically to aid learners;
+This document presents the macros thematically;
 for those needing only a quick reference,
 the following table lists them alphabetically,
 with cross-references to appropriate subsections below.
 .
 .
+.\" BEGIN NOT-STYLE
+.\".PP
+.\"Man page authors and maintainers who are not already experienced
+.\".I groff
+.\"users should consult
+.\".IR groff_man_tutorial (@MAN7EXT@),
+.\"an expanded version of this document,
+.\"for additional explanations and advice.
+.\".
+.\"It covers only those concepts required for man page document
+.\"maintenance,
+.\"and not the full breadth of the
+.\".I groff
+.\"typesetting system.
+.\".
+.\".
+.\" END NOT-STYLE
 .PP
 .TS
 l l l.
@@ -103,7 +120,7 @@ _
 \&.SY  Synopsis start  Command synopsis macros
 \&.TH  Title heading   Document structure macros
 \&.TP  Tagged paragraph        Paragraph macros
-\&.TQ  Tagged paragraph continuation   Paragraph macros
+\&.TQ  Supplemental paragraph tag      Paragraph macros
 \&.UE  URL end Hyperlink and email macros
 \&.UR  URL start       Hyperlink and email macros
 \&.YS  Synopsis end    Command synopsis macros
@@ -120,10 +137,51 @@ Macros whose use we discourage
 .BR .PT ,
 and
 .BR .UC )
-are described in subsection \(lqDeprecated features\(rq, below.
+are described in subsection \(lqDeprecated features\(rq below.
+.\" BEGIN STYLE
 .
 .
 .\" ====================================================================
+.\" .SS "Fundamental concepts"
+.\" ====================================================================
+.\" TODO: Write an introduction for non-typographers.  Cover the
+.\" following:
+.\"
+.\" word (delimited by spaces or newlines)
+.\" sentence (including end-of-sentence detection)
+.\" filling, hyphenation, breaking, adjustment (elsewhere:
+.\" justification)
+.\" font (family, style [elsewhere: face])
+.\" point size
+.\" typesetter (troff device, PostScript, PDF)
+.\" terminal (nroff device, emulator, typewriter, TTY)
+.\"
+.\" ====================================================================
+.\" .SS "Input file format"
+.\" ====================================================================
+.\" UTF-8 (or just ASCII) is a good input encoding.
+.\" Unix line endings
+.\" text lines vs. control lines (macro calls)
+.\" The above distinction works well with filling.
+.\" Don't fill your input text yourself; let groff do the work.
+.\" Also good for diffs.
+.\" escapes--pretty much just "see Portability"
+.\"
+.\" ====================================================================
+.\" .SS "Why have a tutorial and style guide?"
+.\" ====================================================================
+.\" the processing pipeline in brief
+.\"   preprocessors, roff itself, various output devices
+.\" Things that aren't groff--why you want the man page language to be
+.\" small (mandoc, Kerrisk's man7.org, manpages.debian.org, non-expert
+.\" humans).
+.\" possibly exihibit a horrorshow docbook-to-man example
+.\"
+.\" Concepts we assume you learned in school, not to be documented here:
+.\"   flush left
+.\"   single-spacing
+.\" END STYLE
+.\" ====================================================================
 .SS "Macro reference preliminaries"
 .\" ====================================================================
 .
@@ -137,18 +195,61 @@ and
 are grouped together.
 .
 .
+.\" BEGIN STYLE
+.PP
+A macro call begins on a line starting with a dot (\(lq.\(rq),
+followed by zero or more spaces and then the macro name.
+.
+Some macros accept arguments;
+each such argument is separated from the macro name and any subsequent
+arguments by one or more spaces.
+.
+A newline,
+unless escaped
+(see subsection \(lqPortability\(rq below),
+terminates the macro call.
+.
+.
+.\" END STYLE
 .PP
+.\" BEGIN STYLE
 Optional macro arguments are indicated by surrounding them with square
 brackets.
 .
 If a macro accepts multiple arguments,
-arguments containing whitespace must be double-quoted ("one two"),
-to be interpreted correctly.
+those containing space or horizontal tab characters must be
+double-quoted to be interpreted correctly.
+.
+.\" END STYLE
+An empty macro argument can be specified with a pair of double-quotes
+(\(lq""\(rq),
+but the
+.I man
+package is designed such that this should seldom be necessary.
+.
+Unused macro arguments are more often simply omitted,
+.\" antipattern: '.TP ""' (just '.TP' will do)
+or good style suggests that a more appropriate macro be chosen,
+.\" antipattern: '.BI "" italic bold' (use '.IB' instead)
+that earlier arguments are more important than later ones,
+.\" antipattern: '.TH foo 1 "" "foo "1.2.3"' (don't skip the date!)
+.\" antipattern: '.IP "" 4n' (use .TP or .RS/.RE, depending on needs)
+or that arguments have identical significance such that skipping any is
+superfluous.
+.\" antipattern: '.B one two "" three' (pointless)
+.\"   Technically, the above has a side-effect of additional space
+.\"   between "two" and "three", but there are much more obvious ways of
+.\"   getting it if desired.
+.\"     .B "one two  three"
+.\"     .B one "two " three
+.\"     .B one two " three"
+.\"     .B one two\~ three
 .
 Most macro arguments are strings that will be output as text;
 exceptions are noted.
 .
 .
+.\" BEGIN STYLE
 .PP
 Bear in mind that
 .I groff
@@ -159,6 +260,7 @@ the verb \(lqto set\(rq is frequently used below in the 
sense \(lqto
 typeset\(rq.
 .
 .
+.\" END STYLE
 .\" ====================================================================
 .SS "Document structure macros"
 .\" ====================================================================
@@ -194,7 +296,7 @@ and
 .BR .EE .
 .
 When none of the foregoing meets a structural demand,
-a section of the discussion can be manually indented within
+a region within a (sub)section can be manually indented within
 .B .RS
 and
 .B .RE
@@ -261,12 +363,14 @@ there is no need to specify
 .IR header-middle ;
 the macro package will supply text for it.
 .
-For HTML output, headers and footers are completely suppressed.
+For HTML output,
+headers and footers are completely suppressed.
 .
 .
 .IP
-Additionally, this macro starts a new page; the page number is reset
-to\~1
+Additionally,
+this macro starts a new page;
+the page number is reset to\~1
 (unless the
 .B \-rC1
 option is given on the command line).
@@ -279,6 +383,7 @@ A man page should contain exactly one
 .B .TH
 call at or near the beginning of the file,
 prior to any other macro calls.
+.\" BEGIN STYLE
 .
 .
 .IP
@@ -288,6 +393,7 @@ is the most recent modification date of the man page source 
document,
 and
 .I footer-inside
 is the name and version or release of the project providing it.
+.\" END STYLE
 .
 .
 .TP
@@ -304,13 +410,11 @@ or the text on the next input line if
 .B .SH
 is given no arguments,
 is set in bold
-(or the font specified by the string register
+(or the font specified by the string
 .BR HF )
 and,
-on
-.IR troff -style
-output devices,
-slightly larger than the base font size.
+on typesetter devices,
+slightly larger than the base point size.
 .
 Additionally,
 the left margin and indentation affecting subsequent text are reset to
@@ -336,14 +440,18 @@ 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
+.IR topic [\c
+.BI , " another-topic"\c
+.RB "].\|.\|.\& \e\- "\c
 .I summary-description
 .RE \" Move left margin back to .IP indentation.
 for a man page to be properly indexed.
 .
 See
+.\" BEGIN NOT-STYLE
+.\" .IR groff_man_tutorial (@MAN7EXT@)
+.\" for suggestions and
+.\" END NOT-STYLE
 .IR man (7)
 for the conventions prevailing on your system.
 .RE \" Move left margin back to standard position.
@@ -354,10 +462,13 @@ for the conventions prevailing on your system.
 .IR subheading-text ]
 Set
 .I subheading-text
-as a subsection heading indented (by default) partway between a section
-heading and a normally-indented paragraph
+as a subsection heading indented partway between a section heading and a
+normally-indented paragraph
 .RB ( .PP ).
 .
+See subsection \(lqHorizontal and vertical spacing\(rq below for the
+precise indentation amount.
+.
 The text following
 .B .SS
 up to the end of the line,
@@ -365,9 +476,8 @@ or the text on the next input line if
 .B .SS
 is given no arguments,
 is set in bold
-(or the font specified by the string register
-.BR HF )
-at the base font size.
+(or the font specified by the string
+.BR HF ).
 .
 Additionally,
 the left margin and indentation affecting subsequent text are reset to
@@ -392,17 +502,19 @@ font is selected.
 .
 Calling
 .B .EE
-enables filling and restores the previous hyphenation setting and font.
+enables filling and
+restores the previous font
+and initial hyphenation mode.
 .
 .
-.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" BEGIN STYLE
 .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)
+.\" END STYLE
 .IP
 .\" Also see subsection "History" below...
 These macros are extensions,
@@ -411,10 +523,14 @@ to the original
 .I man
 package.
 .
-Many (but not all) legacy Unix systems
-running classic
+Many systems running
+AT&T,
+Heirloom Doctools,
+or Plan 9
 .I troff
 support them.
+.\" However, Plan 9 troff's .EX/.EE don't manipulate filling or
+.\" hyphenation, so AT&T Unix's probably didn't either.
 .
 To be certain your page will be portable to systems that do not,
 copy their definitions from the
@@ -450,17 +566,22 @@ calls is\~1.
 Move the left margin back to that corresponding to indentation level
 .IR level .
 .
-If no argument is given, move the left margin one level back.
+If no argument is given,
+move the left margin one level back.
 .
 .
 .\" ====================================================================
 .SS "Paragraph macros"
 .\" ====================================================================
 .
-A typical paragraph
+An ordinary paragraph
 .RB ( .PP )
-is set at the current left margin,
-which by default is indented from the left margin of the output device.
+.\" BEGIN STYLE
+like this one
+.\" END STYLE
+is set without a first-line indent at the current left margin,
+which by default is indented from the leftmost position of the output
+device.
 .
 In man pages and other technical literature,
 definition lists are frequently encountered;
@@ -478,6 +599,26 @@ with
 .BR .TP ,
 or to present an itemized or ordered list.
 .
+All paragraph macros break the output line at the current position.
+.
+If another paragraph macro has occurred since the previous
+.B .SH
+or
+.BR .SS ,
+they
+(except for
+.BR .TQ )
+follow the break with a default amount of vertical space,
+which can be changed by the deprecated
+.B .PD
+macro;
+see subsection \(lqHorizontal and vertical spacing\(rq below.
+.
+They also reset the point size and font style to defaults
+.RB ( .TQ
+again excepted);
+see subsection \(lqFont style macros\(rq below.
+.
 .
 .TP
 .B .LP
@@ -488,22 +629,14 @@ or to present an itemized or ordered list.
 Begin a new paragraph;
 these macros are synonymous.
 .
-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).
-.
-The font size and style are reset to defaults;
-see subsection \(lqFont style macros\(rq below.
-.
-Finally, the left margin and indentation are reset to default values.
+The left margin and indentation are reset to default values.
 .
 .
 .TP
 .BR .TP " ["\c
 .IR indent ]
-Set a tagged, indented paragraph.
+Set a tagged,
+indented paragraph.
 .
 The input line following this macro,
 known as the
@@ -531,6 +664,7 @@ entirely indented.
 The line containing the tag can include a macro call,
 for instance to set the tag in bold with
 .BR .B .
+.\" BEGIN STYLE
 .
 .
 .IP
@@ -540,6 +674,7 @@ was used to write the first paragraph of this description of
 and
 .B .IP
 the subsequent ones.
+.\" END STYLE
 .
 .
 .TP
@@ -555,7 +690,7 @@ handled as with
 .
 .
 .IP
-This macro is not defined on legacy Unix systems running classic
+This macro is not defined on systems running AT&T or Plan\~9
 .IR troff .
 .
 To be certain your page will be portable to those systems,
@@ -564,6 +699,7 @@ copy its definition from the
 file of a
 .I groff
 installation.
+.\" BEGIN STYLE
 .
 .
 .IP
@@ -576,6 +712,7 @@ above were written using
 .B .TP
 and
 .BR .TQ .
+.\" END STYLE
 .
 .
 .TP
@@ -599,7 +736,7 @@ argument to
 cannot include a macro call.
 .
 .
-.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" BEGIN STYLE
 .IP
 Two convenient use cases for
 .B .IP
@@ -625,14 +762,15 @@ and
 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,
+such as a bullet (\(bu)\(emobtained with the
+.B \e(bu
+special 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.
 .
 .
-.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" END STYLE
 .\" ====================================================================
 .SS "Command synopsis macros"
 .\" ====================================================================
@@ -642,9 +780,10 @@ 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.
 .
-Furthermore,
-some tools are able to interpret these macros semantically and treat
-them appropriately for localization and/or presentation.
+.\" TODO: Determine whether this (is still? was ever?) true.
+.\" Furthermore,
+.\" some tools are able to interpret these macros semantically and treat
+.\" them appropriately for localization and/or presentation.
 .
 A command synopsis is wrapped in
 .BR .SY / .YS
@@ -654,7 +793,7 @@ with command-line options of some formats indicated by
 .
 .
 .PP
-These macros are not defined on legacy Unix systems running classic
+These macros are not defined on systems running AT&T or Plan\~9
 .IR troff .
 .
 To be certain your page will be portable to those systems,
@@ -689,22 +828,25 @@ Indicate an optional command parameter called
 .IR option-name ,
 which is set in bold.
 .
-If the option takes an argument, specify
+If the option takes an argument,
+specify
 .I option-argument
-using a noun, abbreviation, or hyphenated noun phrase.
+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.
+Square brackets in roman surround both arguments.
 .
 .
 .TP
 .B .YS
 End synopsis.
 .
-Restore indentation and hyphenation to previous values.
+Restore previous indentation amount and initial hyphenation mode.
 .
 .
 .PP
@@ -723,9 +865,9 @@ 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 STYLE
 .
 .
-.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
 .PP
 For example,
 .
@@ -802,8 +944,6 @@ produces the following output.
 .
 .PP
 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.
 .
 .
 .IP \(bu
@@ -813,7 +953,8 @@ is used for vertical spacing in the input file for 
readability by the
 document maintainer.
 .
 Do not put blank
-(i.e., empty)
+(i.e.,
+empty)
 lines in a
 .I roff
 source document.
@@ -826,7 +967,9 @@ to cue the user that they should be input literally.
 .
 .
 .IP \(bu
-Option dashes are specified with the \(oq\e\-\(cq escape sequence;
+Option dashes are specified with the
+.B \e\-
+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.
@@ -835,7 +978,7 @@ text file.
 .IP \(bu
 Option arguments and command operands are presented in
 .I italics
-(underlined on some output devices, such as terminals and emulators),
+(but see subsection \(lqFont style macros\(rq below regarding terminals)
 to cue the user that they must be replaced with appropriate text.
 .
 .
@@ -848,26 +991,16 @@ 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 \(oq|\(cq-separated items
-within the braces must be input.
-.
-If this braced construct is furthermore surrounded by square brackets,
-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 \(oq\e&\(cq on both sides of the ellipsis;
-this is a good practice to avoid surprises in the event the ellipsis
-gets refilled in your text editor.
-.
-See \(lqPortability\(rq, below.
+escape sequence
+.B \e&
+preceding the ellipsis,
+which prevents it from being misinterpreted as an invalid control line,
+and after it,
+which prevents it from being misinterpreted as the end of a sentence.
 .
-The morbidly curious may consult
-.IR groff (7)
-regarding the narrow-space escape sequence \(oq\e|\(cq.
+See subsection \(lqPortability\(rq below.
+.\" END STYLE
 .
 .
 .\" ====================================================================
@@ -881,7 +1014,7 @@ and URL hyperlinks with
 .
 .
 .PP
-These macros are not defined on legacy Unix systems running classic
+These macros are not defined on systems running AT&T or Plan\~9
 .IR troff .
 .
 To be certain your page will be portable to those systems,
@@ -921,11 +1054,11 @@ 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)
+.\" BEGIN STYLE
 .IP
 When rendered by
 .I groff
-to a TTY or PostScript output device,
+to a terminal or PostScript device,
 .RS
 .IP
 .EX
@@ -939,17 +1072,18 @@ for more information.
 .
 .
 .IP
-displays as: \(lqContact Fred Foonly
-\(lafred.foonly@\:fubar.net\(ra for more information.\(rq.
+displays as \(lqContact Fred Foonly \(lafred.foonly@\:fubar.net\(ra for
+more information.\(rq.
 .
 .
 .IP
-The use of \(oq\e:\(cq to insert hyphenless discretionary breaks is a
-.I groff
-extension and can be omitted.
+The use of
+.B \e:
+to insert hyphenless discretionary breaks is a
+GNU extension and can be omitted.
 .
 .
-.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" END STYLE
 .TP
 .BI .UR " URL"
 .TQ
@@ -977,35 +1111,37 @@ 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)
+.\" BEGIN STYLE
 .IP
 When rendered by
 .I groff
-to a TTY or PostScript output device,
+to a terminal or PostScript device,
 .RS
 .IP
 .EX
-The GNU Project of the Free Software Foundation hosts the
+The GNU Project of the Free Software Foundation
+hosts the
 \&.UR https://\e:www.gnu.org/\e:software/\e:groff/
-Groff home page
+groff home page
 \&.UE .
 .EE
 .RE
 .
 .
 .IP
-displays as: \(lqThe GNU Project of the Free Software Foundation hosts
-the Groff home page
+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 \(oq\e:\(cq to insert hyphenless discretionary breaks is a
-.I groff
-extension and can be omitted.
+The use of
+.B \e:
+to insert hyphenless discretionary breaks is a GNU extension and can be
+omitted.
 .
 .
-.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" END STYLE
 .\" ====================================================================
 .SS "Font style macros"
 .\" ====================================================================
@@ -1019,22 +1155,20 @@ offering only
 .RB \~( .I ),
 and roman.
 .
-Italic text is usually set underscored instead on terminals and other
-classical
-.IR nroff -style
-output devices.
+Italic text is usually set underscored instead on terminal devices.
 .
 The
 .B .SM
 and
 .B .SB
-macros set text in roman or bold, respectively, at a smaller point size;
+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.
+typesetter devices.
 .
 It is often necessary to set text in different styles without
-intervening whitespace.
+intervening space.
 .
 The macros
 .BR .BI ,
@@ -1044,10 +1178,15 @@ The macros
 .BR .RB ,
 and
 .BR .RI ,
-where \(oqB\(cq, \(oqI\(cq, and \(oqR\(cq indicate bold, italic, and
-roman, respectively,
+where \(lqB\(rq,
+\(lqI\(rq,
+and \(lqR\(rq indicate bold,
+italic,
+and roman,
+respectively,
 set their odd- and even-numbered arguments in alternating styles,
-with no whitespace separating them.
+with no space separating them.
+.\" BEGIN STYLE
 .
 .
 .PP
@@ -1057,12 +1196,12 @@ used to mark file or path names,
 environment variables,
 in-line literals,
 and man page cross-references.
+.\" END STYLE
 .
 .
 .PP
-The default font size and family (for
-.I troff
-output devices)
+The default point size and family
+(for typesetter devices)
 is 10-point Times.
 .
 The default style is roman.
@@ -1079,23 +1218,26 @@ 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)
+.\" BEGIN STYLE
 .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.
+this page uses bold for macro,
+string,
+and register names.
 .
 In
 .BR .EX / .EE
-examples of interactive I/O (such as a shell session),
+examples of interactive I/O
+(such as a shell session),
 set only user input in bold.
 .
 .
 .
-.\" END USAGE (TODO: move to tutorial/style guide when we have it)
+.\" END STYLE
 .TP
 .BR .I \~[\c
 .IR text ]
@@ -1107,7 +1249,7 @@ If the macro is given no arguments,
 the text of the next input line is set in italics.
 .
 .
-.\" BEGIN USAGE (TODO: move to tutorial/style guide when we have it)
+.\" BEGIN STYLE
 .IP
 Use italics
 for file and path names,
@@ -1139,13 +1281,13 @@ and italics again in running roman text when referring 
to the variable
 material.
 .
 .
-.\" END USAGE (TODO: move to tutorial/style guide when we have it)
+.\" END STYLE
 .TP
 .BR .SM \~[\c
 .IR text ]
 Set
 .I text
-one point size smaller than the default size.
+one point smaller than the default point size.
 .
 If the macro is given no arguments,
 the text of the next input line is set smaller.
@@ -1153,17 +1295,14 @@ the text of the next input line is set smaller.
 .
 .IP
 .IR Note :
-.IR nroff -style
-output devices,
-such as terminals,
-will render
+terminals will render
 .I text
-at the normal font size instead.
+at normal size instead.
 .
 Do not rely upon
 .B .SM
 to communicate semantic information distinct from using roman style at
-the normal size;
+normal size;
 it will be hidden from readers using such devices.
 .
 .
@@ -1173,7 +1312,7 @@ it will be hidden from readers using such devices.
 Set
 .I text
 in bold,
-one point size smaller than the default size.
+one point smaller than the default point size.
 .
 If the macro is given no arguments,
 the text of the next input line is set smaller and in bold.
@@ -1181,21 +1320,18 @@ the text of the next input line is set smaller and in 
bold.
 .
 .IP
 .IR Note :
-.IR nroff -style
-output devices,
-such as terminals,
-will render
+terminals will render
 .I text
-in bold at the normal font size instead.
+in bold at the normal size instead.
 .
 Do not rely upon
 .B .SB
 to communicate semantic information distinct from using bold style at
-the normal size;
+normal size;
 it will be hidden from readers using such devices.
 .
 .
-.\" BEGIN USAGE (TODO: move to tutorial/style guide when we have it)
+.\" BEGIN STYLE
 .PP
 Note what is
 .I not
@@ -1228,40 +1364,45 @@ such as references to individual characters or short 
strings,
 including section and subsection headings of man pages,
 are suitable objects for quotation;
 see the
-\(oq\e(lq\(cq,
-\(oq\e(rq\(cq,
-\(oq\e(oq\(cq,
+.BR \e(lq ,
+.BR \e(rq ,
+.BR \e(oq ,
 and
-\(oq\e(cq\(cq
+.B \e(cq
 escapes in subsection \(lqPortability\(rq below.
 .
 .
-.\" END USAGE (TODO: move to tutorial/style guide when we have it)
+.\" END STYLE
 .PP
 Unlike the above font style macros,
-the font alternation macros below accept only arguments on the same
-line as the macro call.
+the font style alternation macros below accept only arguments on the
+same line as the macro call.
 .
-If whitespace is required within one of the arguments,
+If space 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 containing embedded space characters.
 .
-Setting all three different styles within one whitespace-delimited word
+Setting all three different styles within a word
 presents challenges;
-it is possible with the \(oq\ec\(cq and/or \(oq\ef\(cq escapes,
+it is possible with the
+.B \ec
+and/or
+.B \ef
+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.
+Set each argument in bold and italics,
+alternately.
 .
 .
-.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" BEGIN STYLE
 .RS
 .IP
 .\" from src/roff/troff/troff.1.man
@@ -1271,19 +1412,21 @@ Set each argument in bold and italics, alternately.
 .RE
 .
 .
-.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" END STYLE
 .TP
 .BI .BR " bold-text roman-text"\c
 \~\&.\|.\|.\&
-Set each argument in bold and roman, alternately.
+Set each argument in bold and roman,
+alternately.
 .
 .
-.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" BEGIN STYLE
 .RS
 .IP
 .\" from tmac/groff_ms.7.man
 .EX
-Any such change becomes effective with the first use of
+Any such change becomes effective with the first
+use of
 \&.BR .NH ,
 \&.I after
 the new alias is defined.
@@ -1291,14 +1434,15 @@ the new alias is defined.
 .RE
 .
 .
-.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" END STYLE
 .TP
 .BI .IB " italic-text bold-text"\c
 \~\&.\|.\|.\&
-Set each argument in italics and bold, alternately.
+Set each argument in italics and bold,
+alternately.
 .
 .
-.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" BEGIN STYLE
 .RS
 .IP
 .\" from man/groff_tmac.5.man
@@ -1312,14 +1456,15 @@ mechanism.
 .RE
 .
 .
-.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" END STYLE
 .TP
 .BI .IR " italic-text roman-text"\c
 \~\&.\|.\|.\&
-Set each argument in italics and roman, alternately.
+Set each argument in italics and roman,
+alternately.
 .
 .
-.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" BEGIN STYLE
 .RS
 .IP
 .\" from man/groff_out.5.man
@@ -1330,33 +1475,36 @@ This is the first command of the
 .RE
 .
 .
-.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" END STYLE
 .TP
 .BI .RB " roman-text bold-text"\c
 \~\&.\|.\|.\&
-Set each argument in roman and bold, alternately.
+Set each argument in roman and bold,
+alternately.
 .
 .
-.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" BEGIN STYLE
 .RS
 .IP
 .\" from src/preproc/eqn/eqn.1.man
 .EX
-Also, the statement
+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)
+.\" END STYLE
 .TP
 .BI .RI " roman-text italic-text"\c
 \~\&.\|.\|.\&
-Set each argument in roman and italics, alternately.
+Set each argument in roman and italics,
+alternately.
 .
 .
-.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" BEGIN STYLE
 .RS
 .IP
 .\" from contrib/mm/groff_mm.7.man
@@ -1367,7 +1515,7 @@ Set each argument in roman and italics, alternately.
 .RE
 .
 .
-.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" END STYLE
 .\" ====================================================================
 .SS "Horizontal and vertical spacing"
 .\" ====================================================================
@@ -1385,14 +1533,12 @@ is a number plus an optional scaling indicator.
 If no scaling indicator is given,
 the
 .I man
-package assumes \(oqn\(cq;
+package assumes \(lqn\(rq;
 that is,
 the width of a letter \(lqn\(rq in the font current when the macro is
-called.
-.
-See section \(lqNumerical Expressions\(rq in
-.IR groff (7)
-for further details.
+called
+(see section \(lqNumerical Expressions\(rq in
+.IR groff (7)).
 .
 An indent specified in a call to
 .BR .IP ,
@@ -1402,7 +1548,8 @@ or the deprecated
 persists until
 (1) another of these macros is called with an explicit indent
 argument,
-or (2)
+or
+(2)
 .BR .SH ,
 .BR .SS ,
 or
@@ -1429,11 +1576,8 @@ exhibited by ordinary
 paragraphs not within an
 .BR .RS / .RE
 relative indent,
-is 7.2n in
-.I troff
-mode and 7n in
-.I nroff
-mode.
+is 7.2n for typesetter devices
+and 7n for terminal devices.
 .
 The HTML output device is an exception;
 it ignores indentation completely.
@@ -1445,17 +1589,24 @@ This same indentation is used again (additively) for 
the defaults of
 and the deprecated
 .BR .HP .
 .
-Section headings
+Headers,
+footers
+(both set with
+.RB .TH ),
+and section headings
 .RB ( .SH )
-are set flush with the left margin of the output device,
+are set flush left
 and subsection headings
 .RB ( .SS )
-are indented 3n.
+are indented 3n
+(but see the
+.B \-rSN
+option).
 .
 .
 .PP
 Resist the temptation to mock up tabular or multi-column output with
-ASCII tab characters or the indentation arguments to
+horizontal tab characters or the indentation arguments to
 .BR .IP ,
 .BR .TP ,
 .BR .RS ,
@@ -1471,8 +1622,7 @@ can likely meet your needs.
 .
 .
 .PP
-The following macros cause a line break with the
-insertion of vertical space:
+The following macros break the output line and insert vertical space:
 .BR .SH ,
 .BR .SS ,
 .BR .TP ,
@@ -1482,12 +1632,9 @@ insertion of vertical space:
 and the deprecated
 .BR .HP .
 .
-The default inter-section and inter-paragraph spacing is 1v in
-.I nroff
-mode,
-and 0.4v in
-.I troff
-mode
+The default inter-section and inter-paragraph spacing is
+is 1v for terminal devices
+and 0.4v for typesetter devices
 (\(lqv\(rq is a unit of vertical distance,
 where 1v is the distance between adjacent text baselines in a
 single-spaced document).
@@ -1521,7 +1668,7 @@ Number registers are described in section \(lqOptions\(rq 
below.
 .
 .
 .\" ====================================================================
-.SS "String registers"
+.SS Strings
 .\" ====================================================================
 .
 The following strings are defined.
@@ -1529,8 +1676,9 @@ The following strings are defined.
 .
 .TP
 .B \e*R
-expands to the character escape for the \(lqregistered sign\(rq glyph,
-\(oq\e(rg\(cq,
+expands to the special character escape for the \(lqregistered sign\(rq
+glyph,
+.BR \e(rg ,
 if available,
 and \(lq(Reg.)\(rq otherwise.
 .
@@ -1538,31 +1686,35 @@ and \(lq(Reg.)\(rq otherwise.
 .
 .TP
 .B \e*S
-expands to an escape setting the font size to the document default.
+expands to an escape setting the point size to the document default.
 .
 .
 .TP
 .B \e*(HF
 expands to the font identifier used to print headings and subheadings.
 .
-The default is \(oqB\(cq.
+The default is \(lqB\(rq.
 .
-This string register is a GNU extension.\" from groff 1.19
+This string is a GNU extension.\" from groff 1.19
 .
 .
 .TP
 .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.
+expand to the special character escapes for left and right
+double-quotation marks,
+.B \e(lq
+and
+.BR \e(rq,
+respectively.
 .
 .
 .TP
 .B \e*(Tm
-expands to the character escape for the \(lqtrade mark sign\(rq glyph,
-\(oq\e(tm\(cq,
+expands to the special character escape for the \(lqtrade mark sign\(rq
+glyph,
+.BR \e(tm ,
 if available,
 and \(lq(TM)\(rq otherwise.
 .
@@ -1593,12 +1745,12 @@ and that a single space character follows the double 
quote.
 The
 .I word
 consists of one letter for each needed preprocessor:
-\(oqe\(cq for
+\(lqe\(rq for
 .IR @g@eqn ,
-\(oqr\(cq for
+\(lqr\(rq for
 .IR @g@refer ,
 and
-\(oqt\(cq for
+\(lqt\(rq for
 .IR @g@tbl .
 .
 Modern implementations of the
@@ -1621,13 +1773,11 @@ and
 .BR .EN ,
 may be used freely.
 .
-Note that
-.I nroff
-output devices are extremely limited in presentation of mathematical
-equations.
+Note that terminal devices are extremely limited in presentation of
+mathematical equations.
+.\" BEGIN STYLE
 .
 .
-.\" TODO BEGIN: move subsection to tutorial/style guide when we have it
 .\" ====================================================================
 .SS Portability
 .\" ====================================================================
@@ -1654,9 +1804,11 @@ however,
 that using raw
 .I groff
 requests
-(apart from the empty request \(oq.\(cq)\&
-is likely to make your page render poorly on the class of viewers that
-transform it to HTML.
+(apart from the empty request
+.RB \(lq . \(rq)\&
+is likely to make your page render poorly when processed by other tools;
+many of these attempt to interpret page sources directly for conversion
+to HTML.
 .
 Some requests make implicit assumptions about things like character
 and page sizes that may not hold in an HTML environment;
@@ -1664,7 +1816,8 @@ 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.
+a problem that can lead to portions of your text being omitted
+or presented incomprehensibly.
 .
 .
 .PP
@@ -1680,10 +1833,12 @@ The macros we have described as extensions
 .BR .UR / .UE ,
 and
 .BR .MT / .ME )
-should be used with caution, as they may not yet be built in to
-some viewer that is important to your audience.
+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 into your page\(emafter the
+If in doubt,
+copy the implementation into your page\(emafter the
 .B .TH
 call and the \(lqName\(rq section,
 to accommodate timid
@@ -1695,7 +1850,23 @@ implementations.
 Similar caveats apply to escapes.
 .
 Some escape sequences are however required for correct typesetting
-even in man pages and usually do not cause portability problems:
+even in man pages and usually do not cause portability problems.
+.
+Several of these render glyphs corresponding to punctuation characters
+in the Unicode basic Latin range
+(U+0000\(enU+007F)
+that are handled specially in
+.I roff
+input;
+the escapes below must be used to render them correctly and portably
+when documenting material that uses them syntactically\(emnamely,
+any of the set
+.B \(aq \- \(ha \(ga \(ti
+(apostrophe,
+dash,
+caret,
+grave accent,
+tilde).
 .
 .
 .TP
@@ -1706,17 +1877,19 @@ Everything after the double-quote to the end of the 
input line is
 ignored.
 .
 Whole-line comments are frequently placed immediately after the empty
-request \(oq.\(cq.
+request
+.RB \(lq . \(rq).
 .
 .
 .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 .
+Except for the update of the input line counter
+(used for diagnostic messages and related purposes),
+a series of lines ending in backslash-newline appears to
+.I groff
+as a single input line.
 .
 Use this escape to break excessively long input lines for document
 maintenance.
@@ -1737,7 +1910,8 @@ Use at the beginning of a word to suppress its 
hyphenation entirely.
 .
 .TP
 .B \e\(ti
-Adjustable, non-breaking space character.
+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).
@@ -1746,16 +1920,17 @@ numerical quantity and its corresponding unit(s).
 .RS
 .IP
 .EX
-Before starting the motor, set the output speed to\e\(ti1.
+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.
+CSTR\e\(ti#8 documents the B\e\(tilanguage.
 .EE
 .RE
 .
 .
 .TP
 .B \e&
-Zero-width space.
+Zero-width non-breaking space.
 .
 Insert at the beginning of an input line to prevent a dot or apostrophe
 from being interpreted as the beginning of a
@@ -1766,12 +1941,38 @@ recognized as such.
 .
 .
 .TP
+.B \e|
+Narrow
+(one-sixth em on typesetters,
+zero-width on terminals)
+non-breaking space.
+.
+Used primarily in ellipses
+(\(lq.\e|.\e|.\(rq)
+to achieve more pleasant spacing on typesetter devices like PostScript
+and PDF.
+.
+.
+.TP
+.B \e\-
+Minus sign or basic Latin hyphen-minus.
+.
+.RB \(lq \- \(rq
+is a hyphen to
+.IR roff ;
+some output devices replace it with U+2010
+(hyphen)
+or similar.
+.
+.
+.TP
 .B \e(aq
-ASCII apostrophe.
+Basic Latin apostrophe.
 .
-Use for syntax elements of programming languages because some
-output devices might replace unescaped apostrophes with right single
-quotation marks.
+Some
+output devices replace
+.RB \(lq \(aq \(rq
+with a right single quotation mark.
 .
 .
 .TP
@@ -1784,16 +1985,26 @@ Closing single quotation mark.
 .
 .
 .IP
-Use these for paired directional single quotes, \(oqlike this\(cq.
+Use these for paired directional single quotes,
+\(oqlike this\(cq.
 .
 .
 .TP
 .B \e(dq
-ASCII double-quote.
+Basic Latin double-quote.
+.
+Use in macro calls to prevent
+.RB \(oq \(dq \(rq
+from being interpreted as beginning a quoted argument.
 .
-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.
+.
+.RS
+.IP
+.\" from src/preproc/eqn/eqn.1.man
+.EX
+\&.BI split\e~\e(dq text \e(dq
+.EE
+.RE
 .
 .
 .TP
@@ -1806,82 +2017,99 @@ Right double quotation mark.
 .
 .
 .IP
-Use these for paired directional double quotes, \(lqlike this\(rq.
+Use these for paired directional double quotes,
+\(lqlike this\(rq.
 .
 .
 .TP
 .B \e(em
 Em-dash.
 .
-Use for an interruption in a sentence\(emsuch as this one.
+Use for an interruption\(emsuch as this one\(emin a sentence.
 .
 .
 .TP
 .B \e(en
 En-dash.
 .
-Use to separate the two ends of a range,
-in particular between numbers,
-for example: the digits 1\(en9.
+Use to separate the ends of a range,
+particularly between numbers;
+for example,
+\(lqthe digits 1\(en9\(rq.
 .
 .
 .TP
 .B \e(ga
-ASCII grave accent.
+Basic Latin grave accent.
 .
-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.
+Some output devices replace
+.RB \(lq \(ga \(rq
+with a left single quotation mark.
 .
 .
 .TP
 .B \e(ha
-ASCII circumflex accent
+Basic Latin circumflex accent
 (\(lqhat\(rq).
 .
-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.
+Some output devices replace
+.RB \(lq \(ha \(rq
+with U+02C6
+(modifier letter circumflex accent)
+or similar.
 .
 .
 .TP
 .B \e(ti
-ASCII tilde.
+Basic Latin 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.
+Some output devices replace
+.RB \(lq \(ti \(rq
+with U+02DC
+(small tilde)
+or similar.
 .
 .
 .TP
-.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.
+.B \ec
 .
-The unescaped \(oq\-\(cq input character is not appropriate for
-these cases because it may render as a hyphen on some output devices.
+Suppress break at the end of the input line.
 .
+Normally,
+the end of an input line is treated like a space;
+.\" end-of-sentence detection is performed, and...
+an output line
+.I may
+be broken there\" in fill mode
+and
+.I will
+be in
+.B .EX/.EE
+examples.\" i.e., no-fill mode
 .
-.TP
+Anything after
 .B \ec
+on the input line
+.\" ...except for \R escapes, which shouldn't appear in man pages...
+is discarded.
 .
-If this escape sequence occurs at the end of an input line, no white
-space is inserted between the last glyph on it and the first glyph
-resulting from the next input line.
+The next line,
+including macro calls,
+is interpreted as usual
+(contrast with
+.BI \e newline\/\c
+).
 .
-This is occasionally useful when three different fonts are needed
-in a single word.
+This is occasionally useful when three different fonts are needed in a
+single word.
 .
 .
 .RS
 .IP
 .\" from contrib/pdfmark/pdfroff.1.man
 .EX
-Normally, the final output file should be named
+Normally,
+the final output file should be named
 \&.IB file .pdf\ec
 \e&.
 .EE
@@ -1893,9 +2121,15 @@ Note that when using this trick with the
 .B .BI
 or
 .B .RI
-macros, you will need to manually add an italic correction escape
-\(oq\e/\(cq before the \(oq\ec\(cq due to way macros expand their
-arguments.
+macros,
+you will need to manually add an italic correction escape
+.RB \(lq \e/ \(rq,
+a GNU extension,
+before the
+.B \ec
+due to way macros expand their arguments\(emif
+you value the improved typesetter output quality over the potential
+reduction in document portability.
 .
 .
 .RS
@@ -1914,11 +2148,15 @@ Files processed with
 .IP
 Alternatively,
 and perhaps with better portability,
-the \(oq\ef\(cq font escape sequence can be used;
+the
+.B \ef
+font style escape sequence can be used;
 see below.
 .
-Using \(oq\ec\(cq to include the output from more than one input line
-into the next-line argument of a
+Using
+.B \ec
+to include the output from more than one input line into the next-line
+argument of a
 .B .TP
 macro will render incorrectly with
 .I groff
@@ -1937,17 +2175,24 @@ It works reliably as long as the
 .B .ec
 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.
+and it is slightly more portable than the more exact
+.B \e(rs
+(\(lqreverse solidus\(rq) special character escape sequence.
 .
 .
 .TP
 .BR \efB ,\  \efI ,\  \efR ,\  \efP
-Switch to bold, italic, roman, or back to the previous font,
+Switch to bold,
+italic,
+roman,
+or back to the previous style,
 respectively.
 .
-Either \(oq\ef\(cq or \(oq\ec\(cq is needed when three different fonts
-are required in a single whitespace-delimited word.
+Either
+.B \ef
+or
+.B \ec
+is needed when three different font styles are required in a word.
 .
 .
 .RS
@@ -1963,46 +2208,56 @@ are required in a single whitespace-delimited word.
 .
 .
 .IP
-Font escapes may be more portable than \(oq\ec\(cq.
+Style escapes may be more portable than
+.BR \ec .
 .
 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,
+it is up to you to account for italic corrections with
+.RB \(lq \e/ \(rq
+and
+.RB \(lq \e, \(rq,
+which are themselves GNU extensions,
 if desired and if supported by your implementation.
 .
 .
 .IP
 Note that
-\(oq\efP\(cq reliably returns to the style in use immediately preceding
-the previous \(oq\ef\(cq escape only if no
+.B \efP
+reliably returns to the style in use immediately preceding the
+previous
+.B \ef
+escape only if no
 sectioning,
 paragraph,
-or font style macro calls have intervened.
+or style macro calls have intervened.
 .
 .
 .IP
-As long as only two fonts are needed in any single whitespace-delimited
-word,
-font alternation macros like
+As long as at most two styles are needed in a word,
+style macros like
+.B .B
+and
 .B .BI
 usually result in more readable
 .I roff
-source than \(oq\ef\(cq escapes do.
+source than
+.B \ef
+escapes do.
 .
 .
 .PP
-For maximum portability, escape sequences and special characters
-not listed above are better avoided in man pages.
+For maximum portability,
+escape sequences and special characters not listed above are better
+avoided in man pages.
+.\" END STYLE
 .
 .
-.\" TODO END: move subsection to tutorial/style guide when we have it
 .\" ====================================================================
 .SS "Deprecated features"
 .\" ====================================================================
 .
-Use of the following is discouraged.
+Use of the following in man pages for public distribution is
+discouraged.
 .
 .
 .TP
@@ -2055,33 +2310,39 @@ such as in \(lqSystem\~V Release\~3\(rq.
 .B .BT
 Set the page footer.
 .
-Redefine this macro to get control of the footer.
-.
-This macro is a GNU extension.\" from groff 1.19
+By redefining this macro
+(a GNU extension)\" from groff 1.19
+in a
+.I man.local
+file
+(see section \(lqFiles\(rq below),
+an adminsitrator can customize the footer for a site.
 .
 .
 .TP
 .B .DT
-Set tabs every 0.5\~inches.
+Set tab stops every 0.5\~inches.
 .
 Since this macro is always called during a
 .B .TH
-macro, it makes sense to call it only if the tab positions have been
-changed.
+macro,
+it makes sense to call it only if the tab stops have been changed.
 .
 .
 .IP
 Use of this presentation-level macro is deprecated.
 .
-It translates poorly to HTML, under which exact whitespace control
-and tabbing are not readily available.
+It translates poorly to HTML,
+under which exact space control and tabulation are not readily
+available.
 .
-Thus, information or distinctions that you use
+Thus,
+information or distinctions that you use
 .B .DT
 to express are likely to be lost.
 .
-If you feel tempted to use it, you should probably be composing a
-table using
+If you feel tempted to use it,
+you should probably be composing a table using
 .IR @g@tbl (@MAN1EXT@)
 markup instead.
 .
@@ -2102,12 +2363,13 @@ is handled as with
 .IP
 Use of this presentation-level macro is deprecated.
 .
-While it is universally portable to legacy Unix systems, a hanging
-indentation cannot be expressed naturally under HTML, and many
-HTML-based manual viewers simply interpret it as a starter for a
-normal paragraph.
+While it is universally portable to legacy Unix systems,
+a hanging indentation cannot be expressed naturally under HTML,
+and HTML-based man page processors may interpret it as starting a normal
+paragraph.
 .
-Thus, any information or distinction you tried to express with the
+Thus,
+any information or distinction you tried to express with the
 indentation may be lost.
 .
 .
@@ -2123,16 +2385,18 @@ the default scaling is \(oqv\(cq).
 .
 Without an argument,
 the spacing is reset to its default value;
-see \(lqHorizontal and vertical spacing\(rq above.
+see subsection \(lqHorizontal and vertical spacing\(rq above.
 .
 .
 .IP
 Use of this presentation-level macro is deprecated.
 .
-It translates poorly to HTML, under which exact control of
-inter-paragraph spacing is not readily available.
+It translates poorly to HTML,
+under which exact control of inter-paragraph spacing is not readily
+available.
 .
-Thus, information or distinctions that you use
+Thus,
+information or distinctions that you use
 .B .PD
 to express are likely to be lost.
 .
@@ -2141,9 +2405,13 @@ to express are likely to be lost.
 .B .PT
 Set the page header.
 .
-Redefine this macro to get control of the header.
-.
-This macro is a GNU extension.\" from groff 1.19
+By redefining this macro
+(a GNU extension)\" from groff 1.19
+in a
+.I man.local
+file
+(see section \(lqFiles\(rq below),
+an adminsitrator can customize the header for a site.
 .
 .
 .TP
@@ -2212,7 +2480,7 @@ and the deprecated
 and
 .BR .UC .
 .
-The only string registers defined were
+The only strings defined were
 .B R
 and
 .BR S ;
@@ -2229,7 +2497,7 @@ in Unix System\~III (1980).
 .B lq
 and
 .B rq
-string registers.
+strings.
 .
 4.3BSD (1986) added
 .\" undocumented .DS and .DE macros for "displays", which are .RS/.RE
@@ -2248,7 +2516,7 @@ and
 .
 Ultrix\~11 (1988) added the
 .B Tm
-string register.
+string.
 .
 SunOS\~4.0 (1988) may have been the first to support
 .BR .SB .
@@ -2273,12 +2541,12 @@ macro package.
 .B \-rcR=1
 Continuous rendering.
 .
-Create a single,
-very long page instead of multiple pages.
+Do not paginate the output;
+produce one
+(potentially very long)
+output page.
 .
-This is the default in
-.I nroff
-mode.
+This is the default for terminal and HTML devices.
 .
 Use
 .B \-rcR=0
@@ -2287,17 +2555,19 @@ to disable it.
 .
 .TP
 .B \-rC1
-Number pages continuously.
+Number output pages continuously.
 .
-If more than one man page is given on the command line, number the
-pages continuously, rather than starting each at\~1.
+If multiple man pages are processed,
+number the output pages in strictly increasing sequence,
+rather than resetting the page number to\~1 at each new man page.
 .
 .
 .TP
 .B \-rCS=1
 Capitalize section headings.
 .
-Set section headings (the argument(s) to
+Set section headings
+(the argument(s) to
 .BR .SH )
 in full capitals.
 .
@@ -2309,7 +2579,8 @@ distinction information.
 .B \-rCT=1
 Capitalize titles.
 .
-Set the man page title (the first argument to
+Set the man page title
+(the first argument to
 .BR .TH )
 in full capitals in headers and footers.
 .
@@ -2324,15 +2595,13 @@ Enable double-sided layout.
 Format footers for even and odd pages differently;
 see the description of
 .B .TH
-in \(lqDocument structure macros\(rq,
-above.
+in subsection \(lqDocument structure macros\(rq above.
 .
 .
 .TP
 .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,
+relative to the bottom of the page if negative or top if positive,
 to
 .IR footer-distance .
 .
@@ -2340,12 +2609,9 @@ The default is \-0.5i.
 .
 .
 .TP
-.BI \-rHY= flags
-Set hyphenation flags.
-.
-Permissible values of
-.I flags
-are documented in section \(lqHyphenation\(rq of
+.BI \-rHY= mode
+Set hyphenation mode,
+as documented in section \(lqHyphenation\(rq of
 .IR groff (7).
 .
 The default is\~4 if continuous rendering is enabled
@@ -2356,14 +2622,16 @@ and\~6 otherwise.
 .
 .TP
 .BI \-rIN= indent
-Set the body text indentation (for normal paragraphs) to
+Set the body text indentation
+(for normal paragraphs)
+to
 .IR indent .
 .
-See \(lqHorizontal and vertical spacing\(rq above for the default
-indentation value.
+See subsection \(lqHorizontal and vertical spacing\(rq above for the
+default indentation value.
 .
 For
-.IR nroff ,
+terminal devices,
 .I indent
 should always be an integer multiple of unit \(oqn\(cq to get consistent
 indentation.
@@ -2373,18 +2641,18 @@ indentation.
 .BI \-rLL= line-length
 Set line length.
 .
-If this option is not given, the line length is set to respect any
-value set by a prior \(lq.ll\(rq request (which
+If this option is not given,
+the line length is set to respect any value set by a prior \(lq.ll\(rq
+request
+(which
 .I must
 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
-.I troff
-mode.
+otherwise it defaults
+to 78n for terminal devices
+and 6.5i for typesetter devices.
 .
 .
 .IP
@@ -2399,11 +2667,12 @@ register should
 .I always
 be preferred to the use of such a request.
 .
-In particular, note that a \(lq.ll\~65n\(rq request does
+In particular,
+note that a \(lq.ll\~65n\(rq request does
 .I not
-preserve the normal
+preserve the default
 .I nroff
-default line length
+line length
 (the
 .I man
 default initialization to 78n prevails),
@@ -2419,10 +2688,11 @@ set a line length of 65n.
 .
 .TP
 .BI \-rLT= title-length
-Set title length.
+Set title length,
+used for headers and footers.
 .
-If this option is not given, the title length defaults to the line
-length.
+If this option is not given,
+the title length defaults to the line length.
 .
 .
 .TP
@@ -2436,9 +2706,11 @@ rather than\~1.
 .BI \-rS point-size
 Use
 .I point-size
-as the base document font size.
+as the base document point size.
 .
-Acceptable values are 10, 11, or 12.
+Acceptable values are 10,
+11,
+or 12.
 .
 See subsection \(lqFont style macros\(rq above for the default.
 .
@@ -2448,8 +2720,8 @@ See subsection \(lqFont style macros\(rq above for the 
default.
 Set subsection indentation to
 .IR subsection-indent .
 .
-See \(lqHorizontal and vertical spacing\(rq above for the default
-indentation value.
+See subsection \(lqHorizontal and vertical spacing\(rq above for the
+default indentation value.
 .
 .
 .TP
@@ -2462,10 +2734,16 @@ number pages as
 .IR p c,
 and so forth.
 .
-For example, the option
+For example,
+the option
 .B \-rX2
 produces the following page
-numbers: 1, 2, 2a, 2b, 2c, and so on.
+numbers: 1,
+2,
+2a,
+2b,
+2c,
+and so on.
 .
 .
 .\" ====================================================================
@@ -2507,7 +2785,9 @@ need not know which package the file
 .I page.1
 uses.
 .
-Multiple man pages, in either format, can be handled.
+Multiple man pages,
+in either format,
+can be handled.
 .
 .
 .TP
@@ -2533,8 +2813,8 @@ The extension macro definitions for
 and
 .BR .MT / .ME
 are contained in this file,
-which is written in classic
-.I troff
+which is written to be compatible with
+.RI AT&T\~ troff
 and permissively licensed\(emnot copylefted.
 .
 Man page authors concerned about portability to legacy Unix systems are
@@ -2560,6 +2840,7 @@ to have any effect.
 .TP
 .I @LOCALMACRODIR@/\:man.local
 Local changes and customizations should be put into this file.
+.\" BEGIN STYLE
 .
 .
 .\" ====================================================================
@@ -2597,7 +2878,8 @@ indentation amount relative to an adjacent
 .B .PP
 paragraph.
 .
-See \(lqHorizontal and vertical spacing\(rq above for the values.
+See subsection \(lqHorizontal and vertical spacing\(rq above for the
+values.
 .
 .
 .TP
@@ -2649,6 +2931,7 @@ all relative indents are cleared and calls to
 have no effect until
 .B .RS
 is used again.
+.\" END STYLE
 .
 .
 .\" ====================================================================