gbranden pushed a commit to branch master
in repository groff.
commit 583f52a8c073e69682359879bb0a49f3add910be
Author: G. Branden Robinson <[email protected]>
AuthorDate: Wed Jul 31 01:12:57 2024 -0500
groff_mm(7): Fix content, style, and markup nits.
Content:
* Specify the 3.3 version of DWB mm as the one that groff mm largely
reimplements. Recent changes have made them more similar, especially
with respect to `LT` letters and `MT` memoranda.
* Advise user to double-quote macro arguments requiring spaces. Expand
example of macro call accordingly.
* Define the term "hook" in introduction to "Macros" section, and apply
it without recapitulating explanation in macro descriptions.
Style:
* Favor active voice over passive.
* Suggest use of explicit scaling units earlier and at less length.
* Fix grammar nit.
Markup:
* Break input lines before multi-word parentheticals.
---
contrib/mm/groff_mm.7.man | 79 ++++++++++++++++++++++++-----------------------
1 file changed, 41 insertions(+), 38 deletions(-)
diff --git a/contrib/mm/groff_mm.7.man b/contrib/mm/groff_mm.7.man
index d02bd721d..a236eb9ee 100644
--- a/contrib/mm/groff_mm.7.man
+++ b/contrib/mm/groff_mm.7.man
@@ -128,8 +128,8 @@ adds an item and
.B LE
ends the (nested) list.
.
-Customized list arrangements are supported by
-.BR LB .
+.B LB
+begins a list with customizable layout parameters.
.
.B DS
and
@@ -144,7 +144,7 @@ either is terminated with
.I groff mm
is intended to be compatible with the
.I mm
-implementation found in the AT&T Documenter's Workbench (DWB),
+implementation found in the AT&T Documenter's Workbench (DWB) 3.3,
with the following limitations and changes.
.
.
@@ -292,13 +292,15 @@ and vertical ones in vees
(scaling unit
.BR v ).
.
+Use explicit scaling units for clarity and predictable behavior.
+.
.
.\" ====================================================================
.SS "Document styles"
.\" ====================================================================
.
.I groff mm
-offers three different frameworks for document organization.
+offers three frameworks for document organization.
.
.BR \%COVER /\: \%COVEND
is a flexible means of preparing any document requiring a cover page.
@@ -593,30 +595,18 @@ for instance with
.SH Macros
.\" ====================================================================
.
-Where a macro accepts an argument expressing a measurement,
-horizontal ones
-(such as indentation)
-are by default reckoned in ens,
-and vertical ones
-(such as spacing around a display)
-are reckoned in vees.
-.
-Use an explicit scaling unit for clarity and predictable behavior.
+Double-quote macro arguments that contain space characters.
.
-.
-.P
-An explicitly empty argument may be specified with a pair of double
-quotes;
-to call a macro
-.B XX
-with an empty second argument but non-empty first and third ones,
-you could input the following.
+An explicitly empty argument may be specified
+with an empty pair of double quotes;
+for example,
+the following macro call has three arguments.
.
.
.P
.RS
.EX
-\&.XX foo \[dq]\[dq] baz
+\&.XX \[dq]foo bar\[dq] \[dq]\[dq] baz
.EE
.RE
.
@@ -630,6 +620,17 @@ if any).
.
.
.P
+.I Hook
+macros are undefined by default;
+.I mm
+calls them to enable customization of its behavior.
+.
+(DWB
+.I mm
+termed these \[lq]exits\[rq].)
+.
+.
+.P
Macro names longer than two characters are GNU extensions;
some shorter names were not part of DWB
.IR mm 's
@@ -717,8 +718,8 @@ and
.
.TP
.B AFX
-This user-definable hook macro assumes responsibility for formatting
-the affiliated firm name defined by
+Define this hook macro to assume responsibility for formatting the
+affiliated firm name defined by
.B AF
in memorandum types 0 and 4 and documents using the
.I ms
@@ -729,10 +730,10 @@ If not defined
internally defined macros handle this task;
see sections \[lq]Internals\[rq] and \[lq]Files\[rq] below.
.
-Applications include setting the firm name in a different font family,
-at a larger type size,
+Applications include setting the firm name in a different font family
+or at a larger type size,
drawing a rule across the page,
-and including an logo image using
+and including a logo image using
.IR groff 's
.B PDFPIC
or
@@ -2032,22 +2033,22 @@ register.
.IP
.I Customizing heading behavior.
.
-.I mm
+.B H
calls
-.I hook
-macros to enable further customization of headings.
-.
-(DWB
-.I mm
-termed them \[lq]exits\[rq].)
+.BR HX ,
+.BR HY ,
+and
+.B HZ
+hook macros to further customize headings.
.
-Hooks can change the heading's
+These can change the heading's
.I mark
(the numbered portion before any heading title),
its vertical spacing,
and its vertical space requirements
(for instance,
-to require a minimum quantity of subsequent output lines).
+to require a minimum quantity of subsequent output lines on the page,
+breaking the page otherwise).
.
Define hook macros in expectation of the following parameters.
.
@@ -2058,7 +2059,8 @@ is the
argument to
.BR H ,
.RB or\~ 0
-for unnumbered headings (see
+for unnumbered headings
+(see
.BR HU ).
.
.I actual-level
@@ -2344,7 +2346,8 @@ B@page number, tab character, heading mark
If
.I macro
is specified,
-it is called for each index entry
+.I "groff mm"
+calls it for each index entry
with the arguments given to
.BR IND .
.
_______________________________________________
Groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
