[groff] 05/05: [ms]: Update footnote documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit b054ed29c152a60bdb126bea6f02a9340163262b
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Apr 9 10:17:34 2021 +1000

    [ms]: Update footnote documentation.
    
    * doc/groff.texi (ms Document Control Settings) <FF>: Update description
      to cover application of footnote format to footnote markers in
      general, not just numbers.  Clarify different behavior of format 1
      with respect to automatic numbers and other markers.
    
      (ms Footnotes): Recast introductory paragraph to drop promotional
      language in favor of describing functionality.  Add concept index
      entry for "footnote marker".  Shift string and macro descriptions from
      sentence fragments to statements in the imperative mood.  Expand
      advice on usage of footnote markers.  Discuss configurable footnote
      parameters with link to "ms Document Control Settings" node.
    
      <*>: Describe string operation in more detail.
    
      <FS>: Describe more precisely how the optional argument is handled.
    
    * doc/ms.ms (Footnotes): Bracket section heading and lead paragraph in a
      keep.  Synchronize with doc/groff.texi.  Add example using document's
      own text as a model.  Move paragraph discussing footnote usage in
      keeps and displays to precede (new) discussion of footnote formatting.
    
    * tmac/groff_ms.7.man (Usage/Footnotes): Resync relevant portions with
      doc/ms.ms.
    
    Fixes <https://savannah.gnu.org/bugs/?60227>.
---
 ChangeLog           |  19 +++++
 doc/groff.texi      |  70 +++++++++-------
 doc/ms.ms           | 226 ++++++++++++++++++++++++++++++++++++++--------------
 tmac/groff_ms.7.man | 118 ++++++++++++++-------------
 4 files changed, 290 insertions(+), 143 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index c12a321..ddaed14 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,22 @@
+2021-04-08  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * doc/groff.texi (ms Document Control Settings) <FF>: Update
+       description to cover application of footnote format to footnote
+       markers in general, not just numbers.  Clarify different
+       behavior of format 1 with respect to automatic numbers and other
+       markers.
+       (ms Footnotes) <*>: Describe string operation in more detail.
+       <FS>: Describe more precisely how the optional argument is
+       handled.
+
+       * doc/ms.ms (Footnotes): Synchronize with doc/groff.texi.  Add
+       example using document's own text as a model.
+
+       * tmac/groff_ms.7.man (Usage/Footnotes): Resync relevant
+       portions with doc/ms.ms.
+
+       Fixes <https://savannah.gnu.org/bugs/?60227>.
+
 2021-04-06  Dave Kemper <saint.snit@gmail.com>
 
        * src/roff/nroff/nroff.sh: Recognize -k and -K options and pass
diff --git a/doc/groff.texi b/doc/groff.texi
index ceaf427..e72f3bd 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2818,25 +2818,23 @@ Default: 2@dmn{n}.
 @endDefmpreg
 
 @Defmpreg {FF, ms}
-Defines the format of
-automatically numbered @c see Savannah #60227
-footnotes at the bottom of a column or page.  This is a Berkeley
-extension.
+Defines the format of automatically numbered footnotes,
+and those for which the @code{FS} request is given a marker argument, at
+the bottom of a column or page.  This is a Berkeley extension.
 @table @code
 @item 0
-Set the footnote number as a superscript; indent the footnote text
+Indent the footnote paragraph and set the marker as a superscript
 (default).
 
 @item 1
-Set the number followed by a period (that is, ``1.@:'') and indent the
-footnote text.
+Like @code{0}, but set the marker as regular text and follow an
+automatic number with a period.
 
 @item 2
-Like @code{1}, but without an indentation.
+Like @code{1}, but without indentation.
 
 @item 3
-Like @code{1}, but set the footnote text as a paragraph with the number
-hanging.
+Like @code{1}, but set the footnote paragraph with the marker hanging.
 @end table
 
 Effective: next footnote.
@@ -3764,36 +3762,54 @@ l | l .
 @cindex @code{ms} macros, footnotes
 @cindex footnotes [@code{ms}]
 
-The @file{ms} macro package has a flexible footnote system.  You can
-specify either numbered footnotes or symbolic footnotes (that is, using
-a marker such as a dagger symbol).
+@cindex footnote marker [@code{ms}]
+@cindex marker, footnote [@code{ms}]
+A footnote is typically anchored to a place in the text with a
+@dfn{marker}, which is a small integer, a symbol such as a dagger, or
+arbitrary user-specified text.  The footnote text is set at the nearest
+available ``foot'', or bottom, of a text column or page.
+
+Automatic numbering of footnotes is available.
 
 @Defstr {*, ms}
-Specifies the location of a numbered footnote marker in the text.
+Place an automatically numbered footnote marker in the text.  Each time
+this string is interpolated, the number it produces increments by one.
+Automatic footnote numbers start at 1.  This is a Berkeley extension.
 @endDefesc
 
-@DefmacList {FS, , ms}
+@DefmacList {FS, [@Var{marker}], ms}
 @DefmacListEndx {FE, , ms}
-Specifies the text of the footnote.  The default action is to create a
-numbered footnote; you can create a symbolic footnote by specifying a
-@dfn{mark} glyph (such as @code{\[dg]} for the dagger glyph) in the body
-text and as an argument to the @code{FS} macro, followed by the text of
-the footnote and the @code{FE} macro.
+Begin (@code{FS}) and end (@code{FE}) a footnote.  A @var{marker}
+argument is placed at the beginning of the footnote text.  If
+@var{marker} is omitted, the next pending automatic footnote number
+enqueued by interpolation of the @code{*} string is used, and if none
+exists, nothing is prefixed.
 @endDefmac
 
-You can control how @file{ms} prints footnote numbers by changing the
-value of the @code{FF} register.  @xref{ms Document Control Settings}.
+You may not desire automatically numbered footnotes in spite of their
+convenience.  You can indicate a footnote with a symbol or other text by
+specifying its marker at the appropriate place (for example, by using
+@code{\[dg]} for the dagger glyph) @emph{and} as an argument to the
+@code{FS} macro.  Such manual marks should be repeated as arguments to
+@code{FS} or as part of the footnote text to disambiguate their
+correspondence.  You may wish to use @code{\*@{} and @code{\*@}} to
+superscript the marker at the anchor point, in the footnote text, or
+both.
 
 @cindex footnotes, and keeps [@code{ms}]
 @cindex keeps, and footnotes [@code{ms}]
 @cindex footnotes, and displays [@code{ms}]
 @cindex displays, and footnotes [@code{ms}]
 Footnotes can be safely used within keeps and displays, but you should
-avoid using numbered footnotes within floating keeps.  You can set a
-second @code{\**} marker between a @code{\**} and its corresponding
-@code{FS} entry; as long as each @code{FS} macro occurs @emph{after}
-the corresponding @code{\**} and the occurrences of @code{FS} are in
-the same order as the corresponding occurrences of @code{\**}.
+avoid using automatically numbered footnotes within floating keeps.  You
+can place a second @code{\**} interpolation between a @code{\**} and its
+corresponding @code{FS} call as long as each @code{FS} call occurs
+@emph{after} the corresponding @code{\**} and the occurrences of
+@code{FS} are in the same order as the corresponding occurrences of
+@code{\**}.  You can control how @file{ms} presents footnotes by
+changing the values of the @code{FI}, @code{FF}, @code{FPS}, @code{FVS},
+and @code{FPD} registers; and the @code{FR} string.  @xref{ms Document
+Control Settings}.
 
 The default footnote line length is 11/12ths of the normal line length
 for compatibility with the expectations of historical @file{ms}
diff --git a/doc/ms.ms b/doc/ms.ms
index 0191d64..d5518c3 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -1835,6 +1835,7 @@ particularly if the
 option is used.
 .
 .
+.KS
 .NH 2
 Footnotes
 .XS
@@ -1843,100 +1844,205 @@ Footnotes
 .
 .
 .LP
-The
-.I ms
-macros provide a flexible footnote system.
-.
-You can specify a numbered footnote\**
+.\" 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 ,
+which is a small integer\**,
 .FS
-This is a numbered footnote.
+like this numeric footnote
+.FE
+a symbol\[dg],
+.FS \[dg]
+like this symbolic footnote
 .FE
-by using the
-.CW \\\\**
-escape,
-followed by the text of the footnote enclosed by
+or arbitrary user-specified text.
+.
+The footnote text is set at the nearest available \[lq]foot\[rq],
+or bottom,
+of a text column or page.
+.KE
+.
+.
+.PP
+Automatic numbering of footnotes is available.
+.
+The
+.CW *
+string places such a footnote marker in the text.
+.
+Each time this string is interpolated,
+the number it produces increments by one.
+.
+Automatic footnote numbers start at 1.
+.
+This is a Berkeley extension.
+.
+.
+.TS
+box;
+cb cb
+lfCR lx .
+Macro  Description
+_
+\&.FS \f[R][\f[I]marker\f[]]   T{
+Begin a footnote.
+.
+A
+.I marker
+argument is placed at the beginning of the footnote text.
+.
+If
+.I marker
+is omitted,
+the next pending automatic footnote number enqueued by interpolation of
+the
+.CW *
+string is used,
+and if none exists,
+nothing is prefixed.
+.
+T}
+_
+\&.FE  End footnote text.
+.TE
+.
+.
+.PP
+You may not desire automatically numbered footnotes in spite of their
+convenience.
+.
+You can indicate a footnote with a symbol or other text by specifying
+its marker at the appropriate place
+(for example,
+by using
+.CW \[rs][dg]
+for the dagger glyph)
+.I and
+as an argument to the
+.CW FS
+macro.
+.
+Such manual marks should be repeated as arguments to
 .CW .FS
+or as part of the footnote text to disambiguate their correspondence.
+.
+You may wish to use
+.CW \[rs]*{
 and
-.CW .FE
-macros.
+.CW \[rs]*}
+to superscript the marker at the anchor point,
+in the footnote text,
+or both.
 .
 .
 .PP
-You can specify symbolic footnotes\[dg]
-.FS
-\[dg]This is a symbolic footnote.
-.FE
-by placing the mark character
-(such as
-.CW \\\\[dg]
-for the
-.if !'\[dg]'*' dagger
-character used here),
-followed by the symbol and the text of the footnote enclosed by
+The following input was used to produce the first sentence in this
+section.
+.
+.
+.TS
+box center;
+lfCR.
+A footnote is anchored to a place in the text with a
+\&.I marker ,
+which is a small integer\[rs]**,
+\&.FS
+like this numeric footnote
+\&.FE
+a symbol\[rs][dg],
+\&.FS \[rs][dg]
+like this symbolic footnote
+\&.FE
+or arbitrary user-specified text.
+.TE
+.
+.
+.PP
+Footnotes can be safely used within keeps and displays,
+but you should avoid using automatically numbered footnotes within
+floating keeps.
+.
+You can place a second
+.CW \[rs]**
+interpolation between a
+.CW \[rs]**
+and its corresponding
+.CW .FS
+call as long as each
 .CW .FS
+call 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]** .
+.
+.
+.PP
+Footnote text is formatted as paragraphs are,
+using analogous parameters.
+.
+The registers
+.CW FI ,
+.CW FPD ,
+.CW FPS ,
 and
-.CW .FE
-macros.
+.CW FVS
+correspond to
+.CW PI ,
+.CW PD ,
+.CW PS ,
+and
+.CW VS ,
+respectively.
+.
+See section \[lq]Document control settings\[rq] above.
 .
 .
 .KS
 .PP
-You can control how
-.I ms
-prints footnote numbers by changing the value of the
+The
 .CW FF
-register as follows.
+register controls the formatting of automatically numbered footnotes,
+and those for which
+.CW .FS
+is given a marker argument,
+at the bottom of a column or page as follows.
 .
 .
 .TS
 box;
 cb cb
 lf(CR) lx .
-Value  Description
+\f[CB]FF\f[] value     Description
 _
 0      T{
-Prints the footnote number as a superscript and indents the footnote
+Indent the footnote paragraph and set the marker as a superscript
 (default).
 T}
 1      T{
-Prints the number followed by a period
-(that is,\~\[lq]1.\[rq]\&)
-and indents the footnote.
+Like
+.CW 0 ,
+but set the marker as regular text,
+and follow an automatic number with a period.
 T}
 2      T{
-Like\~1,
-without an indent.
+Like
+.CW 1 ,
+but without indentation.
 T}
 3      T{
-Like\~1,
-but prints the footnote number as a paragraph with a hanging indent.
+Like
+.CW 1 ,
+but set the footnote paragraph with the marker hanging.
 T}
 .TE
 .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]** .
-.
-.
 .PP
 The default footnote line length is 11/12ths of the normal line length
 for compatibility with the expectations of historical
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index b82532b..4ca40e0 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1171,90 +1171,96 @@ option is used.
 .SS Footnotes
 .\" ====================================================================
 .
-The
-.I ms
-macros provide a flexible footnote system.
+A footnote is typically anchored to a place in the text with a
+.I marker ,
+which is a small integer,
+a symbol,
+or arbitrary user-specified text.
 .
-You can specify a numbered footnote by using the
-.B \[rs]**
-escape,
-followed by the text of the footnote enclosed by
-.B FS
-and
-.B FE
-macros.
+The footnote text is set at the nearest available \[lq]foot\[rq],
+or bottom,
+of a text column or page.
 .
 .
 .PP
-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]
-and
-.B FE
-macros.
+Automatic numbering of footnotes is available.
 .
+The
+.B *
+string places such a footnote marker in the text.
 .
-.PP
-You can control how
-.I ms
-prints footnote numbers by changing the value of the
+Each time this string is interpolated,
+the number it produces increments by one.
+.
+Automatic footnote numbers start at 1.
+.
+This is a Berkeley extension.
+.
+.
+.TP
+.B .FS\c
+.RI \~[ marker ]
+Begin a footnote.
+.
+A
+.I marker
+argument is placed at the beginning of the footnote text.
+.
+If
+.I marker
+is omitted,
+the next pending automatic footnote number enqueued by interpolation of
+the
+.B *
+string is used,
+and if none exists,
+nothing is prefixed.
+.
+.
+.TP
+.B .FE
+End footnote text.
+.
+.
+The
 .B FF
-register as follows.
+register controls the formatting of automatically numbered footnotes,
+and those for which
+.B .FS
+is given a marker argument,
+at the bottom of a column or page as follows.
 .
 .
 .RS
 .TP
 0
-Prints the footnote number as a superscript and indents the footnote
+Indent the footnote paragraph and set the marker as a superscript
 (default).
 .
 .
 .TP
 1
-Prints the number followed by a period
-(that is,\~\[lq]1.\[rq]\&)
-and indents the footnote.
+Like
+.BR 0 ,
+but set the marker as regular text,
+and follow an automatic number with a period.
 .
 .
 .TP
 2
-Like\~1,
-without an indent.
+Like
+.BR 1 ,
+but without indentation.
 .
 .
 .TP
 3
-Like\~1,
-but prints the footnote number as a paragraph with a hanging
-indent.
+Like
+.BR 1 ,
+but set the footnote paragraph with the marker hanging.
 .RE
 .
 .
-.PP
-You can use footnotes safely within keeps and displays,
-but avoid using numbered footnotes within floating keeps.
-.
-You can set a second
-.B \[rs]**
-between a
-.B \[rs]**
-and its corresponding
-.BR .FS ,
-as long as each
-.B .FS
-occurs
-.I after
-the corresponding
-.B \[rs]**
-and the occurrences of
-.B .FS
-are in the same order as the corresponding occurrences of
-.BR \[rs]** .
-.
-.
 .\" ====================================================================
 .SS "Headers and footers"
 .\" ====================================================================