gbranden pushed a commit to branch master
in repository groff.
commit bcda589fdf0f271b892dd28507e1f549a754fd5b
Author: G. Branden Robinson <[email protected]>
AuthorDate: Thu Jul 9 11:19:41 2026 -0500
[ms]: Tighten discussion of optional macro args.
Also synchronize material between our ms manual, our Texinfo manual, and
our ms(7) man page.
Break Texinfo input lines in convenient places for roffing and diffing.
In man page, consistently quote the word "no" when used as a macro
argument; setting it in boldface does not survive copy-and-paste
operations, or serve to highlight it specially when rendered as unstyled
text.
---
doc/groff.texi.in | 135 ++++++++++++++++++++++++++++++++++++++--------------
doc/ms.ms.in | 38 +++++++--------
tmac/groff_ms.7.man | 32 ++++++-------
3 files changed, 135 insertions(+), 70 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index e87a0acae..3fb10e7bd 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -3064,7 +3064,7 @@ and consistently formatted bibliographic citations.
@code{groff} @file{ms}
is mostly compatible with the documented interface
and behavior of AT&T Unix Version@tie{}7
-@code{ms}.
+@file{ms}.
It recreates most extensions from 4.2BSD (Berkeley)
@c Few changes were made in 4.3, Tahoe, Reno, or 4.4.
and Research Tenth Edition Unix.
@@ -3111,6 +3111,7 @@ identifiers use only capital letters,
numerals,
and
@samp{-}.
+Macro arguments surrounded by [brackets] are optional.
@menu
* ms basic information::
@@ -3761,31 +3762,79 @@ Default: @code{\w'000'}
@cindex document description macros, [@file{ms}]
Only the simplest document lacks a title.@footnote{Distinguish a
-document title from ``titles'', which are what @code{roff} systems call
-headers and footers collectively.} As its level of sophistication (or
-complexity) increases, it tends to acquire a date of revision,
-explicitly identified authors, sponsoring institutions for authors, and,
-at the rarefied heights, an abstract of its content. Define these
-data by calling the macros below in the order shown; @code{DA} or
-@code{ND} can be called to set the document date (or other identifier)
-at any time before (a) the abstract, if present, or (b) its information
-is required in a header or footer. Use of these macros is optional,
-except that @code{TL} is mandatory if any of @code{RP}, @code{AU},
-@code{AI}, or @code{AB} is called, and @code{AE} is mandatory if
-@code{AB} is called.
+document title from ``titles'',
+which are what
+@code{roff}
+systems call headers and footers collectively.}
+As its level of sophistication
+(or complexity)
+increases,
+it tends to acquire a date of revision,
+explicitly identified authors,
+sponsoring institutions for authors,
+and,
+at the rarefied heights,
+an abstract of its content.
+By default,
+@file{ms}
+.I ms
+arranges most of the document description
+(the title,
+author names and institutions,
+and abstract,
+but not the date)
+at the top of the first page.
+
+Define these
+data by calling the macros below in the order shown;
+@code{DA}
+or
+@code{ND}
+can be called to set the document date
+(or other identifier)
+at any time before
+(a) the abstract,
+if present,
+or
+(b) its information is required in a header or footer.
+Use of these macros is optional,
+except that
+@code{TL}
+is mandatory if any of
+@code{RP},
+@code{AU},
+@code{AI},
+or
+@code{AB}
+is called, and
+@code{AE}
+is mandatory if
+@code{AB}
+is called.
@Defmac {RP, [@code{no-repeat-info}] [@code{no-renumber}], ms}
-Use the ``report'' (@acronym{AT&T}: ``released paper'') format for your
-document, creating a separate cover page. The default arrangement is to
-place most of the document description (title, author names and
-institutions, and abstract, but not the date) at the top of the first
-page. If the optional @code{no-repeat-info} argument is given,
-@file{ms} produces a cover page but does not repeat any of its
-information subsequently (but see the @code{DA} macro below regarding
-the date). Normally, @code{RP} sets the page number following the cover
-page to@tie{}1. Specifying the optional @code{no-renumber} argument
-suppresses this alteration.
-Optional arguments can occur in any order.
+Use the ``report''
+(@acronym{AT&T}:@:
+``released paper'')
+format for your document,
+creating a separate cover page.
+A
+@code{no-repeat-info}
+argument causes
+@file{ms}
+to produce a cover page
+without repeating any of its information subsequently
+(but see the
+@code{DA}
+macro below regarding
+the date).
+Normally,
+@code{RP}
+sets the page number following the cover page to@tie{}1.
+Specifying the
+@code{no-renumber}
+argument suppresses this alteration.
+Arguments can occur in any order.
@file{ms}
recognizes
@code{no}
@@ -3834,7 +3883,8 @@ page. This is @code{groff} @file{ms}'s default.
Begin the abstract. @file{ms} collects text on input lines following
this call into the abstract until reaching an @code{AE} call. By
default, @file{ms} places the word ``ABSTRACT'' centered and in italics
-above the text of the abstract. The optional argument @code{no}
+above the text of the abstract.
+@code{no}
suppresses this heading.
@endDefmac
@@ -3978,7 +4028,6 @@ in the @code{PI} register.
@Defmac {IP, [@Var{mark} [@Var{width}]], ms}
Set a paragraph with a left indentation.
-The optional
@var{mark}
is not indented and is empty by default.
It has several applications;
@@ -4148,8 +4197,11 @@ labels, and @code{XS}/@code{XA}/@code{XE} table of
contents entries.
@Defmac {SH, [@Var{depth}] [@Var{name}], ms}
Set an unnumbered heading.
-The optional @var{depth} argument is a GNU extension indicating the
-heading depth corresponding to the @var{depth} argument of @code{NH}.
+@var{depth}
+is a GNU extension indicating the heading depth corresponding to the
+@var{depth}
+argument of
+@code{NH}.
It matches the type size at which the heading is set to that of a
numbered heading at the same depth when the @code{GROWPS} and
@code{PSINCR} heading size adjustment mechanism is in effect.
@@ -4759,13 +4811,26 @@ The formatter interprets them as macro calls.
@DefmacList {TS, [@code{H}], ms}
@DefmacListEndx {TE, , ms}
-Demarcate a table to be processed by the @code{tbl} preprocessor. The
-optional argument@tie{}@code{H} to @code{TS} instructs @file{ms} to
-repeat table rows (often column headings) at the top of each new page
-the table spans, if applicable; calling the @code{TH} macro marks the
-end of such rows. The GNU @cite{tbl@r{(1)}} man page provides a
-comprehensive reference to the preprocessor and offers examples of its
-use.
+Demarcate a table to be processed by the
+@code{tbl}
+preprocessor.
+An
+@code{H}
+argument to
+@code{TS}
+instructs
+@file{ms}
+to repeat table rows
+(often column headings)
+at the top of each new page the table spans,
+if applicable;
+calling the
+@code{TH}
+macro marks the end of such rows.
+The GNU
+@cite{tbl@r{(1)}}
+man page provides a comprehensive reference
+to the preprocessor and offers examples of its use.
@endDefmac
@DefmacList {PS, @var{h} @var{v}, ms}
diff --git a/doc/ms.ms.in b/doc/ms.ms.in
index 66a933f60..ffbfe8ebc 100644
--- a/doc/ms.ms.in
+++ b/doc/ms.ms.in
@@ -170,6 +170,9 @@ numerals,
and
.CW \- \[rq]. \[lq]
.
+Macro arguments surrounded by [brackets] are optional.
+.
+.
.PP
To turn on PDF features please use
.CW -rPDFFEAT=1
@@ -792,16 +795,17 @@ _
.TH
\&.RP \f[R][\f[I]option\f[] .\|.\|.] T{
Use the \[lq]report\[rq]
-(AT&T: \[lq]released paper\[rq])
+(AT&T:
+\[lq]released paper\[rq])
format for your document,
creating a separate cover page.
.
-If the optional
+A
.CW no\-\:\%repeat\-\:\%info
-argument is given,
+argument causes
.I ms
-produces a cover page but does not repeat any of its information
-subsequently
+to produce a cover page
+without repeating any of its information subsequently
(but see the
.CW DA
macro below regarding the date).
@@ -810,21 +814,21 @@ Normally,
.CW RP
sets the page number following the cover page to\~1.
.
-Specifying the optional
+Specifying the
.CW no\-\:\%renumber
argument suppresses this alteration.
.
-Optional arguments can occur in any order.
+Arguments can occur in any order.
.
.I ms
recognizes
-.CW no
+.CW no \*[U] \*[Q]
as a synonym of
.CW no\-\:\%repeat\-\:\%info
to maintain AT&T compatibility.
.
Options other than
-.CW no
+.CW no \*[U] \*[Q]
are GNU extensions.
T}
_
@@ -915,8 +919,7 @@ By default,
places the word \[lq]ABSTRACT\[rq] centered and in italics above the
text of the abstract.
.
-The optional argument
-.CW no
+.CW no \*[U] \*[Q]
suppresses this heading.
T}
_
@@ -1179,7 +1182,6 @@ _
\&.IP \f[R][\f[I]mark\f[] [\f[I]width\f[]]] T{
Set a paragraph with a left indentation.
.
-The optional
.I mark
is not indented and is empty by default.
.
@@ -1496,10 +1498,8 @@ _
\&.SH [\f[I]depth\f[]] \fI\m[red][name]\m[]\fP T{
Set an unnumbered heading.
.
-The optional
.I depth
-argument is a GNU extension indicating the heading depth corresponding
-to the
+is a GNU extension indicating the heading depth corresponding to the
.I depth
argument of
.CW NH .
@@ -2590,7 +2590,7 @@ Demarcate a table to be processed by the
.I tbl
preprocessor.
.
-The optional
+An
.CW H
argument to
.CW TS
@@ -3726,7 +3726,7 @@ Each entry is associated with
a
.I page-number
of
-.CW no
+.CW no \*[U] \*[Q]
prevents a leader and page number from being emitted for that entry.
.
Use of
@@ -3757,7 +3757,7 @@ _
Switch to single-column layout.
.
Unless
-.CW no
+.CW no \*[U] \*[Q]
is specified,
center and interpolate
.CW \[rs]*[TOC]
@@ -3772,7 +3772,7 @@ the page number format to lowercase Roman numerals,
and call
.CW PX
(with a
-.CW no
+.CW no \*[U] \*[Q]
argument,
if present).
T}
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 17773c5bb..9c3215b97 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -490,7 +490,8 @@ is called.
.TP
.BR .RP\~ [ no\-repeat\-info ]\~[ no\-renumber ]
Use the \[lq]report\[rq]
-(AT&T: \[lq]released paper\[rq])
+(AT&T:
+\[lq]released paper\[rq])
format for your document,
creating a separate cover page.
.
@@ -501,12 +502,12 @@ and abstract,
but not the date)
at the top of the first page.
.
-If the optional
+A
.B no\-\:\%repeat\-\:\%info
-argument is given,
+argument causes
.I ms
-produces a cover page but does not repeat any of its information
-subsequently
+to produce a cover page
+without repeating any of its information subsequently
(but see the
.B DA
macro below regarding the date).
@@ -515,21 +516,21 @@ Normally,
.B RP
sets the page number following the cover page to\~1.
.
-Specifying the optional
+Specifying the
.B no\-\:\%renumber
argument suppresses this alteration.
.
-Optional arguments can occur in any order.
+Arguments can occur in any order.
.
.I ms
recognizes
-.B no
+.RB \[lq] no \[rq]
as a synonym of
.B no\-\:\%repeat\-\:\%info
to maintain AT&T compatibility.
.
Options other than
-.B no
+.RB \[lq] no \[rq]
are GNU extensions.
.
.
@@ -628,7 +629,6 @@ By default,
places the word \[lq]ABSTRACT\[rq] centered and in italics above the
text of the abstract.
.
-The optional argument
.RB \[lq] no \[rq]
suppresses this heading.
.
@@ -782,9 +782,9 @@ register.
.IR mark \~[ width ]]
Set a paragraph with a left indentation.
.
-The optional
.I mark
is not indented,
+.\" the following line is unique to groff_ms(7)
is useful in the construction of lists,
and is empty by default.
.
@@ -984,10 +984,8 @@ table of contents entries.
.IR depth "] [" name
Set an unnumbered heading.
.
-The optional
.I depth
-argument is a GNU extension indicating the heading depth corresponding
-to the
+is a GNU extension indicating the heading depth corresponding to the
.I depth
argument of
.BR NH .
@@ -1573,8 +1571,10 @@ Demarcate a table to be processed by the
.I tbl
preprocessor.
.
-The optional
-.BR H "\~argument"
+An
+.B H
+arugment to
+.B TS
instructs
.I ms
to repeat table rows
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
