[groff] 01/08: mdoc: Accept mixed-case section headings.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 0438b1b905ebe9ac5fc678af06db911d25c3a030
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Sep 14 21:18:02 2020 +1000

    mdoc: Accept mixed-case section headings.
    
    * tmac/mdoc/doc-common-u (doc-prepare-section-heading): New macro
      defines new string doc-sec-head to anable recognition of mixed-case
      section headings in mdoc man pages.  For example, "Name" and
      "Description" are now recognized in addition to "NAME" and
      "DESCRIPTION".
    
      (doc-section-{name,synopsis,library,description,see-also,files,
      authors}): Redefine strings to be mixed-case.  Add trailing comment
      guard per recommended best practice.
    
      (Sh): Call doc-prepare-section-heading instead of doc-first-parameter,
      and compare predefined section strings to doc-sec-head instead of
      doc-str-dfp.
    
    * tmac/tests/doc-accept-mixed-case-section-headings.sh: Test it.
    
    * tmac/tests/doc-smoke-test.sh: Use mixed-case section headings.
    
    * tmac/tmac.am: Run test.
---
 ChangeLog                                          | 18 +++++++
 tmac/mdoc/doc-common-u                             | 60 ++++++++++++++++------
 ...h => doc-accept-mixed-case-section-headings.sh} | 45 ++++++++--------
 tmac/tests/doc-smoke-test.sh                       |  6 +--
 tmac/tmac.am                                       |  1 +
 5 files changed, 90 insertions(+), 40 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 436ee4d..545cbb8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,21 @@
+2020-09-14  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * tmac/mdoc/doc-common-u (doc-prepare-section-heading): New
+       macro defines new string doc-sec-head to anable recognition of
+       mixed-case section headings in mdoc man pages.  For example,
+       "Name" and "Description" are now recognized in addition to
+       "NAME" and "DESCRIPTION".
+       (doc-section-{name,synopsis,library,description,see-also,files,
+       authors}): Redefine strings to be mixed-case.  Add trailing
+       comment guard per recommended best practice.
+       (Sh): Call doc-prepare-section-heading instead of
+       doc-first-parameter, and compare predefined section strings to
+       doc-sec-head instead of doc-str-dfp.
+
+       * tmac/tests/doc-accept-mixed-case-section-headings.sh: Test it.
+       * tmac/tests/doc-smoke-test.sh: Use mixed-case section headings.
+       * tmac/tmac.am: Run test.
+
 2020-09-03  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * FOR-RELEASE: Start a release checklist.  We probably should
diff --git a/tmac/mdoc/doc-common-u b/tmac/mdoc/doc-common-u
index acb84d9..f98c077 100644
--- a/tmac/mdoc/doc-common-u
+++ b/tmac/mdoc/doc-common-u
@@ -1118,6 +1118,34 @@
 ..
 .
 .
+.\" NS doc-prepare-section-heading macro
+.\" NS   define `doc-sec-head`, `macro` prepared for string matching
+.\"
+.\" NS
+.\" NS local variables:
+.\" NS   doc-str-tmp1
+.\" NS   doc-str-tmp2
+.\" NS   doc-tmp-strlen
+.
+.de doc-prepare-section-heading
+.  ds doc-str-tmp1 "\$*
+.  ds doc-str-tmp2 "\$*
+.  length doc-tmp-strlen \$*
+.  \" Leave (nonstandard) section headings of length 0 or 1 unchanged.
+.  ie \n[doc-tmp-strlen]>1 \{\
+.    substring doc-str-tmp1 0 0
+.    substring doc-str-tmp2 1
+.    stringdown doc-str-tmp2
+.    ds doc-sec-head \*[doc-str-tmp1]\*[doc-str-tmp2]\"
+.  \}
+.  el \
+.    ds doc-sec-head "\$*
+.    rm doc-str-tmp1
+.    rm doc-str-tmp2
+.    rr doc-tmp-strleq
+..
+.
+.
 .\" NS Sh user macro (not callable)
 .\" NS   section headers
 .\" NS
@@ -1141,13 +1169,13 @@
 .\" NS
 .\" NS width register 'Sh' set in doc-common
 .
-.ds doc-section-name        NAME
-.ds doc-section-synopsis    SYNOPSIS
-.ds doc-section-library     LIBRARY
-.ds doc-section-description DESCRIPTION
-.ds doc-section-see-also    SEE
-.ds doc-section-files       FILES
-.ds doc-section-authors     AUTHORS
+.ds doc-section-name        Name\"
+.ds doc-section-synopsis    Synopsis\"
+.ds doc-section-library     Library\"
+.ds doc-section-description Description\"
+.ds doc-section-see-also    See also\"
+.ds doc-section-files       Files\"
+.ds doc-section-authors     Authors\"
 .
 .de Sh
 .  ie \n[doc-arg-limit] \{\
@@ -1181,10 +1209,10 @@
 .    if t \
 .      ad
 .
-.    \" this resolves e.g. '.Sh "SEE ALSO"'
-.    doc-first-parameter \$*
+.    \" this resolves, e.g., '.Sh "SEE ALSO"'
+.    doc-prepare-section-heading \$*
 .
-.    ie "\*[doc-str-dfp]"\*[doc-section-name]" \{\
+.    ie "\*[doc-sec-head]"\*[doc-section-name]" \{\
 .      doc-setup-header
 .      in 0
 .    \}
@@ -1195,30 +1223,30 @@
 .      nr doc-in-files-section 0
 .      nr doc-in-authors-section 0
 .
-.      ie        "\*[doc-str-dfp]"\*[doc-section-synopsis]" \{\
+.      ie        "\*[doc-sec-head]"\*[doc-section-synopsis]" \{\
 .        if t \
 .          na
 .        nr doc-in-synopsis-section 1
 .        nr doc-indent-synopsis 0
 .        nr doc-indent-synopsis-active 0
 .      \}
-.      el \{ .ie "\*[doc-str-dfp]"\*[doc-section-library]" \{\
+.      el \{ .ie "\*[doc-sec-head]"\*[doc-section-library]" \{\
 .        nr doc-in-library-section 1
 .      \}
-.      el \{ .ie "\*[doc-str-dfp]"\*[doc-section-description]" \{\
+.      el \{ .ie "\*[doc-sec-head]"\*[doc-section-description]" \{\
 .        nr doc-is-func 0
 .        nr doc-func-count 0
 .        nr doc-func-args-processed 0
 .        nr doc-num-func-args 0
 .      \}
-.      el \{ .ie "\*[doc-str-dfp]"\*[doc-section-see-also]" \{\
+.      el \{ .ie "\*[doc-sec-head]"\*[doc-section-see-also]" \{\
 .        if t \
 .          na
 .        nr doc-in-see-also-section 1
 .      \}
-.      el \{ .ie "\*[doc-str-dfp]"\*[doc-section-files]" \
+.      el \{ .ie "\*[doc-sec-head]"\*[doc-section-files]" \
 .        nr doc-in-files-section 1
-.      el .if    "\*[doc-str-dfp]"\*[doc-section-authors]" \
+.      el .if    "\*[doc-sec-head]"\*[doc-section-authors]" \
 .        nr doc-in-authors-section 1
 .      \}\}\}\}
 .
diff --git a/tmac/tests/doc-smoke-test.sh 
b/tmac/tests/doc-accept-mixed-case-section-headings.sh
similarity index 56%
copy from tmac/tests/doc-smoke-test.sh
copy to tmac/tests/doc-accept-mixed-case-section-headings.sh
index 607c770..0f68847 100755
--- a/tmac/tests/doc-smoke-test.sh
+++ b/tmac/tests/doc-accept-mixed-case-section-headings.sh
@@ -20,52 +20,55 @@
 
 groff="${abs_top_builddir:-.}/test-groff"
 
-# Regression-test Savannah #51003.
-#
-# Ensure we can render mdoc man pages from a build tree.
+# Ensure we recognize mixed-case section headings ("Name" as well as
+# "NAME").
 
 EXAMPLE='\
-.Dd August 25, 2020
+.Dd September 14, 2020
 .Dt mdoc\-test 7
 .Os
-.Sh NAME \" It REALLY DOES need to be in full caps.
+.Sh Name
 .Nm mdoc\-test
 .Nd a smoke test for groff'"'"'s mdoc implementation
 .Sh Description
-If you can read this without a hailstorm of warnings,
-things are probably working.'
+This page has mixed-case section headings.
+.Pp
+This paragraph works around Savannah #59106.
+.Dd September 14, 2020
+.Dt mdoc\-test 7
+.Os
+.Sh NAME
+.Nm mdoc\-test
+.Nd a smoke test for groff'"'"'s mdoc implementation
+.Sh DESCRIPTION
+This page has fully-capitalized section headings.\
+'
 
 OUTPUT=$(printf "%s\n" "$EXAMPLE" | "$groff" -Tascii -P-cbou -mdoc)
 FAIL=
 
-if ! echo "$OUTPUT" | grep -qE '^mdoc-test\(7\) +BSD Miscellaneous'
-then
-    FAIL=yes
-    echo "header check failed" >&2
-fi
-
-if ! echo "$OUTPUT" | grep -qE '^NAME$'
+if [ -z "$(echo "$OUTPUT" | sed -n '/Name/{N;/smoke/p}')" ]
 then
     FAIL=yes
-    echo "\"NAME\" section heading missing" >&2
+    echo "section \"Name\" check failed" >&2
 fi
 
-if ! echo "$OUTPUT" | grep -qE '^Description$'
+if [ -z "$(echo "$OUTPUT" | sed -n '/Description/{N;/mixed-case/p}')" ]
 then
     FAIL=yes
-    echo "\"Description\" section heading missing" >&2
+    echo "section \"Description\" check failed" >&2
 fi
 
-if ! echo "$OUTPUT" | grep -qE 'you can read this'
+if [ -z "$(echo "$OUTPUT" | sed -n '/NAME/{N;/smoke/p}')" ]
 then
     FAIL=yes
-    echo "paragraph body check failed" >&2
+    echo "section \"NAME\" check failed" >&2
 fi
 
-if ! echo "$OUTPUT" | grep -qE '^BSD +August 25, 2020'
+if [ -z "$(echo "$OUTPUT" | sed -n '/DESCRIPTION/{N;/fully-cap/p}')" ]
 then
     FAIL=yes
-    echo "footer check failed" >&2
+    echo "section \"DESCRIPTION\" check failed" >&2
 fi
 
 test -z "$FAIL"
diff --git a/tmac/tests/doc-smoke-test.sh b/tmac/tests/doc-smoke-test.sh
index 607c770..daeda2a 100755
--- a/tmac/tests/doc-smoke-test.sh
+++ b/tmac/tests/doc-smoke-test.sh
@@ -28,7 +28,7 @@ EXAMPLE='\
 .Dd August 25, 2020
 .Dt mdoc\-test 7
 .Os
-.Sh NAME \" It REALLY DOES need to be in full caps.
+.Sh Name
 .Nm mdoc\-test
 .Nd a smoke test for groff'"'"'s mdoc implementation
 .Sh Description
@@ -44,10 +44,10 @@ then
     echo "header check failed" >&2
 fi
 
-if ! echo "$OUTPUT" | grep -qE '^NAME$'
+if ! echo "$OUTPUT" | grep -qE '^Name$'
 then
     FAIL=yes
-    echo "\"NAME\" section heading missing" >&2
+    echo "\"Name\" section heading missing" >&2
 fi
 
 if ! echo "$OUTPUT" | grep -qE '^Description$'
diff --git a/tmac/tmac.am b/tmac/tmac.am
index 44477e9..e099064 100644
--- a/tmac/tmac.am
+++ b/tmac/tmac.am
@@ -152,6 +152,7 @@ tmac_TESTS = \
   tmac/tests/an-old_CT_register_unspecified.sh \
   tmac/tests/an-old_TH_repairs_ad_damage.sh \
   tmac/tests/an-old_TH_repairs_hy_damage.sh \
+  tmac/tests/doc-accept-mixed-case-section-headings.sh \
   tmac/tests/doc-smoke-test.sh
 TESTS += $(tmac_TESTS)