ellipsis.dtx

% \iffalse meta-comment
%<*package>
%%
%% Copyright (C) 2003-2020 by Peter Heslin <p.j.heslin@dur.ac.uk>
%% ---------------------------------------------------------------------
%%
%% This work may be distributed and/or modified under the conditions
%% of the LaTeX Project Public License, version 1.3c of the 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.3c or later is part of all distributions of
%% LaTeX version 2005/12/01 or later.
%%
%% This work has the LPPL maintenance status "author-maintained".
%%
%% The current maintainer and author of this work is Peter Heslin.
%%
%</package>
% \fi
%
% \iffalse
%<*batch>
\ifx\documentclass\undefined

\input docstrip.tex
\keepsilent
\askforoverwritefalse
\usedir{tex/latex/ellipsis}

\preamble

ellipsis -- fixes spacing around ellipses (three dots)

\endpreamble

\generate{\file{ellipsis.sty}{\from{ellipsis.dtx}{package}}}

\obeyspaces
\Msg{*************************************************************}
\Msg{*                                                           *}
\Msg{* To finish the installation you have to move the following *}
\Msg{* file into a directory searched by TeX:                    *}
\Msg{*                                                           *}
\Msg{*     ellipsis.sty                                          *}
\Msg{*                                                           *}
\Msg{* To produce the documentation run the file ellipsis.dtx    *}
\Msg{* through LaTeX.                                            *}
\Msg{*                                                           *}
\Msg{* Happy TeXing!                                             *}
\Msg{*                                                           *}
\Msg{*************************************************************}

\else

\let\endbatchfile\relax

\fi
\endbatchfile
%</batch>
% \fi
%
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}
%<*driver>
\ifx\ProvidesFile\undefined\def\ProvidesFile#1[#2]{}\fi
\ProvidesFile{ellipsis.dtx}%
%</driver>
%<package>\ProvidesPackage{ellipsis}%
  [2020/05/22 v1.8 fixes spacing around ellipses (three dots)]
%<*driver>
\documentclass{ltxdoc}
\usepackage{ellipsis}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{ellipsis.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{153}
%
% \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.}
% \changes{v1.7}{2020/5/22}{Fixed incompatilbility with amsmath; fixed fragile
% command; fixed spacing when \cs{nofrenchspacing}; all fixes thanks to Frank
% Mittelbach. Added ref to xellipsis package.}
% \changes{v1.8}{2004/9/28}{Code cleanups contributed by Falk Hanisch.}
%
% \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
%   and bugfixes that greatly improved this package.}}
% \author{^^A
%   Peter J. Heslin\\^^A
%   \texttt{p.j.heslin@dur.ac.uk}\\^^A
%   \texttt{https://github.com/pjheslin/ellipsis}}
%
% \maketitle
%
% \section{Introduction}
%
% There is an unevenness in the way \LaTeX\ puts space around ellipses (|\dots|)
% in text mode.  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 does not offer 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.  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 commands |\dots| and
% |\textellipsis| so that they can look ahead at the next character and change
% their behavior accordingly: if the next character is one of \texttt{.,;:?!}
% 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 are two other packages, \textsf{lips} and \textsf{xellipsis}, that
% address the problem of text ellipses in \LaTeX.  The former 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 also imposes its
% own set of rules for the spacing before and after an ellipsis.  The latter
% offers more flexibility, but also tends to prefer the Chicago/MLA style.  The
% Chicago and MLA manuals are good guides for preparing a typescript that will
% be typeset by someone else; but for fine typography, they are the wrong
% authorities to follow.
%
% Traditional typographers 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
% package option |chicago|. \DescribeMacro{mla} There is also package option
% |mla|, modeled on the same feature of \textsf{lips.sty}, which automatically
% puts square brackets around all ellipses. If, on the other hand, you want to
% adhere to the full recommendations of the Chicago manual, then you should
% consider using \textsf{lips} or \textsf{xellipsis} instead of this package.
%
% In conclusion, the best solution to the problem of typesetting ellipses is not
% to use this package at all, but to use XeTeX.  You can put the Unicode
% character for ``horizontal ellipsis'' into your source, and use a font with a
% precomposed ellipsis glyph.  If you use a professional-quality OpenType font,
% it will have an ellipsis glyph created by the type designer to fit with the
% typeface and with proper kerning for punctuation afterward.  Not all fonts do
% this, so make sure that the ellipsis character kerns properly with
% \texttt{.,;:?!} 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.  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 \texttt{.,;:?!} 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}, and putting it after
%   |\begin{document}|
%    \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 actual macro that looks ahead at the next token, stores 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}%
\DeclareRobustCommand\textellipsis {\futurelet\ellipsis@token\@textellipsis}
%    \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
  \@ifpackageloaded{amsmath}%
    {%
      \DeclareRobustCommand\dots{%
        \ifmmode \@xp \mdots@ \else \@xp \textellipsis \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