[groff] 11/16: [ms]: Revise font styling and decoration docs.

[G. Branden Robinson]

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