[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 03/17: [ms]: Fix documentation style nits.
From: |
G. Branden Robinson |
Subject: |
[groff] 03/17: [ms]: Fix documentation style nits. |
Date: |
Sat, 23 Jul 2022 12:40:44 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 5408e1340cb438252b0ad4dac91c3eb53a95811d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Jul 17 06:18:10 2022 -0500
[ms]: Fix documentation style nits.
* Drop redundant sentence from ms.ms and our Texinfo manual, which have
the "Basic information" section.
* Annotate the 4.2BSD `HD` macro as originally undocumented.
* Improve introduction to body text macros.
* Vary wording.
---
doc/groff.texi | 18 ++++++++++--------
doc/ms.ms | 12 ++++--------
tmac/groff_ms.7.man | 7 +++++--
3 files changed, 19 insertions(+), 18 deletions(-)
diff --git a/doc/groff.texi b/doc/groff.texi
index 126348f3..112e0b2f 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2612,8 +2612,7 @@ Wallace said my exposure had been
The @file{ms} macro package expects a certain amount of structure:
a well-formed document contains at least one paragraphing or heading
-macro call. To compose a document from scratch, begin it by calling
-@code{LP} or @code{PP}. Longer documents have a structure as follows.
+macro call. Longer documents have a structure as follows.
@table @strong
@item Document type
@@ -3168,8 +3167,9 @@ added features are more in line with user demand.
@cindex @file{ms} macros, body text
A variety of macros, registers, and strings can be used to structure and
-style the body of your document. Examples include paragraphs, headings,
-footnotes, and inclusions of material such as tables and figures.
+style the body of your document. They organize your text into
+paragraphs, headings, footnotes, and inclusions of material such as
+tables and figures.
@menu
* Text settings in ms::
@@ -3401,7 +3401,7 @@ define the alias as follows.
Any such change in numbering style becomes effective from the next use
of @code{NH} following redefinition of the alias for @code{SN-STYLE}.
The formatted number of the current heading is available in the
-@code{SN} string (a feature first documented by Berkeley); this feature
+@code{SN} string (a feature first documented by Berkeley); this string
facilitates its inclusion in, for example, table captions, equation
labels, and @code{XS}/@code{XA}/@code{XE} table of contents entries.
@endDefmpstr
@@ -4238,9 +4238,11 @@ be written, and @code{BT} (``bottom trap'') when the
footer is to be.
The page location trap that @file{ms} sets up to format the header also
calls the (normally undefined) @code{HD} macro after @code{PT}; you can
define @code{HD} if you need additional processing after setting the
-header (for example, to draw a line below it). The @code{HD} hook is a
-Berkeley extension. Any such macros you (re)define must implement any
-desired specialization for odd-, even-, or first numbered pages.
+header (for example, to draw a line below it).
+@c Although undocumented in Tuthill's 4.2BSD ms.diffs paper...
+The @code{HD} hook is a Berkeley extension. Any such macros you
+(re)define must implement any desired specialization for odd-, even-, or
+first numbered pages.
@c ---------------------------------------------------------------------
diff --git a/doc/ms.ms b/doc/ms.ms
index 64340c1e..b670ece8 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -369,12 +369,6 @@ macro package expects a certain amount of structure:
a well-formed document contains at least one paragraphing or heading
macro call.
.
-To compose a document from scratch,
-begin it by calling
-.CW .LP
-or
-.CW .PP .
-.
Longer documents have a structure as follows.
.
.
@@ -837,7 +831,8 @@ registers,
and strings can be used to structure and style the body of your
document.
.
-Examples include paragraphs,
+They organize your text into
+paragraphs,
headings,
footnotes,
and inclusions of material such as tables and figures.
@@ -1279,7 +1274,7 @@ following redefinition of the alias for
The formatted number of the current heading is available in
.CW \[rs]*[SN]
(a feature first documented by Berkeley);
-this feature facilitates its inclusion in,
+this string facilitates its inclusion in,
for example,
table captions,
equation labels,
@@ -3146,6 +3141,7 @@ if you need additional processing after setting the header
(for example,
to draw a line below it).
.
+.\" Although undocumented in Tuthill's 4.2BSD ms.diffs paper...
The
.CW HD
hook is a Berkeley extension.
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 7dd5c7a9..888fe918 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -107,7 +107,9 @@ macro package expects a certain amount of structure:
a well-formed document contains at least one paragraphing or heading
macro call.
.
-To compose a document from scratch,
+.\" This sentence is unique to the man page because we omit the "Basic
+.\" information" section from ms.ms.
+To compose a simple document from scratch,
begin it by calling
.B .LP
or
@@ -894,7 +896,7 @@ following redefinition of the alias for
The formatted number of the current heading is available in
.B \[rs]*[SN]
(a feature first documented by Berkeley);
-this feature facilitates its inclusion in,
+this string facilitates its inclusion in,
for example,
table captions,
equation labels,
@@ -1887,6 +1889,7 @@ you can define
.B .HD
if you need additional processing after setting the header.
.
+.\" Although undocumented in Tuthill's 4.2BSD ms.diffs paper...
The
.B HD
hook is a Berkeley extension.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 03/17: [ms]: Fix documentation style nits.,
G. Branden Robinson <=