[groff] 11/29: [ms]: Update discussion of footnote paragraphing.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 29f3a7b9e2b5632d547f218b69ec39d40712d635
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Apr 17 16:35:56 2022 +1000

    [ms]: Update discussion of footnote paragraphing.
    
    * Introduce term "automatic number" to (somewhat) abbreviate the
      sesquipedialian alternative "automatically generated footnote number".
    
    * tmac/groff_ms.7.man: Undocument FP macro, partially reverting
      4aae5708b, 1 October.  As noted in
      <https://savannah.gnu.org/bugs/?61022>, we should probably gate this
      macro name behind some sort of compatibility selector, perhaps a
      string which the user can set to "ATT" or "BSD" (or a default, "GNU").
      This string would also affect the semantics of "P1" and potentially
      "TM" (which means incompatible things in the AT&T and Berkeley ms
      traditions, but GNU ms supports neither).
---
 doc/groff.texi      | 20 +++++++++--------
 doc/ms.ms           | 17 +++++++++-----
 tmac/groff_ms.7.man | 64 +++++++++++------------------------------------------
 3 files changed, 35 insertions(+), 66 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index be458a38..ab6bbaa3 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2914,10 +2914,11 @@ 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 an automatic number as a superscript (on typesetter devices) or
-surrounded by square brackets (on terminals).  The footnote paragraph is
-indented as with @code{PP} if there is an @code{FS} argument or an
-automatic number, and as with @code{LP} otherwise.  This is the default.
+Set an automatic number@footnote{defined in @ref{ms Footnotes}) below}
+as a superscript (on typesetter devices) or surrounded by square
+brackets (on terminals).  The footnote paragraph is indented as with
+@code{PP} if there is an @code{FS} argument or an automatic number, and
+as with @code{LP} otherwise.  This is the default.
 
 @item 1
 As @code{0}, but set the marker as regular text and follow an
@@ -3945,9 +3946,10 @@ A footnote is typically anchored to a place in the text 
with a
 arbitrary user-specified text.
 
 @Defmpstr {*, ms}
-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.
+Place an @dfn{automatic number}, an automatically generated numeric
+footnote marker, in the text.  Each time this string is interpolated,
+the number it produces increments by one.  Automatic numbers start at 1.
+This is a Berkeley extension.
 @endDefesc
 
 Enclose the footnote text in @code{FS} and @code{FE} macro calls to set
@@ -4002,8 +4004,8 @@ parameters.  The registers @code{FI}, @code{FPD}, 
@code{FPS}, and
 respectively.
 
 The @code{FF} register controls the formatting of automatically numbered
-footnotes and those for which @code{FS} is given a marker argument.
-@xref{ms Document Control Settings}.
+footnote paragraphs and those for which @code{FS} is given a marker
+argument.  @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 76772dd7..450f3b87 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -2232,12 +2232,15 @@ lf(CR) lx.
 String Description
 _
 \[rs]**        T{
-Place an automatically numbered footnote marker in the text.
+Place an
+.I automatic number,
+an automatically generated numeric footnote marker,
+in the text.
 .
 Each time this string is interpolated,
 the number it produces increments by one.
 .
-Automatic footnote numbers start at 1.
+Automatic numbers start at 1.
 .
 This is a Berkeley extension.
 T}
@@ -2275,8 +2278,7 @@ which is then also placed at the beginning of the 
footnote text.
 If
 .I marker
 is omitted,
-the next pending automatic footnote number enqueued by interpolation of
-the
+the next pending automatic number enqueued by interpolation of the
 .CW *
 string is used,
 and if none exists,
@@ -2417,10 +2419,13 @@ respectively.
 .PP
 The
 .CW FF
-register controls the formatting of automatically numbered footnotes,
+register controls the formatting of automatically numbered footnote
+paragraphs,
 and those for which
 .CW .FS
-is given a marker argument,
+is given a
+.I marker
+argument,
 at the bottom of a column or page as follows.
 .
 .
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 5d2b0b9f..708dc394 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1502,12 +1502,15 @@ or arbitrary user-specified text.
 .
 .TP
 .B \[rs]**
-Place an automatically numbered footnote marker in the text.
+Place an
+.I automatic number,
+an automatically generated numeric footnote marker,
+in the text.
 .
 Each time this string is interpolated,
 the number it produces increments by one.
 .
-Automatic footnote numbers start at 1.
+Automatic numbers start at 1.
 .
 This is a Berkeley extension.
 .
@@ -1539,8 +1542,7 @@ which is then also placed at the beginning of the 
footnote text.
 If
 .I marker
 is omitted,
-the next pending automatic footnote number enqueued by interpolation of
-the
+the next pending automatic number enqueued by interpolation of the
 .B *
 string is used,
 and if none exists,
@@ -1591,33 +1593,22 @@ respectively.
 .
 .
 .P
-Paragraph-level formatting of footnotes is performed by a macro named
-.BR FP ,
-which is called once for each individual footnote.
-A default implementation of
-.B FP
-is provided;
-alternatively,
-you may define your own replacement implementation,
-and so assert your own control over footnote paragraph formatting.
-.
-.P
-When using the default implementation of
-.BR FP ,
-the
+The
 .B FF
-register controls the formatting of automatically numbered footnotes,
+register controls the formatting of automatically numbered footnote
+paragraphs,
 and those for which
 .B .FS
 is given a
 .I marker
 argument,
-at the bottom of a column or page as follows:-
+at the bottom of a column or page as follows.
+.
 .
 .RS
 .TP
 0
-Set an automatically generated number,
+Set an automatic number,
 or a specified
 .B FS
 .I marker
@@ -1644,7 +1635,7 @@ This is the default.
 As
 .BR 0 ,
 but set the marker as regular text,
-and follow an automatically generated number with a period.
+and follow an automatic number with a period.
 .
 .
 .TP
@@ -1666,35 +1657,6 @@ but set the footnote paragraph with the marker hanging
 .RE
 .
 .
-.P
-Conversely,
-if you choose to provide your own
-.B FP
-macro implementation,
-.I you
-have control of how footnote paragraphs will be formatted;
-it is your choice as to how the
-.B FF
-register should be interpreted,
-(if at all).
-For each individual footnote,
-your macro will be called with one argument,
-which represents either an automatically generated footnote number,
-or the verbatim
-.I marker
-argument passed in the initiating
-.B FS
-macro call;
-in the latter case,
-an explicit second argument of
-.RB \[lq] no \[rq]
-will also be present,
-indicating that no embellishment of the footnote
-.I marker
-(as may be appropriate for footnote numbers)
-is required.
-.
-.
 .\" ====================================================================
 .SS "Headers and footers"
 .\" ====================================================================