summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ellipsis/ellipsis.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/ellipsis/ellipsis.dtx')
-rw-r--r--macros/latex/contrib/ellipsis/ellipsis.dtx371
1 files changed, 186 insertions, 185 deletions
diff --git a/macros/latex/contrib/ellipsis/ellipsis.dtx b/macros/latex/contrib/ellipsis/ellipsis.dtx
index 4db66a1410..42462ab2a2 100644
--- a/macros/latex/contrib/ellipsis/ellipsis.dtx
+++ b/macros/latex/contrib/ellipsis/ellipsis.dtx
@@ -1,8 +1,8 @@
% \iffalse meta-comment
%
-% Copyright (C) 2003 by Peter J. Heslin <p.j.heslin@dur.ac.uk>
+% Copyright (C) 2003-20 by Peter Heslin <pheslin@gmail.com>
% --------------------------------------------------
-%
+%
% 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
@@ -18,12 +18,12 @@
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{ellipsis}
-%<package> [2004/9/28 v1.6 ellipsis: fixes spacing around \dots]
+%<package> [2020/5/22 v1.7 ellipsis: fixes spacing around \dots]
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{ellipsis}
-\EnableCrossrefs
+\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
@@ -32,7 +32,7 @@
%</driver>
% \fi
%
-% \CheckSum{135}
+% \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
@@ -65,198 +65,189 @@
% 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.}
%
% \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.}}
+% and bugfixes 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.
-%
+% 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 |\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
+% |\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 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 they 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 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
+% 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} or \textsf{xellipsis} 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 .,:;!?
+% 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 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,
+%
+% 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:
+% \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.
+% \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.
+% 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}
%
@@ -274,8 +265,8 @@
% \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.
-%
+% 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
@@ -309,22 +300,22 @@
% when punctuation such as .,:;!? follows.
% \begin{macrocode}
\newcommand{\ellipsis@default}{%
- \ellipsis@before
- .\kern\ellipsisgap
+ \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.
+% 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}
+ .\@\ellipsis@after\relax}
% \end{macrocode}
% \end{macro}
%
@@ -338,7 +329,8 @@
% 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}.
+% \cs{renewcommand} for \cs{newcommand}, and putting it after
+% |\begin{document}|
% \begin{macrocode}
\newcommand\ellipsispunctuation{,.:;!?}
% \end{macrocode}
@@ -358,7 +350,7 @@
\def\ellipsis@two{#2}% the remainder of the string
\ifx\ellipsis@token\ellipsis@one
\ellipsis@default
- \else
+ \else
\ifx\ellipsis@two\empty
\ellipsis@centered
\else
@@ -377,6 +369,7 @@
\ifellipsis@alwayscenter\ellipsis@centered\else
\ellipsis@scan%
\fi\ellipsis@xspace}%
+\DeclareRobustCommand\textellipsis {\futurelet\ellipsis@token\@textellipsis}
% \end{macrocode}
% \end{macro}
%
@@ -398,13 +391,21 @@
\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}}
+ \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
@@ -415,7 +416,7 @@
\kern\ellipsisgap
.\kern\ellipsisgap
.\kern\ellipsisgap
- .\kern\ellipsisgap\relax}
+ .\@\kern\ellipsisgap\relax}
% \end{macrocode}
% \end{macro}
%