[groff] 07/40: Document ms FR string more.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 3945b4dfcf225d6832e1b8b9ecd8b7df6508dd24
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Feb 6 13:23:46 2021 +1100

    Document ms FR string more.
    
    * NEWS: Add news item.
    * doc/groff.texi (ms Document Control Settings): Clarify when changes to
      FR take effect.  Add motivation for new string and its default value.
      Advise users to migrate from \n[FL] (now otherwise undocumented) to
      \*[FR].  Explain how to simulate old absolute setting effect of \n[FL]
      for those whose recall of *roff arithmetic and/or the zero product
      property is poor.  Supply example.
    * doc/ms.ms (Document control settings): Sync with the above.
    * tmac/groff_ms (Usage/Document control registers): Drop documentation
      of FL register.  Clarify when changes to FR take effect.
---
 NEWS                | 22 ++++++++++++++++++----
 doc/groff.texi      | 35 ++++++++++++++++++++++++-----------
 doc/ms.ms           | 39 +++++++++++++++++++++++++++++++++++----
 tmac/groff_ms.7.man | 13 +++++++------
 4 files changed, 84 insertions(+), 25 deletions(-)

diff --git a/NEWS b/NEWS
index 69ceb6e..017e450 100644
--- a/NEWS
+++ b/NEWS
@@ -118,10 +118,24 @@ o The doc (mdoc) macro package now honors the HY register 
as the an
   furthermore recognizes but ignores the AD string (see above) for
   compatibility with an (man).
 
-o The s (ms) macro package has changed the default footnote line length
-  (\n[FL]) from 5/6ths of the text line length (\n[LL]) to 11/12ths for
-  better compatibility with ms documents prepared with AT&T ms or its
-  descendant implementations in Heirloom Doctools and neatroff.
+o The s (ms) macro package supports a new string, FR, which defines the
+  ratio of the footnote line length to the current line length.
+  The default expression is "11/12", 11/12ths of the normal line length,
+  adopted for better compatibility with ms documents prepared with AT&T
+  ms or its descendant implementations in Heirloom Doctools and
+  neatroff.  This is a change from previous groff releases, which used a
+  ratio of 5/6ths.
+
+  You may wish to set the FR string to 1 to align with contemporary
+  typesetting practices.  In Version 7 Unix ms, its descendants, and
+  groff prior to this release, an FL register was used for the line
+  length in footnotes; however, setting this register at document
+  initialization time had no effect on the footnote line length in
+  multi-column arrangements.
+
+  FR should be used in preference to the old FL register in contemporary
+  documents.  See the groff Texinfo manual or the "Using groff with the
+  ms macros" document, also part of this release, for more information.
 
 o The s (ms) macro package has added strings, \*< and \*>, to perform
   subscripting within a paragraph.  They work analogously to the \*{ and
diff --git a/doc/groff.texi b/doc/groff.texi
index 01b9e20..8eb4822 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2633,8 +2633,8 @@ your document, or just after the @code{RP} macro.  You 
can set other
 registers later in your document, but you should keep them together at
 the beginning to make them easy to find and edit as necessary.
 
-A list of document control registers (and one string) follows.  They are
-presented in the syntax used to interpolate them.
+A list of document control registers (and two strings) follows.  They
+are presented in the syntax used to interpolate them.
 
 @unnumberedsubsubsec Margin Settings
 
@@ -2809,14 +2809,6 @@ Default: 1.
 
 @unnumberedsubsubsec Footnote Settings
 
-@Defmpreg {FL, ms}
-Defines the length of a footnote.
-
-Effective: next footnote.
-
-Default: @math{@code{@\n[LL]} * 11 / 12}.
-@endDefmpreg
-
 @Defmpreg {FI, ms}
 Defines the footnote indentation.
 
@@ -2878,11 +2870,32 @@ Default: @math{@code{@\n[PD]} / 2}.
 Defines the ratio of the footnote line length to the current line
 length.
 
-Effective: start of document or before each @code{.MC} or @code{.2C}.
+Effective: next footnote in single-column arrangements, next page
+otherwise.
 
 Default: @math{11/12}.
 @endDefmpreg
 
+The default footnote line length is 11/12ths of the normal line length
+for compatibility with the expectations of historical @file{ms}
+documents; you may wish to set the @code{FR} string to @samp{1} to align
+with contemporary typesetting practices.  In the past,@footnote{in
+Version 7 Unix @file{ms}, its descendants, and GNU @file{ms} prior to
+@code{groff} version 1.23.0} an @code{FL} register was used for the line
+length in footnotes; however, setting this register at document
+initialization time had no effect on the footnote line length in
+multi-column arrangements.
+
+@code{FR} should be used in preference to the old @code{FL} register in
+contemporary documents.  The footnote line length is effectively
+computed as @samp{\n[@slanted{column-width}] * \*[FR]}.  If an absolute
+footnote line length is required, recall that arithmetic expressions in
+@code{roff} languages are evaluated from left to right.
+
+@Example
+.ds FR 0+3i
+@endExample
+
 @unnumberedsubsubsec Miscellaneous Registers
 
 @Defmpreg {MINGW, ms}
diff --git a/doc/ms.ms b/doc/ms.ms
index be60033..3ee243b 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -264,13 +264,14 @@ Paragraphs        \[rs]n[PI]      Initial indent  next 
\(pp       5n
 \^     \[rs]n[PD]      Space between paragraphs        next \(pp       0.3v
 \^     \[rs]n[QI]      Quoted paragraph indent next \(pp       5n
 _
-Footnotes      \[rs]*[FR]      Footnote length ratio   next footnote   11/12
+Footnotes      \[rs]*[FR]      Footnote length ratio   special 11/12
 \^     \[rs]n[FI]      Footnote indent next footnote   2n
 \^     \[rs]n[FF]      Footnote format next footnote   0
 _
 Other  \[rs]n[MINGW]   Minimum width between columns   next page       2n
 .TE
 .
+.
 .PP
 The default footnote line length is 11/12ths of the normal line length
 for compatibility with the expectations of historical
@@ -280,7 +281,7 @@ you may wish to set
 .CW \[rs]*[FR]
 to
 .CW 1
-to suit contemporary typesetting practices.
+to align with contemporary typesetting practices.
 .
 In the past,\**
 .FS
@@ -297,8 +298,38 @@ an
 .CW FL
 register was used for the line length in footnotes;
 however,
-setting this register had no effect on the footnote line length in
-multi-column environments.
+setting this register at document initialization time had no effect on
+the footnote line length in multi-column arrangements.
+.
+.
+.PP
+.CW \[rs]*[FR]
+should be used in preference to
+.CW \[rs]n[FL]
+in contemporary documents.
+.
+The footnote line length is effectively computed as
+.CW "\[rs]n[\f[I]column-width\f[]] * \[rs]*[FR]" \[rq]. \[lq]
+.
+If an absolute footnote line length is required,
+recall that arithmetic expressions in
+.I roff
+languages are evaluated from left to right.
+.
+.
+.DS
+.CW
+\&.ds FR 0+3i
+.R
+.DE
+.
+.
+.PP
+Changes to the footnote length ratio
+.CW \[rs]*[FR]
+take effect with the next footnote written in single-column
+arrangements,
+but on the next page in multiple-column contexts.
 .
 .
 .\" ------------------------
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 35ef453..66b18e6 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -237,17 +237,12 @@ cb   cb cb cb
 lfCR l  l  l.
 Reg.   Definition      Effective       Default
 _
-FL     Footnote length T{
-next footnote; not effective in multicolumn mode
-T}     \[rs]n[LL]*\[rs]*[FR]
 FI     Footnote indent next footnote   2n
 FF     Footnote format next footnote   0
 FPS    Point size      next footnote   \[rs]n[PS]\-2
 FVS    Vert.\& spacing next footnote   \[rs]n[FPS]+2
 FPD    Para.\& spacing next footnote   \[rs]n[PD]/2
-FR     Footnote ratio  T{
-before first paragraph, or before each .MC
-T}     11/12
+FR     Line length ratio       special 11/12
 _
 .TE
 .RE
@@ -259,6 +254,12 @@ is a string and should be set with the
 .B .ds
 request.
 .
+Changes to the footnote line length ratio
+.B \[rs]*[FR]
+take effect with the next footnote written in single-column
+arrangements,
+but on the next page in multiple-column contexts.
+.
 .
 .LP
 .ne 6