Debian Codegraph @

texmf-dist/doc/generic/ulem/ulem.ltx

raw
1 %
2 % ulem.ltx Manual for ulem.sty
3 %
4 %
5 % Copyright (c) 1989-2019 by Donald Arseneau
6 %
7 % Version date 2019/11/18
8 %
9 \documentclass[12pt]{ltxdoc}
10 \addtolength{\textwidth}{1cm}
11 %\makeshortverb`\|
12 \usepackage{ulem}
13 \def\baselinestretch{1.06}
14 \setlength\parskip{2pt}
15 \hyphenation{normalem uwforbf ulforem}
16 \title{The ulem package:\\ underlining for emphasis}
17 \author{Donald Arseneau\\ [email protected]}
18 \date{2019/11/18}
19 \begin{document}
20
21 \maketitle
22 \sloppy
23
24 \begin{abstract}
25 The ulem package provides various types of underlining that can stretch
26 between words and be broken across lines. Use it with \LaTeX\ or plain \TeX.
27
28 In \LaTeX, ulem normally replaces italics with underlining in text
29 emphasized by \cs{emph}, and to some extent by \cs{em}. A declaration
30 of |\normalem| or the |\usepackage| option |[normalem]| disables this
31 feature.
32
33 The following commands are defined for general use:\\[5pt]
34 \indent \begin{tabular}{l@{\quad}l}\hline\noalign{\vskip2pt}
35 |\uline{important}| & underlined text like \uline{important}\\[1pt]
36 |\uuline{urgent}| & double-underlined text like \uuline{urgent}\\[1pt]
37 |\uwave{boat}| & wavy underline like {\let\ULleaders\cleaders\uwave{boat}}\\[1pt]
38 |\sout{wrong}| & line struck through word like \sout{wrong}\\[1pt]
39 |\xout{removed}| & marked over like \xout{removed} \\[1pt]
40 |\dashuline{dashing}|& dashed underline like \dashuline{dashing}\\[1pt]
41 |\dotuline{dotty}| & dotted underline like \dotuline{dotty}\\[3pt]\hline
42 \end{tabular}\\[6pt]
43 Other similar commands can be defined with relative ease by utilizing the
44 \cs{markoverwith} command provided by ulem.
45 \end{abstract}
46
47
48 \begin{footnotesize}
49 \noindent The ulem package is Copyright \copyright\ 1989--2019 by
50 Donald Arseneau (Vancouver, Canada).\\
51 The package (ulem.sty) and this documentation (ulem.ltx, ulem.pdf) may be
52 freely transmitted, reproduced, or modified for any purpose provided that the
53 copyright notice is left intact.
54 (Small excerpts may of course be taken and used without any restriction.)\par
55 \end{footnotesize}
56
57 \section{Basic Use}
58 Ulem is a package for \LaTeX\ or plain \TeX\ which provides various types of
59 underlining that can stretch between words and be broken across lines.
60 Such underlining is given by the \cs{uline} command, leaving the original
61 \cs{underline} command available for math mode.
62 To load this package in plain \TeX, use `|\input ulem.sty|'.
63
64 In \LaTeX\ ulem replaces italics with underlining in text emphasized
65 by \cs{em} or \cs{emph} -- but only if the text is delimited by
66 braces. Unlike regular \cs{emph} emphasis, nested ulem emphasis generates
67 multiple underlining; it does not alternate on and off.
68 To use \cs{uline} for underlining, but have \cs{em} and \cs{emph} still
69 produce normal italics, load ulem with |\usepackage[normalem]{ulem}|,
70 or declare \cs{normalem} in the preamble.
71
72 Unlike regular underlining, ulem allows line breaks, and manual
73 hyphenation, within the underlined text; but it is far from perfect. It is
74 most suitable for simple text like {\em \LaTeX: A document preparation
75 system\/} that may need to be underlined in a manuscript submitted for
76 publication. Again, ulem can only give underlined text for \cs{em} when
77 the text is delimited by explicit braces.
78
79 The thickness of the underline rule is given by the command macro
80 \cs{ULthickness}; use \cs{renewcommand} (not the usual
81 \cs{setlength}) to change it.\footnote
82 {Users of plain \TeX\ should use \textbackslash def wherever these
83 instructions recommend \textbackslash(re)newcommand, and dimen
84 assignments wherever \textbackslash setlength is mentioned.}\,
85 The depth of the underline is controlled
86 by the length \cs{ULdepth}. The default value is a special flag
87 (\cs{maxdimen}) which lets the depth vary depending on the current font.
88 You can set a particular value to \cs{ULdepth} (using \cs{setlength}) to
89 force a particular depth, either locally for a special purpose, or
90 for the document as a whole. (See the definition of \cs{sout} for an
91 example.)
92
93 Other types of underlining are defined as well:
94 a wavey underline with \cs{uwave} (\uwave{under-wave}), double underlines
95 using \cs{uuline} (\uuline{two lines under this}), dashed \cs{dashuline}
96 (\dashuline{dashes underneath}) or dotted \cs{dotuline} (\dotuline{dots
97 below}) underlines. Non-underlines are: a line to strike out text \cs{sout}
98 (\sout{strike out}), and text crossed-out with hatching \cs{xout}
99 (\xout{cross out}). See them tabulated in the abstract.
100
101 Alternative package: soul.
102
103 \section{Defining new commands}
104
105 You can define your own styles of overprinting or underlining by using
106 the \cs{markoverwith} command in the definition of your new command.
107 The definition should be something like:\\[6pt]
108 \cs{newcommand}\cs{cmd}|{|\cs{bgroup} \meta{settings}\cs{markoverwith}|{|\meta{something}|}|\cs{ULon}|}|\\[8pt]
109 The `\meta{something}' can be as simple as a single character, or as complex as
110 you can keep track of; it will likely contain some repositioning commands, perhaps
111 \cs{raisebox}.
112
113 Producing a colored underline or strike-through is not supported by
114 regular |\uline| or |\sout|, but it is quite easy to colorize using
115 the \cs{markoverwith} mechanism: just put |\textcolor{|\dots|}| in
116 the \meta{something}, such as this definition:
117 \begin{verbatim}
118 \newcommand\reduline{\bgroup\markoverwith
119 {\textcolor{red}{\rule[-0.5ex]{2pt}{0.4pt}}}\ULon}
120 \end{verbatim}
121 If you really feel the need to make a new command with a truly
122 flexible rule, then look in ulem.sty and copy from the definitions
123 of \cs{uline} and \cs{sout}.
124
125 Any type of underlining can be substituted for any font-selection command
126 by issuing a proper \cs{useunder} declaration:\\[3pt]
127 \cs{useunder}|{|\meta{underlinecommand}|}{|\meta{fontdeclaration}|}{|\meta{fontcommand}|}|\\[3pt]
128 e.g., |\useunder{\uuline}{\bfseries}{\textbf}| gives a double underline
129 instead of bold face in \LaTeX\ (but note the problem explained next).
130
131 The commands \cs{normalem} and \cs{ULforem} respectively disable and enable
132 underlining for \cs{em}/\cs{emph}, and so do the \cs{usepackage}
133 options [normalem] and [ULforem]. There is also the \cs{usepackage}
134 option [UWforbf] to replace boldface from \cs{textbf} with a wavey underline.
135 These features use the \cs{useunder} command internally.
136 UWforbf specifically employs
137 \cs{useunder}|{|\cs{uwave}|}|\allowbreak|{|\cs{bf}|}|\allowbreak|{|\cs{textbf}|}|,
138 so the \cs{bfseries}
139 command still produces bold face, but \cs{bf} makes an
140 under-wave (if \cs{bf} is defined at all). That is
141 because section title formatting typically uses \cs{bfseries} not delimited by
142 braces, which would give errors for \cs{uwave}.\footnote{%% no verbatim in footnotes
143 To get under-waved section titles (in ordinary \LaTeX\ classes) you could define:\\
144 \texttt{\string\renewcommand\string\@seccntformat[1]\string{\string\uwave
145 \string{\string\csname\ the\#1\string\endcsname\string}\string\hskip 1em\string}}\\
146 and later specify
147 \texttt{\string\section[...]\string{\string\uwave\string{...\string}\string}}.
148 But you don't want to enter that swamp.}
149 In plain \TeX\ there is \cs{bf} but no \cs{textbf} so you could say |\useunder{\uwave}{\bf}{}|.
150
151 Some commands, such as |\\| and \cs{hskip} are given special treatment to
152 work within uline, but others are not. Support for others can sometimes
153 be added by assigning special meanings in the token register \cs{UL@hook}.
154 (In \LaTeX\ do
155 |\addto@hook\UL@hook{\let\cmd\|\textsl{UL-version-of-cmd}|}|.) The UL
156 versions of commands should be modelled on |\UL@hskip| or |\UL@cr|, and
157 should include the test `|\ifx\ \LA@space|'. For example, support for
158 \cs{marginpar} is added through the hook mechanism.
159
160 All the underlining commands are robust in \LaTeX.
161
162
163 \section{Complications}
164 The various underlining commands are essentially textual, and will not
165 work quite the same in math mode. But since some font commands,
166 in the old-\LaTeX\ style (`oldlfont') serve both for text and math,
167 math mode is handled (in an approximate way). Generally, you should
168 avoid using ulem's commands within math, but math may appear in the
169 text argument to ulem's commands.
170
171 Every word is typeset in an underlined box, so automatic hyphenation is
172 disabled, but explicit discretionary hyphens (|\-|) will still be
173 obeyed. Several text-formatting commands are specially supported within
174 the underlining: |\-|, |\ |, |~|, |\\|, |\newline|, |\linebreak|,
175 |\nolinebreak|, |\penalty|, |\hskip|, |\hspace|, |\hfil|, |\hfill|, |\hss|.
176 Displayed math is not supported. The special commands
177 do have a problem: they end a group so any local assignments are lost.
178
179 The underlines continue between words, and stretch just like ordinary
180 spaces do. Since spaces delimit words, there may be some difficulty
181 with syntactical spaces (e.g. `|2.3 pt|'). Some effort is made to handle
182 such cases, but sometimes (such as |\let\x= y|) the space is interpreted
183 incorrectly. You can usually solve the problem by enclosing the offending
184 command in braces or in a macro (like |\newcommand\xeqy{\let\x= y}|),
185 but\,\dots
186
187 One important incompatibility with braces and macro replacement:
188 \textbf{All the text in braces or coming from a macro is typeset in a box}
189 (as if in \cs{mbox}). Consequently,
190 braces will suppress stretching and line-breaking in the text they
191 enclose. Moreover, the specially-handled commands |\-|, |\\|, |\newline|
192 and |\linebreak| are usually ignored if they appear inside extra braces.
193 They operate only when the braces delimit a command parameter without
194 introducing a level of grouping. (Even though braces delimiting command
195 parameters do not normally imply grouping, many commands will add their
196 own grouping.) Thus, you should try to limit inner braces to short bits of
197 text or for delimiting parameters to commands. For emergency repairs, see
198 the sadistic `Marat/Sade' example below. Syntactical spaces inside braces
199 never cause a problem, nor do spaces in math mode.
200
201 Text produced by expansion of a command (macro) is boxed too, but |\\|, |\ |,
202 and |\-| still work properly in the expansion text so that while\\[2pt]
203 \indent |\newcommand\iff{if and only if} ... \uline{\iff}|\\[2pt]
204 prevents stretching and line-breaking between words, the alternative\\[2pt]
205 \indent |\newcommand\iff{if\ and\ only\ if} ... \uline{\iff}|\\[2pt]
206 allows stretching and line-breaking. There is a remaining problem though:
207 the |\ | (backslash-space) between words closes a group and any local
208 assignments will be lost, in particular, font changes and color changes.
209
210 This loss of local assignments will break some other standard commands,
211 (e.g., \cs{cite}) which produce multiple `words' using local assignments.
212 The way to protect such commands is to bury them in an \cs{mbox}:
213 \hskip 5pt plus 2in
214 |\emph{every\-one agrees~\mbox{\cite{you,me}}.}|
215
216 With ULforem in effect,
217 nested \cs{em} or \cs{emph} commands produce multiple underlining,
218 but heed the warnings
219 about braces above. To get italics without underlining, use \cs{it},
220 \cs{itshape}, or \cs{textit}. Nesting
221 of other types of underline is also possible, but the `underlines' may
222 overlap.
223
224 \medskip
225 Here is a simple example (highlighting all invented words):\\[4pt]
226 \begin{minipage}[t]{.58\linewidth}\hbadness=9999
227 \ttfamily \rightskip=0pt plus 2cm
228 |'Twas| |\emph{brillig}| |and| |the| |\emph{slithy~toves}|
229 |did| |\emph{gyre}| |and| |\emph{gim\-ble}| |in| |the| |\emph{wabe,\\| |}|
230 |All| |\emph{mim\-sey}| |were| |the| |\emph{boro\-goves}| |and|
231 |the| |\emph{mome| |raths| |outgrabe}.|
232 \end{minipage}\hfill
233 \begin{minipage}[t]{.4\linewidth}\hbadness=9999
234 'Twas \emph{brillig} and the \emph{slithy~toves}
235 did \emph{gyre} and \emph{gim\-ble} in the \emph{wabe,\\ }
236 All \emph{mim\-sey} were the \emph{boro\-goves} and
237 the \emph{mome raths out\-grabe}.\par\mbox{}
238 \end{minipage}\vspace{6pt}
239 Note use
240 of explicit hyphenation in `gimble' and `borogoves', the tie (|~|)
241 that prevents a line break in `slithy toves', but stretches like a
242 usual space, the `|\\|' that gives a proper linebreak, and the regular
243 (unforced) linebreak in `mome raths outgrabe'.
244
245 \medskip
246 Here is an ugly example showing how nested uline (\cs{emph}) needs
247 to be broken up to allow line-breaks\\[2pt]
248 \begin{minipage}[t]{.5\linewidth}
249 \ttfamily \rightskip=0pt plus 1.5cm \hbadness=9999
250 |No,| |I| |did| |{\em| |not}| |act| |in| |the| |movie| |{\em| |\emph{The}|
251 |\emph{Persecution}| |\emph{and}| |\emph{Assassin}\-\emph{ation}| |\emph{of}|
252 |\emph{Jean-Paul}| |\emph{Marat},| |as| |Per\-formed| |by| |the| |Inmates|
253 |of| |the| |Asylum| |of| |Charenton| |Under| |the| |Direc\-tion| |of| |the|
254 |Marquis| |de~Sade!}| |But| |I| |{\em| |did}| |see| |it.|\\\mbox{}
255 \end{minipage}\hfill
256 \begin{minipage}[t]{.43\linewidth}\hbadness=9999
257 No, I did {\em not} act in the movie {\em \emph{The}
258 \emph{Persecution} \emph{and} \emph{Assassin}\-\emph{ation} \emph{of}
259 \emph{Jean-Paul} \emph{Marat}, as Per\-formed by the Inmates
260 of the Asylum of Charenton Under the Direc\-tion of the
261 Marquis de~Sade!} But I {\em did} see it.
262 \end{minipage}\\
263 In the nested emphasis, \cs{emph} had to be given for each word separately
264 so the spaces between could stretch and break into lines. Even the
265 discretionary hyphen (|\-|) in `Assassination' had to be outside the braces,
266 but the hyphen in `Direction' was just fine because it was not in nested
267 braces. The same applies to other special commands like |\ | and |~|. Also,
268 the spaces are printed with only a single underline because they are
269 outside the nested \cs{emph} commands. This example really illustrates that
270 ulem does not handle nested emphasis very well! It should be reserved for
271 simpler cases where it performs well without effort.
272
273 \end{document}