ulem now its own generic package (29jan10)

git-svn-id: svn://tug.org/texlive/trunk@16866 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 265 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/generic/ulem/ulem.ltx b/Master/texmf-dist/doc/generic/ulem/ulem.ltx
new file mode 100644
index 00000000000..e51be35e33e
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/ulem/ulem.ltx
@@ -0,0 +1,265 @@
+%
+%  ulem.ltx   Manual for ulem.sty
+%
+%
+%  Copyright (c) 1989-2010 by Donald Arseneau
+%
+%  Version date 2010/01/21
+%
+\documentclass[12pt]{ltxdoc}
+\addtolength{\textwidth}{1cm}
+%\makeshortverb`\|
+\usepackage{ulem}
+\def\baselinestretch{1.06}
+\setlength\parskip{2pt}
+
+\title{The ulem package:\\ underlining for emphasis}
+\author{Donald Arseneau\\ asnd@triumf.ca}
+\date{2010/01/21}
+\begin{document}
+
+\maketitle
+
+\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 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 drawn 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--2010 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.
+For underlining 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} or \cs{def} (not the usual 
+\cs{setlength}) to change it.  The depth of the underline is controlled 
+by the length \cs{ULdepth}.  The default value is a special flag 
+(\cs{maxdimen}) which lets the current font control the depth.  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, 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 frm 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.% Pfooey: no verbatim in footnotes
+\footnote{%
+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.}
+In plain \TeX\ there is 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 (like \cs{marginpar}) 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\ULversion}|.)  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:\\[2pt]
+\indent  |\newcommand\iff{if and only if} {\em \iff}|\\[2pt]
+does not allow any stretching or linebreaking between words, but\\[2pt]
+\indent  |\newcommand\iff{if\ and\ only\ if} {\em \iff}|\\[2pt]
+allows stretching and linebreaking.  There is a 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}
+\ttfamily \rightskip=0pt plus 1cm
+|'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}
+'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
+\end{minipage}\vspace{6pt}
+Note use
+of explicit hyphenation in `gimble', the tie (|~|) that prevents
+a line break in `slithy toves', but stretches like a usual space, 
+and the regular 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 1cm
+|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.|\par
+\end{minipage}\hfill
+\begin{minipage}[t]{.43\linewidth}
+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}\\[8pt]
+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!  Nevertheless, it is fine
+for simple things.
+
+\end{document}
diff --git a/Master/texmf-dist/doc/generic/ulem/ulem.pdf b/Master/texmf-dist/doc/generic/ulem/ulem.pdf
new file mode 100644
index 00000000000..a33d9b36f8d
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/ulem/ulem.pdf