% \iffalse meta-comment % % Copyright (C) 2003 by Peter J. Heslin % -------------------------------------------------- % % 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 %\NeedsTeXFormat{LaTeX2e} %\ProvidesPackage{ellipsis} % [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} % % \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