[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 01/19: [ms]: Fix style nits in docs.
From: |
G. Branden Robinson |
Subject: |
[groff] 01/19: [ms]: Fix style nits in docs. |
Date: |
Wed, 6 Jul 2022 15:45:42 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit c44e627b6f97186829ab65afbe645e4ad5221e57
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jul 5 21:49:42 2022 -0500
[ms]: Fix style nits in docs.
* doc/ms.ms:
- Recast description of "\~" to align with current terminology in our
Texinfo manual.
- Clarify that type size parameters are ignored on terminal devices
(n.b., vertical spacing is not).
- Turn off adjustment of source examples in tbl text blocks.
- Recast to reduce terminological collisions on the term "box";
consistently refer to "boxed keeps" as such, to avoid confusion with
boxes produced by `BX` and the groff extension that is a diversion
with special behavior. All are distinct.
- Say that pages are odd- or even- _numbered_.
- Drop a hyphen from an attributive phrase. One says "the second
numbered page", not "the second-numbered page".
- Tighten wording.
- Bump document revision date.
---
doc/groff.texi | 45 ++++++++++++++++++++++++---------------------
doc/ms.ms | 40 ++++++++++++++++++++--------------------
tmac/groff_ms.7.man | 36 ++++++++++++++++++------------------
3 files changed, 62 insertions(+), 59 deletions(-)
diff --git a/doc/groff.texi b/doc/groff.texi
index 14054386..f264da67 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2677,10 +2677,9 @@ Set string @var{name} to @var{contents}. If @var{name}
exists, it is
removed first.
@endDefreq
-A list of document control registers and strings follows. They are
-presented in the syntax used to interpolate them. For any parameter
-whose default is unsatisfactory, define its register or string before
-calling any @file{ms} macro other than @code{RP}.
+A list of document control registers and strings follows. For any
+parameter whose default is unsatisfactory, define its register or string
+before calling any @file{ms} macro other than @code{RP}.
@unnumberedsubsubsec Margin settings
@@ -3189,13 +3188,17 @@ footnotes, and inclusions of material such as tables
and figures.
@cindex @file{ms} macros, text settings
The @code{FAM} string sets the font family for body text; the default is
-@samp{T} (Times). The font family setting is ignored on terminal
-devices. Setting the @code{FAM} string before the first call of a
-heading, paragraphing, or (non-date) document description macro also
-applies it to headers, footers, and (for @code{FAM}) footnotes.
+@samp{T} (Times). The @code{PS} and @code{VS} registers set the type
+size and vertical spacing (distance between text baselines),
+respectively. The font family and type size are ignored on terminal
+devices. Setting these parameters before the first call of a heading,
+paragraphing, or (non-date) document description macro also applies them
+to headers, footers, and (for @code{FAM}) footnotes.
The hyphenation mode (as used by the @code{hy} request) is set from the
-@code{HY} register.
+@code{HY} register. Setting @code{HY} to @samp{0} is equivalent to
+using the @code{nh} request. This is a Tenth Edition Research Unix
+extension.
@c ---------------------------------------------------------------------
@@ -3819,8 +3822,7 @@ One application of @code{ne} is to reserve space on the
page for a
figure or illustration to be included later.
@cindex boxes [@file{ms}]
-A keep can also be @dfn{boxed}. Text in a box is automatically placed
-in a diversion (keep).
+A keep have a frame drawn around it; this is called a @dfn{boxed keep}.
@DefmacList {B1, , ms}
@DefmacListEndx {B2, , ms}
@@ -3828,10 +3830,10 @@ in a diversion (keep).
boxed keep.
@endDefmac
-Box macros cause breaks; if you need to box a word or phrase within a
-line, see the @code{BX} macro in @ref{Typeface and decoration}. Box
-lines are drawn as close as possible to the text they enclose so that
-they are usable within paragraphs. If you wish to box one or more
+Boxed keep macros cause breaks; if you need to box a word or phrase
+within a line, see the @code{BX} macro in @ref{Typeface and decoration}.
+Box lines are drawn as close as possible to the text they enclose so
+that they are usable within paragraphs. If you wish to box one or more
paragraphs, you may improve the appearance by calling @code{B1} after
the first paragraphing macro, and by adding a small amount of vertical
space before calling @code{B2}.
@@ -3847,8 +3849,9 @@ speeds.
.B2
@endCartoucheExample
-If you want a box to float, you will need to enclose the @code{B1} and
-@code{B2} calls within a pair of @code{KF} and @code{KE} calls.
+If you want a boxed keep to float, you will need to enclose the
+@code{B1} and @code{B2} calls within a pair of @code{KF} and @code{KE}
+calls.
@cindex displays [@file{ms}]
@dfn{Displays} turn off filling; lines of verse or program code are
@@ -4183,11 +4186,11 @@ There are multiple ways to produce headers and footers.
One is to
define the strings @code{LH}, @code{CH}, and @code{RH} to set the left,
center, and right headers, respectively; and @code{LF}, @code{CF}, and
@code{RF} to set the left, center, and right footers similarly. This
-approach works best for documents that do not distinguish odd and even
-pages.
+approach works best for documents that do not distinguish odd- and
+even-numbered pages.
Another method is to call macros with arguments that set headers or
-footers for odd or even pages; these variables produce four
+footers for odd- or even-numbered pages; these variables produce four
combinations, so four macros are available. Each takes a delimiter
separating the left, center, and right header or footer texts from each
other. You can replace the neutral apostrophes (@code{'}) with any
@@ -4224,7 +4227,7 @@ 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.
+desired specialization for odd-, even-, or first numbered pages.
@c ---------------------------------------------------------------------
diff --git a/doc/ms.ms b/doc/ms.ms
index 559e54ef..a5f3358f 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -22,8 +22,8 @@
.nr TC-MARGIN \w'00' \" expect 2-digit page numbers at most
.ie t .nr PI 3.5n
.el .nr PI 4n
-.ND June 2022
-.EH '%''June 2022'
+.ND July 2022
+.EH '%''July 2022'
.EF ''''
.OH 'Using \f[I]groff\f[] with the \f[I]ms\f[] macros''%'
.OF ''''
@@ -316,8 +316,7 @@ Interpolate glyph of special character named
T}
\[rs]& non-printing, zero-width dummy character
\[rs]\[ti] T{
-Move horizontally by the current font's space width
-(\[lq]non-breaking space\[rq]).
+Insert an unbreakble space that is adjustable like a normal space.
T}
\[rs]| T{
Move horizontally by one-sixth em
@@ -482,8 +481,8 @@ Document control settings
.
.
.LP
-The following list of document parameters is presented in the syntax
-used to interpolate them.
+The document parameters below are presented in the syntax
+used to interpolate their values.
.
For any unsatisfactory default,
define its register,
@@ -846,8 +845,6 @@ the default is
.CW T \[rq] \[lq]
(Times).
.
-The font family setting is ignored on terminal devices.
-.
The
.CW PS
and
@@ -856,6 +853,8 @@ registers set the type size and vertical spacing
(distance between text baselines),
respectively.
.
+The font family and type size are ignored on terminal devices.
+.
Setting these parameters before the first call of a heading,
paragraphing,
or (non-date) document description macro also applies them to headers,
@@ -1649,6 +1648,7 @@ Cb Cb
Lf(CR) L.
Input Result
T{
+.na
The course\[aq]s students found one C language keyword
.br
\&.CW static ) \[rs]%(
@@ -1676,6 +1676,7 @@ Cb Cb
Lf(CR) L.
Input Result
T{
+.na
The course\[aq]s students found one C language keyword
.br
(\[rs]c
@@ -2145,10 +2146,9 @@ included later.
.
.
.PP
-A keep can also be
-.I boxed .
-.
-Text in a box is automatically placed in a diversion (keep).
+A keep have a frame drawn around it;
+this is called a
+.I "boxed keep."
.
.
.TS
@@ -2163,7 +2163,7 @@ _
.
.
.LP
-Box macros cause breaks;
+Boxed keep macros cause breaks;
if you need to box a word or phrase within a line,
see the
.CW BX
@@ -2172,8 +2172,8 @@ macro in section \[lq]Typeface and decoration\[rq] above.
Box lines are drawn as close as possible to the text they enclose so
that they are usable within paragraphs.
.
-If you wish to box one or more paragraphs,
-you may improve the appearance by calling
+If you wish to place one or more paragraphs in a boxed keep,
+you may improve their appearance by calling
.CW .B1
after the first paragraphing macro,
and by adding a small amount of vertical space before calling
@@ -2193,7 +2193,7 @@ Happy Fun Ball may suddenly accelerate to dangerous
speeds.
.
.
.LP
-If you want a box to float,
+If you want a boxed keep to float,
you will need to enclose the
.CW .B1
and
@@ -2981,13 +2981,13 @@ to set the left,
center,
and right footers similarly.
.
-This approach works best for documents that do not distinguish odd and
-even pages.
+This approach works best for documents that do not distinguish odd- and
+even-numbered pages.
.
.
.PP
Another method is to call macros with arguments that set headers or
-footers for odd or even pages;
+footers for odd- or even-numbered pages;
these variables produce four combinations,
so four macros are available.
.
@@ -3096,7 +3096,7 @@ hook is a Berkeley extension.
Any such macros you (re)define must implement any desired specialization
for odd-,
even-,
-or first-numbered pages.
+or first numbered pages.
.
.
.KS
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 1a1a822f..d1c2828a 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -8,7 +8,7 @@ groff_ms \- GNU roff manuscript macro package for formatting
documents
.\" Legal Terms
.\" ====================================================================
.\"
-.\" Copyright (C) 1989-2021 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2022 Free Software Foundation, Inc.
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
@@ -217,12 +217,12 @@ its preparation requires separate processing.
.SS "Document control settings"
.\" ====================================================================
.
-The following tables list the document control registers and strings.
+The following tables list the document control registers,
+strings,
+and special characters.
.
For any parameter whose default is unsatisfactory,
-define its register,
-string,
-or special character before calling any
+define it before calling any
.I ms
macro other than
.BR RP .
@@ -586,8 +586,6 @@ the default is
.RB \[lq] T \[rq]
(Times).
.
-The font family setting is ignored on terminal devices.
-.
The
.B PS
and
@@ -596,6 +594,8 @@ registers set the type size and vertical spacing
(distance between text baselines),
respectively.
.
+The font family and type size are ignored on terminal devices.
+.
Setting these parameters before the first call of a heading,
paragraphing,
or (non-date) document description macro also applies them to headers,
@@ -1251,9 +1251,9 @@ vertical space specified in its argument remaining on the
page.
.
.
.PP
-A keep can also be boxed.
-.
-Text in a box is automatically placed in a diversion (keep).
+A keep have a frame drawn around it;
+this is called a
+.I boxed keep.
.
.
.TP
@@ -1267,7 +1267,7 @@ End boxed keep.
.
.
.P
-Box macros cause breaks;
+Boxed keep macros cause breaks;
if you need to box a word or phrase within a line,
see the
.B BX
@@ -1276,8 +1276,8 @@ macro in section \[lq]Highlighting\[rq] above.
Box lines are drawn as close as possible to the text they enclose so
that they are usable within paragraphs.
.
-If you wish to box one or more paragraphs,
-you may improve the appearance by calling
+If you wish to place one or more paragraphs in a boxed keep,
+you may improve their appearance by calling
.B .B1
after the first paragraphing macro,
and by adding a small amount of vertical space before calling
@@ -1285,7 +1285,7 @@ and by adding a small amount of vertical space before
calling
.
.
.P
-If you want a box to float,
+If you want a boxed keep to float,
you will need to enclose the
.B .B1
and
@@ -1771,13 +1771,13 @@ to set the left,
center,
and right footers similarly.
.
-This approach works best for documents that do not distinguish odd and
-even pages.
+This approach works best for documents that do not distinguish odd- and
+even-numbered pages.
.
.
.P
Another method is to call macros with arguments that set headers or
-footers for odd or even pages;
+footers for odd- or even-numbered pages;
these variables produce four combinations,
so four macros are available.
.
@@ -1873,7 +1873,7 @@ hook is a Berkeley extension.
Any such macros you (re)define must implement any desired specialization
for odd-,
even-,
-or first-numbered pages.
+or first numbered pages.
.
.
.\" ====================================================================
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 01/19: [ms]: Fix style nits in docs.,
G. Branden Robinson <=