summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ulem/ulem.ltx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/ulem/ulem.ltx')
-rw-r--r--macros/latex/contrib/ulem/ulem.ltx273
1 files changed, 273 insertions, 0 deletions
diff --git a/macros/latex/contrib/ulem/ulem.ltx b/macros/latex/contrib/ulem/ulem.ltx
new file mode 100644
index 0000000000..2979659c30
--- /dev/null
+++ b/macros/latex/contrib/ulem/ulem.ltx
@@ -0,0 +1,273 @@
+%
+% ulem.ltx Manual for ulem.sty
+%
+%
+% Copyright (c) 1989-2011 by Donald Arseneau
+%
+% Version date 2011/03/18
+%
+\documentclass[12pt]{ltxdoc}
+\addtolength{\textwidth}{1cm}
+%\makeshortverb`\|
+\usepackage{ulem}
+\def\baselinestretch{1.06}
+\setlength\parskip{2pt}
+\hyphenation{normalem uwforbf ulforem}
+\title{The ulem package:\\ underlining for emphasis}
+\author{Donald Arseneau\\ asnd@triumf.ca}
+\date{2011/03/18}
+\begin{document}
+
+\maketitle
+\sloppy
+
+\begin{abstract}
+ The ulem package provides various types of underlining that can stretch
+ between words and be broken across lines. Use it with \LaTeX\ or plain \TeX.
+
+ In \LaTeX, ulem normally replaces italics with underlining in text
+ emphasized by \cs{emph}, and to some extent by \cs{em}. A declaration
+ of |\normalem| or the |\usepackage| option |[normalem]| disables this
+ feature.
+
+ The following commands are defined for general use:\\[5pt]
+ \indent \begin{tabular}{l@{\quad}l}\hline\noalign{\vskip2pt}
+ |\uline{important}| & underlined text like \uline{important}\\[1pt]
+ |\uuline{urgent}| & double-underlined text like \uuline{urgent}\\[1pt]
+ |\uwave{boat}| & wavy underline like {\let\ULleaders\cleaders\uwave{boat}}\\[1pt]
+ |\sout{wrong}| & line struck through word like \sout{wrong}\\[1pt]
+ |\xout{removed}| & marked over like \xout{removed} \\[1pt]
+ |\dashuline{dashing}|& dashed underline like \dashuline{dashing}\\[1pt]
+ |\dotuline{dotty}| & dotted underline like \dotuline{dotty}\\[3pt]\hline
+ \end{tabular}\\[6pt]
+ Other similar commands can be defined with relative ease by utilizing the
+ \cs{markoverwith} command provided by ulem.
+\end{abstract}
+
+
+\begin{footnotesize}
+\noindent The ulem package is Copyright \copyright\ 1989--2011 by
+Donald Arseneau (Vancouver, Canada).\\
+The package (ulem.sty) and this documentation (ulem.ltx, ulem.pdf) may be
+freely transmitted, reproduced, or modified for any purpose provided that the
+copyright notice is left intact.
+(Small excerpts may of course be taken and used without any restriction.)\par
+\end{footnotesize}
+
+\section{Basic Use}
+Ulem is a package for \LaTeX\ or plain \TeX\ which provides various types of
+underlining that can stretch between words and be broken across lines.
+Such underlining is given by the \cs{uline} command, leaving the original
+\cs{underline} command available for math mode.
+To load this package in plain \TeX, use `|\input ulem.sty|'.
+
+In \LaTeX\ ulem replaces italics with underlining in text emphasized
+by \cs{em} or \cs{emph} -- but only if the text is delimited by
+braces. Unlike regular \cs{emph} emphasis, nested ulem emphasis generates
+multiple underlining; it does not alternate on and off.
+To use \cs{uline} for underlining, but have \cs{em} and \cs{emph} still
+produce normal italics, load ulem with |\usepackage[normalem]{ulem}|,
+or declare \cs{normalem} in the preamble.
+
+Unlike regular underlining, ulem allows line breaks, and manual
+hyphenation, within the underlined text; but it is far from perfect. It is
+most suitable for simple text like {\em \LaTeX: A document preparation
+system\/} that may need to be underlined in a manuscript submitted for
+publication. Again, ulem can only give underlined text for \cs{em} when
+the text is delimited by explicit braces.
+
+The thickness of the underline rule is given by the command macro
+\cs{ULthickness}; use \cs{renewcommand} (not the usual
+\cs{setlength}) to change it.\footnote
+{Users of plain \TeX\ should use \textbackslash def wherever these
+instructions recommend \textbackslash(re)newcommand, and dimen
+assignments wherever \textbackslash setlength is mentioned.}\,
+The depth of the underline is controlled
+by the length \cs{ULdepth}. The default value is a special flag
+(\cs{maxdimen}) which lets the depth vary depending on the current font.
+You can set a particular value to \cs{ULdepth} (using \cs{setlength}) to
+force a particular depth, either locally for a special purpose, or
+for the document as a whole. (See the definition of \cs{sout} for an
+example.)
+
+Other types of underlining are defined as well:
+a wavey underline with \cs{uwave} (\uwave{under-wave}), double underlines
+using \cs{uuline} (\uuline{two lines under this}), dashed \cs{dashuline}
+(\dashuline{dashes underneath}) or dotted \cs{dotuline} (\dotuline{dots
+below}) underlines. Non-underlines are: a line to strike out text \cs{sout}
+(\sout{strike out}), and text crossed-out with hatching \cs{xout}
+(\xout{cross out}). See them tabulated in the abstract.
+
+Alternative package: soul.
+
+\section{Defining new commands}
+
+You can define your own styles of overprinting or underlining by using
+the \cs{markoverwith} command in the definition of your new command.
+The definition should be something like:\\[3pt]
+\indent
+ \cs{newcommand}\cs{cmd}|{|\cs{bgroup} \cs{markoverwith}|{|\meta{something}|}|\cs{ULon}|}|\\[3pt]
+The `\meta{something}' can be as simple as a single character, or as complex as
+you can keep track of; it will likely contain some repositioning commands, perhaps
+\cs{raisebox}.
+
+Producing a colored underline or strike-through is not supported by
+regular |\uline| or |\sout|, but it is quite easy to colorize using
+the \cs{markoverwith} mechanism: just put |\textcolor{|\dots|}| in
+the \meta{something}, such as this definition:
+\begin{verbatim}
+ \newcommand\reduline{\bgroup\markoverwith
+ {\textcolor{red}{\rule[-0.5ex]{2pt}{0.4pt}}}\ULon}
+\end{verbatim}
+If you really feel the need to make a new command with a truly
+flexible rule, then look in ulem.sty and copy from the definitions
+of \cs{uline} and \cs{sout}.
+
+Any type of underlining can be substituted for any font-selection command
+by issuing a proper \cs{useunder} declaration:\\[3pt]
+ \cs{useunder}|{|\meta{underlinecommand}|}{|\meta{fontdeclaration}|}{|\meta{fontcommand}|}|\\[3pt]
+e.g., |\useunder{\uuline}{\bfseries}{\textbf}| gives a double underline
+instead of bold face in \LaTeX.
+
+The commands \cs{normalem} and \cs{ULforem} respectively disable and enable
+underlining for \cs{em}/\cs{emph}, and so do the \cs{usepackage}
+options [normalem] and [ULforem]. There is also the \cs{usepackage}
+option [UWforbf] to replace boldface with a wavey underline. These features
+use the \cs{useunder} command internally. UWforbf does handle bold in
+math mode, in a limited way, but it doesn't work in section titles,
+unfortunately, because the titles are not delimited by explicit braces when
+printed by the \cs{section} command. Currently under UWforbf the \cs{bfseries}
+command still produces bold face, but \cs{bf} makes an
+under-wave\footnote{%% no verbatim in footnotes
+To get under-waved section titles (in ordinary \LaTeX\ classes) you could define:\\
+\texttt{\string\renewcommand\string\@seccntformat[1]\string{\string\uwave
+\string{\string\csname\ the\#1\string\endcsname\string}\string\hskip 1em\string}}\\
+and later specify
+\texttt{\string\section[...]\string{\string\uwave\string{...\string}\string}}.
+But you don't want to enter that swamp.}
+(if |\bf| is defined at all).
+In plain \TeX\ there is |\bf| but no \cs{textbf} so you could say |\useunder{\UWave}{\bf}{}|.
+
+Some commands, such as |\\| and \cs{hskip} are given special treatment to
+work within uline, but others are not. Support for others can sometimes
+be added by assigning special meanings in the token register \cs{UL@hook}.
+(In \LaTeX\ do
+|\addto@hook\UL@hook{\let\cmd\|\textsl{UL-version-of-cmd}|}|.) The UL
+versions of commands should be modelled on |\UL@hskip| or |\UL@cr|, and
+should include the test `|\ifx\ \LA@space|'. For example, support for
+\cs{marginpar} is added through the hook mechanism.
+
+All the underlining commands are robust (self-protecting) in \LaTeX.
+
+
+\section{Complications}
+The various underlining commands are essentially textual, and will not
+work quite the same in math mode. But since some font commands,
+in the old-\LaTeX\ style (`oldlfont') serve both for text and math,
+math mode is handled (in an approximate way). Generally, you should
+avoid using ulem's commands within math, but math may appear in the
+text argument to ulem's commands.
+
+Every word is typeset in an underlined box, so automatic hyphenation is
+disabled, but explicit discretionary hyphens (|\-|) will still be
+obeyed. Several text-formatting commands are specially supported within
+the underlining: |\-|, |\ |, |~|, |\\|, |\newline|, |\linebreak|,
+|\nolinebreak|, |\penalty|, |\hskip|, |\hspace|, |\hfil|, |\hfill|, |\hss|.
+Displayed math is not supported. The special commands
+do have a problem: they end a group so any local assignments are lost.
+
+The underlines continue between words, and stretch just like ordinary
+spaces do. Since spaces delimit words, there may be some difficulty
+with syntactical spaces (e.g. `|2.3 pt|'). Some effort is made to handle
+such cases, but sometimes (such as |\let\x= y|) the space is interpreted
+incorrectly. You can usually solve the problem by enclosing the offending
+command in braces or in a macro (like |\newcommand\xeqy{\let\x= y}|),
+but\,\dots
+
+One important incompatibility with braces and macro replacement:
+\textbf{All the text in braces or coming from a macro is typeset in a box}
+(as if in \cs{mbox}). Consequently,
+braces will suppress stretching and line-breaking in the text they
+enclose. Moreover, the specially-handled commands |\-|, |\\|, |\newline|
+and |\linebreak| are usually ignored if they appear inside extra braces.
+They operate only when the braces delimit a command parameter without
+introducing a level of grouping. (Even though braces delimiting command
+parameters do not normally imply grouping, many commands will add their
+own grouping.) Thus, you should try to limit inner braces to short bits of
+text or for delimiting parameters to commands. For emergency repairs, see
+the sadistic `Marat/Sade' example below. Syntactical spaces inside braces
+never cause a problem, nor do spaces in math mode.
+
+Text produced by expansion of a command (macro) is boxed too, but |\\|, |\ |,
+and |\-| still work properly in the expansion text so that while\\[2pt]
+\indent |\newcommand\iff{if and only if} ... \uline{\iff}|\\[2pt]
+prevents stretching and line-breaking between words, the alternative\\[2pt]
+\indent |\newcommand\iff{if\ and\ only\ if} ... \uline{\iff}|\\[2pt]
+allows stretching and line-breaking. There is a remaining problem though:
+the |\ | (backslash-space) between words closes a group and any local
+assignments will be lost, in particular, font changes and color changes.
+
+This loss of local assignments will break some other standard commands,
+(e.g., \cs{cite}) which produce multiple `words' using local assignments.
+The way to protect such commands is to bury them in an \cs{mbox}:
+\hskip 5pt plus 2in
+|\emph{every\-one agrees~\mbox{\cite{you,me}}.}|
+
+With ULforem in effect,
+nested \cs{em} or \cs{emph} commands produce multiple underlining,
+but heed the warnings
+about braces above. To get italics without underlining, use \cs{it},
+\cs{itshape}, or \cs{textit}. Nesting
+of other types of underline is also possible, but the `underlines' may
+overlap.
+
+\medskip
+Here is a simple example (highlighting all invented words):\\[4pt]
+\begin{minipage}[t]{.58\linewidth}\hbadness=9999
+\ttfamily \rightskip=0pt plus 2cm
+|'Twas| |\emph{brillig}| |and| |the| |\emph{slithy~toves}|
+|did| |\emph{gyre}| |and| |\emph{gim\-ble}| |in| |the| |\emph{wabe,\\| |}|
+|All| |\emph{mim\-sey}| |were| |the| |\emph{boro\-goves}| |and|
+|the| |\emph{mome| |raths| |outgrabe}.|
+\end{minipage}\hfill
+\begin{minipage}[t]{.4\linewidth}\hbadness=9999
+'Twas \emph{brillig} and the \emph{slithy~toves}
+did \emph{gyre} and \emph{gim\-ble} in the \emph{wabe,\\ }
+All \emph{mim\-sey} were the \emph{boro\-goves} and
+the \emph{mome raths out\-grabe}.\par\mbox{}
+\end{minipage}\vspace{6pt}
+Note use
+of explicit hyphenation in `gimble' and `borogoves', the tie (|~|)
+that prevents a line break in `slithy toves', but stretches like a
+usual space, the `|\\|' that gives a proper linebreak, and the regular
+(unforced) linebreak in `mome raths outgrabe'.
+
+\medskip
+Here is an ugly example showing how nested uline (\cs{emph}) needs
+to be broken up to allow line-breaks\\[2pt]
+\begin{minipage}[t]{.5\linewidth}
+\ttfamily \rightskip=0pt plus 1.5cm \hbadness=9999
+|No,| |I| |did| |{\em| |not}| |act| |in| |the| |movie| |{\em| |\emph{The}|
+|\emph{Persecution}| |\emph{and}| |\emph{Assassin}\-\emph{ation}| |\emph{of}|
+|\emph{Jean-Paul}| |\emph{Marat},| |as| |Per\-formed| |by| |the| |Inmates|
+|of| |the| |Asylum| |of| |Charenton| |Under| |the| |Direc\-tion| |of| |the|
+|Marquis| |de~Sade!}| |But| |I| |{\em| |did}| |see| |it.|\\\mbox{}
+\end{minipage}\hfill
+\begin{minipage}[t]{.43\linewidth}\hbadness=9999
+No, I did {\em not} act in the movie {\em \emph{The}
+\emph{Persecution} \emph{and} \emph{Assassin}\-\emph{ation} \emph{of}
+\emph{Jean-Paul} \emph{Marat}, as Per\-formed by the Inmates
+of the Asylum of Charenton Under the Direc\-tion of the
+Marquis de~Sade!} But I {\em did} see it.
+\end{minipage}\\
+In the nested emphasis, \cs{emph} had to be given for each word separately
+so the spaces between could stretch and break into lines. Even the
+discretionary hyphen (|\-|) in `Assassination' had to be outside the braces,
+but the hyphen in `Direction' was just fine because it was not in nested
+braces. The same applies to other special commands like |\ | and |~|. Also,
+the spaces are printed with only a single underline because they are
+outside the nested \cs{emph} commands. This example really illustrates that
+ulem does not handle nested emphasis very well! It should be reserved for
+simpler cases where it performs well without effort.
+
+\end{document}