gbranden pushed a commit to branch master in repository groff. commit 583f52a8c073e69682359879bb0a49f3add910be Author: G. Branden Robinson <g.branden.robin...@gmail.com> 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 Groff-commit@gnu.org https://lists.gnu.org/mailman/listinfo/groff-commit