summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/ellipsis/ellipsis.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-11 23:03:17 +0000
committerKarl Berry <karl@freefriends.org>2006-01-11 23:03:17 +0000
commitecf966f305f6aeff2bbdf42c82d8425921aa9eda (patch)
treedb606a57e3619610e4c35cae849d41cf4e0937d5 /Master/texmf-dist/source/latex/ellipsis/ellipsis.dtx
parentac3c55a3216b5988f0e48ba9414ddb059f19a699 (diff)
source 1
git-svn-id: svn://tug.org/texlive/trunk@105 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/ellipsis/ellipsis.dtx')
-rw-r--r--Master/texmf-dist/source/latex/ellipsis/ellipsis.dtx423
1 files changed, 423 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/ellipsis/ellipsis.dtx b/Master/texmf-dist/source/latex/ellipsis/ellipsis.dtx
new file mode 100644
index 00000000000..4db66a1410b
--- /dev/null
+++ b/Master/texmf-dist/source/latex/ellipsis/ellipsis.dtx
@@ -0,0 +1,423 @@
+% \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