Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % File: xpunctuate.dtx
4 %
5 % Copyright (C) 2023 by Philip G. Ratcliffe <[email protected]>
6 %
7 % It may be distributed and/or modified under the conditions of the
8 % LaTeX Project Public License (LPPL), either version 1.3c of this
9 % license or (at your option) any later version.
10 % The latest version of this license is in the file
11 %
12 % http://www.latex-project.org/lppl.txt
13 %
14 % This file is part of the "xpunctuate package" (the Work in LPPL)
15 % and all files in that package must be distributed together.
16 %
17 % The released version of this package is available from CTAN.
18 %
19 % This package has the LPPL maintenance status "maintained".
20 %
21 % The current maintainer of this package is Philip G. Ratcliffe.
22 %
23 % This work consists of the files xpunctuate.dtx and xpunctuate.ins
24 % and the derived file xpunctuate.sty.
25 %
26 % \fi
27 %
28 % \iffalse
29 %
30 %<package>\NeedsTeXFormat{LaTeX2e}[2020/10/01]
31 %<package>\ProvidesPackage{xpunctuate}
32 %<package> [2023/08/13 v2.0 punctuation after command names (PGR)]
33 %
34 %<*driver>
35 \documentclass[british]{ltxdoc}
36 \usepackage{xpunctuate}
37 %
38 \NewDocElement[macrolike=false]{Generic}{generic}
39 \renewcommand\thefootnote{\color{red}{\emph{\alph{footnote}}}}
40 \newenvironment{codelist}
41 {\begin{list}{}{\setlength\leftmargin{3em}}\item[]}{\end{list}}
42 \newcommand\eg{\xperiodafter{\emph{e}.\emph{g}}}
43 \newcommand\ie{\xperiodafter{\emph{i}.\emph{e}}}
44 %
45 \CodelineIndex
46 \EnableCrossrefs
47 \RecordChanges
48 \DoNotIndex{\def,\let,\futurelet}
49 \DoNotIndex{\if,\else,\fi,\ifx,\fi,\iftrue,\fi,\iffalse,\fi}
50 \DoNotIndex{\the,\csname,\endcsname,\expandafter,\noexpand,\protect}
51 %
52 \begin{document}
53 \DocInput{xpunctuate.dtx}
54 \end{document}
55 %</driver>
56 % \fi
57 %
58 % \CheckSum{154}
59 %
60 % \CharacterTable
61 % {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
62 % 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
63 % Digits \0\1\2\3\4\5\6\7\8\9
64 % Exclamation \! Double quote \" Hash (number) \#
65 % Dollar \$ Percent \% Ampersand \&
66 % Acute accent \' Left paren \( Right paren \)
67 % Asterisk \* Plus \+ Comma \,
68 % Minus \- Point \. Solidus \/
69 % Colon \: Semicolon \; Less than \<
70 % Equals \= Greater than \> Question mark \?
71 % Commercial at \@ Left bracket \[ Backslash \\
72 % Right bracket \] Circumflex \^ Underscore \_
73 % Grave accent \` Left brace \{ Vertical bar \|
74 % Right brace \} Tilde \~}
75 %
76 % \changes{v1.0}{2012/05/21}{first public release}
77 % \changes{v2.0}{2023/08/13}{general upgrade}
78 %
79 % \GetFileInfo{xpunctuate.sty}
80 %
81 % \DoNotIndex{\CodelineIndex,\EnableCrossrefs,\RecordChanges}
82 %
83 % \title{The \texttt{xpunctuate} package for \LaTeX2e
84 % \\[1ex] \small (\fileversion, last revision \filedate)}
85 %
86 % \author{Philip G. Ratcliffe
87 % \\[1ex] \small \textsf{[email protected]}
88 % \\[2ex] \small Dipartimento di Scienza e Alta Tecnologia
89 % \\ \small Universit\`a degli Studi dell'Insubria---Como
90 % \\ \small and
91 % \\ \small Istituto Nazionale di Fisica Nucleare
92 % \\ \small Sezione di Milano Bicocca}
93 %
94 % \date{}
95 %
96 % \maketitle
97 %
98 % \begin{abstract}
99 % The |xpunctuate| package provides package writers and ordinary users with
100 % automatic post-macro punctuation insertion, \ie beyond (but similar to) that
101 % of the |xspace| package, which is required here. Three new macros are
102 % defined: |\xperiod|, |\xcomma| and |\xperiodcomma|, designed to insert the
103 % required punctuation marks \emph{if and only if} necessary, following a
104 % similar procedure to the |xspace| package. A further four macros
105 % (|\xspaceafter|, |\xperiodafter|, |\xcommaafter| and |\xperiodcommaafter|)
106 % are constructed to avoid the small superfluous space after possible font
107 % changes (such as |\emph|) that involve the correction |\/|, which would
108 % otherwise be hidden.
109 % \end{abstract}
110 %
111 % \section{Introduction}
112 %
113 % The present package is mainly intended for package writers, but may also
114 % serve the ordinary user; it provides additional post-macro punctuation
115 % insertion, similar to that of the |xspace| package. Three new macros are
116 % defined: |\xperiod|, |\xcomma| and |\xperiodcomma|, which, in an analogous
117 % fashion to the standard |\xspace| macro, insert any relevant punctuation
118 % where necessary. Four additional macros, of the form |\x|\dots|after|, avoid
119 % the small superfluous space due to the following period or comma being
120 % isolated from a preceding~|\/|.
121 %
122 % \section{Package call}
123 %
124 % \DescribeGeneric{package call}
125 % The package is loaded via a standard call:
126 % \begin{codelist}
127 % |\usepackage{xpunctuate}|
128 % \end{codelist}
129 %
130 % \subsection{User options}
131 %
132 % \DescribeGeneric{user options}
133 % There are at present \emph{no} user options.
134 %
135 % \subsection{User macros}
136 %
137 % Three user macros are defined, each having a pre-punctuation space-correcting
138 % variant, plus a similar extension of the |\xspace| macro.
139 %
140 % \DescribeMacro{\xperiod}
141 % The purpose of this macro is to insert a period if not found as the
142 % successive \LaTeX\ input token. Typical use will be in defining
143 % abbreviations, where there may or may not be a following \emph{accidental}
144 % sentence-terminating full stop. If \emph{no} explicit period follows, one is
145 % inserted, the occurrence is assumed to be mid-sentence and therefore normal
146 % inter-word spacing is applied. However, if it \emph{is} followed by a period,
147 % then this is considered to be a sentence terminator, it is left as is with no
148 % further insertions and the appropriate trailing space will then naturally
149 % ensue.
150 %
151 % After defining |\newcommand{\gb}{G.B\xperiod}|, the command |\gb| will
152 % determine when to insert a period after itself and when not, with also the
153 % correct mid-sentence or end-of-sentence spacing as required. Thus, the input
154 % \newcommand{\gb}{G.B\@\xperiod}
155 % \begin{codelist}
156 % |\gb is a very nice place to live.\\|\\
157 % |I live in \gb. It is a small island off the coast of France|\\
158 % |\gb\footnote{The small island off the coast of France.}|\\
159 % |is a very nice place to live.|
160 % \end{codelist}
161 % results in the output
162 % \begin{codelist}
163 % \gb is a very nice place to live.\\
164 % I live in \gb. It is a small island off the coast of France.\\
165 % \gb\footnote{The small island off the coast of France.}
166 % is a very nice place to live.
167 % \end{codelist}
168 %
169 % \DescribeMacro{\xcomma}
170 % This macro similarly inserts a comma if not found as the next token. A
171 % typical application might be following an abbreviation such as `eg' (\ie when
172 % used \emph{without} periods), which according to different standard style
173 % manuals should or should not be followed by a comma. It has no special
174 % spacing behaviour.
175 %
176 % \DescribeMacro{\xperiodcomma}
177 % This macro inserts a period \emph{and} a comma if not found as the next input
178 % tokens. Typical use will be, as above, for abbreviations such as `e.g.'\ (\ie
179 % \emph{with} periods) when they should be followed by a comma, but may also
180 % occur fortuitously immediately preceding an explicit sentence-closing period
181 % or indeed an explicit comma, the correct trailing space of which would then
182 % ensue. Note that this action \emph{cannot} be reproduced via successive use
183 % of the single macros, \ie the combination |\xperiod\xcomma|.
184 %
185 % \DescribeMacro{\xspaceafter}
186 % \DescribeMacro{\xperiodafter}
187 % \DescribeMacro{\xcommaafter}
188 % \DescribeMacro{\xperiodcommaafter}
189 % The variants |\x|\dots|after| are similar to the above except that they take
190 % the object word or phrase to be spaced or punctuated as an argument; the
191 % slight incorrect spacing adjustment between the word and following period or
192 % comma is thus avoided when, for example, the word is |\emph|'asised. Other
193 % punctuation marks do \emph{not} suffer from this problem.
194 %
195 % Note that although the action of |\xperiodcommaafter| may also be obtained
196 % via suitable nesting of |\xperiodafter| and |\xcommaafter|, this combination
197 % has not been thoroughly tested; the compound macro is thus included for both
198 % safety and backwards compatibility.
199 %
200 % In the case of the macros that guarantee a trailing period (\emph{with} or
201 % \emph{without} a comma), if the final letter of the word or phrase is a
202 % capital (\eg `Ph.D.'), to guarantee the correct end-of-sentence trailing
203 % spacing, it should be immediately followed by an explicit |\@|. That is, the
204 % definition should be of the form
205 % \begin{codelist}
206 % |\newcommand\PhD{Ph.D\@\xperiod}|\\[-0.67ex]
207 % \hspace*{-\leftmargin}\, or\\[-0.67ex]
208 % |\newcommand\PhD{\xperiodafter{Ph.D\@}}|
209 % \end{codelist}
210 % N.B. If the ending capital letter or letters are \eg |\emph|'asised, the |\@|
211 % should be placed \emph{inside} the |\emph|'asis:\footnote{It is for this
212 % reason that it \emph{cannot} be incorporated directly into the |xpunctuate|
213 % macros.}
214 % \begin{codelist}
215 % |\newcommand\PhD{\emph{Ph}.\emph{D\@}\xperiod}|\\[-0.67ex]
216 % \hspace*{-\leftmargin}\, or\\[-0.67ex]
217 % |\newcommand\PhD{\xperiodafter{\emph{Ph}.\emph{D\@}}}|
218 % \end{codelist}
219 %
220 % The following are various other examples of possible usage:
221 % \begin{codelist}
222 % |\newcommand\etc{etc\xperiod}|\\
223 % |\newcommand\eg{i.e\xperiodcomma}|\\
224 % |\newcommand\etal{\xperiodafter{\emph{et al}}}|\\
225 % |\newcommand\ie{\xperiodcommaafter{\emph{e}.\emph{g}}}|
226 % \end{codelist}
227 % Note how the closing period in the above is \emph{not} explicitly present,
228 % being inserted by the relevant macro as and when necessary, with too the
229 % correct spacing.
230 %
231 % \subsection{Caveats}
232 %
233 % \begin{generic}{caveats}
234 % No specific care should be necessary when employing the macros defined here;
235 % in particular, they are all \emph{robust}. However, trailing punctuation
236 % hidden inside or by other macro definitions may not always be correctly
237 % interpreted. Moreover, the known limitations of |\xspace| remain.
238 % \end{generic}
239 %
240 % \subsection{External package requirements}
241 %
242 % \begin{generic}{xspace}
243 % The |xspace| package is required and is loaded automatically. Note that, in
244 % the \emph{absence} of |\xspace|, the necessary presence of explicit trailing
245 % backslashes for correct spacing following command strings, would frustrate
246 % the functionality of all the macros defined here.\footnote{Users who shun the
247 % use of |xspace| will probably not appreciate the present package either.}
248 % \end{generic}
249 %
250 % \subsection{Package conflicts}
251 %
252 % \begin{generic}{conflicts}
253 % There are no known conflicts with any standard \LaTeX2e\ packages.
254 % \end{generic}
255 %
256 % \StopEventually{\PrintChanges\PrintIndex}
257 %
258 % \section{Implementation}
259 %
260 % \subsection{External packages}
261 % \begin{generic}{packages}
262 % First, load the |xspace| package, for automatic trailing-space insertion:
263 % \begin{macrocode}
264 \RequirePackage{xspace}
265 % \end{macrocode}
266 % \changes{v2.0}{2023/08/13}{useful \texttt{xspace} exceptions added}
267 % \begin{generic}{exceptions}
268 % and add some useful extra |xspace| exceptions relevant to the present
269 % package.
270 % \begin{macrocode}
271 \xspaceaddexceptions{\xcomma\xperiod\xperiodcomma}
272 % \end{macrocode}
273 % \end{generic}
274 % \end{generic}
275 %
276 % \subsection{User commands}
277 %
278 % \changes{v2.0}{2023/08/13}{revamped all macros}
279 % \begin{macro}{\xspaceafter}
280 % \changes{v2.0}{2023/08/13}{macro added}
281 % This macro takes one argument, which it prints as is. It then inserts
282 % |\xspace| immediately after, but nothing if followed by a comma or period.
283 % \begin{macrocode}
284 \NewDocumentCommand\xspaceafter{}{\xpnct@aux\xspace@aux}
285 % \end{macrocode}
286 % The correct spacing between the argument and any following comma or period is
287 % thus maintained in the case of, say, an |\emph|'asised argument. The
288 % necessity arises as the presence of |\xspace| `hides' any following
289 % punctuation from a possible |\/| spacing-correction command.
290 % \end{macro}
291 %
292 % \begin{macro}{\xperiod}
293 % The following macro inserts a period if this is not found to be the next
294 % character.
295 % \begin{macrocode}
296 \NewDocumentCommand\xperiod{}{\xpnct@aux\xperiod@aux{}}
297 % \end{macrocode}
298 % It may thus be used to construct common abbreviations (such as `etc.').
299 % \end{macro}
300 %
301 % \begin{macro}{\xperiodafter}
302 % This macro takes one argument and inserts a period after it if this is not
303 % found to be the next character.
304 % \begin{macrocode}
305 \NewDocumentCommand\xperiodafter{}{\xpnct@aux\xperiod@aux}
306 % \end{macrocode}
307 % The correct spacing between the argument and period is again thus maintained
308 % in the case of, say, |\emph|, as in often \emph{italicised} abbreviations
309 % (such as `\emph{etc}.').
310 % \end{macro}
311 %
312 % \begin{macro}{\xcomma}
313 % The following macro inserts a comma if this is not found to be the next
314 % character.
315 % \begin{macrocode}
316 \NewDocumentCommand\xcomma{}{\xpnct@aux\xcomma@aux{}}
317 % \end{macrocode}
318 % It may thus be used to construct those common abbreviations (without periods)
319 % that might normally be followed by a comma, such as `eg' or `ie' according to
320 % standard American-English usage.
321 % \end{macro}
322 %
323 % \begin{macro}{\xcommaafter}
324 % The following macro takes one argument and inserts a comma after it if this
325 % is not found to be the next character.
326 % \begin{macrocode}
327 \NewDocumentCommand\xcommaafter{}{\xpnct@aux\xcomma@aux}
328 % \end{macrocode}
329 % \end{macro}
330 %
331 % \begin{macro}{\xperiodcomma}
332 % The following macro first adds a period and then a comma if these are not
333 % found to be the next characters.
334 % \begin{macrocode}
335 \NewDocumentCommand\xperiodcomma{}{\xpnct@aux\xperiodcomma@aux{}}
336 % \end{macrocode}
337 % It may thus be used to construct those common abbreviations that might
338 % normally be followed by a comma (such as `e.g.,'), the comma being inserted
339 % \emph{if and only if} there is no following explicit sentence-ending period.
340 % Here, there is of course no problem of spacing either preceding or following
341 % the period. If only a period is found, it is treated as an end-of-sentence
342 % and the correct spacing will ensue accordingly. A following period--comma
343 % combination, if found, will be left as is.
344 % \end{macro}
345 %
346 % \begin{macro}{\xperiodcommaafter}
347 % This macro takes one argument and inserts a period and/or a comma after it if
348 % these are not found to be the next characters.
349 % \begin{macrocode}
350 \NewDocumentCommand\xperiodcommaafter{}{\xpnct@aux\xperiodcomma@aux}
351 % \end{macrocode}
352 % It may thus be used to construct those common \emph{italicised} abbreviations
353 % that should normally be followed by a comma (such as `\eg,').
354 % \end{macro}
355 %
356 % \subsection{Internal macros}
357 %
358 % \begin{macro}{\xpnct@tok}
359 % A token register is defined to store a possible object word or phrase:
360 % \begin{macrocode}
361 \newtoks\xpnct@tok
362 % \end{macrocode}
363 % \end{macro}
364 %
365 % \begin{macro}{\xpnct@aux}
366 % The general setup and call to the final output macros for the above user
367 % commands is handled by the following auxiliary macro:
368 % \begin{macrocode}
369 \def\xpnct@aux#1#2{%
370 \xpnct@tok{#2}%
371 \futurelet\xpnct@nxt#1}
372 % \end{macrocode}
373 % \end{macro}
374 % Note that all the user commands defined earlier terminate by inserting an
375 % |\xspace| \emph{if} and \emph{only if} the required punctuation has actually
376 % been inserted by the macro.
377 %
378 % \begin{macro}{\xspace@aux}
379 % Testing and output for |\xspaceafter| are performed by the following macro:
380 % \begin{macrocode}
381 \def\xspace@aux{%
382 \ifx\xpnct@nxt,\else
383 \ifx\xpnct@nxt.\else
384 \xpnct@tok\expandafter{\the\xpnct@tok\xspace}%
385 \fi\fi
386 \the\xpnct@tok}
387 % \end{macrocode}
388 % Only periods and commas need be excluded, as the spacing is correct for all
389 % other punctuation marks.
390 % \end{macro}
391 %
392 % \begin{macro}{\xperiod@aux}
393 % Testing and output for |\xperiod| and |\xperiodafter| are performed by this
394 % macro:
395 % \begin{macrocode}
396 \def\xperiod@aux{%
397 \ifx\xpnct@nxt.\else
398 \xpnct@tok\expandafter{\the\xpnct@tok.\@\xspace}%
399 \fi
400 \the\xpnct@tok}
401 % \end{macrocode}
402 % The approach adopted is to treat an explicit following period as an
403 % end-of-sentence full stop; the trailing space is then handled accordingly.
404 % However, when an explicit period is \emph{not} found), the placement of |\@|
405 % immediately after the inserted period thus avoids standard end-of-sentence
406 % spacing, assuming such an occurrence to be mid-sentence (as for
407 % abbreviations). If, in contrast, an explicit period \emph{is} found, it is
408 % retained as is and will thus generate the correct end-of-sentence spacing.
409 % \end{macro}
410 %
411 % \begin{macro}{\xcomma@aux}
412 % Testing and output for |\xcomma| and |\xcommaafter| are performed by the
413 % following macro (shamelessly copied from an \emph{old} |xspace.sty| and
414 % suitably hacked):
415 % \begin{macrocode}
416 \def\xcomma@aux{%
417 \ifx\xpnct@nxt.\else
418 \ifx\xpnct@nxt,\else
419 \ifx\xpnct@nxt:\else
420 \ifx\xpnct@nxt;\else
421 \ifx\xpnct@nxt!\else
422 \ifx\xpnct@nxt?\else
423 \ifx\xpnct@nxt/\else
424 \ifx\xpnct@nxt-\else
425 \ifx\xpnct@nxt'\else
426 \ifx\xpnct@nxt)\else
427 \ifx\xpnct@nxt]\else
428 \ifx\xpnct@nxt\}\else
429 \ifx\xpnct@nxt\egroup\else
430 \ifx\xpnct@nxt\/\else
431 \xpnct@tok\expandafter{\the\xpnct@tok,\xspace}%
432 \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
433 \the\xpnct@tok}
434 % \end{macrocode}
435 % Note that certain of the default exceptions set by the |xspace| package are
436 % missing here, for obvious reasons.
437 % \end{macro}
438 %
439 % \begin{macro}{\xperiodcomma@aux}
440 % Testing and output for |\xperiodcomma| and |\xperiodcommaafter| are performed
441 % by the following:
442 % \begin{macrocode}
443 \def\xperiodcomma@aux{%
444 \ifx\xpnct@nxt.\else
445 \xpnct@tok\expandafter{\the\xpnct@tok.\@\xcomma}%
446 \fi
447 \the\xpnct@tok}
448 % \end{macrocode}
449 % The presence or absence of an explicit following period is again taken to
450 % imply an end-of- or mid-sentence respectively, unless followed by an explicit
451 % comma, other closing punctuation or brackets say, when it will be assumed
452 % mid-sentence. Note, moreover, that |\@| is \emph{still} necessary here as the
453 % period may not necessarily be immediately followed by a comma, \eg if it is
454 % followed by a closing bracket or quotation marks.
455 % \end{macro}
456 %
457 % \begin{macro}{\endinput}
458 % Finally, explicitly terminate the package input here.
459 % \begin{macrocode}
460 \endinput
461 % \end{macrocode}
462 % \end{macro}
463 %
464 % \Finale
465 %
466 \endinput
467 %%
468 %% End of file `xpunctuate.dtx'.