[groff] 02/04: Tidy up after groff_man_style(7) split.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a40d76c5ba8e4f61b1c4fb56684f77d953b58f16
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Aug 12 21:28:20 2020 +1000

    Tidy up after groff_man_style(7) split.
    
    * ChangeLog, NEWS: Fix typo and missing comma.  (You know you've been
      writing about man macro packages way too much when you misspell
      "tmac.am" as "tmac.an" :-|.)
    
    * tmac/tmac.am: Use a stamp file for m4 keyword check.  Turns out I
      cannot tolerate the spurious rebuilds of the generated pages.
    
    * tmac/groff_man.7.man.in:
      + Add lengthy note to document maintainers (not visible in generated
        man pages).
      + Drop redundant use of dnl in black-hole diversion.
      + Add comment (visible in man page sources) noting generated status of
        document.
      + Shift more material to tutorial/style guide.
      + Recast a sentence to cope with "Portability" subsection being in the
        tutorial/style guide.  The only such cross-reference in the shorter
        reference page involves the three-font problem, which is too common
        a frustration to overlook.
      + Move explanations of typographical units to tutorial/style guide.
      + Condense a sentence.
---
 ChangeLog               |  6 +++-
 NEWS                    |  2 +-
 tmac/groff_man.7.man.in | 73 ++++++++++++++++++++++++++++++++++++++++++++-----
 tmac/tmac.am            | 13 +++++----
 4 files changed, 79 insertions(+), 15 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 19a518d..c0b1b6b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2020-08-12  G. Branden Robinson <g.branden.robinson@gmail.com>
 
+       * tmac/tmac.am: Use a stamp file for m4 keyword check.
+
+2020-08-12  G. Branden Robinson <g.branden.robinson@gmail.com>
+
        Split groff_man(7) into two pages; one a (relatively) terse
        reference and the other a tutorial and style guide.  Both are
        generated from the same source, which is processed by m4 into
@@ -15,7 +19,7 @@
        control.  Uncomment material intended only for basic reference
        page.
 
-       * tmac/tmac.an: Add groff_man_style.7 to man7_MANS.  Add
+       * tmac/tmac.am: Add groff_man_style.7 to man7_MANS.  Add
        groff_man.7.man.in to EXTRADIST.  Add m4-generated man page
        sources tmac/groff_man{,_style}.7.man to MOSTLYCLEANFILES.  Add
        targets to generate those same two pages from the renamed file.
diff --git a/NEWS b/NEWS
index f933a5e..9d876fe 100644
--- a/NEWS
+++ b/NEWS
@@ -103,7 +103,7 @@ o The an (man) macro package supports new CS and CT number 
registers to
 o The groff_man(7) man page documenting the groff implementation of the
   man macro package has been split into two pages.  The original page
   remains as a terser reference for experienced users.  A new page,
-  groff_man_style(7) is a tutorial and style guide containing the same
+  groff_man_style(7), is a tutorial and style guide containing the same
   material supplemented with explanations, examples, and advice for the
   reader who is not an expert in *roff systems or in writing man pages.
 
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index e9b4b1e..f1447f5 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -1,9 +1,44 @@
 divert(-1)
-define(`_ifstyle',`ifdef(`_groff_man_style',,`divert(-1)')')dnl
-define(`_ifnotstyle',`ifdef(`_groff_man_style',`divert(-1)')')dnl
+Note to maintainers of this document: while it is desirable to bracket
+material that differs between groff_man(7) and groff_man_style(7) as
+tightly as possible to honor the Don't Repeat Yourself principle, in
+GBR's opinion this maxim has limits.
+
+Consider this ghastly example:
+
+If no scale indicator is given,
+the
+.I man
+package assumes \(lqn\(rq\c
+_ifstyle()dnl
+; that is,
+the width of a letter \(lqn\(rq in the font current when the macro is
+called
+(see section \(lqNumerical Expressions\(rq in
+.IR groff (@MAN7EXT@))\c
+_endif
+\&.
+
+These man pages serve multiple goals, one of which is to serve as a
+model for good man page writing by people who examine its source.
+
+After processing by m4, both child pages in the above case will carry \c
+escapes followed by text lines starting with punctuation one normally
+does not find in that position (and in the case of the period, which has
+to be protected from interpretation as a control line).
+
+This is ugly, fragile, and unnecessary; all of these traits are
+offensive to good pedagogy.
+
+Consequently, it is  better to repeat a small amount of material than
+write a man page that looks like the output of docbook-to-man.
+
+define(`_ifstyle',`ifdef(`_groff_man_style',,`divert(-1)')')
+define(`_ifnotstyle',`ifdef(`_groff_man_style',`divert(-1)')')
 define(`_endif',`divert`'')
 divert`'dnl
 '\" t
+.\" This page is generated by m4 from tmac/groff_man.7.man.in.
 _ifnotstyle()dnl
 .TH groff_man @MAN7EXT@ "@MDATE@" "groff @VERSION@"
 _endif()dnl
@@ -1334,12 +1369,13 @@ _endif()dnl
 .IR text ]
 Set
 .I text
-one point smaller than the default point size.
+one point smaller than the default point size on typesetter devices.
 .
 If the macro is given no arguments,
 the text of the next input line is set smaller.
 .
 .
+_ifstyle()dnl
 .IP
 .IR Note :
 terminals will render
@@ -1353,18 +1389,21 @@ normal size;
 it will be hidden from readers using such devices.
 .
 .
+_endif()dnl
 .TP
 .BR .SB \~[\c
 .IR text ]
 Set
 .I text
-in bold,
+in bold and
+(on typesetter devices)
 one point smaller than the default point size.
 .
 If the macro is given no arguments,
 the text of the next input line is set smaller and in bold.
 .
 .
+_ifstyle()dnl
 .IP
 .IR Note :
 terminals will render
@@ -1378,7 +1417,6 @@ normal size;
 it will be hidden from readers using such devices.
 .
 .
-_ifstyle()dnl
 .PP
 Note what is
 .I not
@@ -1434,12 +1472,23 @@ double-quote an argument containing embedded space 
characters.
 .
 Setting all three different styles within a word
 presents challenges;
+_ifstyle()dnl
 it is possible with the
 .B \ec
 and/or
 .B \ef
 escapes,
-but see subsection \(lqPortability\(rq below for caveats.
+but
+_endif()dnl
+see subsection \(lqPortability\(rq
+_ifnotstyle()dnl
+in
+.IR groff_man_style (@MAN7EXT@)
+for approaches.
+_endif()dnl
+_ifstyle()dnl
+below for caveats.
+_endif()dnl
 .
 .
 .TP
@@ -1580,12 +1629,17 @@ is a number plus an optional scale indicator.
 If no scale indicator is given,
 the
 .I man
+_ifstyle()dnl
 package assumes \(lqn\(rq;
 that is,
 the width of a letter \(lqn\(rq in the font current when the macro is
 called
 (see section \(lqNumerical Expressions\(rq in
 .IR groff (@MAN7EXT@)).
+_endif()dnl
+_ifnotstyle()dnl
+package assumes \(lqn\(rq.
+_endif()dnl
 .
 An indentation specified in a call to
 .BR .IP ,
@@ -1818,10 +1872,15 @@ and the deprecated
 .
 The default inter-section and inter-paragraph spacing is
 is 1v for terminal devices
+_ifstyle()dnl
 and 0.4v for typesetter devices
 (\(lqv\(rq is a unit of vertical distance,
 where 1v is the distance between adjacent text baselines in a
 single-spaced document).
+_endif()dnl
+_ifnotstyle()dnl
+and 0.4v for typesetter devices.
+_endif()dnl
 .
 In
 .BR .EX / .EE
@@ -3046,7 +3105,7 @@ to have any effect.
 .
 .TP
 .I @LOCALMACRODIR@/\:man.local
-Local changes and customizations should be put into this file.
+Put local changes and customizations into this file.
 _ifstyle()dnl
 .
 .
diff --git a/tmac/tmac.am b/tmac/tmac.am
index f60174d..277b850 100644
--- a/tmac/tmac.am
+++ b/tmac/tmac.am
@@ -118,6 +118,7 @@ MOSTLYCLEANFILES += $(TMACMDOCFILES) \
    tmac/groff_man.7.man \
    tmac/groff_man_style.7.man \
    tmac/www.tmac \
+   tmac/*-stamp \
    tmac/stamp-wrap \
    tmac/*-wrap
 
@@ -169,18 +170,18 @@ tmac/www.tmac: tmac/www.tmac.in
          $(tmac_srcdir)/www.tmac.in > $(top_builddir)/tmac/www.tmac
 
 
+# Check input file for bare m4 keywords.
 M4WORDS = define|divert|include|index|shift|undefine|undivert
+M4CHECK = tmac/check-groff_man-stamp
 
-# Check input file for bare m4 keywords.
-#
-# Rule only reads, and is cheap; not using stamp file or phony target.
-check-groff_man: tmac/groff_man.7.man.in
+$(M4CHECK): tmac/groff_man.7.man.in
        ! grep -E '(^|[[:space:]])($(M4WORDS))($$|[[:space:]])' $<
+       > $@
 
-tmac/groff_man.7.man: tmac/groff_man.7.man.in check-groff_man
+tmac/groff_man.7.man: tmac/groff_man.7.man.in $(M4CHECK)
        m4 -D_groff_man_not_style $< > $@
 
-tmac/groff_man_style.7.man: tmac/groff_man.7.man.in check-groff_man
+tmac/groff_man_style.7.man: tmac/groff_man.7.man.in $(M4CHECK)
        m4 -D_groff_man_style $< > $@
 
 # The installation of groff compatibility wrappers for vendor-provided