path: root/Master/texmf-dist/source/latex/ellipsis/ellipsis.dtx

% \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