[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 02/04: Tidy up after groff_man_style(7) split.
From: |
G. Branden Robinson |
Subject: |
[groff] 02/04: Tidy up after groff_man_style(7) split. |
Date: |
Wed, 12 Aug 2020 09:02:31 -0400 (EDT) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 02/04: Tidy up after groff_man_style(7) split.,
G. Branden Robinson <=