From: Michael Witten <mfwitten@gmail.com>
Date: Sat, 30 Jun 2018 03:15:52 -0000
Subject: [PATCH] groff.texi, groff(7), groff_char(7): Overhaul underlining

* Make the terminology a bit more consistent and precise; for
  example, "underlining" is used instead of "an underline".

* Explain why it matters in which order 2 characters participate in
  overstriking.

* Provide superior example macros for performing underlining via
  overstriking.

* Document "\_", "\[ul]", "\[ru]", and "\[br]" more completely.

* Note what happens when one "ul" request is made while another
  "ul" request is still in effect.

* In the course of these edits:

  . Use the "nop" request to clarify the "box" macro example.
  . Re-write "zero width space" as "zero-width space".
  . Replace a couple uses of "See @ref" with "@xref".
  . Generally improve the surrounding prose.
  . Improve surrounding index terms.
---
 doc/groff.texi       | 225 +++++++++++++++++++++++++++++++------------
 man/groff.7.man      | 193 +++++++++++++++++++++++++++++--------
 man/groff_char.7.man |   2 +-
 3 files changed, 316 insertions(+), 104 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index f7de6362..f34725b0 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -3566,9 +3566,14 @@ string that contains spaces, use a digit-width space (@code{\0}).
 @endDefmac
 
 @Defmac {UL, [@Var{txt} [@Var{post}]], ms}
-Prints its first argument with an underline.  If you specify a second
+Prints its first argument with underlining.  If you specify a second
 argument, @code{groff} prints it in the previous font after the
 underlined text, with no intervening space.
+
+This macro depends on the output device being able to process motion and
+drawing commands at a resolution that is too high for a TTY; @pxref{Line
+Control}, for an example of how to draw underlining if the output device
+supports overstriking.
 @endDefmac
 
 @Defmac {LG, , ms}
@@ -5595,12 +5600,12 @@ assigning an empty macro to it.
 
 @xref{Blank Line Traps}.
 
-@cindex zero width space character (@code{\&})
-@cindex character, zero width space (@code{\&})
-@cindex space character, zero width (@code{\&})
+@cindex zero-width space character (@code{\&})
+@cindex character, zero-width space (@code{\&})
+@cindex space character, zero-width (@code{\&})
 @cindex @code{\&}, escaping control characters
 To begin a line with a control character without it being interpreted,
-precede it with @code{\&}.  This represents a zero width space, which
+precede it with @code{\&}.  This represents a zero-width space, which
 means it does not affect the output.
 
 In most cases the period is used as a control character.  Several
@@ -6726,7 +6731,7 @@ filled.  The read-only number register @code{.u} is set to@tie{}1.
 The fill mode status is associated with the current environment
 (@pxref{Environments}).
 
-See @ref{Line Control}, for interaction with the @code{\c} escape.
+@xref{Line Control}, for interaction with the @code{\c} escape.
 @endDefreq
 
 @Defreq {nf, }
@@ -6740,7 +6745,7 @@ disables adjusting; it also causes a break.  The number register
 The fill mode status is associated with the current environment
 (@pxref{Environments}).
 
-See @ref{Line Control}, for interaction with the @code{\c} escape.
+@xref{Line Control}, for interaction with the @code{\c} escape.
 @endDefreq
 
 @DefreqList {ad, [@Var{mode}]}
@@ -8169,7 +8174,7 @@ set with the @code{shc} request.
 @item
 @cindex @code{\&}, and translations
 The pair @samp{@var{c}\&} (this is an arbitrary character@tie{}@var{c}
-followed by the zero width space character) maps this character to
+followed by the zero-width space character) maps this character to
 nothing.
 
 @Example
@@ -8544,13 +8549,15 @@ This is a   test.
 This is a             test.
 @endExample
 
+@cindex underlining, by drawing a line second
 The main usage of this feature is to define macros that act exactly at
 the place where called.
 
 @Example
-.\" A simple macro to underline a word
+.\" A simple macro to underline a word.
+.\" Usage: .underline <word>
 .de underline
-.  nop \\$1\l'|0\[ul]'
+.  nop \\$1\l'|0\_'
 ..
 @endExample
 
@@ -8558,7 +8565,48 @@ the place where called.
 In the above example, @samp{|0} specifies a negative distance from the
 current position (at the end of the just emitted argument @code{\$1})
 back to the beginning of the input line.  Thus, the @samp{\l} escape
-draws a line from right to left.
+draws a line from right to left (@pxref{Drawing Requests}).
+
+@cindex underlining, by drawing a line first
+@cindex overstriking, order matters for a TTY
+@cindex TTY, overstriking order matters
+However, while the previous example produces a result that is visually
+correct, the resulting output may obscure the textual characters, because
+the line is drawn after the textual characters have been processed; on a
+TTY output device (such as that driven by @code{grotty}), the textual
+characters may be rendered properly, but nevertheless interpreted as
+having been replaced with underscore characters, such that an attempt
+to search the output for the underlined word will fail. To avoid this
+unfortunate outcome, it is necessary to reverse the steps: Draw the
+underlining first, and then overstrike (that@tie{}is, overwrite) those
+underscore characters with the textual characters:
+
+@Example
+.\" A simple macro to underline text.
+.\" Usage: .underline <prefix> <text> [suffix]
+.de underline3
+. nop \\$1\Z`\l"\w'\\$2'u\_"`\\$2\\$3
+..
+.
+.\" A better macro to underline a word.
+.\" Usage: .underline <word> [suffix]
+.de underline
+.  underline3 "" \\$@
+..
+@endExample
+
+@noindent
+For example:
+
+@Example
+When you
+.underline3 s tar t
+using these macros, your fellow Groffers
+will
+.underline stop
+wanting to tar and feather
+.underline you !
+@endExample
 
 @cindex input line continuation (@code{\})
 @cindex line, input, continuation (@code{\})
@@ -9509,13 +9557,20 @@ example, @code{^E_u0301} is invalid.
 Insert a symbol @var{name} (two-character name @var{nm}) or a composite
 glyph with component glyphs @var{component1}, @var{component2},
 @enddots{} There is no special syntax for one-character names -- the
-natural form @samp{\@var{n}} would collide with escapes.@footnote{Note
+natural form @samp{\@var{n}} would collide with escapes.
+@footnote{
+@cindex character, from code point (@code{\[charXXX]})
+@cindex code point, specifying explicitly (@code{\[charXXX]})
+Note
 that a one-character symbol is not the same as an input character, i.e.,
 the character @code{a} is not the same as @code{\[a]}.  By default,
 @code{groff} defines only a single one-character symbol, @code{\[-]}; it
-is usually accessed as @code{\-}.  On the other hand, @code{gtroff} has
-the special feature that @code{\[char@var{XXX}]} is the same as the
-input character with character code @var{XXX}.  For example,
+is usually accessed as @code{\-}.  In contrast, though @code{\_} is
+functionally a single-character symbol, it is technically an escape
+sequence that maps to the two-character symbol @code{\[ul]}.
+On a related note, @code{gtroff} has a special feature for specifying a
+symbol by its code point: @code{\[char@var{XXX}]} is equivalent to
+the character that has code point @var{XXX}.  For example,
 @code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII}
 encoding is active.}
 
@@ -9616,7 +9671,7 @@ the @code{char} request:
 @cindex glyphs, unnamed
 The code of each glyph is given in the fourth column in the font
 description file after the @code{charset} command.  It is possible to
-include unnamed glyphs in the font description file by using a name of
+include an unnamed glyph in the font description file by using the name
 @samp{---}; the @code{\N} escape sequence is the only way to use these.
 
 No kerning is applied to glyphs accessed with @code{\N}.
@@ -9641,7 +9696,11 @@ This is the same as @code{\[-]}, the minus sign in the current font.
 @endDefesc
 
 @Defesc {\\_, , , }
-This is the same as @code{\[ul]}, the underline character.
+@cindex underlining, underscore glyph (@code{\\_ or \\[ul]})
+@cindex glyph, underscore (@code{\[ul]}, @code{\_})
+This is the same as @code{\[ul]}, the underscore glyph. It is often
+used to draw underlining; @pxref{Line Control}, for an example of such
+usage.
 @endDefesc
 
 @Defreq {cflags, n c1 c2 @dots{}}
@@ -9689,8 +9748,11 @@ value@tie{}64 to override this behaviour.
 @cindex overlapping characters
 @cindex characters, overlapping
 @cindex @code{ul} glyph, and @code{cflags}
+@cindex underscore glyph (@code{\[ul]}), and @code{cflags}
 @cindex @code{rn} glyph, and @code{cflags}
+@cindex overline glyph (@code{\[rn]}), and @code{cflags}
 @cindex @code{ru} glyph, and @code{cflags}
+@cindex baseline rule glyph (@code{\[ru]}), and @code{cflags}
 @cindex @code{radicalex} glyph, and @code{cflags}
 @cindex @code{sqrtex} glyph, and @code{cflags}
 The character overlaps horizontally if used as a horizontal line
@@ -10057,20 +10119,31 @@ troff manual; the slant is always set to an absolute value.
 @cindex underlining (@code{ul})
 The @code{ul} request normally underlines subsequent lines if a TTY
 output device is used.  Otherwise, the lines are printed in italics
-(only the term `underlined' is used in the following).  The single
-argument is the number of input lines to be underlined; with no
-argument, the next line is underlined.  If @var{lines} is zero or
-negative, stop the effects of @code{ul} (if it was active).  Requests
-and empty lines do not count for computing the number of underlined
-input lines, even if they produce some output like @code{tl}.  Lines
-inserted by macros (e.g.@: invoked by a trap) do count.
-
-At the beginning of @code{ul}, the current font is stored and the
-underline font is activated.  Within the span of a @code{ul} request, it
-is possible to change fonts, but after the last line affected by
-@code{ul} the saved font is restored.
-
-This number of lines still to be underlined is associated with the
+(only the term `underlined' is used in the following);
+@pxref{Line Control}, for an example of underlining even when the
+output device is not a TTY.
+
+The single argument is the number of non-empty text lines to be
+underlined; with no argument, only the next non-empty text line is
+underlined. Neither a request nor an empty line counts when computing
+the number of underlined input lines, even if that input line produces
+output (as happens with the @code{tl} request); however, a text line
+that is inserted by a macro (e.g.@: when the macro is invoked by a
+trap) does count. If @var{lines} is zero or negative, then any previous
+underlining is stopped as though it finished counting non-empty text
+lines (and no new underlining is begun); if a @code{ul} request is made
+while another @code{ul} request is in effect, then the new request
+overrides the old request (there's actually only ever one @code{ul}
+request in effect at a time; the state is shared across requests).
+
+When a @code{ul} request is made, the current font is stored and the
+underline font is activated; if one @code{ul} request is in effect when
+another @code{ul} request is made, then the saved font is necessarily
+the underline font itself. Within the span of a @code{ul} request, it
+is possible to change the font, but after the last line affected by
+@code{ul}, the saved font is restored.
+
+The number of text lines still to be underlined is associated with the
 current environment (@pxref{Environments}).  The underline font can be
 changed with the @code{uf} request.
 
@@ -10086,7 +10159,8 @@ The @code{ul} request does not underline spaces.
 @cindex continuous underlining (@code{cu})
 @cindex underlining, continuous (@code{cu})
 The @code{cu} request is similar to @code{ul} but underlines spaces as
-well (if a TTY output device is used).
+well (if a TTY output device is used).  @xref{Line Control}, for an
+example of underlining even when the output device is not a TTY.
 @endDefreq
 
 @Defreq {uf, font}
@@ -10212,9 +10286,9 @@ enable pairwise kerning, otherwise disable it.  The read-only number
 register @code{.kern} is set to@tie{}1 if pairwise kerning is enabled,
 0@tie{}otherwise.
 
-@cindex zero width space character (@code{\&})
-@cindex character, zero width space (@code{\&})
-@cindex space character, zero width (@code{\&})
+@cindex zero-width space character (@code{\&})
+@cindex character, zero-width space (@code{\&})
+@cindex space character, zero-width (@code{\&})
 If the font description file contains pairwise kerning information,
 glyphs from that font are kerned.  Kerning between two glyphs can be
 inhibited by placing @code{\&} between them: @samp{V\&A}.
@@ -12089,7 +12163,7 @@ glyphs.
 @Defesc {\\z, , g, }
 @cindex zero-width printing (@code{\z}, @code{\Z})
 @cindex printing, zero-width (@code{\z}, @code{\Z})
-Print glyph @var{g} with zero width, i.e., without spacing.  Use this to
+Print glyph @var{g} with zero-width, i.e., without spacing.  Use this to
 overstrike glyphs left-aligned.
 @endDefesc
 
@@ -12134,8 +12208,9 @@ All drawing is done via escapes.
 @DefescList {\\l, ', l, '}
 @DefescListEnd {\\l, ', lg, '}
 @cindex drawing horizontal lines (@code{\l})
-@cindex horizontal line, drawing (@code{\l})
-@cindex line, horizontal, drawing (@code{\l})
+@cindex horizontal line drawing (@code{\l})
+@cindex line, horizontal drawing (@code{\l})
+@cindex rule, horizontal drawing (@code{\l})
 Draw a line horizontally.  @var{l} is the length of the line to be
 drawn.  If it is positive, start the line at the current location and
 draw to the right; its end point is the new current location.  Negative
@@ -12146,46 +12221,72 @@ and draws to the left, but the current location doesn't move.
 @samp{|}), which draws back to the beginning of the input line.  Default
 scaling indicator is @samp{m}.
 
-@cindex underscore glyph (@code{\[ru]})
-@cindex glyph, underscore (@code{\[ru]})
-@cindex line drawing glyph
-@cindex glyph, for line drawing
-The optional second parameter@tie{}@var{g} is a glyph to draw the line
-with.  If this second argument is not specified, @code{gtroff} uses the
-underscore glyph, @code{\[ru]}.
-
-@cindex zero width space character (@code{\&})
-@cindex character, zero width space (@code{\&})
-@cindex space character, zero width (@code{\&})
-To separate the two arguments (to prevent @code{gtroff} from
-interpreting a drawing glyph as a scaling indicator if the glyph is
-represented by a single character) use @code{\&}.
+@cindex baseline rule glyph (@code{\[ru]})
+@cindex glyph, baseline rule (@code{\[ru]})
+@cindex rule, baseline rule glyph (@code{\[ru]})
+@cindex underlining, line drawing (@code{\l})
+@cindex underlining, glyphs
+@cindex underscore glyph (@code{\[ul]}, @code{\_})
+@cindex glyph, underscore (@code{\[ul]}, @code{\_})
+@cindex glyph, for underlining
+@cindex glyph, for line drawing (horizontal)
+The optional second parameter@tie{}@var{g} is a glyph with which to
+draw the line. If this second argument is not specified, @code{gtroff}
+uses the baseline rule glyph, @code{\[ru]}, which is a font-invariant
+horizontal rule of length 0.5@dmn{em}. In many instances, it may prove
+better to use instead the underscore glyph, @code{\[ul]}, which may also
+be specified with the dedicated escape sequence, @code{\_}. @xref{Line
+Control}, for an example of using @code{\l} to produce underlining, and
+for a discussion of handling overstriking properly.
+
+@cindex zero-width space character (@code{\&})
+@cindex character, zero-width space (@code{\&})
+@cindex space character, zero-width (@code{\&})
+If the drawing glyph, meant to be provided in parameter @var{g}, could
+be interpreted as a scaling indicator for the argument passed through
+parameter @var{l}, then @code{gtroff} interprets it as a scaling
+indicator, and therefore assumes no argument is being passed through
+@var{g}. To avoid this interpretation, use a zero-width space character
+(@code{\&}) to separate the two arguments. Compare these usages:
+
+@Example
+After consuming its input, Groff sat back
+and let loose a groan of pleasure:
+\l'20\&m'
+\l'20m'
+@endExample
 
-Here a small useful example:
+@cindex box rule glyph (@code{\[br]})
+@cindex glyph, box rule (@code{\[br]})
+@cindex rule, box rule glyph (@code{\[br]})
+Here's another small example, which draws a crude box around the
+provided input:
 
 @Example
 .de box
-\[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
+.  nop \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
 ..
 @endExample
 
 @noindent
-Note that this works by outputting a box rule (a vertical line), then
-the text given as an argument and then another box rule.  Finally, the
-line drawing escapes both draw from the current location to the
-beginning of the @emph{input} line -- this works because the line length
-is negative, not moving the current point.
+This macro outputs a box rule (a vertical line), then processes the
+input that is given as arguments, and then outputs another box rule.
+Finally, both line-drawing escapes draw from the current output location
+to the place that corresponds to the beginning of the @emph{input} line;
+the last horizontal-line drawing escape works because the line length
+given to each escape is negative, and therefore the current output
+location isn't moved by them.
 @endDefesc
 
 @DefescList {\\L, ', l, '}
 @DefescListEnd {\\L, ', lg, '}
 @cindex drawing vertical lines (@code{\L})
 @cindex vertical line drawing (@code{\L})
-@cindex line, vertical, drawing (@code{\L})
-@cindex line drawing glyph
-@cindex glyph for line drawing
+@cindex line, vertical drawing (@code{\L})
 @cindex box rule glyph (@code{\[br]})
+@cindex rule, box rule glyph (@code{\[br]})
 @cindex glyph, box rule (@code{\[br]})
+@cindex glyph, for line drawing (vertical)
 Draw vertical lines.  Its parameters are similar to the @code{\l}
 escape, except that the default scaling indicator is @samp{v}.  The
 movement is downwards for positive values, and upwards for negative
diff --git a/man/groff.7.man b/man/groff.7.man
index facc1705..e1162445 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -129,7 +129,7 @@ groff \- a short reference for the GNU roff language
 .  Text "\f[CB]\e\\$1\[lB]\f[]\,\f[I]\\$2\/\f[]\f[CB]\[rB]\f[]"
 ..
 .\" ====================================================================
-.\" .ESCq name arg
+.\" .ESCq name arg [suffix]
 .\"
 .\" Synopsis for escape sequence with a bracketed long argument
 .\" Args   : 2 obligatory
@@ -138,7 +138,7 @@ groff \- a short reference for the GNU roff language
 .\" Result : prints \name'arg', where 'name' is in CB, 'arg' in I
 .\"
 .de ESCq
-.  Text "\f[CB]\e\\$1\[cq]\f[]\,\f[I]\\$2\/\f[]\f[CB]\[cq]\f[]"
+.  Text "\f[CB]\e\\$1\[cq]\f[]\,\f[I]\\$2\/\f[]\f[CB]\[cq]\f[]\\$3"
 ..
 .\" ====================================================================
 .\" .ESC? arg
@@ -2845,7 +2845,7 @@ The \- (minus) sign in the current font.
 .ESC _
 The same as
 .esc (ul ,
-the underline character.
+the underscore character.
 .
 .TP
 .ESC .
@@ -4378,9 +4378,12 @@ there is the macro
 .BR .UL .
 .
 But this works only in
-.BR troff ,
-not in
-.BR nroff .
+.B troff
+(for a graphical output),
+and never in
+.BR nroff ;
+more precisely, it depends on a line-drawing operation whose resolution
+is too high for a TTY.
 .
 .
 .\" ====================================================================
@@ -4399,6 +4402,8 @@ in
 .I ms
 for writing a useful new macro, something like
 .
+.
+.P
 .RS
 .EX
 \&.de UNDERLINE
@@ -4410,6 +4415,8 @@ for writing a useful new macro, something like
 .EE
 .RE
 .
+.
+.P
 If
 .BR doclifter (1)
 makes trouble, change the macro name
@@ -4431,6 +4438,8 @@ If one does not want to use macro definitions, e.g., when
 .B doclifter
 gets lost, use the following:
 .
+.
+.P
 .RS
 .EX
 \&.ds u1 before
@@ -4443,6 +4452,8 @@ gets lost, use the following:
 .EE
 .RE
 .
+.
+.P
 Due to
 .BR doclifter ,
 it might be necessary to change the variable writing
@@ -4457,7 +4468,10 @@ and so on.
 .
 .
 .P
-Then these lines could look like
+Then these lines could look like the following:
+.
+.
+.P
 .RS
 .EX
 \&.ds u1 before
@@ -4471,7 +4485,10 @@ Then these lines could look like
 .
 .
 .P
-The result looks like
+The result looks like this:
+.
+.
+.P
 .RS
 .ft CR
 before
@@ -4483,7 +4500,7 @@ after
 .
 .
 .\" ====================================================================
-.SS Underlining with Overstriking \ez and \e(ul
+.SS Underlining with overstriking
 .\" ====================================================================
 .
 There is another possibility for underlining by using overstriking
@@ -4493,66 +4510,160 @@ with
 .I c
 with zero width without spacing) and
 .B \e(ul
-(underline character).
-.
-This produces the underlining of 1 character, both in
-.B nroff
-and in
-.BR troff .
+(underscore character).
 .
+This produces the underlining of 1 character, in both
+.B troff
+and
+.BR nroff ;
 .
-.P
-For example the underlining of a character say
-.B t
+for example, underlining the character \[lq]t\[rq]
 looks like
 .B \ez\e[ul]t
 or
 .B \ez\e(ult
+or
+.B \ez\e_t
+(all of which are equivalent).
+.
+.
+.P
+However, note that the order in which the
+characters are written matters;
+the sequences
+.B \ez\e_t
+and
+.B \ezt\e_
+are
+.I not
+equivalent;
+.
+though an output device (namely, a TTY) may render the glyphs properly,
+it may also determine that the last character which was output in a
+certain place is the intended textual data:
+.
+In one case, the \[lq]t\[rq] is output last, and so \[lq]t\[rq] is
+correctly determined to be the inteded textual data;
+.
+in the other case, an underscore (\c
+.dquoted_char \_ )
+is output last, obscuring the author's intended textual data, and
+thereby thwarting attempts to search programmatically for the underlined
+text, etc.
 .
 .
 .P
-Longer words look then a bit strange, but a useful mode is to write
-each character into a whole own line.
+This method causes a long word to look a bit strange. A style that
+remains relatively comprehensible is to place each sequence on a whole
+line of its own;
 .
-To underlines the 3 character part "tar" of the word "start":
+here's how to underline \[lq]tar\[rq] in the word
+\[lq]s\
+\z\_t\
+\z\_a\
+\z\_r\
+t\[rq]:
 .
+.
+.P
 .RS
 .EX
 .br
-before s\[rs]
-\[rs]z\[rs][ul]t\[rs]
-\[rs]z\[rs][ul]a\[rs]
-\[rs]z\[rs][ul]r\[rs]
-t after
+s\e
+\ez\e_t\e
+\ez\e_a\e
+\ez\e_r\e
+t
 .EE
 .RE
 .
-or
 .
+.\" ====================================================================
+.SS Overstriking with line drawing
+.\" ====================================================================
+.
+The technique of overstriking underscore characters (\c
+.dquoted_char \e_ )
+with corresponding textual output can be automated by using the
+horizontal-line drawing escape,
+.ESCq l Nc ,
+where
+.I N
+is a length whose default scaling indicator is the em (\c
+.dquoted_char m ),
+and where
+.I c
+is an optional argument that specifies which glyph should be used
+to draw the line;
+.
+by default,
+.I c
+is the \[lq]baseline rule\[rq] glyph (\c
+.dquoted_char \e[ru] ),
+which is a font-invariant horizontal rule of length 0.5em, but it's
+probably safest to use the underscore character explicitly.
+.
+Here's how it might be used in a macro:
+.
+.
+.P
 .RS
 .EX
-.br
-before s\[rs]
-\[rs]z\[rs](ult\[rs]
-\[rs]z\[rs](ula\[rs]
-\[rs]z\[rs](ulr\[rs]
-t after
+\&.de underline3
+\&.  nop \e\e$1\eZ`\el"\ew'\e\e$2'u\e_"`\e\e$2\e\e$3
+\&..
 .EE
 .RE
 .
 .
+.de underline3
+. nop \\$1\Z`\l"\w'\\$2'u\_"`\\$2\\$3
+..
+.P
+Now, the \[lq]tar\[rq] in
+.underline3 \[lq]s tar t\[rq]
+can be underlined easily:
+.
+.
 .P
-The result looks like
 .RS
-.ft CR
-before s\
-\z\[ul]t\
-\z\[ul]a\
-\z\[ul]r\
-t after
-.ft R
+.EX
+\&.underline3 s tar t
+.EE
 .RE
 .
+.
+.P
+However, there's usually little need to produce underlining in the
+middle of a word; the usage can be simplified with another macro:
+.
+.
+.P
+.RS
+.EX
+\&.de underline
+\&.  underline3 "" \e\e$@
+\&..
+\&.
+Then there's
+\&.underline no
+end to the
+\&.underline possibilities .
+.EE
+.RE
+.
+.
+.P
+.de underline
+.  underline3 "" \\$@
+..
+.
+Then there's
+.underline no
+end to the
+.underline possibilities .
+.
+.
 .\" ====================================================================
 .SH COMPATIBILITY
 .\" ====================================================================
diff --git a/man/groff_char.7.man b/man/groff_char.7.man
index bae9fec8..d72c3458 100644
--- a/man/groff_char.7.man
+++ b/man/groff_char.7.man
@@ -991,7 +991,7 @@ Output	Input	PostScript	Unicode	Notes
 _
 \[ba]	\e[ba]	bar	u007C
 \[br]	\e[br]	SF110000	u2502	box rule +
-\[ul]	\e[ul]	underscore	u005F	+
+\[ul]	\e[ul] or \e_	underscore	u005F	+
 \[rn]	\e[rn]	overline	u203E	+
 \[ru]	\e[ru]	---	---	baseline rule +
 \[bb]	\e[bb]	brokenbar	u00A6
-- 
2.17.1

