diff options
Diffstat (limited to 'Master/texmf-dist/source/latex')
| -rw-r--r-- | Master/texmf-dist/source/latex/ellipsis/ellipsis.dtx | 371 |
1 files changed, 186 insertions, 185 deletions
diff --git a/Master/texmf-dist/source/latex/ellipsis/ellipsis.dtx b/Master/texmf-dist/source/latex/ellipsis/ellipsis.dtx index 4db66a1410b..42462ab2a25 100644 --- a/Master/texmf-dist/source/latex/ellipsis/ellipsis.dtx +++ b/Master/texmf-dist/source/latex/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} % |