[groff] 05/09: [docs]: Update and sync ms FS-MARK material.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 95af210cf6f3c6d87419f8c8940d8f2c7a544325
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Oct 11 06:24:18 2021 +1100

    [docs]: Update and sync ms FS-MARK material.
    
    Also add a NEWS item for it.
---
 NEWS                |  8 ++++++++
 doc/groff.texi      | 21 ++++++++++++++-----
 doc/ms.ms           | 42 ++++++++++++++++++++++++++++++++++++--
 tmac/groff_ms.7.man | 58 ++++++++++++++++++++++++-----------------------------
 4 files changed, 90 insertions(+), 39 deletions(-)

diff --git a/NEWS b/NEWS
index 3b0f8b1..5fb23fb 100644
--- a/NEWS
+++ b/NEWS
@@ -246,6 +246,14 @@ o The s (ms) macro package has added strings, \*< and \*>, 
to perform
   subscripting.  They work analogously to the \*{ and \*} superscripting
   strings that have been present in groff ms since 1991 or earlier.
 
+o The s (ms) macro package has added a hook macro, FS-MARK, which is
+  called automatically by the FS macro (with same arguments given to FS)
+  before any other footnote processing.  It is empty by default but can
+  be defined by the user to, for example, place a hyperlink anchor so
+  that a link within a footnote can return to its referential context.
+  "Portable Document Format Publishing with GNU Troff", distributed with
+  groff as pdfmark.ms, uses this technique.
+
 grotty
 ------
 
diff --git a/doc/groff.texi b/doc/groff.texi
index 489cd9a..26bc618 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -3874,11 +3874,12 @@ page.
 
 @DefmacList {FS, [@Var{marker}], ms}
 @DefmacListEndx {FE, , ms}
-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.
+Begin (@code{FS}) and end (@code{FE}) a footnote.  @code{FS} calls
+@code{FS-MARK} with any supplied @var{marker} argument, which is then
+also 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 may not desire automatically numbered footnotes in spite of their
@@ -3891,6 +3892,16 @@ correspondence.  You may wish to use @code{\*@{} and 
@code{\*@}} to
 superscript the marker at the anchor point, in the footnote text, or
 both.
 
+@code{groff} @file{fs} provides a hook macro, @code{FS-MARK}, for
+user-determined operations to be performed when the @code{FS} macro is
+called.  It is passed the same arguments as @code{FS} itself.  An
+application of @code{FS-MARK} is anchor placement for a hyperlink
+reference, so that a footnote can link back to its referential
+context.@footnote{``Portable Document Format Publishing with GNU
+Troff'', @file{pdfmark.ms} in the @code{groff} distribution, uses this
+technique.}  By default, this macro has an empty definition.
+@code{FS-MARK} is a GNU extension.
+
 @cindex footnotes, and keeps [@code{ms}]
 @cindex keeps, and footnotes [@code{ms}]
 @cindex footnotes, and displays [@code{ms}]
diff --git a/doc/ms.ms b/doc/ms.ms
index 35776ec..90ba8ca 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -2204,9 +2204,14 @@ _
 \&.FS \f[R][\f[I]marker\f[]]   T{
 Begin a footnote.
 .
-A
+The
+.CW FS\-MARK
+hook
+(see below)
+is called with any supplied
 .I marker
-argument is placed at the beginning of the footnote text.
+argument,
+which is then also placed at the beginning of the footnote text.
 .
 If
 .I marker
@@ -2253,6 +2258,39 @@ or both.
 .
 .
 .PP
+.I "groff ms"
+provides a hook macro,
+.CW FS\-MARK ,
+for user-determined operations to be performed when the
+.CW FS
+macro is called.
+.
+It is passed the same arguments as
+.CW FS
+itself.
+.
+An application of
+.CW FS\-MARK
+is anchor placement for a hyperlink reference,
+so that a footnote can link back to its referential context.\**
+.
+.FS
+\[lq]Portable Document Format Publishing with GNU Troff\[rq],
+.I pdfmark.ms
+in the
+.I groff
+distribution,
+uses this technique.
+.FE
+.
+By default,
+this macro has an empty definition.
+.
+.CW FS\-MARK
+is a GNU extension.
+.
+.
+.PP
 The following input was used to produce the first sentence in this
 section.
 .
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 8a23709..e36a8b5 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1440,9 +1440,14 @@ of a text column or page.
 .RI \~[ marker ]
 Begin a footnote.
 .
-A
+The
+.B .FS\-MARK
+hook
+(see below)
+is called with any supplied
 .I marker
-argument is placed at the beginning of the footnote text.
+argument,
+which is then also placed at the beginning of the footnote text.
 .
 If
 .I marker
@@ -1454,36 +1459,6 @@ string is used,
 and if none exists,
 nothing is prefixed.
 .
-.IP
-Immediately,
-on entry to
-.BR FS ,
-a macro named
-.B FS-MARK
-is called,
-passing the same
-.I marker
-argument
-(if any)
-as passed to
-.B FS
-itself.
-By default,
-this macro does nothing;
-however,
-you may define an alternative implementation of
-.BR FS-MARK ,
-if,
-for example,
-you require some additional action
-on placement of the footnote
-.IR marker ,
-or footnote number,
-in the body text,
-beyond that which can be achieved by simple interpolation of the
-.B *
-string.
-.
 .
 .TP
 .B .FE
@@ -1491,6 +1466,25 @@ End footnote text.
 .
 .
 .P
+.I groff ms
+provides a hook macro,
+.BR FS\-MARK ,
+for user-determined operations to be performed when the
+.B FS
+macro is called.
+.
+It is passed the same arguments as
+.B .FS
+itself.
+.
+By default,
+this macro has an empty definition.
+.
+.B .FS\-MARK
+is a GNU extension.
+.
+.
+.P
 Footnote text is formatted as paragraphs are,
 using analogous parameters.
 .