Debian Codegraph @

texmf-dist/source/latex/ellipsis/ellipsis.dtx

raw
1 % \iffalse meta-comment
2 %<*package>
3 %%
4 %% Copyright (C) 2003-2020 by Peter Heslin <[email protected]>
5 %% ---------------------------------------------------------------------
6 %%
7 %% This work may be distributed and/or modified under the conditions
8 %% of the LaTeX Project Public License, version 1.3c of the license
9 %% or (at your option) any later version. The latest version of this
10 %% license is in:
11 %%
12 %% http://www.latex-project.org/lppl.txt
13 %%
14 %% and version 1.3c or later is part of all distributions of
15 %% LaTeX version 2005/12/01 or later.
16 %%
17 %% This work has the LPPL maintenance status "author-maintained".
18 %%
19 %% The current maintainer and author of this work is Peter Heslin.
20 %%
21 %</package>
22 % \fi
23 %
24 % \iffalse
25 %<*batch>
26 \ifx\documentclass\undefined
27
28 \input docstrip.tex
29 \keepsilent
30 \askforoverwritefalse
31 \usedir{tex/latex/ellipsis}
32
33 \preamble
34
35 ellipsis -- fixes spacing around ellipses (three dots)
36
37 \endpreamble
38
39 \generate{\file{ellipsis.sty}{\from{ellipsis.dtx}{package}}}
40
41 \obeyspaces
42 \Msg{*************************************************************}
43 \Msg{* *}
44 \Msg{* To finish the installation you have to move the following *}
45 \Msg{* file into a directory searched by TeX: *}
46 \Msg{* *}
47 \Msg{* ellipsis.sty *}
48 \Msg{* *}
49 \Msg{* To produce the documentation run the file ellipsis.dtx *}
50 \Msg{* through LaTeX. *}
51 \Msg{* *}
52 \Msg{* Happy TeXing! *}
53 \Msg{* *}
54 \Msg{*************************************************************}
55
56 \else
57
58 \let\endbatchfile\relax
59
60 \fi
61 \endbatchfile
62 %</batch>
63 % \fi
64 %
65 % \iffalse
66 %<package>\NeedsTeXFormat{LaTeX2e}
67 %<*driver>
68 \ifx\ProvidesFile\undefined\def\ProvidesFile#1[#2]{}\fi
69 \ProvidesFile{ellipsis.dtx}%
70 %</driver>
71 %<package>\ProvidesPackage{ellipsis}%
72 [2020/05/22 v1.8 fixes spacing around ellipses (three dots)]
73 %<*driver>
74 \documentclass{ltxdoc}
75 \usepackage{ellipsis}
76 \EnableCrossrefs
77 \CodelineIndex
78 \RecordChanges
79 \begin{document}
80 \DocInput{ellipsis.dtx}
81 \end{document}
82 %</driver>
83 % \fi
84 %
85 % \CheckSum{153}
86 %
87 % \CharacterTable
88 % {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
89 % 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
90 % Digits \0\1\2\3\4\5\6\7\8\9
91 % Exclamation \! Double quote \" Hash (number) \#
92 % Dollar \$ Percent \% Ampersand \&
93 % Acute accent \' Left paren \( Right paren \)
94 % Asterisk \* Plus \+ Comma \,
95 % Minus \- Point \. Solidus \/
96 % Colon \: Semicolon \; Less than \<
97 % Equals \= Greater than \> Question mark \?
98 % Commercial at \@ Left bracket \[ Backslash \\
99 % Right bracket \] Circumflex \^ Underscore \_
100 % Grave accent \` Left brace \{ Vertical bar \|
101 % Right brace \} Tilde \~}
102 %
103 %
104 % \changes{v1.0}{2003/09/30}{Initial version}
105 % \changes{v1.1}{2003/10/01}{Modelled definition of \cs{textellipsis}
106 % on \textsf{xspace.sty}, added chicago option}
107 % \changes{v1.2}{2003/10/2}{Added mla option, removed hard-coded list
108 % of punctuation in favor or a configurable list}
109 % \changes{v1.3}{2003/10/3}{Removed \@ to make \cs{ellipsisspacing}
110 % and \cs{ellipsispunctuation} user configurable. Changed
111 % \cs{ellipsisspacing} from a length to a command to make em pick up
112 % the font size when it is used, rather than when it is defined}
113 % \changes{v1.4}{2003/10/4}{Changed \cs{ellipsisspacing} to
114 % \cs{ellipsisgap} for readability, added \cs{relax} to prevent spaces
115 % from being gobbled.}
116 % \changes{v1.5}{2004/9/24}{Added the xspace option.}
117 % \changes{v1.6}{2004/9/28}{Fixed incompatibility with French Babel.}
118 % \changes{v1.7}{2020/5/22}{Fixed incompatilbility with amsmath; fixed fragile
119 % command; fixed spacing when \cs{nofrenchspacing}; all fixes thanks to Frank
120 % Mittelbach. Added ref to xellipsis package.}
121 % \changes{v1.8}{2004/9/28}{Code cleanups contributed by Falk Hanisch.}
122 %
123 % \GetFileInfo{ellipsis.sty}
124 %
125 % \title{The \textsf{ellipsis} package\thanks{This document
126 % corresponds to \textsf{ellipsis}~\fileversion, dated \filedate.
127 % Many thanks to Frank Mittelbach, who made numerous suggestions
128 % and bugfixes that greatly improved this package.}}
129 % \author{^^A
130 % Peter J. Heslin\\^^A
131 % \texttt{[email protected]}\\^^A
132 % \texttt{https://github.com/pjheslin/ellipsis}}
133 %
134 % \maketitle
135 %
136 % \section{Introduction}
137 %
138 % There is an unevenness in the way \LaTeX\ puts space around ellipses (|\dots|)
139 % in text mode. This package attempts to fix that bug, and this documentation
140 % offers an explanation of the bug and offers advice on how to use ellipses in
141 % your text. This document does not offer guidance on the use of ellipses in
142 % mathematical formulas or non-English language text.
143 %
144 % The standard definition of |\dots| in \LaTeX\ takes the inter-word stretch for
145 % the current font and puts that amount of space in between three normal dots;
146 % it then also adds that amount of space \emph{after} the final dot. The
147 % documentation of the \LaTeX\ code acknowledges that this is a `kludge' in that
148 % the interword stretch is being used for a purpose it was not meant for. There
149 % is another problem with this definition, however: the extra space after the
150 % final dot of the ellipsis. There is always more space after the ellipsis
151 % than before it, so that it is not properly centered between the text on either
152 % side.
153 %
154 % That extra space is there for a good reason. When the ellipsis is followed by
155 % another dot, as at the end of a sentence, it is important that all four dots
156 % should be evenly spaced, otherwise the final dot is much closer than the
157 % others and the result is hideous. The same holds true for commas, exclamation
158 % marks and other punctuation on the baseline. So the extra space is necessary
159 % when an ellipsis is followed by certain punctuation characters, and the bug
160 % consists in the fact that \LaTeX\ always adds it, regardless of what text
161 % follows.
162 %
163 % This package implements a simple fix. It redefines the commands |\dots| and
164 % |\textellipsis| so that they can look ahead at the next character and change
165 % their behavior accordingly: if the next character is one of \texttt{.,;:?!}
166 % the extra space is added, if not, no extra space is added (if you load a
167 % package that makes any of these characters active, you may want to reload
168 % this list; see the section below on see below on |\ellipsispunctuation| and
169 % compatibility). This particular list of punctuation marks was not chosen
170 % arbitrarily: it includes all marks with a dot on the baseline (or a comma,
171 % which is like a dot with a tail). These marks produce a series of four dots
172 % which must be spaced evenly~-- no other punctuation mark would normally
173 % benefit from having the extra space added.
174 %
175 % The solution can be brittle~-- for example, if you write |\dots{}.| then the
176 % extra space will \emph{not} be added, since the braces come between the
177 % command and the dot; the result will be very ugly. The solution to this is to
178 % enter ellipses carefully and consistently in your source text. If you use
179 % ellipses as recommended below, then the potential problem of evenly spacing an
180 % ellipsis that comes immediately after a baseline punctuation mark does not
181 % arise, since that combination of characters will not normally be used.
182 %
183 % There are two other packages, \textsf{lips} and \textsf{xellipsis}, that
184 % address the problem of text ellipses in \LaTeX. The former strictly follows
185 % the advice of the \emph{Chicago Manual of Style} in putting full word spaces
186 % between the dots of the ellipsis, and does not provide the possibility of more
187 % a tightly set ellipsis like the normal \LaTeX\ default. It also imposes its
188 % own set of rules for the spacing before and after an ellipsis. The latter
189 % offers more flexibility, but also tends to prefer the Chicago/MLA style. The
190 % Chicago and MLA manuals are good guides for preparing a typescript that will
191 % be typeset by someone else; but for fine typography, they are the wrong
192 % authorities to follow.
193 %
194 % Traditional typographers firmly reject the Chicago style of setting ellipses,
195 % and rightly so; see Jan Tschichold, \emph{The Form of the Book: Essays on the
196 % Morality of Good Design} (Hartley \& Marks, 1991), pp~130f, or Robert
197 % Bringhurst, \emph{The Elements of Typographic Style}
198 % (2\textsuperscript{nd}~ed, Hartley \& Marks, 1997) pp~82f.
199 %
200 % \DescribeMacro{chicago} If you nevertheless want or have to use the
201 % Chicago-style, widely spaced ellipsis with this package, you can pass it the
202 % package option |chicago|. \DescribeMacro{mla} There is also package option
203 % |mla|, modeled on the same feature of \textsf{lips.sty}, which automatically
204 % puts square brackets around all ellipses. If, on the other hand, you want to
205 % adhere to the full recommendations of the Chicago manual, then you should
206 % consider using \textsf{lips} or \textsf{xellipsis} instead of this package.
207 %
208 % In conclusion, the best solution to the problem of typesetting ellipses is not
209 % to use this package at all, but to use XeTeX. You can put the Unicode
210 % character for ``horizontal ellipsis'' into your source, and use a font with a
211 % precomposed ellipsis glyph. If you use a professional-quality OpenType font,
212 % it will have an ellipsis glyph created by the type designer to fit with the
213 % typeface and with proper kerning for punctuation afterward. Not all fonts do
214 % this, so make sure that the ellipsis character kerns properly with
215 % \texttt{.,;:?!} following.
216 %
217 % \section{Usage}
218 %
219 % Install the package and put |\usepackage{ellipsis}| in your preamble. As
220 % noted above, you should be consistent in the way you enter ellipses in your
221 % text. For English text, Bringhurst (loc.\ cit.) recommends putting a space
222 % before and after an ellipsis that appears between two words, but no space
223 % before an ellipsis that appears before a punctuation mark such as a period,
224 % comma, etc. Then there is the question of breaking or non-breaking space. I
225 % think it is odd to find an ellipsis at the beginning of a line, so normally I
226 % would enter text like this: |uh~\dots\ oh|. If setting text in narrow columns
227 % you may prefer to allow line breaks before the ellipsis as well as after.
228 % Before punctuation, you would enter ellipses without a space before or after,
229 % like so: |one, two, three\dots, ten\dots.| Note, however, that some
230 % publishers do not like to see an ellipsis combined with a period or comma, and
231 % would rather a simple ellipsis at the end of a sentence and so forth.
232 %
233 % One problem with using the |\dots| command is that it does not take an
234 % argument. So there is no brace to terminate it, and if you want a space to
235 % follow the ellipsis, you need to take care that it does not disappear, and so
236 % to write it like this: |\dots\|\textvisiblespace\ or
237 % |{\dots}|\textvisiblespace\ or |\dots{}|\textvisiblespace. If you forget to
238 % do this, the space will disappear, gobbled up by the macro. I frequently find
239 % myself making this mistake, so I have added another option to help with it.
240 % \DescribeMacro{xspace} If you pass the option |xspace| to
241 % \textsf{ellipsis.sty}, an |\xspace| macro will be added after every |\dots|
242 % macro. See the \emph{\LaTeX\ Companion} for full information on that package,
243 % but in short, it adds a space except when followed by certain punctuation
244 % characters (a superset of the |\ellipsispunctuation| list mentioned above).
245 % So you automatically get space after the ellipsis, unless it is immediately
246 % followed by punctuation, even if you write it like this:
247 % |one~\dots|\textvisiblespace|two|. If there are a few places where you don't
248 % want a space after |\dots|, then write it like this: |\dots{}|, and the space
249 % will be suppressed.
250 %
251 % \DescribeMacro{\ellipsisgap}
252 % You may wish to redefine the command |\ellipsisgap|, which is the space
253 % between the dots of the ellipsis. If you do this, you must do it in your
254 % preamble, \emph{after} the |\usepackage| line. The default value is the
255 % interword stretch of the current font, which is the normal \LaTeX\ definition.
256 % If you are using a font other than Computer Modern and if you are obsessive,
257 % you might wish to examine the ellipsis that the font designer included in your
258 % font and recreate it by defining the |\ellipsisgap| to an appropriate value,
259 % like so:
260 % \begin{verbatim}
261 % \usepackage{ellipsis}
262 % This value seems right for the native ellipsis in Adobe Caslon:
263 % \renewcommand{\ellipsisgap}{0.1em}
264 % \end{verbatim}
265 % You should probably define this in font-size dependent units, such as the em.
266 % See Bringhurst (loc.\ cit.) for further thoughts on the construction of
267 % ellipses.
268 %
269 % \section{Compatibility}
270 %
271 % It was mentioned above that if certain punctuation characters are made active,
272 % it will interfere with the ability of this package to recognize them. One
273 % important example of that practice is in the French option of Babel, which
274 % makes certain `double punctuation' characters active, in order to put a bit of
275 % space before them. In this particular case, however, you do \emph{not} want
276 % to redefine the |\ellipsispunctuation| list to make this package aware of
277 % these characters. If you were to do so, extra kerning would be added after an
278 % ellipsis in addition to thin space before the following punctuation, resulting
279 % in about twice as much space as needed. If you leave the default value of
280 % |\ellipsispunctuation|, then these active characters will not be recognized,
281 % and no extra kern will be added. Instead, the ellipsis will be separated from
282 % any following double punctuation by a thin space. This may not be quite the
283 % same as the space between dots of the ellipsis, but it may be close enough
284 % that no one will notice the difference. In any case, that's what French Babel
285 % does.
286 %
287 % Whether Babel is here following some sophisticated French typographical rule,
288 % or it's just a fudge, I don't know. Because Babel French removes the extra
289 % space from after |\dots|, but only adds space before `double punctuation',
290 % there is no space between an ellipsis and `single punctuation', which looks
291 % ugly to my (non-French) eyes. In these cases, using |ellipsis.sty| will add
292 % the extra space whereas French Babel on its own does not. This may be the
293 % wrong thing to do; if you are typesetting a text in French, you should
294 % familiarize yourself with the relevant norms, and possibly refrain from using
295 % this package. If you are loading the French option of Babel because you are
296 % quoting French text in a document whose main language is not French, then you
297 % should not worry about these issues. Because French Babel wants to redefine
298 % |\dots|, you must load |ellipsis.sty| \emph{after} Babel if you are using the
299 % French option (even if you have no French text in your document).
300 %
301 % The Spanish option of Babel has its own way of setting an ellipsis,but it uses
302 % a different command (|\...|), so that doesn't interfere with the working of
303 % this package.
304 %
305 % \StopEventually{\PrintChanges}
306 %
307 % \section{Implementation}
308 %
309 % \begin{macro}{\ellipsisgap}
310 % Set the amount of space to put between the dots of the ellipse.
311 % Defaults to the standard \LaTeX\ amount.
312 % \begin{macrocode}
313 \newcommand{\ellipsisgap}{\fontdimen3\font}
314 \DeclareOption{chicago}{\renewcommand{\ellipsisgap}{\fontdimen2\font}}
315 % \end{macrocode}
316 % \end{macro}
317 %
318 % \begin{macro}{\ellipsis@before}
319 % \begin{macro}{\ellipsis@after}
320 % We provide the hooks \cs{ellipsis@before} and \cs{ellipsis@after} to
321 % allow the production of automatically bracketed ellipses.
322 %
323 % \DescribeMacro{mla}
324 % The \textsf{mla} package option sets these so as to produce ellipses
325 % like this: [...] If you do this, you never want the extra space
326 % after the ellipsis, so we set \cs{ellipsis@alwayscentertrue}
327 % \begin{macrocode}
328 \newcommand{\ellipsis@before}{}
329 \newcommand{\ellipsis@after}{}
330 \newif\ifellipsis@alwayscenter
331 \ellipsis@alwayscenterfalse
332 \DeclareOption{mla}{%
333 \renewcommand{\ellipsis@before}{[\kern\ellipsisgap}%
334 \renewcommand{\ellipsis@after}{\kern\ellipsisgap ]}
335 \ellipsis@alwayscentertrue}
336 % \end{macrocode}
337 % \end{macro}
338 % \end{macro}
339 %
340 % \begin{macro}{\ellipsis@xspace}
341 % Append |\xspace| if the |xspace| option is set.
342 % \begin{macrocode}
343 \newcommand\ellipsis@xspace{}
344 \DeclareOption{xspace}{%
345 \renewcommand{\ellipsis@xspace}{\xspace}}
346 \ProcessOptions\relax
347 \RequirePackage{xspace}
348 % \end{macrocode}
349 % \end{macro}
350 %
351 % \begin{macro}{\ellipsis@default}
352 % This is the LaTeX default definition, which is necessary to use
353 % when punctuation such as \texttt{.,;:?!} follows.
354 % \begin{macrocode}
355 \newcommand{\ellipsis@default}{%
356 \ellipsis@before
357 .\kern\ellipsisgap
358 .\kern\ellipsisgap
359 .\@\kern\ellipsisgap
360 \ellipsis@after\relax}
361 % \end{macrocode}
362 % \end{macro}
363 %
364 % \begin{macro}{\ellipsis@centered}
365 % This is our new ellipsis \emph{without} the extra space after it.
366 % \begin{macrocode}
367 \newcommand{\ellipsis@centered}{%
368 \ellipsis@before
369 .\kern\ellipsisgap
370 .\kern\ellipsisgap
371 .\@\ellipsis@after\relax}
372 % \end{macrocode}
373 % \end{macro}
374 %
375 % \begin{macro}{\ellipsispunctuation}
376 % Here we define the list of punctuation marks before which we want
377 % to put \cs{ellipsis@spacing} space. This may be redefined by the
378 % user if desired. If you load a package that changes the
379 % \cs{catcode} of a character in this list, such as a language
380 % package that makes one of them active, and you want the extra
381 % kerning to be added in front of those characters, then you `must
382 % then explicitly reset the list. Otherwise the changed character
383 % will no longer be recognized.' (quote from \textsf{ltfntcmd.dtx})
384 % In such a case, just repeat the line below, substituting
385 % \cs{renewcommand} for \cs{newcommand}, and putting it after
386 % |\begin{document}|
387 % \begin{macrocode}
388 \newcommand\ellipsispunctuation{,.:;!?}
389 % \end{macrocode}
390 % \end{macro}
391 %
392 % \begin{macro}{\textellipsis}
393 % This is the new definition for an ellipsis which looks ahead: if the
394 % next char is in |\ellipsispunctuation| use |\default@ellipsis|, else
395 % use our new |\center@ellipsis|.
396 %
397 % This is the auxiliary code that scans through the list of punctuation.
398 %
399 % \begin{macrocode}
400 \def\ellipsis@scan{\expandafter\ellipsis@scan@aux\ellipsispunctuation\ellipsis@delim}
401 \def\ellipsis@scan@aux #1#2\ellipsis@delim{%
402 \let\ellipsis@one=#1% the first char
403 \def\ellipsis@two{#2}% the remainder of the string
404 \ifx\ellipsis@token\ellipsis@one
405 \ellipsis@default
406 \else
407 \ifx\ellipsis@two\empty
408 \ellipsis@centered
409 \else
410 \ellipsis@scan@aux #2\ellipsis@delim
411 \fi
412 \fi}
413 % \end{macrocode}
414 %
415 % Here is the actual macro that looks ahead at the next token, stores it in
416 % \cs{ellipsis@token}, and invokes the code to scan for it in the
417 % punctuation list.
418 %
419 % \begin{macrocode}
420 \renewcommand{\textellipsis}{\futurelet\ellipsis@token\@textellipsis}
421 \def\@textellipsis{%
422 \ifellipsis@alwayscenter\ellipsis@centered\else
423 \ellipsis@scan%
424 \fi\ellipsis@xspace}%
425 \DeclareRobustCommand\textellipsis {\futurelet\ellipsis@token\@textellipsis}
426 % \end{macrocode}
427 % \end{macro}
428 %
429 % \begin{macro}{\dots}
430 % Here we redefine the standard \LaTeX\ command to use our new
431 % definition. (the |\expandafter| needs to be added to make
432 % lookahead work). The only reason this must be done at the
433 % beginning of the document is that the French option of Babel
434 % unpleasantly redefines |\dots| at the beginning of the document,
435 % and so we have to override it again -- and this is true even if
436 % you never use any French text in your document. We need to throw
437 % an error in the case where French Babel is loaded after us,
438 % because its AtBeginDocument hook is about to clobber our
439 % definition of |\dots|.
440 % \begin{macrocode}
441 \ifx\bbl@frenchdots\@undefined\else\def\ellipsis@frenchloaded{\relax}\fi
442 \AtBeginDocument{%
443 \ifx\ellipsis@frenchloaded\@undefined
444 \ifx\bbl@frenchdots\@undefined\else
445 \PackageError{ellipsis}{Babel French loaded after ellipsis.sty}%
446 {If you load Babel with the French option, do it before ellipsis.sty}%
447 \fi
448 \fi
449 \@ifpackageloaded{amsmath}%
450 {%
451 \DeclareRobustCommand\dots{%
452 \ifmmode \@xp \mdots@ \else \@xp \textellipsis \fi}%
453 }%
454 {%
455 \DeclareRobustCommand\dots{%
456 \ifmmode \mathellipsis \else \expandafter \textellipsis\fi}%
457 }%
458 }
459 % \end{macrocode}
460 % \end{macro}
461 %
462 % \begin{macro}{\midwordellipsis}
463 % An extra command: this may be useful for the rare time when you want
464 % an ellipsis in the very middle of a word or whenever you just want a
465 % small bit of space (the intra-ellipsis spacing) before and after the
466 % ellipsis.
467 % \begin{macrocode}
468 \DeclareRobustCommand{\midwordellipsis}{%
469 \kern\ellipsisgap
470 .\kern\ellipsisgap
471 .\kern\ellipsisgap
472 .\@\kern\ellipsisgap\relax}
473 % \end{macrocode}
474 % \end{macro}
475 %
476 % \Finale
477 \endinput