[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 11/16: [ms]: Revise font styling and decoration docs.
From: |
G. Branden Robinson |
Subject: |
[groff] 11/16: [ms]: Revise font styling and decoration docs. |
Date: |
Thu, 9 Jun 2022 23:59:15 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 430c61e330d874fc673576c63e5095fb7a79dfd0
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jun 8 00:46:21 2022 -0500
[ms]: Revise font styling and decoration docs.
* Retitle (sub-)subsection from "Highlighting (in ms)" to "Typeface and
decoration".
* Recast introduction. Observe argument order weirdness in font style
macros (and, except in groff_ms(7), explain it).
* Tighten presentation.
* Add example (except in groff_ms(7)) of idiosyncratic argument
ordering, and an alternative method for achieving the same results.
---
doc/groff.texi | 149 +++++++++++++++++-------------
doc/ms.ms | 257 +++++++++++++++++++++++++++++++++-------------------
tmac/groff_ms.7.man | 183 ++++++++++++++++++++-----------------
3 files changed, 353 insertions(+), 236 deletions(-)
diff --git a/doc/groff.texi b/doc/groff.texi
index 20d83f3c..00632330 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -468,7 +468,7 @@ developing GNU and promoting software freedom.''
@title groff
@subtitle The GNU implementation of @code{troff}
@subtitle Edition 1.23.0
-@subtitle May 2022
+@subtitle June 2022
@author Trent@tie{}A.@: Fisher
@author Werner Lemberg
@author G.@tie{}Branden Robinson
@@ -3084,7 +3084,7 @@ The hyphenation mode (as used by the @code{hy} request)
is set from the
* Typographical symbols in ms::
* Paragraphs in ms::
* Headings in ms::
-* Highlighting in ms::
+* Typeface and decoration::
* Lists in ms::
* Indented regions in ms::
* ms keeps and displays::
@@ -3204,7 +3204,7 @@ software.
@c ---------------------------------------------------------------------
-@node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text
+@node Headings in ms, Typeface and decoration, Paragraphs in ms, ms Body Text
@subsubsection Headings
@cindex @file{ms} macros, headings
@@ -3349,86 +3349,111 @@ displays} and @ref{ms Insertions}.
@c ---------------------------------------------------------------------
-@node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text
-@subsubsection Highlighting
+@node Typeface and decoration, Lists in ms, Headings in ms, ms Body Text
+@subsubsection Typeface and decoration
@cindex @file{ms} macros, highlighting
-The @file{ms} macros provide a variety of methods to highlight or
-emphasize text.
-
-@Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
-Sets its first argument in @strong{bold type}. If you specify a second
-argument, @code{groff} @file{ms} prints it in the previous font after
-the bold text, with no intervening space (this allows you to set
-punctuation after the highlighted text without highlighting the
-punctuation). Similarly, it prints the third argument (if any) in the
-previous font @emph{before} the first argument. For example,
-
-@Example
-.B foo ) (
-@endExample
-
-prints @samp{(@strong{foo})}.
-
-If you give this macro no arguments, @code{groff} @file{ms} prints all
-text following in bold until the next highlighting, paragraphing, or
-heading macro.
+The @file{ms} macros provide a variety of ways to style text.
+Attend closely to the ordering of arguments labeled @var{pre} and
+@var{post}, which is not intuitive. Support for @var{pre}
+arguments is a GNU extension.@footnote{This idiosyncrasy arose through
+feature accretion; for example, the @code{B} macro in Version@tie{}6
+Unix @file{ms} (1975) accepted only one argument, the text to be set in
+boldface. By Version@tie{}7 (1979) it recognized a second argument; in
+1990, @code{groff} @file{ms} added a ``pre'' argument, placing it third
+to avoid breaking support for older documents.}
+
+@Defmac {B, [@Var{text} [@Var{post} [@Var{pre}]]], ms}
+Style @var{text} in @b{bold}, followed by @var{post} in the previous
+font style without intervening space, and preceded by @var{pre}
+similarly. Without arguments, @file{ms} styles subsequent text in bold
+until the next highlighting, paragraphing, or heading macro call.
@endDefmac
-@Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
-Sets its first argument in roman (or regular) type. It operates
-similarly to the @code{B}@tie{}macro otherwise.
+@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.
@endDefmac
-@Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
-Sets its first argument in @emph{italic type}. It operates similarly
-to the @code{B}@tie{}macro otherwise.
+@Defmac {I, [@Var{text} [@Var{post} [@Var{pre}]]], ms}
+As @code{B}, but use an @i{italic} or oblique style instead of bold.
@endDefmac
-@Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
-Sets its first argument in bold italic type. It operates similarly to
-the @code{B}@tie{}macro otherwise. This is a Tenth Edition Research
-Unix extension.
+@Defmac {BI, [@Var{text} [@Var{post} [@Var{pre}]]], ms}
+As @code{B}, but use a bold italic or bold oblique style instead of
+upright bold. This is a Tenth Edition Research Unix extension.
+@c possibly 9th, but definitely not Berkeley
@endDefmac
-@Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
-Sets its first argument in a @code{constant-width} (monospaced)
-roman typeface. It operates similarly to the @code{B}@tie{}macro
-otherwise. This is a Tenth Edition Research Unix extension.
+@Defmac {CW, [@Var{text} [@Var{post} [@Var{pre}]]], ms}
+As @code{B}, but use a @t{constant-width} (monospaced) roman typeface
+instead of bold. This is a Tenth Edition Research Unix extension.
@c possibly 9th, but definitely not Berkeley
@endDefmac
-@Defmac {BX, [@Var{txt}], ms}
-Typeset @var{txt} and draw a box around it. On terminal devices,
-reverse video is used instead. If you want the argument to contain
-space, use non-breaking space escape sequences of appropriate width
-(@code{\~}, @code{\^}, @code{\|}, @code{\0}) or @code{\h}.
+@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}).
@endDefmac
-@Defmac {UL, [@Var{txt} [@Var{post}]], ms}
-Typeset @var{txt} with an underline. If you specify @var{post},
-@file{ms} sets it after the underlined text, with no intervening space.
+@Defmac {UL, [@Var{text} [@Var{post}]], ms}
+Typeset @var{text} with an underline. Set @var{post}, if present, after
+@var{text} with no intervening space.
@endDefmac
@Defmac {LG, , ms}
-Set all subsequent text in larger type (two points larger than the
+Set subsequent text in larger type (two points larger than the
current size) until the next font size, highlighting, paragraphing, or
-heading macro. You can specify this macro multiple times to enlarge the
-type size as needed.
+heading macro call. You can specify this macro multiple times to
+enlarge the type size as needed.
@endDefmac
@Defmac {SM, , ms}
-Set all subsequent text in smaller type (two points smaller than the
-current size) until the next type size, highlighting, paragraphing, or
-heading macro. You can specify this macro multiple times to reduce the
+Set subsequent text in smaller type (two points smaller than the current
+size) until the next type size, highlighting, paragraphing, or heading
+macro call. You can specify this macro multiple times to reduce the
type size as needed.
@endDefmac
@Defmac {NL, , ms}
-Set all text following at the normal type size (that is, the value of
-the @code{PS} register).
+Set subsequent text at the normal type size (the amount in the @code{PS}
+register).
@endDefmac
+@var{pre} and @var{post} arguments are typically used to simplify the
+attachment of punctuation to styled words. When @var{pre} is used,
+a hyphenation control escape sequence @code{\%} that would ordinarily
+start @var{text} must start @var{pre} instead to have the desired
+effect.
+
+@CartoucheExample
+The course's students found one C language keyword
+.CW static ) \%(
+most troublesome.
+@endCartoucheExample
+
+The foregoing example produces output as follows.
+
+@CartoucheExample
+@r{The course's students found one C language keyword (@t{static}) most
+troublesome.}
+@endCartoucheExample
+
+You might prefer to use the output line continuation escape sequence
+@code{\c} to achieve the same result (@pxref{Line Continuation}). It is
+also portable to older @file{ms} implementations.
+
+@CartoucheExample
+The course's students found one C language keyword
+(\c
+.CW \%static\c
+.R
+) most troublesome.
+@endCartoucheExample
+
@code{groff} @file{ms} also offers strings to begin and end super- and
subscripting. These are GNU extensions.
@@ -3453,7 +3478,7 @@ syntactical elements of @file{ms} and @code{groff}.
@c ---------------------------------------------------------------------
-@node Lists in ms, Indented regions in ms, Highlighting in ms, ms Body Text
+@node Lists in ms, Indented regions in ms, Typeface and decoration, ms Body
Text
@subsubsection Lists
@cindex @file{ms} macros, lists
@@ -3701,12 +3726,12 @@ 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{Highlighting in ms}. 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}.
+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}.
@c Wrap example at 56 columns.
@CartoucheExample
diff --git a/doc/ms.ms b/doc/ms.ms
index 1f1c94e6..fe90d40c 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 March 2022
-.EH '%''March 2022'
+.ND June 2022
+.EH '%''June 2022'
.EF ''''
.OH 'Using \f[I]groff\f[] with the \f[I]ms\f[] macros''%'
.OF ''''
@@ -1290,16 +1290,42 @@ grouping.
.br
.ne (\n[.p]u / 2u)
.NH 2
-Highlighting
+Typeface and decoration
.XS
- Highlighting
+ Typeface and decoration
.XE
.
.
.LP
The
.I ms
-macros provide a variety of methods to highlight or emphasize text.
+macros provide a variety of ways to style text.
+.
+Attend closely to the ordering of arguments labeled
+.I pre
+and
+.I post,
+which is not intuitive.
+.
+Support for
+.I pre
+arguments is a GNU extension.\**
+.FS
+This idiosyncrasy arose through feature accretion;
+for example,
+the
+.CW B
+macro in Version\~6 Unix
+.I ms
+(1975) accepted only one argument,
+the text to be set in boldface.
+.
+By Version\~7 (1979) it recognized a second argument;
+in 1990,
+.I "groff ms"
+added a \*[Q]pre\*[U] argument,
+placing it third to avoid breaking support for older documents.
+.FE
.
.
.TS H
@@ -1309,92 +1335,70 @@ lf(CR) lx.
Macro Description
_
.TH
-\&.B [txt [post [pre]]] T{
-Sets its first argument in
-.B "bold type" .
-.
-If you specify a second argument,
-.I groff
-prints it in the previous font after the bold text,
-with no intervening space
-(this allows you to set punctuation after the highlighted text without
-highlighting the punctuation).
-.
-Similarly,
-it prints the third argument
-(if any)
-in the previous font
-.B before
-the first argument.
-.
-For example,
-.
-.
-.sp \n[PD]u
-.ti +3n
-\&.B foo ) (
-.
-.
-.sp \n[PD]u
-prints
-.B foo ). (
-.
-.
-.sp \n[PD]u
-If you give this macro no arguments,
-.I groff
-prints all text following in bold until the next highlighting,
+\&.B \f[R][\f[I]text\f[] [\f[I]post\f[] [\f[I]pre\f[]]]] T{
+Style
+.I text
+in
+.B bold ,
+followed by
+.I post
+in the previous font style without intervening space,
+and preceded by
+.I pre
+similarly.
+.
+Without arguments,
+.I ms
+styles subsequent text in bold
+until the next highlighting,
paragraphing,
-or heading macro.
+or heading macro call.
T}
_
-\&.R [txt [post [pre]]] T{
-Sets its first argument in roman
-(or regular)
-type.
+\&.R \f[R][\f[I]text\f[] [\f[I]post\f[] [\f[I]pre\f[]]]] T{
+As
+.CW .B ,
+but use the roman style
+(upright text of normal weight)
+instead of bold.
.
-It operates similarly to the
-.CW .B
-macro otherwise.
+Arguments are recognized only by
+.I "groff ms."
T}
_
-\&.I [txt [post [pre]]] T{
-Sets its first argument in
-.I "italic type" .
-.
-It operates similarly to the
-.CW .B
-macro otherwise.
+\&.I \f[R][\f[I]text\f[] [\f[I]post\f[] [\f[I]pre\f[]]]] T{
+As
+.CW .B ,
+but use an
+.I italic
+or oblique style instead of bold.
T}
_
-\&.BI [txt [post [pre]]] T{
-Sets its first argument in
-.BI "bold italic type" .
-.
-It operates similarly to the
-.CW .B
-macro otherwise.
+\&.BI \f[R][\f[I]text\f[] [\f[I]post\f[] [\f[I]pre\f[]]]] T{
+As
+.CW .B ,
+but use a
+.BI "bold italic"
+or bold oblique style instead of upright bold.
.
This is a Tenth Edition Research Unix extension.
.\" possibly 9th, but definitely not Berkeley
T}
_
-\&.CW [txt [post [pre]]] T{
-Sets its first argument in a
+\&.CW \f[R][\f[I]text\f[] [\f[I]post\f[] [\f[I]pre\f[]]]] T{
+As
+.CW .B ,
+but use a
.CW constant-width
-(monospaced) roman typeface.
-.
-It operates similarly to the
-.CW .B
-macro otherwise.
+(monospaced) roman typeface instead of bold.
.
This is a Tenth Edition Research Unix extension.
.\" possibly 9th, but definitely not Berkeley
T}
_
-\&.BX [txt] T{
+\&.BX \f[R][\f[I]text\f[]] T{
Typeset
-.I txt
+.I text
and draw a
.BX box
around it.
@@ -1403,31 +1407,34 @@ On terminal devices,
reverse video is used instead
(see the implementation note below).
.
-If you want the argument to contain space,
-use non-breaking space escape sequences of appropriate width
+If you want
+.I text
+to contain space,
+use horizontal motion escape sequences of appropriate width
.CW \[rs]\[ti] , (
.CW \[rs]\[ha] ,
.CW \[rs]| ,
-.CW \[rs]0 ),
+.CW \[rs]0 ,
or
-.CW \[rs]h .
+.CW \[rs]h ).
T}
_
-\&.UL [txt [post]] T{
+\&.UL \f[R][\f[I]text\f[] [\f[I]post\f[]]] T{
Typeset
-.I txt
+.I text
with an
.UL underline .
.
-If you specify
-.I post ,
-.I ms
-sets it after the underlined text,
+Set
+.I post,
+if present,
+after
+.I text
with no intervening space.
T}
_
\&.LG T{
-Set all subsequent text in
+Set subsequent text in
.LG
larger type
.NL
@@ -1436,7 +1443,7 @@ until
the next font size,
highlighting,
paragraphing,
-or heading macro.
+or heading macro call.
.
You can
.LG
@@ -1448,7 +1455,7 @@ to enlarge the type size as needed.
T}
_
\&.SM T{
-Set all subsequent text in
+Set subsequent text in
.SM
smaller type
.NL
@@ -1457,7 +1464,7 @@ until
the next type size,
highlighting,
paragraphing,
-or heading macro.
+or heading macro call.
.
You can
.SM
@@ -1469,13 +1476,81 @@ to reduce the type size as needed.
T}
_
\&.NL T{
-Set all subsequent text at the normal type size
-(that is,
-the value of the
-.CW PS
-register).
+Set subsequent text at the normal type size
+.CW \[rs]n[PS] ). (
+T}
+.TE
+.
+.
+.PP
+.I pre
+and
+.I post
+arguments
+are typically used to simplify the attachment of punctuation to styled
+words.
+When
+.I pre
+is used,
+a hyphenation control escape sequence
+.CW \[rs]%
+that would ordinarily start
+.I text
+must start
+.I pre
+instead to have the desired effect.
+.
+.TS
+box center;
+Cb Cb
+Lf(CR) L.
+Input Result
+T{
+The course\[aq]s students found one C language keyword
+.br
+\&.CW static ) \[rs]%(
+.br
+most troublesome.
+T} T{
+The course's students found one C language keyword
+.CW static ) \%(
+most troublesome.
+T}
+.TE
+.
+.KS
+You might prefer to use the output line continuation escape sequence
+.CW \[rs]c
+to achieve the same result.
+.
+It is also portable to older
+.I ms
+implementations.
+.
+.TS
+box center;
+Cb Cb
+Lf(CR) L.
+Input Result
+T{
+The course\[aq]s students found one C language keyword
+.br
+(\[rs]c
+.br
+\&.CW \[rs]%static\[rs]c
+.br
+\&.R
+.br
+) most troublesome.
+T} T{
+The course's students found one C language keyword
+(\c
+.CW \%static\c
+.R
+) most troublesome.
T}
.TE
+.KE
.
.
.PP
@@ -1949,7 +2024,7 @@ Box macros cause breaks;
if you need to box a word or phrase within a line,
see the
.CW BX
-macro in section \[lq]Highlighting\[rq] above.
+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.
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index c39c3b7d..613bdc50 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1004,153 +1004,170 @@ grouping.
.
.
.\" ====================================================================
-.SS Highlighting
+.SS "Typeface and decoration"
.\" ====================================================================
.
+.
+.P
The
.I ms
-macros provide a variety of methods to highlight
-or emphasize text:
+macros provide a variety of ways to style text.
.
-.TP
-.B .B\c
-.RI " [" txt " [" post " [" pre ]]]
-Sets its first argument in
-.BR "bold type" .
+Attend closely to the ordering of arguments labeled
+.I pre
+and
+.I post,
+which is not intuitive.
+.
+Support for
+.I pre
+arguments is a GNU extension.
.
-If you specify a second argument,
-.I groff
-prints it in the previous font after
-the bold text, with no intervening space
-(this allows you to set punctuation after
-the highlighted text without highlighting
-the punctuation).
-.
-Similarly, it prints the third argument (if any)
-in the previous font
-.B before
-the first argument.
-.
-If you give this macro no arguments,
-.I groff
-prints all text following in bold until
-the next highlighting, paragraphing, or heading macro.
.
.TP
-.B .R\c
-.RI " [" txt " [" post " [" pre ]]]
-Sets its first argument in
-roman
-(or regular)
-type.
+.BR .B \~[\c
+.IR text \~[ post \~[ pre ]]]
+Style
+.I text
+in bold,
+followed by
+.I post
+in the previous font style without intervening space,
+and preceded by
+.I pre
+similarly.
+.
+Without arguments,
+.I ms
+styles subsequent text in bold
+until the next highlighting,
+paragraphing,
+or heading macro call.
.
-It operates similarly to the
-.B B
-macro otherwise.
.
.TP
-.B .I\c
-.RI " [" txt " [" post " [" pre ]]]
-Sets its first argument in
-.IR "italic type" .
-It operates similarly to the
-.B B
-macro otherwise.
+.BR .R \~[\c
+.IR text \~[ post \~[ pre ]]]
+As
+.BR .B ,
+but use the roman style
+(upright text of normal weight)
+instead of bold.
+.
+Arguments are recognized only by
+.I groff ms.
.
.
.TP
-.B .BI\c
-.RI " [" txt " [" post " [" pre ]]]
-Sets its first argument in bold italic type.
+.BR .I \~[\c
+.IR text \~[ post \~[ pre ]]]
+As
+.BR .B ,
+but use an italic or oblique style instead of bold.
+.
.
-It operates similarly to the
-.B B
-macro otherwise.
+.TP
+.BR .BI \~[\c
+.IR text \~[ post \~[ pre ]]]
+As
+.BR .B ,
+but use a bold italic or bold oblique style instead of upright bold.
.
This is a Tenth Edition Research Unix extension.
.\" possibly 9th, but definitely not Berkeley
.
.
.TP
-.B .CW\c
-.RI " [" txt " [" post " [" pre ]]]
-Sets its first argument in a \[lq]constant-width\[rq] (monospaced) roman
-typeface.
-.
-It operates similarly to the
-.B B
-macro otherwise.
+.BR .CW \~[\c
+.IR text \~[ post \~[ pre ]]]
+As
+.BR .B ,
+but use a constant-width (monospaced) roman typeface instead of bold.
.
This is a Tenth Edition Research Unix extension.
.\" possibly 9th, but definitely not Berkeley
.
.
.TP
-.B .BX\c
-.RI " [" txt ]
+.BR .BX \~[\c
+.IR text ]
Typeset
-.I txt
+.I text
and draw a box around it.
.
On terminal devices,
reverse video is used instead.
.
-If you want the argument to contain space,
-use non-breaking space escape sequences of appropriate width
+If you want
+.I text
+to contain space,
+use horizontal motion escape sequences of appropriate width
.RB ( \[rs]\[ti] ,
.BR \[rs]\[ha] ,
.BR \[rs]| ,
-.BR \[rs]0 ),
+.BR \[rs]0 ,
or
-.BR \[rs]h .
+.BR \[rs]h ).
.
.
.TP
-.B .UL\c
-.RI " [" txt " [" post ]]
+.BR .UL \~[\c
+.IR text \~[ post ]]
Typeset
-.I txt
+.I text
with an underline.
.
-If you specify
-.IR post ,
-.I ms
-sets it after the underlined text,
+Set
+.I post,
+if present,
+after
+.I text
with no intervening space.
.
.
.TP
.B .LG
-Set all subsequent text in larger type
-(2\~points larger than the current size) until
-the next font size,
+Set subsequent text in larger type
+(2\~points larger than the current size)
+until the next font size,
highlighting,
paragraphing,
-or heading macro.
+or heading macro call.
.
You can specify this macro multiple times to enlarge the type size as
needed.
.
+.
.TP
.B .SM
-Set all subsequent text in
-smaller type
-(2\~points smaller than the current size) until
-the next type size,
+Set subsequent text in smaller type
+(2\~points smaller than the current size)
+until the next type size,
highlighting,
paragraphing,
-or heading macro.
+or heading macro call.
.
You can specify this macro multiple times to reduce the type size as
needed.
.
+.
.TP
.B .NL
-Set all subsequent text at the normal type size
-(that is,
-the value of the
-.B PS
-register).
+Set subsequent text at the normal type size
+.RB ( \[rs]n[PS] ).
+.
+.
+.P
+When
+.I pre
+is used,
+a hyphenation control escape sequence
+.B \[rs]%
+that would ordinarily start
+.I text
+must start
+.I pre
+instead.
.
.
.P
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 11/16: [ms]: Revise font styling and decoration docs.,
G. Branden Robinson <=