| 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} |