source 1

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

1 files changed, 423 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/ellipsis/ellipsis.dtx b/Master/texmf-dist/source/latex/ellipsis/ellipsis.dtx
new file mode 100644
index 00000000000..4db66a1410b
--- /dev/null
+++ b/Master/texmf-dist/source/latex/ellipsis/ellipsis.dtx
@@ -0,0 +1,423 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2003 by Peter J. Heslin <p.j.heslin@dur.ac.uk>
+% --------------------------------------------------
+% 
+% This file may be distributed and/or modified under the conditions of
+% the LaTeX Project Public License, either version 1.2 of this license
+% or (at your option) any later version.  The latest version of this
+% license is in:
+%
+%    http://www.latex-project.org/lppl.txt
+%
+% and version 1.2 or later is part of all distributions of LaTeX
+% version 1999/12/01 or later.
+%
+% \fi
+%
+% \iffalse
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{ellipsis}
+%<package>   [2004/9/28 v1.6 ellipsis: fixes spacing around \dots] 
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{ellipsis}
+\EnableCrossrefs         
+\CodelineIndex
+\RecordChanges
+\begin{document}
+  \DocInput{ellipsis.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{135}
+%
+% \CharacterTable
+%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+%   Digits        \0\1\2\3\4\5\6\7\8\9
+%   Exclamation   \!     Double quote  \"     Hash (number) \#
+%   Dollar        \$     Percent       \%     Ampersand     \&
+%   Acute accent  \'     Left paren    \(     Right paren   \)
+%   Asterisk      \*     Plus          \+     Comma         \,
+%   Minus         \-     Point         \.     Solidus       \/
+%   Colon         \:     Semicolon     \;     Less than     \<
+%   Equals        \=     Greater than  \>     Question mark \?
+%   Commercial at \@     Left bracket  \[     Backslash     \\
+%   Right bracket \]     Circumflex    \^     Underscore    \_
+%   Grave accent  \`     Left brace    \{     Vertical bar  \|
+%   Right brace   \}     Tilde         \~}
+%
+%
+% \changes{v1.0}{2003/09/30}{Initial version}
+% \changes{v1.1}{2003/10/01}{Modelled definition of \cs{textellipsis}
+% on \textsf{xspace.sty}, added chicago option}
+% \changes{v1.2}{2003/10/2}{Added mla option, removed hard-coded list
+% of punctuation in favor or a configurable list}
+% \changes{v1.3}{2003/10/3}{Removed \@ to make \cs{ellipsisspacing}
+% and \cs{ellipsispunctuation} user configurable.  Changed
+% \cs{ellipsisspacing} from a length to a command to make em pick up
+% the font size when it is used, rather than when it is defined}
+% \changes{v1.4}{2003/10/4}{Changed \cs{ellipsisspacing} to
+% \cs{ellipsisgap} for readability, added \cs{relax} to prevent spaces
+% from being gobbled.}
+% \changes{v1.5}{2004/9/24}{Added the xspace option.}
+% \changes{v1.6}{2004/9/28}{Fixed incompatibility with French Babel.}
+%
+% \GetFileInfo{ellipsis.sty}
+%
+% \title{The \textsf{ellipsis} package\thanks{This document
+%   corresponds to \textsf{ellipsis}~\fileversion, dated \filedate.
+%   Many thanks to Frank Mittelbach, who made numerous suggestions
+%   that greatly improved this package.}}
+% \author{Peter J. Heslin \\ \texttt{p.j.heslin@dur.ac.uk}}
+%
+% \maketitle
+%
+% \section{Introduction}
+%
+% There is an unevenness in the way \LaTeX\ puts space around ellipses
+% (|\dots|) in text mode.  It is a small problem, but it is a serious
+% matter for those who care about such things.  This package attempts
+% to fix that bug, and this documentation offers an explanation of the
+% bug and offers advice on how to use ellipses in your text.  This
+% document should not be taken as offering guidance on the use of
+% ellipses in mathematical formulas or non-English language text.
+%  
+% The standard definition of |\dots| in \LaTeX\ takes the inter-word
+% stretch for the current font and puts that amount of space in
+% between three normal dots; it then also adds that amount of space
+% \emph{after} the final dot.  The documentation of the \LaTeX\ code
+% acknowledges that this is a `kludge' in that the interword stretch
+% is being used for a purpose it was not meant for.  There is another
+% problem with this definition, however: the extra space after the
+% final dot of the ellipsis.  Thus there is always more space after
+% the ellipsis than before it, so that it is not properly centered
+% between the text on either side.
+%  
+% That extra space is there for a good reason.  When the ellipsis is
+% followed by another dot, as at the end of a sentence, it is
+% important that all four dots should be evenly spaced, otherwise the
+% final dot is much closer than the others and the result is hideous.
+% The same holds true for commas, exclamation marks and other
+% punctuation on the baseline.  So the extra space is necessary when
+% an ellipsis is followed by certain punctuation characters, and the
+% bug consists in the fact that \LaTeX\ always adds it, regardless of
+% what text follows.
+%  
+% This package implements a simple fix.  It redefines the |\dots| and
+% |\textellipsis| commands so that they can look ahead at the next
+% character and change their behavior accordingly: if the next
+% character is one of .,;:?! the extra space is added, if not, no
+% extra space is added (if you load a package that makes any of these
+% characters active, you may want to reload this list; see the section
+% below on see below on |\ellipsispunctuation| and compatibility).
+% This particular list of punctuation marks was not chosen
+% arbitrarily: it includes all marks with a dot on the baseline (or a
+% comma, which is like a dot with a tail).  These marks produce a
+% series of four dots which must be spaced evenly~-- no other
+% punctuation mark would normally benefit from having the extra space
+% added.
+%  
+% The solution can be brittle~-- for example, if you write |\dots{}.|
+% then the extra space will \emph{not} be added, since the braces come
+% between the command and the dot; the result will be very ugly.  The
+% solution to this is to enter ellipses carefully and consistently in
+% your source text.  If you use ellipses as recommended below, then
+% the potential problem of evenly spacing an ellipsis that comes
+% immediately after a baseline punctuation mark does not arise, since
+% that combination of characters will not normally be used.
+%  
+% There is another package, \textsf{lips.sty}, that addresses the
+% problem of text ellipses in \LaTeX.  It strictly follows the advice
+% of the \emph{Chicago Manual of Style} in putting full word spaces
+% between the dots of the ellipsis, and does not provide the
+% possibility of more a tightly set ellipsis like the normal \LaTeX\
+% default.  It imposes its own set of rules for the spacing before and
+% after an ellipsis.  Many typographers, however, firmly reject the
+% Chicago style of setting ellipses, and rightly so; see Jan
+% Tschichold, \emph{The Form of the Book: Essays on the Morality of
+%   Good Design} (Hartley \& Marks, 1991), pp~130f, or Robert
+% Bringhurst, \emph{The Elements of Typographic Style}
+% (2\textsuperscript{nd}~ed, Hartley \& Marks, 1997) pp~82f.
+% \DescribeMacro{chicago} If you nevertheless want or have to use the
+% Chicago-style, widely spaced ellipsis with this package, you can
+% pass it the option |chicago|, like so:
+% |\usepackage[chicago]{ellipsis}|.  If, on the other hand, you want
+% to adhere to the full recommendations of the Chicago manual, then
+% you should probably use \textsf{lips.sty} instead of this package.
+% \DescribeMacro{mla} \textsf{Ellipsis.sty} also has an |mla| package
+% option, modeled on the same feature of \textsf{lips.sty}, which
+% automatically puts square brackets around all ellipses.
+%
+% A different solution to the general problem would be to install a
+% font which includes a precomposed ellipsis glyph, and to redefine
+% |\dots| simply to insert this character.  In that case, you do not
+% need this package at all, but you should make sure that the ellipsis
+% character kerns properly, especially with following .,:;!?
+%
+% \section{Usage}
+%  
+% Install the package and put |\usepackage{ellipsis}| in your
+% preamble.  As noted above, you should be consistent in the way you
+% enter ellipses in your text.  For English text, Bringhurst (loc.\
+% cit.)  recommends putting a space before and after an ellipsis that
+% appears between two words, but no space before an ellipsis that
+% appears before a punctuation mark such as a period, comma, etc.
+% Then there is the question of breaking or non-breaking space.  I
+% think it is odd to find an ellipsis at the beginning of a line, so
+% normally I would enter text like this: |uh~\dots\ oh|.  If setting
+% text in narrow columns you may prefer to allow line breaks before
+% the ellipsis as well as after.  Before punctuation, you would enter
+% ellipses without a space before or after, like so: 
+% |one, two, three\dots, ten\dots.|  Note, however, that some
+% publishers do not like to see an ellipsis combined with a period or
+% comma, and would rather a simple ellipsis at the end of a sentence
+% and so forth.
+% 
+% One problem with using the |\dots| command is that it does not take
+% an argument.  So there is no brace to terminate it, and if you want
+% a space to follow the ellipsis, you need to take care that it does
+% not disappear, and so to write it like this:
+% |\dots\|\textvisiblespace\ or |{\dots}|\textvisiblespace\ or
+% |\dots{}|\textvisiblespace.  If you forget to do this, the space
+% will disappear, gobbled up by the macro.  I frequently find myself
+% making this mistake, so I have added another option to help with
+% it. \DescribeMacro{xspace} If you pass the option |xspace| to
+% \textsf{ellipsis.sty}, an |\xspace| macro will be added after every
+% |\dots| macro.  See the \emph{\LaTeX\ Companion} for full
+% information on that package, but in short, it adds a space except
+% when followed by certain punctuation characters (a superset of the
+% |\ellipsispunctuation| list mentioned above).  So you automatically
+% get space after the ellipsis, unless it is immediately followed by
+% punctuation, even if you write it like this:
+% |one~\dots|\textvisiblespace|two|.  If there are a few places where
+% you don't want a space after |\dots|, then write it like this:
+% |\dots{}|, and the space will be suppressed.
+% 
+% \DescribeMacro{\ellipsisgap} 
+% You may wish to redefine the command |\ellipsisgap|, which is the
+% space between the dots of the ellipsis.  If you do this, you must do
+% it in your preamble, \emph{after} the |\usepackage| line.  The
+% default value is the interword stretch of the current font, which is
+% the normal \LaTeX\ definition.  If you are using a font other than
+% Computer Modern and if you are obsessive, you might wish to examine
+% the ellipsis that the font designer included in your font and
+% recreate it by defining the |\ellipsisgap| to an appropriate value,
+% like so:
+% \begin{verbatim}
+% \usepackage{ellipsis} 
+% This value seems right for the native ellipsis in Adobe Caslon: 
+% \renewcommand{\ellipsisgap}{0.1em}
+% \end{verbatim} 
+% You should probably define this in font-size dependent units, such
+% as the em.  See Bringhurst (loc.\ cit.) for further thoughts on the
+% construction of ellipses.
+%
+% \section{Compatibility}
+%
+% It was mentioned above that if certain punctuation characters are
+% made active, it will interfere with the ability of this package to
+% recognize them.  One important example of that practice is in the
+% French option of Babel, which makes certain `double punctuation'
+% characters active, in order to put a bit of space before them.  In
+% this particular case, however, you do \emph{not} want to redefine
+% the |\ellipsispunctuation| list to make this package aware of these
+% characters.  If you were to do so, extra kerning would be added
+% after an ellipsis in addition to thin space before the following
+% punctuation, resulting in about twice as much space as needed.  If
+% you leave the default value of |\ellipsispunctuation|, then these
+% active characters will not be recognized, and no extra kern will be
+% added.  Instead, the ellipsis will be separated from any following
+% double punctuation by a thin space.  This may not be quite the same
+% as the space between dots of the ellipsis, but it may be close
+% enough that no one will notice the difference.  In any case, that's
+% what French Babel does.
+%
+% Whether Babel is here following some sophisticated French
+% typographical rule, or it's just a fudge, I don't know.  Because
+% Babel French removes the extra space from after |\dots|, but only
+% adds space before `double punctuation', there is no space between an
+% ellipsis and `single punctuation', which looks ugly to my
+% (non-French) eyes.  In these cases, using |ellipsis.sty| will add
+% the extra space whereas French Babel on its own does not.  This may
+% be the wrong thing to do; if you are typesetting a text in French,
+% you should familiarize yourself with the relevant norms, and
+% possibly refrain from using this package.  I have not familiarized
+% myself with the rules for typesetting ellipses in languages other
+% than English.  If you are loading the French option of Babel because
+% you are quoting French text in a document whose main language is not
+% French, then you should not worry about these issues.  Because
+% French Babel wants to redefine |\dots|, you must load |ellipsis.sty|
+% \emph{after} Babel if you are using the French option (even if you
+% have no French text in your document).
+%
+% The Spanish option of Babel has its own way of setting an
+% ellipsis,but it uses a different command (|\...|), so that doesn't
+% interfere with the working of this package.
+%
+% \StopEventually{\PrintChanges}
+%
+% \section{Implementation}
+%
+% \begin{macro}{\ellipsisgap}
+% Set the amount of space to put between the dots of the ellipse.
+% Defaults to the standard \LaTeX\ amount.
+%    \begin{macrocode}
+\newcommand{\ellipsisgap}{\fontdimen3\font}
+\DeclareOption{chicago}{\renewcommand{\ellipsisgap}{\fontdimen2\font}}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ellipsis@before}
+% \begin{macro}{\ellipsis@after}
+% We provide the hooks \cs{ellipsis@before} and \cs{ellipsis@after} to
+% allow the production of automatically bracketed ellipses.  
+% 
+% \DescribeMacro{mla}
+% The \textsf{mla} package option sets these so as to produce ellipses
+% like this: [...]  If you do this, you never want the extra space
+% after the ellipsis, so we set \cs{ellipsis@alwayscentertrue}
+%    \begin{macrocode}
+\newcommand{\ellipsis@before}{}
+\newcommand{\ellipsis@after}{}
+\newif\ifellipsis@alwayscenter
+\ellipsis@alwayscenterfalse
+\DeclareOption{mla}{%
+  \renewcommand{\ellipsis@before}{[\kern\ellipsisgap}%
+  \renewcommand{\ellipsis@after}{\kern\ellipsisgap ]}
+  \ellipsis@alwayscentertrue}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\ellipsis@xspace}
+% Append |\xspace| if the |xspace| option is set.
+%    \begin{macrocode}
+\newcommand\ellipsis@xspace{}
+\DeclareOption{xspace}{%
+  \renewcommand{\ellipsis@xspace}{\xspace}}
+\ProcessOptions\relax
+\RequirePackage{xspace}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ellipsis@default}
+% This is the LaTeX default definition, which is necessary to use
+% when punctuation such as .,:;!? follows.
+%    \begin{macrocode}
+\newcommand{\ellipsis@default}{%
+  \ellipsis@before 
+  .\kern\ellipsisgap
+  .\kern\ellipsisgap
+  .\kern\ellipsisgap
+  \ellipsis@after\relax}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ellipsis@centered}
+% This is our new ellipsis \emph{without} the extra space after it.
+%    \begin{macrocode}
+\newcommand{\ellipsis@centered}{%
+  \ellipsis@before
+  .\kern\ellipsisgap
+  .\kern\ellipsisgap
+  .\ellipsis@after\relax}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ellipsispunctuation}
+%   Here we define the list of punctuation marks before which we want
+%   to put \cs{ellipsis@spacing} space.  This may be redefined by the
+%   user if desired.  If you load a package that changes the
+%   \cs{catcode} of a character in this list, such as a language
+%   package that makes one of them active, and you want the extra
+%   kerning to be added in front of those characters, then you `must
+%   then explicitly reset the list.  Otherwise the changed character
+%   will no longer be recognized.'  (quote from \textsf{ltfntcmd.dtx})
+%   In such a case, just repeat the line below, substituting
+%   \cs{renewcommand} for \cs{newcommand}.
+%    \begin{macrocode}
+\newcommand\ellipsispunctuation{,.:;!?}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\textellipsis}
+% This is the new definition for an ellipsis which looks ahead: if the
+% next char is in |\ellipsispunctuation| use |\default@ellipsis|, else
+% use our new |\center@ellipsis|.
+%
+% This is the auxiliary code that scans through the list of punctuation.
+%
+%    \begin{macrocode}
+\def\ellipsis@scan{\expandafter\ellipsis@scan@aux\ellipsispunctuation\ellipsis@delim}
+\def\ellipsis@scan@aux #1#2\ellipsis@delim{%
+  \let\ellipsis@one=#1%   the first char
+  \def\ellipsis@two{#2}%   the remainder of the string
+  \ifx\ellipsis@token\ellipsis@one
+    \ellipsis@default
+  \else   
+    \ifx\ellipsis@two\empty
+      \ellipsis@centered
+    \else
+      \ellipsis@scan@aux #2\ellipsis@delim
+    \fi
+  \fi}
+%    \end{macrocode}
+%
+% Here is the macro that looks ahead at the next token, put it in
+% \cs{ellipsis@token}, and invokes the code to scan for it in the
+% punctuation list.
+%
+%    \begin{macrocode}
+\renewcommand{\textellipsis}{\futurelet\ellipsis@token\@textellipsis}
+\def\@textellipsis{%
+  \ifellipsis@alwayscenter\ellipsis@centered\else
+    \ellipsis@scan%
+  \fi\ellipsis@xspace}%
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\dots}
+%   Here we redefine the standard \LaTeX\ command to use our new
+%   definition. (the |\expandafter| needs to be added to make
+%   lookahead work).  The only reason this must be done at the
+%   beginning of the document is that the French option of Babel
+%   unpleasantly redefines |\dots| at the beginning of the document,
+%   and so we have to override it again -- and this is true even if
+%   you never use any French text in your document.  We need to throw
+%   an error in the case where French Babel is loaded after us,
+%   because its AtBeginDocument hook is about to clobber our
+%   definition of |\dots|.
+%    \begin{macrocode}
+\ifx\bbl@frenchdots\@undefined\else\def\ellipsis@frenchloaded{\relax}\fi
+\AtBeginDocument{%
+    \ifx\ellipsis@frenchloaded\@undefined
+      \ifx\bbl@frenchdots\@undefined\else
+        \PackageError{ellipsis}{Babel French loaded after ellipsis.sty}%
+          {If you load Babel with the French option, do it before ellipsis.sty}%
+       \fi
+     \fi
+     \DeclareRobustCommand{\dots}{%
+       \ifmmode\mathellipsis\else\expandafter\textellipsis\fi}}
+%    \end{macrocode}
+% \end{macro}
+% 
+% \begin{macro}{\midwordellipsis}
+% An extra command: this may be useful for the rare time when you want
+% an ellipsis in the very middle of a word or whenever you just want a
+% small bit of space (the intra-ellipsis spacing) before and after the
+% ellipsis.
+%    \begin{macrocode}
+\DeclareRobustCommand{\midwordellipsis}{%
+    \kern\ellipsisgap
+   .\kern\ellipsisgap
+   .\kern\ellipsisgap
+   .\kern\ellipsisgap\relax}
+%    \end{macrocode}
+% \end{macro}
+%
+% \Finale
+\endinput