Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2016 by Philippe Faist <[email protected]>
4 % -------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3 or later is part of all distributions of LaTeX
14 % version 2005/12/01 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{phfparen.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
23 %<package>\ProvidesPackage{phfparen}
24 %<*package>
25 [2016/08/15 v1.0 phfparen package]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \usepackage{xcolor}
31 \usepackage{phfqit}
32 \usepackage{amsmath}
33 \usepackage[backtickon]{phfparen}
34 \makeatletter
35 \providecommand\phfnote@pkgdoc@setupmainfont{
36 \renewcommand{\rmdefault}{futs}% only rm font, not math
37 }\makeatother
38 \usepackage[preset=xpkgdoc]{phfnote}
39 \EnableCrossrefs
40 \CodelineIndex
41 \RecordChanges
42
43 \verbdef\phfverbpren+\paren+
44 \robustify\phfverbpren
45
46 \begin{document}
47 \DocInput{phfparen.dtx}
48 \end{document}
49 %</driver>
50 % \fi
51 %
52 % \CheckSum{0}
53 %
54 % \CharacterTable
55 % {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
56 % 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
57 % Digits \0\1\2\3\4\5\6\7\8\9
58 % Exclamation \! Double quote \" Hash (number) \#
59 % Dollar \$ Percent \% Ampersand \&
60 % Acute accent \' Left paren \( Right paren \)
61 % Asterisk \* Plus \+ Comma \,
62 % Minus \- Point \. Solidus \/
63 % Colon \: Semicolon \; Less than \<
64 % Equals \= Greater than \> Question mark \?
65 % Commercial at \@ Left bracket \[ Backslash \\
66 % Right bracket \] Circumflex \^ Underscore \_
67 % Grave accent \` Left brace \{ Vertical bar \|
68 % Right brace \} Tilde \~}
69 %
70 %
71 % \changes{v1.0}{2016/04/20}{Initial version}
72 %
73 % \GetFileInfo{phfparen.dtx}
74 %
75 % \DoNotIndex{\newcommand,\newenvironment,\def,\gdef,\edef,\xdef,\if,\else,\fi,\ifx}
76 %
77 % \title{\phfqitltxPkgTitle{phfparen}}
78 % \author{Philippe Faist\quad\email{[email protected]}}
79 % \date{\pkgfmtdate\filedate}
80 % \maketitle
81 %
82 % \begin{abstract}
83 % \pkgname{phfparen}---Parenthetic math expressions made simpler and less
84 % redundant.
85 % \end{abstract}
86 %
87 % \inlinetoc
88 %
89 % \section{Introduction}
90 %
91 % The \pkgname{phfparen} package provides an easier way to handle
92 % parenthetic expressions in math formulae, by reducing the amount of
93 % redundancy in the \LaTeX{} code.
94 %
95 % The basic command is |\paren|\hspace{0.25ex}\meta{optional size
96 % arg}\hspace{0.25ex}\meta{opening delimiter} \ldots{} \meta{closing
97 % delimiter}. It puts the given contents (``\ldots'') within the given
98 % delimiters (such as ``[...]'', ``(...)'' or ``\{...\}''), and where the
99 % delimiters are sized according to the default size (no argument), the
100 % explicitly given size argument (``|\big|''), or the automatic sizing
101 % (``|*|''). As a shorthand, you may use a backtick character (``|`|'')
102 % instead of |\paren|.
103 %
104 % For example, you can use |`\Big(1+\hat{f}`\big(x))| or
105 % |\paren\Big(1+\hat{f}\paren\big(x))| instead of
106 % |\Bigl(1+\hat{f}\bigl(x\bigr)\Bigr)|, to display
107 % $`\Big(1+\hat{f}`\big(x))$. In this way, the writing is more condensed.
108 % Moreover, you don't have to repeat the size for the second delimiter,
109 % making it easier to change the delimiter sizes if you later change your
110 % mind. See further examples in \autoref{sec:examples}.
111 %
112 % \iffalse META-COMMENT :: TOO LONG
113 % \begin{verbatim}
114 % \begin{align}
115 % P\,`\bigg[\Phi_{XA\to X'A}`*(\sigma_{XR}\otimes
116 % \frac{P_A\Gamma_A P_A}{\tr P_A\Gamma_A})
117 % \,,\; \rho_{X'R}\otimes
118 % \frac{P'_{A'}\Gamma_{A'}P'_{A'}}{\tr P'_{A'}\Gamma_{A'}}
119 % ] \leqslant \epsilon\ .
120 % \end{align}
121 % \end{verbatim}
122 % for:
123 % \begin{align}
124 % P\,`\bigg[\Phi_{XA\to X'A}`*(\sigma_{XR}\otimes
125 % \frac{P_A\Gamma_A P_A}{\tr P_A\Gamma_A})
126 % \,,\; \rho_{X'R}\otimes
127 % \frac{P'_{A'}\Gamma_{A'}P'_{A'}}{\tr P'_{A'}\Gamma_{A'}}
128 % ] \leqslant \epsilon\ .
129 % \end{align}
130 % \fi
131 %
132 %
133 % \section{The \phfverbpren{} command and \phfverb` backtick shorthand}
134 %
135 % \DescribeMacro{\paren} The basic macro of this package is |\paren|. It
136 % handles a parenthetic expression including parsing matching delimiters
137 % and adjusting their sizing.
138 %
139 % \leavevmode\marginpar{\raggedleft\phfverb`\texttt\ldots} The backtick
140 % char provides a shorthand for specifying |\paren|. It is useful to
141 % de-clutter long formulas.
142 %
143 % The syntax for |\paren| and |`| is:
144 % \begin{center}
145 % |\paren|\meta{optional size argument}\meta{open-delimiter} \ldots \meta{close-delimiter}
146 % \par or\par
147 % |`|\meta{optional size argument}\meta{open-delimiter} \ldots \meta{close-delimiter}
148 % \end{center}
149 %
150 % By default, the following pairs of delimiters are recognized:
151 % |\paren(expression in parenthesis)|,\\
152 % |\paren[expression in brackets]|,\\
153 % |\paren<expression in angle brackets>|,\\
154 % |\paren\{expression in curly braces\}|, and\\
155 % |\paren{expression in curly braces}| (alternative syntax for curly
156 % braces). Of course, the same are available with the backtick shorthand:
157 % |`(expression)|, |`[expression]|, |`<expression>|, and so on.
158 %
159 % Delimiters are balanced, meaning that %
160 % |\paren[g[x] + f[x]]| is parsed as you would expect (the expression is %
161 % ``|g[x] + f[x]|'') and not as \TeX/\LaTeX{} usually parses default
162 % arguments (in which case the argument would be ``|g[x|''). \iffalse]\fi
163 %
164 %
165 % The optional size argument must be a single token. It may be one of |*|,
166 % |\big|, |\Big|, |\bigg|, |\Bigg|, or another standard sizing command. If
167 % the optional size argument is |*|, then the delimiters are sized with
168 % |\left(| \ldots{} |\right)|, that is, they are sized
169 % automatically.
170 %
171 % \subsection{Examples}
172 % \label{sec:examples}
173 %
174 % \makeatletter
175 % \def\showcaseexample{\begingroup\catcode`\\=12\catcode`\_=12\catcode`\^=12\catcode`\{=12\catcode`\}=12\relax\showcaseexample@}
176 % \def\showcaseexample@!!#1!!{\endgroup\showcaseexample@@{#1}{\scantokens{#1}}}
177 % \def\showcaseexample@@#1#2{\par\noindent\begin{minipage}{0.5\textwidth}\centering\ttfamily #1\end{minipage}\hspace{0.05\textwidth}\begin{minipage}{0.45\textwidth}\centering $\displaystyle #2$\end{minipage}\par\vskip 0.5em\relax}
178 % \makeatother
179 %
180 % \showcaseexample!! \log\paren\big( a + \sin(x) - y) !!
181 % \showcaseexample!! \log`\Big( a + \sin(x) - y) !!
182 % \showcaseexample!! \log`*( \sum_k`\big[ a_k^\dagger - a_k ] ) !!
183 % \showcaseexample!! F = `\big< f(x) >_x = `*< \sum g(`<p>) > !!
184 % \showcaseexample!! `\Big[\sum_j `[x]^2 - \sum [y]^2 + \sum f`*(x_3^\dagger)^2] !!
185 % \showcaseexample!! `(z + \backtick x) !!
186 % \showcaseexample!! `\{\vec z\} !!
187 % \showcaseexample!! `{\vec z} !!
188 % \showcaseexample!! `*{ \vec z : \sum_i z_i = 1 } !!
189 % \showcaseexample!! `\big{ \vec z : \sum_i z_i = 1 } !!
190 %
191 %
192 %
193 % \subsection{Controlling the behavior of the \phfverb` backtick shorthand}
194 %
195 % The behavior of the backtick character is only altered in math mode. The
196 % character works as normal in text mode. (Its catcode is in fact not
197 % changed, only its mathcode.)
198 %
199 % \DescribeMacro{\backtick} If you need a literal backtick, you may in any
200 % case use the macro |\backtick|.
201 %
202 % You may use the |backtick| package option to enable or disable the |`|
203 % backtick shorthand.
204 %
205 % \begin{pkgoptions}
206 % \item[backtick=true] Enable the |`| backtick shorthand. This is the
207 % default.
208 % \item[backtick=false] Disable the |`| backtick shorthand. A backtick
209 % character in math mode will now simply display a backtick character.
210 % \end{pkgoptions}
211 %
212 % \DescribeMacro{\parenMakeBacktickActiveParen} You may use the command
213 % |\parenMakeBacktickActiveParen| to enable the backtick shorthand at any
214 % time in the document. Similarly, the command
215 % \DescribeMacro{\parenMakeNormalBacktick} |\parenMakeNormalBacktick|
216 % disables the backtick shorthand. These changes are local to \LaTeX{}
217 % groups, which means that you can temporarily disable the backtick
218 % shorthand with
219 % \begin{verbatim}
220 % {\parenMakeNormalBacktick Normal backtick in math mode: $`$.}
221 % \end{verbatim}
222 %
223 %
224 % \section{Declaring matching delimiters and corresponding representations}
225 %
226 % \DescribeMacro{\parenRegister} Register a new delimiter type with
227 % |\parenRegister|. This macro should only be called in the preamble.
228 %
229 % Syntax is: |\parenRegister|\marg{internal name}\marg{open parse
230 % delimiter}\marg{close parse delimiter}\marg{open display
231 % delimiter}\marg{close display delimiter}.
232 %
233 % The \meta{internal name} is just an internal identifier: use plain ascii
234 % chars please (e.g. ``|angbrackets|'').
235 %
236 % The \meta{open parse delimiter} and \meta{close parse delimiter} are
237 % those characters which will be used to parse the delimited expression.
238 % They may differ from the actual delimiters used to display the
239 % expression, given by \marg{open display delimiter} and \marg{close
240 % display delimiter}.
241 %
242 % For example, you may use
243 % \begin{verbatim}
244 % \parenRegister{angbrackets}{<}{>}{\langle}{\rangle}
245 % \end{verbatim}
246 % to instruct |\paren| (and |`|) to do the following: whenever the ``|<|''
247 % open delimiter is encountered, then the expression is to be parsed within
248 % the delimiters %
249 % ``|< ... >|,'' and the final expression is to be delimited as %
250 % ``|\langle ... \rangle|,'' where the |\langle| and |\rangle| are possibly
251 % sized according to an optional size argument.
252 %
253 % You may repeat calls to |\parenRegister|, with different internal
254 % identifiers, to register different kinds of delimiters. It is always the
255 % opening delimiter which determines which registered info to use.
256 %
257 % \begin{pkgnote}
258 % With older versions of \pkgname{xparse} (older than
259 % \texttt{2015/11/04}), only single-character tokens or single-character
260 % escape sequences (such as |\{|) could be used as delimiters for parsing
261 % (second and third arguments to |\parenRegister|).
262 %
263 % Otherwise, with versions of \pkgname{xparse} newer than
264 % \texttt{2015/11/04}, you may use full macros to delimit content, for
265 % example |\parenRegister{testang}{\start}{\stop}{\langle}{\rangle}|
266 % allows you to write e.g.\@ \fbox{\phfverb{`\start content...\stop}},
267 % and the content will be displayed in angle brackets.
268 % \end{pkgnote}
269 %
270 % \DescribeMacro{\parenRegsiterSimpleBraces} The case where the delimiters
271 % are a normal \LaTeX{} group, that is ``|`{...}|,'' is treated specially.
272 % In this case, you need to specify which internal identifier to fall back
273 % to. For example, if you defined
274 % |\parenRegister{braces}{\{}{\}}{\{}{\}}|, then you may use
275 % |\parenRegisterSimpleBraces{braces}| to instruct |\paren| (and |`|) to
276 % use curly braces whenever both the forms |`\{...\}| and |`{...}| are
277 % used.
278 %
279 % \DescribeMacro{\parenRegisterDefaults} Register the default set of
280 % delimiters: |`(...)|, |`[...]|, |`<...>|, |`\{...\}|, and with |`{...}|
281 % the same as |`\{...\}|.
282 %
283 % There is a package option |registerdefaults| to instruct to load or not
284 % to load the default set of delimiters:
285 % \begin{pkgoptions}
286 % \item[registerdefaults=true] Set up the default set of delimiters
287 % provided by |\parenRegisterDefaults| when loading the package. This is
288 % the default.
289 % \item[registerdefaults=false] Do not set up any delimiters. It is your
290 % job to call |\parenRegister| as necessary to register all your
291 % delimiters.
292 % \end{pkgoptions}
293 %
294 %
295 %
296 %
297 %
298 %
299 %
300 %
301 %
302 %
303 %
304 %
305 %
306 %
307 %
308 % \StopEventually{\PrintChangesAndIndex}
309 %
310 % \section{Implementation}
311 %
312 % Load some utility packages.
313 %
314 % \begin{macrocode}
315 \RequirePackage{etoolbox}
316 \RequirePackage{kvoptions}
317 \RequirePackage{xparse}
318 \RequirePackage{amsmath}
319 \RequirePackage{mathtools}
320 % \end{macrocode}
321 %
322 %
323 % \subsection{Internal \phfverbpren{} API for different delimiters}
324 % \label{sec:internal-API-for-delimiters}
325 %
326 % The idea is to combine the power of the delimiter-parsing mechanism of
327 % \pkgname{xparse} with the display power of paired delimiters provided by
328 % \pkgname{mathtools}. With \pkgname{xparse}, you can define commands
329 % which parse an argument given by arbitrary (but fixed) delimiters. The
330 % \pkgname{mathtools} package allows you to define commands such as |\abs|
331 % with |\DeclarePairedDelimiter|, such that you can use them as |\abs{x}|
332 % for default delimiter sizes, |\abs*{x}| for automatic delimiter sizing,
333 % and |\abs[\big]{x}| to use an explicitly given size.
334 %
335 % The idea for |\paren| is the following: detect what the open delimiter
336 % is, and relay the call to a macro which knows how to parse a balanced
337 % argument with those delimiters. That macro then relays the call to the
338 % paired-delimiter-display macro with appropriate star, optional argument
339 % and mandatory argument.
340 %
341 % When parsing, a delimiter set is recognized by its opening delimiter
342 % token. Furthermore, to each delimiter set corresponds an internal
343 % identifier name.
344 %
345 % A delimiter set is declared by |\parenRegister| via three macros. First,
346 % the macro |\paren@registered@delims@|\meta{open delimiter token (as
347 % \phfverb\string)} is defined to expand to the internal identifier name
348 % for this delimiter pair.
349 %
350 % Then, the macro |\paren@impl@|\meta{internal identifier name} is defined
351 % to accept one argument, the possible modifiers passed to |\paren| before
352 % the opening delimiter.
353 %
354 % Finally, the macro |\paren@impl@|\meta{internal identifier name}|@go| is
355 % a |\DeclarePairedDelimiter|-declared macro which can display the
356 % delimited expression.
357 %
358 %
359 % \subsection{Implementation of \phfverbpren}
360 %
361 % \begin{macro}{\paren}
362 % Define the main |\paren| macro. The syntax is:
363 % |\paren|\meta{modifier-token}\meta{delimited-argument}, where
364 % modifier-token is optional and can be |*| or a sizing command such as
365 % |\big|.
366 %
367 % Because of the way \LaTeX{} parses arguments, we need to treat the case
368 % |\paren{...}| separately form, say, |\paren\{...\}|. Recall that
369 % |\@ifnextchar\bgroup| checks for an opening brace. Then, delegate call
370 % to appropriate macro for further processing.
371 % \begin{macrocode}
372 \def\paren{%
373 \@ifnextchar\bgroup\paren@impl@bgroup\paren@impl@nobgroup%
374 }
375 % \end{macrocode}
376 %
377 % Treat the special case in which we have a single \LaTeX{} group as
378 % argument, no modifiers. In this case, directly call the display macro
379 % corresponding to the delimiter set we should use in this case. (We know
380 % that the main argument follows in the input token chain.)
381 % \begin{macrocode}
382 \def\paren@impl@bgroup{%
383 \csname paren@impl@\paren@registered@default @go\endcsname%
384 }
385 % \end{macrocode}
386 %
387 %
388 % Parse the following token. See if |#1| is an opening delimiter. Do that
389 % by seeing if |#1| is a known and registered delimiter by checking if
390 % |\paren@registered@delims@|\meta{open delimiter token as \phfverb\string}
391 % is defined. If it is not a recognized open delimiter, assume that it is
392 % a modifier token.
393 % \begin{macrocode}
394 \def\paren@impl@nobgroup#1{%
395 \ifcsdef{paren@registered@delims@\string#1}{%
396 \paren@impl@nomod{#1}%
397 }{%
398 \paren@impl@mod{#1}%
399 }%
400 }
401 % \end{macrocode}
402 %
403 % We have just parsed and recognized an open delimiter token, repeated here
404 % as argument |#1|. So get the internal delimiter identifier via
405 % |\paren@registered@delims@\string|\meta{open delim}, and relay the call
406 % to |\paren@impl@|\meta{internal delim identifier}. Don't forget an empty
407 % argument as we saw no modifier tokens.
408 % \begin{macrocode}
409 \def\paren@impl@nomod#1{%
410 \letcs\paren@tmp@delimname{paren@registered@delims@\string#1}%
411 \csname paren@impl@\paren@tmp@delimname\endcsname{}#1%
412 %
413 }
414 % \end{macrocode}
415 %
416 % We have just seen a token which is not recognized as an open delimiter,
417 % so we've assumed it's a modifier token (repeated here as |#1|). Store it
418 % in |\paren@tmp@modtoken|, and parse further, keeping in mind that again
419 % we may have a \LaTeX{} braced group instead of a single token.
420 % \begin{macrocode}
421 \def\paren@impl@mod#1{%
422 \def\paren@tmp@modtoken{#1}%
423 \@ifnextchar\bgroup\paren@impl@modBgroup\paren@impl@modNobgroup%
424 }
425 % \end{macrocode}
426 %
427 % We have seen a modifier token, then a \LaTeX{} braced group. First, use
428 % |\paren@util@parseModifs| to parse the modifier token and to get the
429 % actual argument to the |\DeclarePairedDelimiter|-defined macro. Then,
430 % see which delimiter set to fall back to, and relay the call to that
431 % including the modifier flags.
432 % \begin{macrocode}
433 \def\paren@impl@modBgroup{%
434 \paren@util@parseModifs\paren@tmp@modifsForMathtools\paren@tmp@modtoken%
435 \letcs\paren@tmp@gocmd{paren@impl@\paren@registered@default @go}%
436 \expandafter\paren@tmp@gocmd\paren@tmp@modifsForMathtools%
437 }
438 % \end{macrocode}
439 %
440 % We have seen a modifier token, stored in |\paren@tmp@modtoken|, and now
441 % there is a next token coming in (|#1|) which has to be the open delimiter
442 % (there cannot be several modifier tokens). First, check that the given
443 % delimiter is known and registered.
444 % |\paren@registered@delims@|\meta{delimiter token as \phfverb\string}
445 % should be defined to be the internal name of the registered delimiter.
446 % Then, call the implementation for that delimiter with the modifier-token
447 % as argument, and let that do the actual parsing.
448 % \begin{macrocode}
449 \def\paren@impl@modNobgroup#1{%
450 \ifcsdef{paren@registered@delims@\string#1}{%
451 \letcs\paren@tmp@delimname{paren@registered@delims@\string#1}%
452 \letcs\paren@tmp@delimcmd{paren@impl@\paren@tmp@delimname}%
453 \edef\paren@tmp@modtokenarg{{\expandonce\paren@tmp@modtoken}}%
454 \expandafter\paren@tmp@delimcmd\paren@tmp@modtokenarg#1%
455 }{%
456 % \end{macrocode}
457 %
458 % In the event the open delimiter is not recognized, display an error
459 % message, and attempt to recover by keeping all arguments as text tokens.
460 % \begin{macrocode}
461 \PackageError{phfqit}{Unknown delimiter: (or can't parse args?)
462 {\expandafter\string\paren@tmp@modtoken}{\string#1}}{Your call
463 to \string\paren couldn't be parsed, presumably because I didn't
464 recognize your delimiter, or because there's a bug in this
465 package.}%
466 \paren@tmp@modtoken#1%
467 }%
468 }
469 % \end{macrocode}
470 % \end{macro}
471 %
472 %
473 % \subsection{Some Utilities}
474 %
475 % \begin{macro}{\paren@util@parseModifs}
476 % Parse a modifier token, and generates the appropriate size argument
477 % tokens (star or optional argument) for a
478 % |\DeclarePairedDelimiter|-declared command.
479 %
480 % \par |#1| = new macro name to be defined.
481 % \par |#2| = macro containing the modifier token. (Will be expanded
482 % once.)
483 %
484 % A call to |\paren@util@parseModifs| defines |#1| to contain
485 % mathtools-compatible size args. |#2| is expanded once, so it is
486 % expected to be a macro which contains the relevant modifiers.
487 %
488 % \begin{macrocode}
489 \def\paren@util@parseModifs#1#2{%
490 % \end{macrocode}
491 %
492 % If the modifier token is a star |*|, then the argument should be a simple star.
493 % \begin{macrocode}
494 \expandafter\ifstrequal\expandafter{#2}{*}{%
495 \def#1{*}%
496 }%
497 % \end{macrocode}
498 % Otherwise, if there is something and |#2| is not blank, put it in an
499 % optional argument (square braces).
500 % \begin{macrocode}
501 {% (else:)
502 \expandafter\ifblank\expandafter{#2}{%
503 \def#1{}%
504 }{%
505 \edef#1{[\expandonce{#2}]}%
506 }%
507 }%
508 }
509 % \end{macrocode}
510 % \end{macro}
511 %
512 % \begin{macro}{\paren@xparsefix@storeparenarg}
513 % The second utility is a fix for a bug (or feature?) in
514 % \pkgname{xparse}. It seems that when specifying a delimited argument
515 % with |r|\meta{open}\meta{close}, if the \meta{open} delimiter is not a
516 % single character, then the argument is not properly prepared: for
517 % example, with some versions of \pkgname{xparse}, for delimiters
518 % |r\{\}|, we get for the macro call |\mymacro\{hi there\}| as parsed
519 % argument |{hi there|. This bug was not present in older versions of
520 % \pkgname{xparse}, where it was impossible to use full macros as
521 % delimiters, but it seemed to have been introduced in more recent
522 % versions (tracked to starting from version \texttt{2015/11/04}).
523 %
524 % So we wrap the fix into a macro
525 % |\paren@xparsefix@storeparenarg|\marg{main argument which may need
526 % fix}. This defines the macro |\paren@tmp@contents| which is the actual
527 % argument, possibly fixed.
528 %
529 % The caller must ensure that the macro |\paren@impl@tmp@delimtoken| is
530 % defined to expand to the opening delimiter token.
531 %
532 % The default implementation assumes that \pkgname{xparse} doesn't have
533 % the bug.
534 % \begin{macrocode}
535 \def\paren@xparsefix@storeparenarg#1{%
536 \def\paren@tmp@contents{#1}%
537 }
538 % \end{macrocode}
539 %
540 % Now, redefine this macro to the correct fix depending on the
541 % \pkgname{xparse} package version. If the version is more recent than
542 % \texttt{2015/11/04}, then we need to strip macro name length (excluding
543 % backslash char) from beginning of argument.
544 % \begin{macrocode}
545 \@ifpackagelater{xparse}{2015/11/04}{
546 \RequirePackage{xstring}%
547 \def\paren@xparsefix@storeparenarg#1{%
548 \fullexpandarg\StrLen{\expandafter\string\paren@impl@tmp@delimtoken}%
549 [\paren@tmp@delimstrlen]%
550 \ifnum\paren@tmp@delimstrlen=1\relax%
551 \def\paren@tmp@contents{#1}%
552 \else%
553 \def\paren@tmp@delimstrlen@{\numexpr\paren@tmp@delimstrlen-1\relax}%
554 \noexpandarg\StrGobbleLeft{#1}{\the\paren@tmp@delimstrlen@}%
555 [\paren@tmp@contents]%
556 \fi%
557 }%
558 }{%
559 }
560 % \end{macrocode}
561 % \end{macro}
562 %
563 %
564 % \subsection{Registering Delimiters}
565 %
566 % Helper to register a delimiter set for use with |\paren|.
567 %
568 % \begin{macro}{\parenRegister}
569 % The macro |\parenRegister| defines the necessary macros documented in
570 % \autoref{sec:internal-API-for-delimiters}. Namely,
571 % |\paren@registered@delims@|\meta{open delimiter token, \phfverb\string
572 % ified} expands to the internal registered \meta{identifier} for this
573 % delimiter. Then, defines |\paren@impl@<name>| which is a parser for
574 % this delimiter and calls the mathtools goodies
575 % etc. |\paren@impl@<name>| takes one mandatory argument, which is all
576 % the stuff to insert before the open delimiter and to pass on to
577 % mathtools (just a |*| or a delimiter size), and then reads the
578 % delimited (balanced) content.
579 %
580 % The syntax is |\parenRegister|\marg{identifier}\marg{open delimiter
581 % token}\marg{close delimiter token}\marg{display open
582 % delimiter}\marg{display close delimiter}.
583 %
584 % This macro should only be called in the preamble.
585 % \begin{macrocode}
586 \newcommand\parenRegister[5]{%
587 % \end{macrocode}
588 % \iffalse meta-comment %}{ -- for matching braces in my editor
589 % \fi
590 %
591 % First, define the actual |\DeclarePairedDelimiter|-type command
592 % |\paren@impl@#1@go| which displays the final delimited expression.
593 % Recall that |#1| = the internal identifier, while |#4| and |#5| are the
594 % delimiters we should use to display the expression.
595 %
596 % Use |\DeclarePairedDelimiterX| so that we put the main argument inside a
597 % \LaTeX{} group, just to be sure. (For example, we want to make sure that
598 % in arguments such as |-1|, the minus sign is a unary minus and not seen
599 % as a binary operator.)
600 % \begin{macrocode}
601 \expandafter\DeclarePairedDelimiterX\csname paren@impl@#1@go\endcsname[1]{#4}{#5}{{##1}}
602 % \end{macrocode}
603 %
604 % The second macro is the one which is capable of parsing the balanced,
605 % delimited expression, while first taking a mandatory argument containing
606 % the possible modifier token.
607 %
608 % Here, we just read the modifier token and store them in a temporary
609 % macro, while relaying the delimiter parsing to a helper macro (not sure
610 % why this is necessary).
611 % \begin{macrocode}
612 \csdef{paren@impl@#1}##1{%
613 \gdef\paren@impl@tmp@modifs{##1}%
614 \csname paren@impl@#1@parsedelim\endcsname%
615 }
616 \expandafter\DeclareDocumentCommand\csname paren@impl@#1@parsedelim\endcsname{r#2#3}{%
617 \letcs\paren@impl@tmp@gocmd{paren@impl@#1@go}%
618 %%\message{********MESSAGE*********}%
619 %%\message{**********\detokenize\expandafter{\paren@impl@tmp@modifs}**********}%
620 %%\message{**********\detokenize{##1}***********}%
621 \paren@util@parseModifs\paren@impl@tmp@modifsForMathtools\paren@impl@tmp@modifs%
622 %%\show\paren@impl@tmp@modifsForMathtools%
623 \def\paren@impl@tmp@delimtoken{#2}%
624 \paren@xparsefix@storeparenarg{##1}%
625 %%\show\paren@impl@tmp@modifsForMathtools
626 %%\show\paren@tmp@contents
627 \expandafter\paren@impl@tmp@gocmd\paren@impl@tmp@modifsForMathtools{\paren@tmp@contents}%
628 }
629 % \end{macrocode}
630 %
631 % Finally, register this open delimiter to be detected by the |\paren|
632 % macro. With this, |\paren| also knows the internal identifier associated
633 % to this open delimiter token.
634 % \begin{macrocode}
635 \csdef{paren@registered@delims@\string#2}{#1}
636 }
637 % \end{macrocode}
638 % \end{macro}
639 %
640 % \begin{macro}{\parenRegisterSimpleBraces}
641 % Specify the internal name for the delimiter which should be used in the
642 % syntax |`{...}| or |\paren{...}| (with or without modifier token).
643 %
644 % If this macro is called multiple times, the last specified name is
645 % used.
646 % \begin{macrocode}
647 \newcommand\parenRegisterSimpleBraces[1]{%
648 \def\paren@registered@default{#1}%
649 }
650 % \end{macrocode}
651 % \end{macro}
652 %
653 %
654 % \begin{macro}{\parenRegisterDefaults}
655 % A macro which registers the default set of delimiters.
656 % \begin{macrocode}
657 \newcommand\parenRegisterDefaults{
658 % \end{macrocode}
659 % \iffalse meta-comment %}{ -- for matching braces in my editor
660 % \fi
661 %
662 % The default set of delimiters:
663 % \begin{macrocode}
664 \parenRegister{parens}{(}{)}{(}{)}
665 \parenRegister{brackets}{[}{]}{[}{]}
666 \parenRegister{angbrackets}{<}{>}{\langle}{\rangle}
667 \parenRegister{braces}{\{}{\}}{\{}{\}}
668 % \end{macrocode}
669 %
670 % And the registered paren type to use when given the syntax |`{...}|:
671 % curly braces.
672 % \begin{macrocode}
673 \parenRegisterSimpleBraces{braces}
674 }
675 % \end{macrocode}
676 % \end{macro}
677 %
678 %
679 % \subsection{Handle backtick shorthand}
680 %
681 % \begin{macro}{\parenMakeBacktickActiveParen}
682 % Change the behavior of the backtick character in math mode to
683 % (|\parenMakeBacktickActiveParen|) be an alias for |\paren|.
684 % \begin{macrocode}
685 \def\parenMakeBacktickActiveParen{%
686 % \end{macrocode}
687 %
688 % Set the backtick character to be active, but only in math mode. It still
689 % has its normal |\catcode|, only its |\mathcode| is altered.
690 % \begin{macrocode}
691 \mathcode`\`="8000\relax%
692 % \end{macrocode}
693 %
694 % Use the usual |\lccode|-trick to do ``|\def`{...}|'' but for an active |`| char
695 % \begin{macrocode}
696 \begingroup%
697 \lccode`\~=`\`%
698 \lowercase{\endgroup\def~}{\paren}%
699 }
700 % \end{macrocode}
701 % \end{macro}
702 %
703 % \begin{macro}{\parenMakeNormalBacktick}
704 % The command |\parenMakeNormalBacktick| changes the behavior of the
705 % backtick character in math mode to be a normal backtick char
706 % (``$\backtick$'').
707 % \begin{macrocode}
708 \def\parenMakeNormalBacktick{\mathcode`\`="0060\relax}
709 % \end{macrocode}
710 % \end{macro}
711 %
712 % \begin{macro}{\backtick}
713 % A literal backtick. Simply done by temporarily disabling our backtick
714 % shorthand within a \LaTeX{} group.
715 % \begin{macrocode}
716 \def\backtick{\begingroup\parenMakeNormalBacktick`\endgroup}
717 % \end{macrocode}
718 % \end{macro}
719 %
720 %
721 %
722 %
723 % \subsection{Parse package options}
724 %
725 %
726 % Set up \pkgname{kvoptions} option parsing.
727 % \begin{macrocode}
728 \SetupKeyvalOptions{
729 family=phfparen,
730 prefix=phfparen@opt@
731 }
732 % \end{macrocode}
733 %
734 %
735 % Option \pkgoptionfmt{backtick}, and complementary option \pkgoptionfmt{nobacktick}.
736 % \begin{macrocode}
737 \DeclareBoolOption[true]{backtick}
738 \DeclareComplementaryOption{nobacktick}{backtick}
739 % \end{macrocode}
740 %
741 % For backwards compatibility with my previous versions of
742 % \pkgname{phfparen}: provide the |backtickon| package option.
743 % \begin{macrocode}
744 \DeclareVoidOption{backtickon}{%
745 \phfparen@opt@backticktrue
746 \PackageWarning{phfparen}{Option 'backtickon' is deprecated. It still works,
747 but please consider using 'backtick=true|false' instead.}%
748 }
749 % \end{macrocode}
750 %
751 %
752 %
753 % Option \pkgoptionfmt{registerdefaults} to specify whether to register the
754 % default set of delimiters or not.
755 % \begin{macrocode}
756 \DeclareBoolOption[true]{registerdefaults}
757 \DeclareComplementaryOption{noregisterdefaults}{registerdefaults}
758 % \end{macrocode}
759 %
760 %
761 % Finally, process the options.
762 % \begin{macrocode}
763 \DeclareDefaultOption{%
764 \@unknownoptionerror
765 }
766 \ProcessKeyvalOptions*
767 % \end{macrocode}
768 %
769 %
770 % Now, execute the settings dictated by the user options.
771 % \begin{macrocode}
772 \ifphfparen@opt@backtick
773 \parenMakeBacktickActiveParen
774 \fi
775 \ifphfparen@opt@registerdefaults
776 \parenRegisterDefaults
777 \fi
778 % \end{macrocode}
779 %
780 %\Finale
781 \endinput