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