[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 01/08: mdoc: Accept mixed-case section headings.
From: |
G. Branden Robinson |
Subject: |
[groff] 01/08: mdoc: Accept mixed-case section headings. |
Date: |
Tue, 15 Sep 2020 07:02:01 -0400 (EDT) |
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)
- [groff] 01/08: mdoc: Accept mixed-case section headings.,
G. Branden Robinson <=