[groff] 25/40: [docs]: Sync ms footnote material.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit dadefabbdbe8a5ec4cadedbbea341489a23ff06e
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Feb 8 18:37:16 2021 +1100

    [docs]: Sync ms footnote material.
    
    Parallelize discussions and make style updates.  These sections are now
    duplicative; in the future I plan to cut groff_ms(7) down to a set of
    reference tables, but doc/ms.ms needs to be brought fully up to date
    first.
    
    * doc/groff.texi
      - (ms Document Control Settings): Supply example of how to set an
        absolute footnote line length.
      - (ms Footnotes) Clarify that ms (instead of groff) determines
        footnote formatting (groff simply does what it's told).
    
    * doc/ms.ms (Footnotes):
      - Use two empty requests where vertical space is expected.
      - Refer to package as "ms" instead of "-ms".  The latter is an
        antiquarian naming convention that invites arguments over whether
        the hyphen should be escaped.
      - Break input lines at commas.
      - Use groff-style special character escapes \[] instead of \(.
      - Recast symbolic footnote explanation.
      - Fix colon-terminated sentence fragments; see commit 3afcaf0e.
      - Bracket table with .na/.ad to improve text block layout.  We can do
        this--it's ms, not man!
      - Set multi-word parentheticals on their own input lines.
      - Use \~ and \& escapes to improve breaking and spacing.
      - Port over paragraphs from groff_ms(7) regarding nesting of footnotes
        and their use in keeps and displays.
      - Supply example of how to set an absolute footnote line length.
      - Clarify that ms (instead of groff) determines footnote formatting
        (groff simply does what it's told).
    
    * tmac/groff_ms.7.man (Usage/Footnotes):
      - Break input lines at commas and semicolons.
      - Rewrap input lines.
      - Use groff-style special character escapes \[] instead of \(.
      - Use \~ escape to improve breaking.
      - Use two empty requests where vertical space is expected.
      - Fix grammar nit, using comma where a semicolon had been present.
      - Clarify that ms (instead of groff) determines footnote formatting
        (groff simply does what it's told).
---
 doc/groff.texi      |  4 +--
 doc/ms.ms           | 80 +++++++++++++++++++++++++++++++++++++++--------------
 tmac/groff_ms.7.man | 43 ++++++++++++++++------------
 3 files changed, 87 insertions(+), 40 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 88ffaa8..43a591a 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2891,7 +2891,7 @@ footnote line length is required, recall that arithmetic 
expressions in
 @code{roff} languages are evaluated from left to right.
 
 @Example
-.ds FR 0+3i
+.ds FR 0+3i \" Set footnote line length to 3 inches.
 @endExample
 
 @unnumberedsubsubsec Other Settings
@@ -3704,7 +3704,7 @@ text and as an argument to the @code{FS} macro, followed 
by the text of
 the footnote and the @code{FE} macro.
 @endDefmac
 
-You can control how @code{groff} prints footnote numbers by changing the
+You can control how @file{ms} prints footnote numbers by changing the
 value of the @code{FF} register.  @xref{ms Document Control Settings}.
 
 @cindex footnotes, and keeps [@code{ms}]
diff --git a/doc/ms.ms b/doc/ms.ms
index 21f0321..9a96efd 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -341,7 +341,7 @@ languages are evaluated from left to right.
 .
 .DS
 .CW
-\&.ds FR 0+3i
+\&.ds FR 0+3i \[rs]" Set footnote line length to 3 inches.
 .R
 .DE
 .
@@ -1190,46 +1190,55 @@ Footnotes
 .XS
        Footnotes
 .XE
+.
+.
 .LP
 The
-.I -ms
-macro package has a flexible footnote system.
+.I ms
+macros provide a flexible footnote system.
+.
 You can specify a numbered footnote\**
 .FS
 This is a numbered footnote.
 .FE
 by using the
 .CW \\\\**
-escape, followed by the text of the footnote
-enclosed by
+escape,
+followed by the text of the footnote enclosed by
 .CW .FS
 and
 .CW .FE
 macros.
+.
+.
 .PP
-You can specify symbolic footnotes\(dg
+You can specify symbolic footnotes\[dg]
 .FS
-\(dgThis is a symbolic footnote.
+\[dg]This is a symbolic footnote.
 .FE
-by placing the
-.if !'\[dg]'*' dagger
-character
+by placing the mark character
 (such as
-.CW \\\\(dg
-for the character used here),
-followed by the symbol and the text of the footnote
-enclosed by
+.CW \\\\[dg]
+for the
+.if !'\[dg]'*' dagger
+character used here),
+followed by the symbol and the text of the footnote enclosed by
 .CW .FS
 and
 .CW .FE
 macros.
+.
+.
 .KS
 .PP
 You can control how
-.I groff
+.I ms
 prints footnote numbers by changing the value of the
 .CW FF
-register as follows:
+register as follows.
+.
+.
+.na
 .TS
 box;
 cb cb
@@ -1237,18 +1246,49 @@ aw(0.75i) lw(5.25i) .
 Value  Description
 _
 0      T{
-Prints the footnote number as a superscript; indents the footnote (default).
+Prints the footnote number as a superscript and indents the footnote
+(default).
 T}
 1      T{
-Prints the number followed by a period (like 1.)
+Prints the number followed by a period
+(that is,\~\[lq]1.\[rq]\&)
 and indents the footnote.
 T}
-2      Like 1, without an indent.
+2      T{
+Like\~1,
+without an indent.
+T}
 3      T{
-Like 1, but prints the footnote number as a hanging paragraph.
+Like\~1,
+but prints the footnote number as a paragraph with a hanging indent.
 T}
 .TE
+.ad
 .KE
+.
+.
+.LP
+You can use footnotes safely within keeps and displays,
+but avoid using numbered footnotes within floating keeps.
+.
+You can set a second
+.CW \[rs]**
+between a
+.CW \[rs]**
+and its corresponding
+.CW .FS ,
+as long as each
+.CW .FS
+occurs
+.I after
+the corresponding
+.CW \[rs]**
+and the occurrences of
+.CW .FS
+are in the same order as the corresponding occurrences of
+.CW \[rs]** .
+.
+.
 .\" ------------------------
 .NH 1
 Page layout
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 7f39a0c..d6db9f3 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1139,8 +1139,8 @@ macros provide a flexible footnote system.
 .
 You can specify a numbered footnote by using the
 .B \[rs]**
-escape, followed by the text of the footnote
-enclosed by
+escape,
+followed by the text of the footnote enclosed by
 .B FS
 and
 .B FE
@@ -1148,13 +1148,12 @@ macros.
 .
 .
 .PP
-You can specify symbolic footnotes
-by placing the mark character (such as
-.B \[rs](dg
+You can specify symbolic footnotes by placing the mark character
+(such as
+.B \[rs][dg]
 for the dagger character) in the body text,
-followed by the text of the footnote
-enclosed by
-.B FS\ \[rs](dg
+followed by the text of the footnote enclosed by
+.B FS\~\[rs][dg]
 and
 .B FE
 macros.
@@ -1162,33 +1161,41 @@ macros.
 .
 .PP
 You can control how
-.I groff
+.I ms
 prints footnote numbers by changing the value of the
 .B FF
-register as follows:
-.RS
-.ne 7
+register as follows.
 .
+.
+.ne 7
+.RS
 .TP
 0
-Prints the footnote number as a superscript; indents the footnote
+Prints the footnote number as a superscript and indents the footnote
 (default).
 .
+.
 .TP
 1
-Prints the number followed by a period (that is,\~\[lq]1.\[rq]\&)
+Prints the number followed by a period
+(that is,\~\[lq]1.\[rq]\&)
 and indents the footnote.
 .
+.
 .TP
 2
-Like\~1, without an indent.
+Like\~1,
+without an indent.
+.
 .
 .TP
 3
-Like\~1, but prints the footnote number as a paragraph with a hanging
+Like\~1,
+but prints the footnote number as a paragraph with a hanging
 indent.
-.
 .RE
+.
+.
 .LP
 You can use footnotes safely within keeps and displays,
 but avoid using numbered footnotes within floating keeps.
@@ -1198,7 +1205,7 @@ You can set a second
 between a
 .B \[rs]**
 and its corresponding
-.BR .FS ;
+.BR .FS ,
 as long as each
 .B .FS
 occurs