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

2020-09-15 Thread Steffen Nurpmeso 
G. Branden Robinson wrote in
 <20200915110201.e2d1820...@vcs0.savannah.gnu.org>:
  ...
 |commit 0438b1b905ebe9ac5fc678af06db911d25c3a030
 |Author: G. Branden Robinson 
 |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".

Just out of interest: why do you change an omnipresent idiom that
is in use for standard section headers in Unix manual pages since
at least fourty years?  This commit changes the world and will
affect the generations of programmers to come, shall they
experience it.  I mean, it is ok, why not, it only strives me as
mysterious.  And i think i will unsubscribe now, shall i ever find
time for my groff clone, .. i do not know.  Not that it matters
anyway.

Ciao,

--steffen
|
|Der Kragenbaer,The moon bear,
|der holt sich munter   he cheerfully and one by one
|einen nach dem anderen runter  wa.ks himself off
|(By Robert Gernhardt)

___
Groff-commit mailing list
Groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit

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

2020-09-15 Thread G. Branden Robinson 
gbranden pushed a commit to branch master
in repository groff.

commit 0438b1b905ebe9ac5fc678af06db911d25c3a030
Author: G. Branden Robinson 
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 
+
+   * 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 
 
* 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-nameNAME
-.ds doc-section-synopsisSYNOPSIS
-.ds doc-section-library LIBRARY
-.ds doc-section-description DESCRIPTION
-.ds doc-section-see-alsoSEE
-.ds doc-section-files   FILES
-.ds doc-section-authors AUTHORS
+.ds doc-section-nameName\"
+.ds doc-section-synopsisSynopsis\"
+.ds doc-section-library Library\"
+.ds doc-section-description Description\"
+.ds doc-section-see-alsoSee 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