[groff] 08/16: [ms]: Fix content, style, markup nits in docs.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 4adc47ab3532ef550100e1f8c42d804027b215e8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jun 7 22:57:54 2022 -0500

    [ms]: Fix content, style, markup nits in docs.
    
    Content:
    * Define `PORPHANS`, `HORPHANS` register effects less circularly.
    * Document `FPD`, `FPS`, and `FVS` registers as GNU extensions.
    * Identify odd- and even-numbered pages as recto and verso.
    * Say "horizontal motion" rather than "horizontally spacing" (escape
      sequences).
    
    Style:
    * Add adverb to reinforce nestability of RS/RE regions.
    * Promote a semicolon to a colon: the second independent clause explains
      the first, rather than simply being related.
    * Tighten wording.
    
    Markup:
    * doc/ms.ms: Fix macro usage error.
    * doc/ms.ms: Place sub/superscripting string table in keep with its
      paragraph.
    * Permit post-italic punctuation to be in italics as well; it works
      better typographically, and even thoug'h it looks slightly weirder on
      terminals that underline instead, we've had terminal emulators with
      true oblique faces for years now.
    * tmac/groff_ms.7.man: Adjust dead-tree typography.
---
 doc/groff.texi      | 42 ++++++++++++++++++++++--------------------
 doc/ms.ms           | 47 +++++++++++++++++++++++++++++------------------
 tmac/groff_ms.7.man | 34 ++++++++++++++++++++++------------
 3 files changed, 73 insertions(+), 50 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 25948c95..0c08a875 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2748,7 +2748,7 @@ Default: 5@dmn{n}.
 
 @Defmpreg {PORPHANS, ms}
 Defines the minimum number of initial lines of any paragraph that must
-be kept together to avoid orphaned lines at the bottom of a page.  If a
+be kept together to avoid isolated lines at the bottom of a page.  If a
 new paragraph is started close to the bottom of a page, and there is
 insufficient space to accommodate @code{PORPHANS} lines before an
 automatic page break, then a page break is forced before the start of
@@ -3129,7 +3129,7 @@ paragraphing macro calls cause the insertion of vertical 
space in the
 amount stored in the @code{PD} register, except at page or column
 breaks.  The @code{PORPHANS} register (@pxref{ms Document Control
 Settings}) operates in conjunction with each of these macros to inhibit
-the printing of orphaned lines at the bottom of any page.
+the printing of isolated lines at the bottom of any page.
 
 @Defmac {LP, , ms}
 Set a paragraph without any (additional) indentation.
@@ -3337,14 +3337,15 @@ specified by the @code{PS} register.  
``Machairodontinae'' is printed at
 11.5 points, since it corresponds to heading level@tie{}2.
 
 The @code{HORPHANS} register operates in conjunction with the @code{NH}
-and @code{SH} macros to inhibit the printing of orphaned headings at the
+and @code{SH} macros to inhibit the printing of isolated headings at the
 bottom of a page; it specifies the minimum number of lines of an
 immediately subsequent paragraph that must be kept on the same page as
 the heading.  If insufficient space remains on the current page to
 accommodate the heading and this number of lines of paragraph text, a
 page break is forced before the heading is printed.  Any display macro
 or @code{tbl}, @code{pic}, or @code{eqn} region between the heading and
-the subsequent paragraph suppresses this grouping.
+the subsequent paragraph suppresses this grouping.  @xref{ms keeps and
+displays} and @ref{ms Insertions}.
 
 @c ---------------------------------------------------------------------
 
@@ -3428,8 +3429,8 @@ Set all text following at the normal type size (that is, 
the value of
 the @code{PS} register).
 @endDefmac
 
-@code{groff} @file{ms} also supports strings to begin and end super- and
-subscripting.  These are all GNU extensions.
+@code{groff} @file{ms} also offers strings to begin and end super- and
+subscripting.  These are GNU extensions.
 
 @DefmpstrList {@lbracechar{}, ms}
 @DefmpstrListEndx {@rbracechar{}, ms}
@@ -3602,8 +3603,8 @@ You may need to indent a region of text while otherwise 
formatting it
 normally.
 
 @Defmac {RS, , ms}
-Begin a region where headings, paragraphs, and displays are indented by
-the amount stored in the @code{PI} register.
+Begin a region where headings, paragraphs, and displays are indented
+(further) by the amount stored in the @code{PI} register.
 @endDefmac
 
 @Defmac {RE, , ms}
@@ -3667,14 +3668,14 @@ two paragraphs together, or a paragraph that refers to 
a table, list, or
 figure adjacent to the item it discusses.  @file{ms} provides the
 @code{KS} and @code{KE} macros for this purpose.
 
-You can alternatively specify a @dfn{floating keep}; if a keep cannot
+You can alternatively specify a @dfn{floating keep}:@: if a keep cannot
 fit on the current page, @file{ms} holds its contents and
 allows material following the keep (in the source document) to fill the
-remainder of the current page.  When the page breaks, whether by an
-explicit @code{bp} request or by reaching the end of the page, @file{ms}
-puts the floating keep at the beginning of the next page.  This is
-useful for placing large graphics or tables that do not need to appear
-exactly where they occur in the source document.
+remainder of the current page.  When the page breaks, whether by
+reaching the end or @code{bp} request, @file{ms} puts the floating keep
+at the beginning of the next page.  This is useful for placing large
+graphics or tables that do not need to appear exactly where they occur
+in the source document.
 
 @DefmacList {KS, , ms}
 @DefmacItemx {KF, , ms}
@@ -3936,7 +3937,8 @@ corresponding @code{FS} call as long as each @code{FS} 
call occurs
 Footnote text is formatted as paragraphs are, using analogous
 parameters.  The registers @code{FI}, @code{FPD}, @code{FPS}, and
 @code{FVS} correspond to @code{PI}, @code{PD}, @code{PS}, and @code{CS},
-respectively.
+respectively. The @code{FPD}, @code{FPS}, and @code{FVS} registers are
+GNU extensions.
 
 The @code{FF} register controls the formatting of automatically numbered
 footnote paragraphs and those for which @code{FS} is given a marker
@@ -4070,9 +4072,9 @@ Berkeley extensions.
 @DefmacItemx {EH, 
@code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}, ms}
 @DefmacItemx {OF, 
@code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}, ms}
 @DefmacListEndx {EF, 
@code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}, ms}
-The @code{OH} and @code{EH} macros define headers for the odd and even
-pages; the @code{OF} and @code{EF} macros define footers for the odd and
-even pages.
+The @code{OH} and @code{EH} macros define headers for odd- (recto)
+and even-numbered (verso) pages, respectively; the @code{OF} and
+@code{EF} macros define footers for them.
 @endDefmac
 
 By default, @file{ms} places no header on any page numbered ``1''
@@ -4178,8 +4180,8 @@ it requires multiple output lines, whether because a 
heading is too long
 to fit or because style dictates that page numbers not be repeated.  You
 may wish to indent the text thus wrapped to correspond to its heading
 depth; this can be done in the entry text by prefixing it with tabs or
-horizontally spacing escape sequences, or by providing a second argument
-to the @code{XA} macro.
+horizontal motion escape sequences, or by providing a second argument to
+the @code{XA} macro.
 
 @code{XS} and @code{XA} automatically associate the page number where
 they are called with the text following them, but they accept arguments
diff --git a/doc/ms.ms b/doc/ms.ms
index 4b237750..1f1c94e6 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -813,7 +813,7 @@ except at page or column breaks.
 The
 .CW PORPHANS
 register defines the minimum number of initial lines of any paragraph
-that must be kept together to avoid orphaned lines at the bottom of a
+that must be kept together to avoid isolated lines at the bottom of a
 page.
 .
 If a new paragraph is started close to the bottom of a page,
@@ -1264,7 +1264,7 @@ register operates in conjunction with the
 .CW NH
 and
 .CW SH
-macros to inhibit the printing of orphaned headings at the bottom of a
+macros to inhibit the printing of isolated headings at the bottom of a
 page;
 it specifies the minimum number of lines of the subsequent paragraph
 that must be kept on the same page as the heading.
@@ -1278,7 +1278,9 @@ Any display macro or
 .I pic ,
 or
 .I eqn
-region between the heading and the subsequent paragraph suppresses this
+region
+(see subsequent sections)
+between the heading and the subsequent paragraph suppresses this
 grouping.
 .
 .
@@ -1504,11 +1506,12 @@ and
 .I groff .
 .
 .
+.KS
 .PP
 .I "groff ms"
-also supports strings to begin and end super- and subscripting.
+also offers strings to begin and end super- and subscripting.
 .
-These are all GNU extensions.
+These are GNU extensions.
 .
 .
 .TS
@@ -1523,6 +1526,7 @@ _
 \[rs]*<        Begin subscripting.
 \[rs]*>        End subscripting.
 .TE
+.KE
 .
 .
 .nr PS -2
@@ -1778,7 +1782,7 @@ _
 \&.RS  T{
 Begin a region where headings,
 paragraphs,
-and displays are indented by
+and displays are indented (further) by
 .CW \[rs]n[PI] .
 T}
 \&.RE  T{
@@ -1878,7 +1882,7 @@ macros for this purpose.
 .
 .PP
 You can alternatively specify a
-.I "floating keep;"
+.I "floating keep:"
 if a keep cannot fit on the current page,
 .I ms
 holds its contents and allows material following the keep
@@ -1886,9 +1890,9 @@ holds its contents and allows material following the keep
 to fill the remainder of the current page.
 .
 When the page breaks,
-whether by an explicit
+whether by reaching the end or
 .CW bp
-request or by reaching the end of the page,
+request,
 .I ms
 puts the floating keep at the beginning of the next page.
 .
@@ -2259,7 +2263,7 @@ Footnotes
 .\" The following sentence is used below as an example as well.  Keep it
 .\" in sync.
 A footnote is typically anchored to a place in the text with a
-.I marker ,
+.I marker,
 which is a small integer\**,
 .FS
 like this numeric footnote
@@ -2280,8 +2284,8 @@ String    Description
 _
 \[rs]**        T{
 Place an
-.I automatic number,
-an automatically generated numeric footnote marker,
+.I "automatic number,"
+an automatically updated numeric footnote marker,
 in the text.
 .
 Each time this string is interpolated,
@@ -2407,7 +2411,7 @@ section.
 box center;
 lfCR.
 A footnote is anchored to a place in the text with a
-\&.I marker ,
+\&.I marker,
 which is a small integer\[rs]**,
 \&.FS
 like this numeric footnote
@@ -2461,6 +2465,13 @@ and
 .CW VS ,
 respectively.
 .
+The
+.CW FPD ,
+.CW FPS ,
+and
+.CW FVS
+registers are GNU extensions.
+.
 .
 .KS
 .PP
@@ -2743,19 +2754,19 @@ Macro   Description
 _
 \&.OH \[aq]\f[I]left\f[]\[aq]\f[I]center\f[]\[aq]\f[I]right\f[]\[aq]\
        T{
-Set the left, center, and right headers on odd-numbered pages.
+Set the left, center, and right headers on odd-numbered (recto) pages.
 T}
 \&.OF \[aq]\f[I]left\f[]\[aq]\f[I]center\f[]\[aq]\f[I]right\f[]\[aq]\
        T{
-Set the left, center, and right footers on odd-numbered pages.
+Set the left, center, and right footers on odd-numbered (recto) pages.
 T}
 \&.EH \[aq]\f[I]left\f[]\[aq]\f[I]center\f[]\[aq]\f[I]right\f[]\[aq]\
        T{
-Set the left, center, and right headers on even-numbered pages.
+Set the left, center, and right headers on even-numbered (verso) pages.
 T}
 \&.EF \[aq]\f[I]left\f[]\[aq]\f[I]center\f[]\[aq]\f[I]right\f[]\[aq]\
        T{
-Set the left, center, and right footers on even-numbered pages.
+Set the left, center, and right footers on even-numbered (verso) pages.
 T}
 .TE
 .
@@ -3000,7 +3011,7 @@ that page numbers not be repeated.
 You may wish to indent the text thus wrapped to correspond to its
 heading depth;
 this can be done in the entry text by prefixing it with tabs or
-horizontally spacing escape sequences,
+horizontal motion escape sequences,
 or by providing a second argument to the
 .CW XA
 macro.
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 0d6efbeb..c39c3b7d 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -700,7 +700,7 @@ except at page or column breaks.
 The
 .B PORPHANS
 register defines the minimum number of initial lines of any paragraph
-that must be kept together to avoid orphaned lines at the bottom of a
+that must be kept together to avoid isolated lines at the bottom of a
 page.
 .
 If a new paragraph is started close to the bottom of a page,
@@ -985,7 +985,7 @@ register operates in conjunction with the
 .B NH
 and
 .B SH
-macros to inhibit the printing of orphaned headings at the bottom of a
+macros to inhibit the printing of isolated headings at the bottom of a
 page;
 it specifies the minimum number of lines of the subsequent paragraph
 that must be kept on the same page as the heading.
@@ -1155,9 +1155,9 @@ register).
 .
 .P
 .I groff ms
-also supports strings to begin and end super- and subscripting.
+also offers strings to begin and end super- and subscripting.
 .
-These are all GNU extensions.
+These are GNU extensions.
 .
 .
 .TP
@@ -1188,7 +1188,7 @@ normally.
 .B .RS
 Begin a region where headings,
 paragraphs,
-and displays are indented by
+and displays are indented (further) by
 .BR \[rs]n[PI] .
 .
 .
@@ -1214,7 +1214,7 @@ This can cause a page break to occur earlier than it 
normally would.
 .
 .P
 You can alternatively specify a
-.I floating keep;
+.I floating keep:
 if a keep cannot fit on the current page,
 .I ms
 holds its contents and allows text following the keep
@@ -1222,9 +1222,9 @@ holds its contents and allows text following the keep
 to fill in the remainder of the current page.
 .
 When the page breaks,
-whether by an explicit
+whether by reaching the end or
 .B bp
-request or by reaching the end of the page,
+request,
 .I ms
 puts the floating keep at the beginning of the next page.
 .
@@ -1527,7 +1527,7 @@ option is used.
 .\" ====================================================================
 .
 A footnote is typically anchored to a place in the text with a
-.IR marker ,
+.I marker,
 which is a small integer,
 a symbol,
 or arbitrary user-specified text.
@@ -1624,6 +1624,13 @@ and
 .BR VS ,
 respectively.
 .
+The
+.BR FPD ,
+.BR FPS ,
+and
+.B FVS
+registers are GNU extensions.
+.
 .
 .P
 The
@@ -1786,6 +1793,8 @@ appearing in the header or footer text.
 These macros are Berkeley extensions.
 .
 .
+.br
+.ne 5v
 .TP
 .BR .OH \~\[aq]\c
 .IR left \[aq] center \[aq] right \[aq]
@@ -1802,12 +1811,13 @@ The
 .B OH
 and
 .B EH
-macros define headers for the odd and even pages;
+macros define headers for odd- (recto) and even-numbered (verso) pages,
+respectively;
 the
 .B OF
 and
 .B EF
-macros define footers for the odd and even pages.
+macros define footers for them.
 .
 .
 .P
@@ -1978,7 +1988,7 @@ that page numbers not be repeated.
 You may wish to indent the text thus wrapped to correspond to its
 heading depth;
 this can be done in the entry text by prefixing it with tabs or
-horizontally spacing escape sequences,
+horizontal motion escape sequences,
 or by providing a second argument to the
 .B XA
 macro.