ulem (13oct10)

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

3 files changed, 58 insertions, 45 deletions

diff --git a/Master/texmf-dist/doc/generic/ulem/README b/Master/texmf-dist/doc/generic/ulem/README
new file mode 100644
index 00000000000..56c71e8637a
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/ulem/README
@@ -0,0 +1,5 @@
+The package provides an \ul (underline) command will break over line ends; 
+this technique may be used to replace \em (both in that form and as the 
+\emph command), so as to make output look as if it comes from a typewriter.  
+The package also offers double and wavy underlining, and striking out 
+(line through words) and crossing out ( ///  over words).
\ No newline at end of file
diff --git a/Master/texmf-dist/doc/generic/ulem/ulem.ltx b/Master/texmf-dist/doc/generic/ulem/ulem.ltx
index e51be35e33e..6aeeb401429 100644
--- a/Master/texmf-dist/doc/generic/ulem/ulem.ltx
+++ b/Master/texmf-dist/doc/generic/ulem/ulem.ltx
@@ -4,7 +4,7 @@
 %
 %  Copyright (c) 1989-2010 by Donald Arseneau
 %
-%  Version date 2010/01/21
+%  Version date 2010/10/03
 %
 \documentclass[12pt]{ltxdoc}
 \addtolength{\textwidth}{1cm}
@@ -15,7 +15,7 @@
 
 \title{The ulem package:\\ underlining for emphasis}
 \author{Donald Arseneau\\ asnd@triumf.ca}
-\date{2010/01/21}
+\date{2010/10/03}
 \begin{document}
 
 \maketitle
@@ -24,16 +24,17 @@
   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.
+  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 drawn through word like \sout{wrong}\\[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
@@ -57,7 +58,7 @@ 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|'.
+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 
@@ -75,11 +76,15 @@ 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 
+\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 current font control the depth.  You 
-can set a particular value to \cs{ULdepth} (using \cs{setlength}) to 
+(\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.)
@@ -105,16 +110,16 @@ 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:
+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 frm the definitions
+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
@@ -132,7 +137,7 @@ 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
+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
@@ -140,16 +145,17 @@ To get under-waved section titles (in ordinary \LaTeX\ classes) you could define
 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}{}|.
+(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 (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.
+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.
 
@@ -175,7 +181,8 @@ 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
+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}
@@ -192,12 +199,12 @@ 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 
+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,
@@ -216,42 +223,43 @@ overlap.
 
 \medskip
 Here is a simple example (highlighting all invented words):\\[4pt]
-\begin{minipage}[t]{.58\linewidth}
-\ttfamily \rightskip=0pt plus 1cm
+\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}
+\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
+the \emph{mome raths out\-grabe}.\par\mbox{}
 \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'.
+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 1cm
+\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.|\par
+|Marquis| |de~Sade!}| |But| |I| |{\em| |did}| |see| |it.|\\\mbox{}
 \end{minipage}\hfill
-\begin{minipage}[t]{.43\linewidth}
+\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}\\[8pt]
+\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,
@@ -259,7 +267,7 @@ 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.
+ulem does not handle nested emphasis very well!  It should be reserved for
+simpler cases where it performs well without effort.
 
 \end{document}
diff --git a/Master/texmf-dist/doc/generic/ulem/ulem.pdf b/Master/texmf-dist/doc/generic/ulem/ulem.pdf
index a33d9b36f8d..401dc885434 100644
--- a/Master/texmf-dist/doc/generic/ulem/ulem.pdf
+++ b/Master/texmf-dist/doc/generic/ulem/ulem.pdf