[groff] 14/14: [man]: Modify typeset URI breaking strategy.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c7efb5fd40aae5293d9de87092b7a4b2be89df91
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Nov 1 19:33:50 2021 +1100

    [man]: Modify typeset URI breaking strategy.
    
    [man]: Try to minimize the number of times a URI is broken when it has
    to be typeset and prevent it from provoking adjustment warnings.
    
    * tmac/an-ext.tmac (UE, ME): Do it.  New Boolean register `mL` records
      whether the URI will cause a break.  New string `m2` contains the
      user-specified URI (`m1`) plus the angle brackets around it and any
      user-specified trailing punctuation (\$1).  New register `mW` stores
      the formatted width of `m2`.  If the page offset plus the indentation
      plus the current horizontal position on the output line plus `mW`
      exceeds the output line length, turn off adjustment and break the line
      _before_ typesetting `m2`.  Then, if we forced a break, restore the
      previous adjustment mode.  Shift off the first macro parameter and
      emit the (undocumented) rest as before.
    
    * tmac/groff_man.7.man.in (Hyperlink macros): Document it.
    
    * tmac/tests/an-ext_UE-breaks-before-long-URIs.sh: Test it.
    * tmac/tmac.am (tmac_TESTS): Run test.
    
    Prompted by a suggestion from James K. Lowden
    <https://lists.gnu.org/archive/html/groff/2021-10/msg00048.html>
    --thanks, James!
    
    Also add a credit for myself to an-ext.tmac.
---
 ChangeLog                                       | 27 ++++++++++++
 tmac/an-ext.tmac                                | 47 ++++++++++++++++++--
 tmac/groff_man.7.man.in                         |  6 +++
 tmac/tests/an-ext_UE-breaks-before-long-URIs.sh | 58 +++++++++++++++++++++++++
 tmac/tmac.am                                    |  1 +
 5 files changed, 135 insertions(+), 4 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index c548606..4ad4047 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,32 @@
 2021-11-01  G. Branden Robinson <g.branden.robinson@gmail.com>
 
+       [man]: Try to minimize the number of times a URI is broken when
+       it has to be typeset and prevent it from provoking adjustment
+       warnings.
+
+       * tmac/an-ext.tmac (UE, ME): Do it.  New Boolean register `mL`
+       records whether the URI will cause a break.  New string `m2`
+       contains the user-specified URI (`m1`) plus the angle brackets
+       around it and any user-specified trailing punctuation (\$1).
+       New register `mW` stores the formatted width of `m2`.  If the
+       page offset plus the indentation plus the current horizontal
+       position on the output line plus `mW` exceeds the output line
+       length, turn off adjustment and break the line _before_
+       typesetting `m2`.  Then, if we forced a break, restore the
+       previous adjustment mode.  Shift off the first macro parameter
+       and emit the (undocumented) rest as before.
+
+       * tmac/groff_man.7.man.in (Hyperlink macros): Document it.
+
+       * tmac/tests/an-ext_UE-breaks-before-long-URIs.sh: Test it.
+       * tmac/tmac.am (tmac_TESTS): Run test.
+
+       Prompted by a suggestion from James K. Lowden
+       <https://lists.gnu.org/archive/html/groff/2021-10/msg00048.html>
+       --thanks, James!
+
+2021-11-01  G. Branden Robinson <g.branden.robinson@gmail.com>
+
        * src/devices/grohtml/post-html.cpp
        (html_printer::do_file_components): Add assertion.
 
diff --git a/tmac/an-ext.tmac b/tmac/an-ext.tmac
index 274f653..fb1b6e4 100644
--- a/tmac/an-ext.tmac
+++ b/tmac/an-ext.tmac
@@ -4,6 +4,7 @@
 .\"
 .\" Written by Eric S. Raymond <esr@thyrsus.com>
 .\"            Werner Lemberg <wl@gnu.org>
+.\"            G. Branden Robinson <g.branden.robinson@gmail.com>
 .\"
 .\" You may freely use, modify and/or distribute this file.
 .\"
@@ -139,11 +140,30 @@
 \&\\$*\"
 .  \}
 .  el \{\
+.    nr mL 0 \" Will the URI+punctuation cause a break?
+.    ds m2 \\*(la\\*(m1\\*(ra\\$1\"
+.    nr mW \\w'\\*(m2'
+.    \" If the URI won't fit on the rest of the line, break early and
+.    \" turn off adjustment.
+.    if \\n(.o+\\n(.i+\\n(.ku+\\n(mWu>\\n(.lu \{\
+.      nr mL 1
+.      nr mJ \\n(.j
+.      br
+.      na
+.    \}
 .    nh
-\\*(la\\*(m1\\*(ra\c
+\\*(m2
+.    \" If we had to break before the URI, restore adjustment.
+.    if \\n(mL .ad \\n(mJ
+.    do shift
 .    ie \n(.g \&\\$*\"
-.    el \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\"
+.    el \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\"
 .    hy \\n(HY
+.    rr mJ
+.    rr mW
+.    rr mL
+.    rm m2
+.    rm m1
 .  \}
 ..
 .
@@ -190,11 +210,30 @@
 \&\\$*\"
 .  \}
 .  el \{\
+.    nr mL 0 \" Will the URI+punctuation cause a break?
+.    ds m2 \\*(la\\*(m1\\*(ra\\$1\"
+.    nr mW \\w'\\*(m2'
+.    \" If the URI won't fit on the rest of the line, break early and
+.    \" turn off adjustment.
+.    if \\n(.o+\\n(.i+\\n(.ku+\\n(mWu>\\n(.lu \{\
+.      nr mL 1
+.      nr mJ \\n(.j
+.      br
+.      na
+.    \}
 .    nh
-\\*(la\\*(m1\\*(ra\c
+\\*(m2
+.    \" If we had to break before the URI, restore adjustment.
+.    if \\n(mL .ad \\n(mJ
+.    do shift
 .    ie \n(.g \&\\$*\"
-.    el \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\"
+.    el \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\"
 .    hy \\n(HY
+.    rr mJ
+.    rr mW
+.    rr mL
+.    rm m2
+.    rm m1
 .  \}
 ..
 .
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 09b912f..ade9cb2 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -1161,6 +1161,12 @@ and
 .B .UR
 URIs are rendered between angle brackets after the linked text.
 .
+If such a URI will not fit on the remainder of the output line,
+the macro package temporarily turns off adjustment
+(if enabled)
+and breaks the line before the URI to minimize the number of output
+lines over which it spreads.
+.
 .
 .P
 .BR .MT ,
diff --git a/tmac/tests/an-ext_UE-breaks-before-long-URIs.sh 
b/tmac/tests/an-ext_UE-breaks-before-long-URIs.sh
new file mode 100755
index 0000000..dab26cb
--- /dev/null
+++ b/tmac/tests/an-ext_UE-breaks-before-long-URIs.sh
@@ -0,0 +1,58 @@
+#!/bin/sh
+#
+# Copyright (C) 2021 Free Software Foundation, Inc.
+#
+# This file is part of groff.
+#
+# groff is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# groff is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+groff="${abs_top_builddir:-.}/test-groff"
+
+input=$(cat <<EOF
+.TH ridonk 1 2021-10-31 "groff test suite"
+.SH Name
+ridonk \- check the typesetting of an absurdly long URI
+.SH Description
+.UR https://\:www\:.adobe\:.com/\:content/\:dam/\:acom/\:en/\:devnet/\:\
+actionscript/\:articles/\:5001\:.DSC_Spec\:.pdf
+Commerce
+.UE ,
+n.:
+A kind of transaction in which A plunders from B the goods of C,
+and for compensation B picks the pocket of D of money belonging to E.
+EOF
+)
+
+fail=
+
+wail () {
+    echo "...$* FAILED" >&2
+    fail=yes
+}
+
+echo "testing that no diagnostic messages are produced" >&2
+output=$(printf "%s" "$input" \
+    | "$groff" -Tascii -P-cbou -man -ww -z 2>&1)
+test -z "$output" || wail
+
+echo "testing that lines break where expected" >&2
+output=$(printf "%s" "$input" | "$groff" -Tascii -P-cbou -man)
+break1=$(echo "$output" | grep -x "  *Commerce")
+break2=$(echo "$output" | grep -x "  *<https.*actionscript/")
+test -n "$break1" || wail "first break"
+test -n "$break2" || wail "second break"
+
+test -z "$fail"
+
+# vim:set ai et sw=4 ts=4 tw=72:
diff --git a/tmac/tmac.am b/tmac/tmac.am
index 8d22005..89f3d10 100644
--- a/tmac/tmac.am
+++ b/tmac/tmac.am
@@ -151,6 +151,7 @@ tmac_TESTS = \
   tmac/tests/an-ext_MT-body-hyphenates.sh \
   tmac/tests/an-ext_UE-punct-hyphenates.sh \
   tmac/tests/an-ext_UR-body-hyphenates.sh \
+  tmac/tests/an-ext_UE-breaks-before-long-URIs.sh \
   tmac/tests/an_AT-and-UC-footer-saved-and-restored.sh \
   tmac/tests/an_CS-register-off.sh \
   tmac/tests/an_CS-register-on.sh \