[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 06/35: [ms]: Fix content and style nits in docs.
From: |
G. Branden Robinson |
Subject: |
[groff] 06/35: [ms]: Fix content and style nits in docs. |
Date: |
Fri, 15 Jul 2022 23:11:56 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 5d86222a062cb5b2afd711a7d2697be71b1ad9cb
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Jul 8 01:06:04 2022 -0500
[ms]: Fix content and style nits in docs.
* Distinguish spaces from horizontal motions.
* Consistently refer to "GNU extensions".
* Tighten wording.
* Vary wording.
* Adjust dead-tree typography (using keeps in ms(7) and .br/.ne in
man(7)).
---
doc/groff.texi | 32 +++++++++++++++-----------------
doc/ms.ms | 36 ++++++++++++++++--------------------
tmac/groff_ms.7.man | 38 ++++++++++++++++++--------------------
3 files changed, 49 insertions(+), 57 deletions(-)
diff --git a/doc/groff.texi b/doc/groff.texi
index 4fcf0e56..fc7ebeb4 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -3218,8 +3218,8 @@ Interpolate an em dash.
@DefmpstrList {Q, ms}
@DefmpstrListEndx {U, ms}
Interpolate typographer's quotation marks where available, and neutral
-quotes otherwise. @code{\*Q} is the left quote and @code{\*U} the
-right. (As a mnemonic, think of ``quote'' and ``unquote''.)
+double quotes otherwise. @code{\*Q} is the left quote and @code{\*U}
+the right.
@endDefmpstr
@c ---------------------------------------------------------------------
@@ -3478,7 +3478,7 @@ until the next highlighting, paragraphing, or heading
macro call.
@Defmac {R, [@Var{text} [@Var{post} [@Var{pre}]]], ms}
As @code{B}, but use the roman style (upright text of normal weight)
-instead of bold.
+instead of bold. Argument recognition is a GNU extension.
@endDefmac
@Defmac {I, [@Var{text} [@Var{post} [@Var{pre}]]], ms}
@@ -3500,9 +3500,9 @@ instead of bold. This is a Tenth Edition Research Unix
extension.
@Defmac {BX, [@Var{text}], ms}
Typeset @var{text} and draw a box around it. On terminal devices,
reverse video is used instead (see the implementation note below).
-If you want @var{text} to contain space, use horizontal motion escape
-sequences of appropriate width (@code{\~}, @code{\^}, @code{\|},
-@code{\0} or @code{\h}).
+If you want @var{text} to contain space, use unbreakable space or
+horizontal motion escape sequences (@code{\~}, @code{\SP}, @code{\^},
+@code{\|}, @code{\0} or @code{\h}).
@endDefmac
@Defmac {UL, [@Var{text} [@Var{post}]], ms}
@@ -4067,8 +4067,7 @@ corresponding @code{FS} call as long as each @code{FS}
call occurs
Footnote text is formatted as paragraphs are, using analogous
parameters. The registers @code{FI}, @code{FPD}, @code{FPS}, and
@code{FVS} correspond to @code{PI}, @code{PD}, @code{PS}, and @code{CS},
-respectively. The @code{FPD}, @code{FPS}, and @code{FVS} registers are
-GNU extensions.
+respectively; @code{FPD}, @code{FPS}, and @code{FVS} are GNU extensions.
The @code{FF} register controls the formatting of automatically numbered
footnote paragraphs and those for which @code{FS} is given a marker
@@ -4189,13 +4188,12 @@ center, and right headers, respectively; and @code{LF},
@code{CF}, and
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-numbered pages; these variables produce four
-combinations, so four macros are available. Each takes a delimiter
+Another method is to call macros that set headers or footers for odd- or
+even-numbered pages. Each such macro takes a delimited argument
separating the left, center, and right header or footer texts from each
-other. You can replace the neutral apostrophes (@code{'}) with any
-character not appearing in the header or footer text. These macros are
-Berkeley extensions.
+other. You can replace the neutral apostrophes (@code{'}) shown below
+with any character not appearing in the header or footer text. These
+macros are Berkeley extensions.
@DefmacList {OH,
@code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}, ms}
@DefmacItemx {EH,
@code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}, ms}
@@ -4450,8 +4448,8 @@ multiplied by 1000. See the @code{PS} register in
@ref{ms Document
Control Settings}.
@item
-@acronym{AT&T} @file{ms}'s @code{AU} macro recognized arguments that
-were used with some cover sheet types; @code{groff} @file{ms} does not.
+@acronym{AT&T} @file{ms}'s @code{AU} macro supported arguments used with
+some document types; @code{groff} @file{ms} does not.
@item
Right-aligned displays are available. The @acronym{AT&T} @file{ms}
@@ -4552,7 +4550,7 @@ original at hand. For informal purposes, a simple
definition of
@cindex strings [@file{ms}]
@code{groff} @file{ms} retains support for some legacy features solely
-to support rendering of historical documents; contemporary ones should
+to support formatting of historical documents; contemporary ones should
not use them because they can render poorly. See the
@cite{groff_char@r{(7)}} man page.
diff --git a/doc/ms.ms b/doc/ms.ms
index 100b3cdb..9c77e065 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -911,15 +911,12 @@ _
_
\[rs]*[Q] T{
Interpolate typographer's quotation marks where available,
-and neutral quotes otherwise.
+and neutral double quotes otherwise.
.
.CW \[rs]*[Q]
is the left quote and
.CW \[rs]*[U]
the right.
-.
-(As a mnemonic,
-think of \*[Q]quote\*[U] and \*[Q]unquote\*[U].)
T}
\[rs]*[U] \^
.TE
@@ -1504,8 +1501,7 @@ but use the roman style
(upright text of normal weight)
instead of bold.
.
-Arguments are recognized only by
-.I "groff ms."
+Argument recognition is a GNU extension.
T}
_
\&.I \f[R][\f[I]text\f[] [\f[I]post\f[] [\f[I]pre\f[]]]] T{
@@ -1552,8 +1548,10 @@ reverse video is used instead
If you want
.I text
to contain space,
-use horizontal motion escape sequences of appropriate width
+use unbreakable space or horizontal motion escape sequences
.CW \[rs]\[ti] , (
+.CW \[rs]\c
+.I space ,
.CW \[rs]\[ha] ,
.CW \[rs]| ,
.CW \[rs]0 ,
@@ -2162,6 +2160,7 @@ _
.TE
.
.
+.KS
.LP
Boxed keep macros cause breaks;
if you need to box a word or phrase within a line,
@@ -2190,6 +2189,7 @@ Happy Fun Ball may suddenly accelerate to dangerous
speeds.
\&.sp \[rs]n[PD]/2
\&.B2
.TE
+.KE
.
.
.LP
@@ -2680,14 +2680,12 @@ correspond to
.CW PS ,
and
.CW VS ,
-respectively.
-.
-The
+respectively;
.CW FPD ,
.CW FPS ,
and
.CW FVS
-registers are GNU extensions.
+are GNU extensions.
.
.
.KS
@@ -2986,17 +2984,15 @@ even-numbered pages.
.
.
.PP
-Another method is to call macros with arguments that set headers or
-footers for odd- or even-numbered pages;
-these variables produce four combinations,
-so four macros are available.
+Another method is to call macros that set headers or footers for odd- or
+even-numbered pages.
.
-Each takes a delimiter separating the left,
+Each such macro takes a delimited argument separating the left,
center,
and right header or footer texts from each other.
.
-You can replace the neutral apostrophes (\[aq]) with any character not
-appearing in the header or footer text.
+You can replace the neutral apostrophes (\[aq]) shown below with any
+character not appearing in the header or footer text.
.
These macros are Berkeley extensions.
.
@@ -3632,7 +3628,7 @@ is preferable.
AT&T
.I ms 's
.CW AU
-macro recognized arguments that were used with some cover sheet types;
+macro supported arguments used with some document types;
.I "groff ms"
does not.
.
@@ -3824,7 +3820,7 @@ Legacy features
.
.LP
.I "groff ms"
-retains support for some legacy features solely to support rendering of
+retains support for some legacy features solely to support formatting of
historical documents;
contemporary ones should not use them because they can render poorly.
.
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index f7ed1270..6513ccfe 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -606,6 +606,8 @@ and
footnotes.
.
.
+.br
+.ne 2v
.P
The
.B HY
@@ -645,16 +647,13 @@ Interpolate an em dash.
.TQ
.B \[rs]*[U]
Interpolate typographer's quotation marks where available,
-and neutral quotes otherwise.
+and neutral double quotes otherwise.
.
.B \[rs]*[Q]
is the left quote and
.B \[rs]*[U]
the right.
.
-(As a mnemonic,
-think of \[lq]quote\[rq] and \[lq]unquote\[rq].)
-.
.
.\" ====================================================================
.SS Paragraphs
@@ -1035,8 +1034,7 @@ but use the roman style
(upright text of normal weight)
instead of bold.
.
-Arguments are recognized only by
-.I groff ms.
+Argument recognition is a GNU extension.
.
.
.TP
@@ -1082,8 +1080,10 @@ reverse video is used instead.
If you want
.I text
to contain space,
-use horizontal motion escape sequences of appropriate width
+use unbreakable space or horizontal motion escape sequences
.RB ( \[rs]\[ti] ,
+.BI \[rs] space\c
+,
.BR \[rs]\[ha] ,
.BR \[rs]| ,
.BR \[rs]0 ,
@@ -1284,6 +1284,8 @@ and by adding a small amount of vertical space before
calling
.B .B2 .
.
.
+.br
+.ne 2v
.P
If you want a boxed keep to float,
you will need to enclose the
@@ -1620,14 +1622,12 @@ correspond to
.BR PS ,
and
.BR VS ,
-respectively.
-.
-The
+respectively;
.BR FPD ,
.BR FPS ,
and
.B FVS
-registers are GNU extensions.
+are GNU extensions.
.
.
.P
@@ -1776,17 +1776,15 @@ even-numbered pages.
.
.
.P
-Another method is to call macros with arguments that set headers or
-footers for odd- or even-numbered pages;
-these variables produce four combinations,
-so four macros are available.
+Another method is to call macros that set headers or footers for odd- or
+even-numbered pages.
.
-Each takes a delimiter separating the left,
+Each such macro takes a delimited argument separating the left,
center,
and right header or footer texts from each other.
.
-You can replace the neutral apostrophes (\[aq]) with any character not
-appearing in the header or footer text.
+You can replace the neutral apostrophes (\[aq]) shown below with any
+character not appearing in the header or footer text.
.
These macros are Berkeley extensions.
.
@@ -2428,7 +2426,7 @@ accessing an undefined register automatically defines it.
AT&T
.IR ms 's
.B AU
-macro recognized arguments that were used with some cover sheet types;
+macro supported arguments used with some document types;
.I groff ms
does not.
.
@@ -2586,7 +2584,7 @@ or lack a stable definition historically
.\" ====================================================================
.
.I "groff ms"
-retains support for some legacy features solely to support rendering of
+retains support for some legacy features solely to support formatting of
historical documents;
contemporary ones should not use them because they can render poorly.
.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 06/35: [ms]: Fix content and style nits in docs.,
G. Branden Robinson <=