[groff] [mom]: Add PREFIX and SUFFIX args to UNDERSCORE(2)

Prevents initial and terminating punctuation of underscored or
double-underscored text from being underscored.

Update ChangeLog and docs.

3 files changed, 96 insertions, 30 deletions

diff --git a/contrib/mom/ChangeLog b/contrib/mom/ChangeLog
index f96bdfe08..6fd29d2ff 100644
--- a/contrib/mom/ChangeLog
+++ b/contrib/mom/ChangeLog
@@ -1,6 +1,10 @@
+2023-02-02
+	* om.tmac (UNDERSCORE, UNDERSCORE2): Add PREFIX and SUFFIX
+	arguments so surrounding punctuation can be protected from
+	underscoring.
 
 2023-01-16
-	* om.tmac (PRINSTYLE): Abort with message if nroff is called on
+	* om.tmac (PRINTSTYLE): Abort with message if nroff is called on
 	a document using PRINTSTYLE TYPESET.
 
 	Fixes <https://savannah.gnu.org/bugs/?63581>.  Thanks to Gene
diff --git a/contrib/mom/momdoc/goodies.html b/contrib/mom/momdoc/goodies.html
index 00e2db037..7c39e1488 100644
--- a/contrib/mom/momdoc/goodies.html
+++ b/contrib/mom/momdoc/goodies.html
@@ -696,11 +696,11 @@ would do the trick.
 </div>
 
 <div class="box-macro-args">
-Macro: <b>UNDERSCORE</b> <kbd class="macro-args">[ &lt;distance below baseline&gt; ] &quot;&lt;string&gt;&quot;</kbd>
+Macro: <b>UNDERSCORE</b> <kbd class="macro-args">[ &lt;distance below baseline&gt; ] [ PREFIX &lt;prefix&gt; ] [ SUFFIX &lt;suffix&gt; ] &quot;&lt;string&gt;&quot;</kbd>
 </div>
 
 <p class="requires">
-&bull;&nbsp;Optional argument requires a <a href="definitions.html#unitofmeasure">unit of measure</a>
+&bull;&nbsp;&lt;distance below baseline&gt; requires a <a href="definitions.html#unitofmeasure">unit of measure</a>
 </p>
 
 <p>
@@ -710,7 +710,7 @@ required
 The string must be enclosed in double-quotes, like this:
 <br/>
 <span class="pre-in-pp">
-  .UNDERSCORE "Unmonitored monopolies breed high prices and poor products."
+  .UNDERSCORE "Unmonitored monopolies breed high prices and poor products"
 </span>
 If you wish to change the distance of the rule from the baseline,
 use the optional argument
@@ -718,7 +718,7 @@ use the optional argument
 (with a unit of measure).
 <br/>
 <span class="pre-in-pp">
-  .UNDERSCORE 3p "Unmonitored monopolies breed high prices and poor products."
+  .UNDERSCORE 3p "Unmonitored monopolies breed high prices and poor products"
 </span>
 The above places the upper edge of the underscore 3 points below the
 <a href="definitions.html#baseline">baseline</a>.
@@ -732,6 +732,19 @@ negative value to the distance argument.
 </p>
 </div>
 
+<p>
+<kbd>PREFIX</kbd> and <kbd>SUFFIX</kbd> allow you to add
+non-underscored punctuation (or other glyphs) to the beginning
+and/or end of the underscored string.  If the argument to either
+<kbd>PREFIX</kbd> or <kbd>SUFFIX</kbd> contains spaces, surround the
+argument with double-quotes.  For example, the following underscores
+the text string but not the surrounding punctuation.
+<br/>
+<span class="pre-in-pp">
+  .UNDERSCORE PREFIX ( SUFFIX .) "Unmonitored monopolies breed high prices and poor products"
+</span>
+</p>
+
 <div class="box-tip">
 <p class="tip">
 <span class="note">Note:</span>
@@ -806,8 +819,9 @@ rather than
   .UNDERSCORE "\*[red]text to underscore\*[black]"
 </span>
 The latter will render the text in red but the underscore in black.
-You can use this to create truly rainbow effects if you want, e.g.
-text in red, underscore in blue, and prevailing type in black:
+You can, of course, use this to create rainbow effects if that's
+what you want, e.g. text in red, underscore in blue, and prevailing
+type in black:
 <br/>
 <span class="pre-in-pp">
   .UNDERSCORE "\*[red]text to underscore\*[blue]"
@@ -822,11 +836,14 @@ text in red, underscore in blue, and prevailing type in black:
 </div>
 
 <div class="box-macro-args">
-Macro: <b>UNDERSCORE2</b> <kbd class="macro-args">[ &lt;distance below baseline&gt; [ &lt;distance between rules&gt; ] ] &quot;&lt;string&gt;&quot;</kbd>
+Macro: <b>UNDERSCORE2</b> <kbd class="macro-args">[ &lt;distance below baseline&gt; [ &lt;distance between rules&gt; ]  [ PREFIX &lt;prefix&gt; ] [ SUFFIX &lt;suffix&gt; ]  &quot;&lt;string&gt;&quot;</kbd>
 </div>
 
 <p class="requires">
-&bull;&nbsp;Optional arguments require a <a href="definitions.html#unitofmeasure">unit of measure</a>
+&bull;&nbsp;&lt;distance below baseline&gt;
+and
+&lt;distance between rules&gt;
+require a <a href="definitions.html#unitofmeasure">unit of measure</a>
 </p>
 
 <p>
@@ -836,7 +853,7 @@ the required
 The string must be enclosed in double-quotes, like this:
 <br/>
 <span class="pre-in-pp">
-  .UNDERSCORE2 "Unmonitored monopolies breed high prices and poor products."
+  .UNDERSCORE2 "Unmonitored monopolies breed high prices and poor products"
 </span>
 The default distance between the two rules is 2 points, measured
 from the bottom edge of the upper rule to the top edge of the lower
@@ -851,7 +868,7 @@ use the optional argument
 (with a unit of measure), e.g.
 <br/>
 <span class="pre-in-pp">
-  .UNDERSCORE2 3p "Unmonitored monopolies breed high prices and poor products."
+  .UNDERSCORE2 3p "Unmonitored monopolies breed high prices and poor products"
 </span>
 which places the upper edge of the first rule of the double
 underscore 3 points below the baseline.
@@ -861,19 +878,37 @@ underscore 3 points below the baseline.
 If you wish to change the distance between the two rules as well,
 use the second optional argument
 <kbd>&lt;distance&nbsp;between&nbsp;rules&gt;</kbd>
-(with a unit of measure).  Be aware that you must give a value for
-the first optional argument if you want to use the second.  The
-distance between the two rules is measured from the bottom edge of
-the upper rule to the top edge of the lower one.
+(with a unit of measure).  The distance between the two rules
+is measured from the bottom edge of the upper rule to the top
+edge of the lower one.  Be aware that you must give a value for
+<kbd>&lt;distance&nbsp;below&nbsp;baseline&gt;</kbd> if you want to
+use <kbd>&lt;distance&nbsp;between&nbsp;rules&gt;</kbd>.
 </p>
 
 <p>
+<kbd>PREFIX</kbd> and <kbd>SUFFIX</kbd> allow you to add
+non-underscored punctuation (or other glyphs) to the beginning
+and/or end of the double-underscored string.  If the argument to
+either <kbd>PREFIX</kbd> or <kbd>SUFFIX</kbd> contains spaces,
+surround the argument with double-quotes.  For example, the
+following double-underscores the text string but not the surrounding
+punctuation.
+<br/>
+<span class="pre-in-pp">
+  .UNDERSCORE2 PREFIX ( SUFFIX .) "Unmonitored monopolies breed high prices and poor products"
+</span>
 The weight (thickness) of double underscores may be controlled with
 the macro
 <a href="#underscore-weight">UNDERSCORE_WEIGHT</a>
 (q.v).
 </p>
 
+<p>
+See
+<a href="#underscore-color">here</a>
+for advice on colourising double-underscored text.
+</p>
+
 <div class="box-tip">
 <p class="tip">
 <span class="note">Note:</span>
diff --git a/contrib/mom/om.tmac b/contrib/mom/om.tmac
index 9c8649151..d92258160 100644
--- a/contrib/mom/om.tmac
+++ b/contrib/mom/om.tmac
@@ -2101,9 +2101,19 @@ end
 .    nr #SAVED_UNDERSCORE_WEIGHT     \\n[#UNDERSCORE_WEIGHT]
 .    nr #SAVED_UNDERSCORE_WEIGHT_ADJ \\n[#UNDERSCORE_WEIGHT_ADJ]
 .    ds $SAVED_UNDERSCORE_GAP        \\*[$UNDERSCORE_GAP]
-.    if \\n[#NUM_ARGS]=2 \{\
-.       ds $UNDERSCORE_GAP \\$1
-.       shift
+.    if \\n[#NUM_ARGS]>=2 \{\
+.       if \B'\\$1' \{\
+.          ds $UNDERSCORE_GAP \\$1
+.          shift
+.       \}
+.       if '\\$1'PREFIX' \{\
+.          ds $PREFIX \\$2
+.          shift 2
+.       \}
+.       if '\\$1'SUFFIX' \{\
+.          ds $SUFFIX \\$2
+.          shift 2
+.       \}
 .    \}
 .    if !'\\*[$TITLE_TYPE]'' \{\
 .       nr #UNDERSCORE_WEIGHT     \\n[#\\*[$TITLE_TYPE]_UNDERLINE_WEIGHT]
@@ -2112,21 +2122,21 @@ end
 .    \}
 .    nr #TEXT_WIDTH \w'\\$1'
 .    ie \\n[.u]=1 \{\
-\Z'\\$1'\
+\\*[$PREFIX]\Z'\\$1'\
 \Z'\D't \\n[#UNDERSCORE_WEIGHT]''\
 \v'\\*[$UNDERSCORE_GAP]+\\n[#UNDERSCORE_WEIGHT_ADJ]u'\
 \D'l \\n[#TEXT_WIDTH]u 0'\
 \Z'\D't \\n[#RULE_WEIGHT]''\
-\v'-(\\*[$UNDERSCORE_GAP]+\\n[#UNDERSCORE_WEIGHT_ADJ]u)'\c
+\v'-(\\*[$UNDERSCORE_GAP]+\\n[#UNDERSCORE_WEIGHT_ADJ]u)'\\*[$SUFFIX]\c
 .       nop
 .    \}
 .    el \{\
-\Z'\\$1'\
+\\*[$PREFIX]\Z'\\$1'\
 \Z'\D't \\n[#UNDERSCORE_WEIGHT]''\
 \v'\\*[$UNDERSCORE_GAP]+\\n[#UNDERSCORE_WEIGHT_ADJ]u'\
 \D'l \\n[#TEXT_WIDTH]u 0'\
 \Z'\D't \\n[#RULE_WEIGHT]''\
-\v'-(\\*[$UNDERSCORE_GAP]+\\n[#UNDERSCORE_WEIGHT_ADJ]u)'
+\v'-(\\*[$UNDERSCORE_GAP]+\\n[#UNDERSCORE_WEIGHT_ADJ]u)\\*[$SUFFIX]'
 .    \}
 .    nr #UNDERSCORE_WEIGHT     \\n[#SAVED_UNDERSCORE_WEIGHT]
 .    nr #UNDERSCORE_WEIGHT_ADJ \\n[#SAVED_UNDERSCORE_WEIGHT_ADJ]
@@ -2134,6 +2144,8 @@ end
 .    rr #SAVED_UNDERSCORE_WEIGHT
 .    rr #SAVED_UNDERSCORE_WEIGHT_ADJ
 .    rm $SAVED_UNDERSCORE_GAP
+.    rm $PREFIX
+.    rm $SUFFIX
 .    rm $TITLE_TYPE
 .END
 \#
@@ -2152,10 +2164,23 @@ end
 .    nr #SAVED_UNDERSCORE_WEIGHT_ADJ \\n[#UNDERSCORE_WEIGHT_ADJ]
 .    ds $SAVED_UNDERSCORE_GAP        \\*[$UNDERSCORE_GAP]
 .    ds $SAVED_RULE_GAP              \\*[$RULE_GAP]
-.    if \\n[#NUM_ARGS]=2 \{\
-.       ds $UNDERSCORE_GAP \\$1
-.       shift
-.    \}
+.    if \\n[#NUM_ARGS]>=2 \{\
+.       if \B'\\$1' \{\
+.          ds $UNDERSCORE_GAP \\$1
+.          shift
+.       \}
+.       if \B'\\$1' \{\
+.          ds $RULE_GAP \\$1
+.          shift
+.       \}
+.       if '\\$1'PREFIX' \{\
+.          ds $PREFIX \\$2
+.          shift 2
+.       \}
+.       if '\\$1'SUFFIX' \{\
+.          ds $SUFFIX \\$2
+.          shift 2
+.       \}
 .    if \\n[#NUM_ARGS]=3 \{\
 .       ds $UNDERSCORE_GAP \\$1
 .       ds $RULE_GAP \\$2
@@ -2169,30 +2194,32 @@ end
 .    \}
 .    nr #TEXT_WIDTH \w'\\$1'
 .    ie \\n[.u]=1 \{\
-\Z'\\$1'\
+\\*[$PREFIX]\Z'\\$1'\
 \Z'\D't \\n[#UNDERSCORE_WEIGHT]''\
 \v'\\*[$UNDERSCORE_GAP]+\\n[#UNDERSCORE_WEIGHT_ADJ]u'\
 \Z'\D'l \\n[#TEXT_WIDTH]u 0''\
 \v'\\*[$RULE_GAP]+\\n[#UNDERSCORE_WEIGHT]u'\
 \D'l \\n[#TEXT_WIDTH]u 0'\
 \Z'\D't \\n[#RULE_WEIGHT]''\
-\v'-(\\*[$UNDERSCORE_GAP]+\\*[$RULE_GAP])-(\\n[#UNDERSCORE_WEIGHT]u*2u)'\c
+\v'-(\\*[$UNDERSCORE_GAP]+\\*[$RULE_GAP])-(\\n[#UNDERSCORE_WEIGHT]u*2u)'\\*[$SUFFIX]\c
 .    \}
 .    el \{\
-\Z'\\$1'\
+\\*[$PREFIX]\Z'\\$1'\
 \Z'\D't \\n[#UNDERSCORE_WEIGHT]''\
 \v'\\*[$UNDERSCORE_GAP]+\\n[#UNDERSCORE_WEIGHT_ADJ]u'\
 \Z'\D'l \\n[#TEXT_WIDTH]u 0''\
 \v'\\*[$RULE_GAP]+\\n[#UNDERSCORE_WEIGHT]u'\
 \D'l \\n[#TEXT_WIDTH]u 0'\
 \Z'\D't \\n[#RULE_WEIGHT]''\
-\v'-(\\*[$UNDERSCORE_GAP]+\\*[$RULE_GAP])-(\\n[#UNDERSCORE_WEIGHT]u*2u)'
+\v'-(\\*[$UNDERSCORE_GAP]+\\*[$RULE_GAP])-(\\n[#UNDERSCORE_WEIGHT]u*2u)\\*[$SUFFIX]'
 .    \}
 .    nr #UNDERSCORE_WEIGHT     \\n[#SAVED_UNDERSCORE_WEIGHT]
 .    nr #UNDERSCORE_WEIGHT_ADJ \\n[#SAVED_UNDERSCORE_WEIGHT_ADJ]
 .    ds $UNDERSCORE_GAP        \\*[$SAVED_UNDERSCORE_GAP]
 .    rr #SAVED_UNDERSCORE_WEIGHT
 .    rr #SAVED_UNDERSCORE_WEIGHT_ADJ
+.    rm $PREFIX
+.    rm $SUFFIX
 .    rm $SAVED_UNDERSCORE_GAP
 .    rm $SAVED_RULE_GAP
 .    rm $TITLE_TYPE