[groff] 05/18: [man,mdoc]: Format for 80n on terminals, not 78n.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit dcf73d56bff9383635f3acb469235768118f21dc
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Jan 1 22:11:42 2024 -0600

    [man,mdoc]: Format for 80n on terminals, not 78n.
    
    [man,mdoc]: Increase default line length to 80n on terminals.  The
    resolution of tbl(1) bugs such as Savannah #63749, #63640, and #62471
    enables us to discard a decades-old convention of using 78n for the
    default line length when formatting for terminals; this was because
    tbl(1) would sometimes overset lines, with ugly consequences.  (I
    _assume_ this was the reason; no one ever seems to have gone on record
    about it--it was seemingly yet another case of Unix folklore that
    "everybody knew".)  Overset lines are still possible; tbl(1) will warn
    if so.  They can also overset if the document disables filling; the
    author is expected to know what they are doing in that case.
    
    * tmac/an.tmac:
    * tmac/doc-old.tmac:
    * tmac/mdoc/doc-nroff: Do it.
    
    * tmac/groff_man.7.man.in:
    * tmac/groff_mdoc.7.man: Update documentation and annotations.
    
    * tmac/tests/an-ext_SY-and-YS-work.sh:
    * tmac/tests/an_HY-register-works.sh:
    * tmac/tests/an_LL-init-sanely.sh:
    * tmac/tests/an_UE-breaks-before-long-URIs.sh:
    * tmac/tests/an_adjust-link-text-correctly.sh:
    * tmac/tests/an_do-not-abbreviate-escape-using-TH-arguments.sh:
    * tmac/tests/an_title-abbreviation-works.sh:
    * tmac/tests/andoc_flush-between-packages.sh:
    * tmac/tests/doc_indents-correctly.sh:
    * tmac/tests/doc_smoke-test.sh: Update test output expectations.
    
    * NEWS: Document it.
---
 ChangeLog                                          | 34 ++++++++++++++++++++++
 NEWS                                               |  9 ++++++
 tmac/an.tmac                                       |  2 +-
 tmac/doc-old.tmac                                  |  8 ++---
 tmac/groff_man.7.man.in                            |  4 +--
 tmac/groff_mdoc.7.man                              |  4 +--
 tmac/mdoc/doc-nroff                                |  2 +-
 tmac/tests/an-ext_SY-and-YS-work.sh                |  2 +-
 tmac/tests/an_HY-register-works.sh                 |  4 +--
 tmac/tests/an_LL-init-sanely.sh                    |  2 +-
 tmac/tests/an_UE-breaks-before-long-URIs.sh        |  4 +--
 tmac/tests/an_adjust-link-text-correctly.sh        |  2 +-
 ..._do-not-abbreviate-escape-using-TH-arguments.sh |  4 +--
 tmac/tests/an_title-abbreviation-works.sh          |  3 +-
 tmac/tests/andoc_flush-between-packages.sh         |  2 +-
 tmac/tests/doc_indents-correctly.sh                |  2 +-
 tmac/tests/doc_smoke-test.sh                       |  2 +-
 17 files changed, 67 insertions(+), 23 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 40ea1b85a..5c73b70f1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,37 @@
+2024-01-02  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [man,mdoc]: Increase default line length to 80n on terminals.
+       The resolution of tbl(1) bugs such as Savannah #63749, #63640,
+       and #62471 enables us to discard a decades-old convention of
+       using 78n for the default line length when formatting for
+       terminals; this was because tbl(1) would sometimes overset
+       lines, with ugly consequences.  (I _assume_ this was the reason;
+       no one ever seems to have gone on record about it--it was
+       seemingly yet another case of Unix folklore that "everybody
+       knew".)  Overset lines are still possible; tbl(1) will warn if
+       so.  They can also overset if the document disables filling; the
+       author is expected to know what they are doing in that case.
+
+       * tmac/an.tmac:
+       * tmac/doc-old.tmac:
+       * tmac/mdoc/doc-nroff: Do it.
+
+       * tmac/groff_man.7.man.in:
+       * tmac/groff_mdoc.7.man: Update documentation and annotations.
+
+       * tmac/tests/an-ext_SY-and-YS-work.sh:
+       * tmac/tests/an_HY-register-works.sh:
+       * tmac/tests/an_LL-init-sanely.sh:
+       * tmac/tests/an_UE-breaks-before-long-URIs.sh:
+       * tmac/tests/an_adjust-link-text-correctly.sh:
+       * tmac/tests/an_do-not-abbreviate-escape-using-TH-arguments.sh:
+       * tmac/tests/an_title-abbreviation-works.sh:
+       * tmac/tests/andoc_flush-between-packages.sh:
+       * tmac/tests/doc_indents-correctly.sh:
+       * tmac/tests/doc_smoke-test.sh: Update test output expectations.
+
+       * NEWS: Document it.
+
 2024-01-02  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/mdoc/doc-nroff (doc-setup-page-layout): Port nroff-mode
diff --git a/NEWS b/NEWS
index 314388a4f..97544604b 100644
--- a/NEWS
+++ b/NEWS
@@ -78,6 +78,15 @@ o Hyperlink support is now enabled by default on non-HTML 
devices that
   Instructions and commented code for disabling it remain in the
   "man.local" file.
 
+o The an (man), doc (mdoc), and doc-old (mdoc-old) macro packages have
+  changed the default line length when formatting on terminals from 78n
+  to 80n.  The latter is a vastly more common configuration, but that
+  line length had been avoided for decades (perhaps as long as as groff
+  has existed), for an undocumented reason.  That reason appears to have
+  been bugs in GNU tbl(1) and its interaction with an aspect of
+  grotty(1)'s design.  Those bugs have been resolved.  A man(1) program
+  can still instruct groff to format for any desired line length.
+
 o The an (man) and doc (mdoc) macro packages now support a `BP` register
   to configure the ("base") paragraph inset amount; that is the amount
   used by man(7) for paragraphs not within an `RS`/`RE` relative inset,
diff --git a/tmac/an.tmac b/tmac/an.tmac
index 316d4abde..a60eb888f 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -1476,7 +1476,7 @@ contains unsupported escape sequence
 .  \" If in troff mode, respect device default.
 .  ie t .nr LL \n[.l]
 .  \" Otherwise, override nroff mode default of 65n.
-.  el   .nr LL 78n
+.  el   .nr LL 80n
 .\}
 .
 .\" title (header, footer) length
diff --git a/tmac/doc-old.tmac b/tmac/doc-old.tmac
index e6bd74f9b..e98955aca 100644
--- a/tmac/doc-old.tmac
+++ b/tmac/doc-old.tmac
@@ -245,12 +245,12 @@
 .\}
 .el \{\
 .\" Line length
-.      nr ll 78n
-.      ll 78n
+.      nr ll 80n
+.      ll 80n
 .\" Title length
-.      nr lt 78n
+.      nr lt 80n
 .\" Title length
-.      lt 78n
+.      lt 80n
 .\" Page offset
 .      nr po 0i
 .\" Page offset
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index a808404ad..39d2f11bb 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -3632,7 +3632,7 @@ indentation.
 .TP
 .BI \-rLL= line-length
 Set line length;
-the default is 78n on terminals
+the default is 80n on terminals
 and 6.5i on typesetters.
 .
 .
@@ -3900,7 +3900,7 @@ _ifstyle()dnl
 \&.ss 12 0 \e" See groff(@MAN7EXT@).
 .ne 2v
 \&.\e" Keep pages narrow even on wide terminals.
-\&.if n .if \en[LL]>78n .nr LL 78n
+\&.if n .if \en[LL]>80n .nr LL 80n
 .EE
 .RE
 .RE
diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index 13647652c..ddfafcc38 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -4834,7 +4834,7 @@ for a full discussion of these special character escape 
sequences.
 .\" 2nd and 3rd columns; we had to steal a character cell from each (the
 .\" default is 3) because in the UCS column, the word "infinity" gets
 .\" written out in full, which in turn pushes the >= and Ge rows past
-.\" the 78n norm.  Update with caution.  See Savannah #59424.
+.\" the historical 78n norm.  Update with caution.  See Savannah #59424.
 .TS
 Cb Lb2 Lb2 Lb Lb Lb
 Lf(CR) L2 L2 L Lf(CR) L.
@@ -5099,7 +5099,7 @@ respectively:
 .Dl groff \-Tutf8 \-rLL=100n \-rLT=100n \-mdoc foo.man | less \-R
 .
 If not set,
-both registers default to 78n for terminal devices and 6.5i otherwise.
+both registers default to 80n for terminal devices and 6.5i otherwise.
 .
 .
 .Pp
diff --git a/tmac/mdoc/doc-nroff b/tmac/mdoc/doc-nroff
index ca5d6fa61..c0562f669 100644
--- a/tmac/mdoc/doc-nroff
+++ b/tmac/mdoc/doc-nroff
@@ -104,7 +104,7 @@
 .  ie r LL \
 .    ll \n[LL]u
 .  el \
-.    ll 78n
+.    ll 80n
 .
 .  ie r LT \
 .    lt \n[LT]u
diff --git a/tmac/tests/an-ext_SY-and-YS-work.sh 
b/tmac/tests/an-ext_SY-and-YS-work.sh
index 8b7856ee7..3ddc7d727 100755
--- a/tmac/tests/an-ext_SY-and-YS-work.sh
+++ b/tmac/tests/an-ext_SY-and-YS-work.sh
@@ -70,7 +70,7 @@ echo "$output" \
 echo 'checking for correct indentation of broken synopsis lines' >&2
 echo "$output" \
     | sed -n -e '/foo operand1/{' \
-        -e 'n;/         operand7.*/p' \
+        -e 'n;/         operand8.*/p' \
         -e '}' \
     | grep -q . || wail
 
diff --git a/tmac/tests/an_HY-register-works.sh 
b/tmac/tests/an_HY-register-works.sh
index 2e8ddc03b..fc7a7a5ab 100755
--- a/tmac/tests/an_HY-register-works.sh
+++ b/tmac/tests/an_HY-register-works.sh
@@ -41,7 +41,7 @@ output=$(printf "%s\n" "$input" | "$groff" -man -Tascii 
-P-cbou)
 echo "$output"
 
 echo "checking hyphenation when HY is default" >&2
-echo "$output" | grep -q "antidisestablish-$" || wail
+echo "$output" | grep -q "antidisestablishmen-$" || wail
 
 output=$(printf "%s\n" "$input" | "$groff" -rHY=0 -man -Tascii -P-cbou)
 echo "$output"
@@ -65,7 +65,7 @@ output=$(printf "%s\n" "$input" | "$groff" -man -Tascii 
-P-cbou)
 echo "$output"
 
 echo "checking hyphenation when HY is default and .SY nested" >&2
-echo "$output" | grep -q "antidisestablish-$" || wail
+echo "$output" | grep -q "antidisestablishmen-$" || wail
 
 output=$(printf "%s\n" "$input" | "$groff" -rHY=0 -man -Tascii -P-cbou)
 echo "$output"
diff --git a/tmac/tests/an_LL-init-sanely.sh b/tmac/tests/an_LL-init-sanely.sh
index 88b9c2b85..68f9d9710 100755
--- a/tmac/tests/an_LL-init-sanely.sh
+++ b/tmac/tests/an_LL-init-sanely.sh
@@ -45,6 +45,6 @@ LL=\n[LL]u, .H=\n[.H]u, length=\n[cells]n
 
 output=$(printf "%s\n" "$input" | "$groff" -Tascii -P-cbou -man)
 echo "$output"
-echo "$output" | grep -q 'LL=1872u'
+echo "$output" | grep -q 'LL=1920u'
 
 # vim:set ai et sw=4 ts=4 tw=72:
diff --git a/tmac/tests/an_UE-breaks-before-long-URIs.sh 
b/tmac/tests/an_UE-breaks-before-long-URIs.sh
index e7eb0122c..97a9d6f0e 100755
--- a/tmac/tests/an_UE-breaks-before-long-URIs.sh
+++ b/tmac/tests/an_UE-breaks-before-long-URIs.sh
@@ -57,8 +57,8 @@ echo "testing that no diagnostic messages are produced" >&2
 test -z "$error" || wail
 echo "testing that lines break where expected" >&2
 break1=$(echo "$output" | grep -x "  *Commerce  *<https.*actionscript/")
-break2=$(echo "$output" | grep -x "  *articles/.* transaction .* plun-")
-break3=$(echo "$output" | grep -x "  *<https.*61234")
+break2=$(echo "$output" | grep -x "  *articles/.* which A  * plunders")
+break3=$(echo "$output" | grep -x "  *<https.*23456")
 test -n "$break1" || wail "first break"
 test -n "$break2" || wail "second break"
 test -n "$break3" || wail "third break"
diff --git a/tmac/tests/an_adjust-link-text-correctly.sh 
b/tmac/tests/an_adjust-link-text-correctly.sh
index b1221aee4..9c84db291 100755
--- a/tmac/tests/an_adjust-link-text-correctly.sh
+++ b/tmac/tests/an_adjust-link-text-correctly.sh
@@ -35,6 +35,6 @@ input='.TH foo 1 2022-11-08 "groff test suite"
 
 output=$(printf "%s\n" "$input" | "$groff" -Tascii -P-cbou -man -rU1)
 echo "$output"
-echo "$output" | grep -q 'HP  PCL/PJL Reference:.*Reference Manual'
+echo "$output" | grep -q 'HP  PCL/PJL  Reference:.*Reference Manual'
 
 # vim:set ai et sw=4 ts=4 tw=72:
diff --git a/tmac/tests/an_do-not-abbreviate-escape-using-TH-arguments.sh 
b/tmac/tests/an_do-not-abbreviate-escape-using-TH-arguments.sh
index 060fe1879..fd5f9b4bc 100755
--- a/tmac/tests/an_do-not-abbreviate-escape-using-TH-arguments.sh
+++ b/tmac/tests/an_do-not-abbreviate-escape-using-TH-arguments.sh
@@ -42,8 +42,8 @@ echo "$output"
 echo "checking that title with escaped hyphen-minus is preserved" >&2
 echo "$output" | grep -q '^f-b(1)' || wail
 
-pattern='Bletcherous Glorfinking Dungrndel 2022-04-08 Greebstank 2.21'
-pattern="$pattern            f-b(1)" # 12 spaces
+pattern='Bletcherous Glorfinking Dungrndel H2022-04-08Greebstank 2.21'
+pattern="$pattern              f-b(1)" # 14 spaces
 echo "checking for insanely long 4th TH argument" >&2
 echo "$output" | grep -Fqx "$pattern" || wail
 
diff --git a/tmac/tests/an_title-abbreviation-works.sh 
b/tmac/tests/an_title-abbreviation-works.sh
index a0e8e923b..c7a07b940 100755
--- a/tmac/tests/an_title-abbreviation-works.sh
+++ b/tmac/tests/an_title-abbreviation-works.sh
@@ -53,7 +53,8 @@ echo "$output"
 
 echo "checking that ultra-long man page title is abbreviated" >&2
 title_abbv="CosNotif...hSupplier(3erl)"
-pattern="$title_abbv Erlang Module Definition $title_abbv"
+# 2 spaces each before "Erlang" and after "Definition"
+pattern="$title_abbv  Erlang Module Definition  $title_abbv"
 echo "$output" | grep -Fq "$pattern" || wail
 
 test -z "$fail"
diff --git a/tmac/tests/andoc_flush-between-packages.sh 
b/tmac/tests/andoc_flush-between-packages.sh
index f4eef6c0e..ace0ee125 100755
--- a/tmac/tests/andoc_flush-between-packages.sh
+++ b/tmac/tests/andoc_flush-between-packages.sh
@@ -71,7 +71,7 @@ test -z "$(echo "$output" \
 echo "checking mdoc to man transition" >&2
 test -z "$(echo "$output" \
     | sed '/^$/d' \
-    | sed -n '/partially-collected/{N;/test page 2/p;}')" \
+    | sed -n '/tially-collected/{N;/test page 2/p;}')" \
     && wail
 
 test -z "$fail"
diff --git a/tmac/tests/doc_indents-correctly.sh 
b/tmac/tests/doc_indents-correctly.sh
index 4f7e2aec8..4a3734e38 100755
--- a/tmac/tests/doc_indents-correctly.sh
+++ b/tmac/tests/doc_indents-correctly.sh
@@ -51,7 +51,7 @@ echo "checking default 'Sh' indentation on 1st line" >&2
 echo "$output" | grep -Eq '^A +long +section +heading' || wail
 
 echo "cehcking default 'Sh' indentation on 2nd line" >&2
-echo "$output" | grep -Eq '^of said title is consistent' || wail
+echo "$output" | grep -Eq '^said title is consistent' || wail
 
 # Verify that paragraph indentation after section heading is correct.
 echo "checking 'Pp' indentation after 'Sh'" >&2
diff --git a/tmac/tests/doc_smoke-test.sh b/tmac/tests/doc_smoke-test.sh
index 7303606d9..502233e8c 100755
--- a/tmac/tests/doc_smoke-test.sh
+++ b/tmac/tests/doc_smoke-test.sh
@@ -54,7 +54,7 @@ echo "checking for section heading \"Description\"" >&2
 echo "$output" | grep -qE '^Description$' || wail
 
 echo "checking paragraph body for correct content" >&2
-echo "$output" | grep -qE 'you can read this' || wail
+echo "$output" | grep -qE 'you +can +read +this' || wail
 
 echo "checking footer for correct content" >&2
 echo "$output" | grep -qE '^GNU +August 25, 2020 +mdoc-test\(7\)' \