Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2025 by Julien Labbé <[email protected]>
4 %
5 % This file may be distributed and/or modified under the conditions of the
6 % LaTeX Project Public License (LPPL), either version 1.3c of this license or
7 % (at your option) any later version. The latest version of this license is in
8 % the file https://www.latex-project.org/lppl.txt
9 %
10 % \fi
11 %
12 % \iffalse
13 %
14 %<package>\NeedsTeXFormat{LaTeX2e}
15 %<package>\ProvidesExplPackage{bracealign}{2025/04/17}{v1.0}{Align underbraces and overbraces}
16 %
17 %<*driver>
18 \documentclass[nohyperref]{ltxdoc}
19
20 \usepackage{bracealign-doc} %^^A defined at end of this file, with guard <docstyle>
21 \usepackage{bracealign}
22
23 \usepackage{mathtools}
24
25 \EnableCrossrefs
26 \PageIndex
27 % \CodelineIndex
28 \RecordChanges
29 % \OnlyDescription
30
31 \begin{document}
32
33 \DocInput{bracealign.dtx}
34
35 \PrintIndex
36 \PrintChanges
37
38 \end{document}
39 %</driver>
40 % \fi
41 %
42 % \changes{v1.0}{2025/04/17}{Initial version.}
43 %
44 % \GetFileInfo{\jobname.sty}
45 %
46 % \title{The \pkg{bracealign} package\thanks{This document corresponds to
47 % \pkg{bracealign}~\fileversion, dated \filedate.}}
48 % \author{Julien Labb\'e \\ {\small \url{https://github.com/julienlabbe/latex-packages}}}
49 %
50 % \maketitle
51 %
52 % \begin{abstract}
53 % A \LaTeX{} package to align braces under and over math expressions. A new
54 % environment called \refEnv{bracealign} is provided, inside which braces and
55 % brackets drawn with the commands \cs{underbrace}, \cs{overbrace},
56 % \cs{underbracket}, \cs{overbracket}, \cs{underparen} or \cs{overparen} are
57 % vertically aligned. The package also allows adding support for new commands.
58 %
59 % \bigskip
60 %
61 % Example:
62 % \iffalse
63 %<*example>
64 % \fi
65 \begin{dispExample}
66 \[
67 \rho c \frac{\partial T}{\partial t} =
68 \begin{bracealign}
69 \underbrace{
70 \begin{bracealign}
71 \underbrace{
72 - \lambda \frac{\partial^2 T}{\partial x^2}
73 }_{\text{diffusion}}
74 - \underbrace{
75 \mu (T^4 - {T_0}^4)
76 }_{\substack{\text{radiative loss}}}
77 \end{bracealign}
78 }_{\text{heat transferts}}
79 + \underbrace{
80 \sum_{i=1}^{n} \dot{q}_i
81 }_{\substack{\text{heat}\\{\text{sources}}}}
82 \end{bracealign}
83 \]
84 \end{dispExample}
85 % \iffalse
86 %</example>
87 % \fi
88 %
89 % \end{abstract}
90 %
91 % \clearpage
92 %
93 % \tableofcontents{}
94 %
95 % \clearpage
96 %
97 % \section{Introduction}
98 %
99 % The \pkg{bracealign} package provides the environment \refEnv{bracealign}
100 % inside which brace-like commands are vertically aligned. Supported brace-like
101 % commands are:
102 % \begin{center}
103 % \begin{tabular}{lll}
104 % \cs{underbrace} &
105 % \cs{underbracket} &
106 % \cs{underparen} \\
107 % \cs{overbrace} &
108 % \cs{overbracket} &
109 % \cs{overparen}
110 % \end{tabular}
111 % \end{center}
112 % \cs{underbrace} and \cs{overbrace} are standard \LaTeX{} commands.
113 % The commands \cs{underbracket} and \cs{overbracket} are defined, for example,
114 % by the packages: \pkg{unicode-math}, \pkg{mathtools}, \pkg{stix2} or
115 % \pkg{libertinus}; the commands \cs{underparen} and \cs{overparen} by:
116 % \pkg{unicode-math}, \pkg{stix2} or \pkg{libertinus}. The support for new
117 % commands can be added by the user.
118 %
119 % Inside the \refEnv{bracealign} environment, the content of brace-like commands
120 % is grabbed and appended inside all same braces with a \cs{vphantom} macro to
121 % generate the braces alignment. Note that this prohibits the use of optional
122 % arguments for the commands (see \emph{Known issue}, section~\ref{sec:issue-command-with-optionnal-arguments}, page~\pageref{sec:issue-command-with-optionnal-arguments}).
123 %
124 % \medskip
125 %
126 % This package originates in an answer on the TeX -- LaTeX Stack
127 % Exchange network\footnote{\url{https://tex.stackexchange.com/a/740290}.}.
128 %
129 % \section{User interface}
130 % \label{sec:user-interface}
131 %
132 % \newcommand{\smallcontent}{\textcolor{cyan}{\rule[-3pt]{1cm}{6pt}}}
133 % \newcommand{\medcontent} {\textcolor{cyan}{\rule[-6pt]{1.2cm}{12pt}}}
134 % \newcommand{\bigcontent} {\textcolor{cyan}{\rule[-12pt]{2cm}{24pt}}}
135 % \newcommand{\hugecontent} {\textcolor{cyan}{\rule[-18pt]{2.5cm}{36pt}}}
136 %
137 % The examples given in this section use the following commands:
138 % \iffalse
139 %<*example>
140 % \fi
141 \begin{dispListing}
142 \newcommand{\smallcontent}{\textcolor{cyan}{\rule[-3pt]{1cm}{6pt}}}
143 \newcommand{\medcontent} {\textcolor{cyan}{\rule[-6pt]{1.2cm}{12pt}}}
144 \newcommand{\bigcontent} {\textcolor{cyan}{\rule[-12pt]{2cm}{24pt}}}
145 \newcommand{\hugecontent} {\textcolor{cyan}{\rule[-18pt]{2.5cm}{36pt}}}
146 \end{dispListing}
147 % \iffalse
148 %</example>
149 % \fi
150 % \noindent The \pkg{xcolor} package is also required (for the command
151 % \cs{textcolor}), as loading the \pkg{amsmath} package (for the command
152 % \cs{text}) and a package that defines \cs{underbracket} (such as
153 % \pkg{mathtools}).
154 %
155 % \subsection{Environment}
156 %
157 % \begin{docEnvironment}{bracealign}{ \oarg{options list} }
158 % Vertically aligns the brace-like commands in \meta{environment content}.
159 % Each command is aligned separately (note that commands that uses
160 % internally a brace-like command are also aligned). \refEnv{bracealign}
161 % environments can be nested.
162 %
163 % The keys described in section~\ref{sec:keys}, can be used in \meta{options list} to
164 % activate, or deactivate, the alignment of each braces.
165 %
166 %\clearpage
167 %
168 % \noindent\vspace{-\baselineskip}
169 %
170 % \marginpar{\hfill
171 % \parbox[t]{0.88\linewidth}{\vspace*{1cm}\raggedright
172 % Separate alignment of brace-like commands
173 % }
174 % }
175 % \iffalse
176 %<*example>
177 % \fi
178 \begin{dispExample}
179 \[
180 \begin{bracealign}
181 \underbrace{\medcontent}_{1}
182 ~+~ \underbracket{\smallcontent}_{A}
183 ~=~ \underbrace{\hugecontent}_{2}
184 ~+~ \underbracket{\bigcontent}_{B}
185 ~+~ \underbrace{\smallcontent}_{3}
186 \end{bracealign}
187 \]
188 \end{dispExample}
189 % \iffalse
190 %</example>
191 % \fi
192 %
193 % \vfill
194 %
195 % \marginpar{\hfill
196 % \parbox[t]{0.88\linewidth}{\vspace*{1cm}\raggedright
197 % Nested \refEnv*{bracealign} environments
198 % }
199 % }
200 % \iffalse
201 %<*example>
202 % \fi
203 \begin{dispExample}
204 \[
205 \begin{bracealign}
206 \underbrace{
207 \begin{bracealign}
208 \underbrace{\medcontent}_{1}
209 ~+~ \underbrace{\smallcontent}_{2}
210 \end{bracealign}
211 }_{\text{nested}}
212 ~=~ \underbrace{\hugecontent}_{3}
213 ~+~ \underbrace{\bigcontent}_{4}
214 ~+~ \underbrace{\smallcontent}_{5}
215 \end{bracealign}
216 \]
217 \end{dispExample}
218 % \iffalse
219 %</example>
220 % \fi
221 %
222 %\vfill
223 %
224 % \marginpar{\hfill
225 % \parbox[t]{0.88\linewidth}{\vspace*{1cm}\raggedright
226 % Using internally a brace-like command
227 %
228 % \bigskip
229 %
230 % \itshape\footnotesize Note: the {\normalfont \cs{ubrace}} command has been
231 % suggested by Enrico Gregorio to fix the syntax and spacing issues of
232 % \cs{underbrace} (see {\normalfont
233 % \url{https://tex.stackexchange.com/a/728627/}}).
234 % }
235 % }
236 % \iffalse
237 %<*example>
238 % \fi
239 \begin{dispExample}
240 \newcommand{\ubrace}[2]{{\underbrace{#1}_{#2}}}
241 \[
242 \begin{bracealign}
243 \ubrace{\medcontent}{1}
244 ~+~ \underbrace{\smallcontent}_{A}
245 ~=~ \ubrace{\hugecontent}{2}
246 ~+~ \underbrace{\bigcontent}_{B}
247 ~+~ \ubrace{\smallcontent}{3}
248 \end{bracealign}
249 \]
250 \end{dispExample}
251 % \iffalse
252 %</example>
253 % \fi
254 %
255 % \clearpage
256 %
257 % \end{docEnvironment}
258 %
259 % \subsection{Command}
260 %
261 %\begin{docCommand}{bracealignsetup}{ \marg{options list} }
262 % Sets options for every \refEnv{bracealign} environments. All keys described
263 % in the section~\ref{sec:keys} can be used in \meta{options list}.
264 %
265 % This is equivalent to \cs{SetKeys} |[bracealign]| \marg{options list}.
266 %
267 % \iffalse
268 %<*example>
269 % \fi
270 \begin{dispExample}
271 \bracealignsetup{underbracket=false}
272
273 \[
274 \begin{bracealign}
275 \underbrace{\medcontent}_{1}
276 ~+~ \underbracket{\smallcontent}_{A}
277 ~=~ \underbrace{\hugecontent}_{2}
278 ~+~ \underbracket{\bigcontent}_{B}
279 ~+~ \underbrace{\smallcontent}_{3}
280 \end{bracealign}
281 \]
282 \end{dispExample}
283 % \iffalse
284 %</example>
285 % \fi
286 % \end{docCommand}
287 %
288 % \subsection{Keys}
289 % \label{sec:keys}
290 %
291 % \begin{docKeys}[
292 % doc keypath = bracealign,
293 % doc parameter = {=true\textbar{}false}
294 % ]
295 % {
296 % {
297 % doc name = {overbrace},
298 % doc description = {default |true|, initially |true|},
299 % },
300 % {
301 % doc name = {nooverbrace},
302 % doc description = {default |true|, inverse of |overbrace|},
303 % },
304 % }
305 % \end{docKeys}
306 % \begin{docKeys}[
307 % doc keypath = bracealign,
308 % doc parameter = {=true\textbar{}false}
309 % ]
310 % {
311 % {
312 % doc name = {underbrace},
313 % doc description = {default |true|, initially |true|},
314 % },
315 % {
316 % doc name = {nounderbrace},
317 % doc description = {default |true|, inverse of |underbrace|},
318 % },
319 % }
320 % \end{docKeys}
321 % \begin{docKeys}[
322 % doc keypath = bracealign,
323 % doc parameter = {=true\textbar{}false}
324 % ]
325 % {
326 % {
327 % doc name = {overbracket},
328 % doc description = {default |true|, initially |true|},
329 % },
330 % {
331 % doc name = {nooverbracket},
332 % doc description = {default |true|, inverse of |overbracket|},
333 % },
334 % }
335 % \end{docKeys}
336 % \begin{docKeys}[
337 % doc keypath = bracealign,
338 % doc parameter = {=true\textbar{}false}
339 % ]
340 % {
341 % {
342 % doc name = {underbracket},
343 % doc description = {default |true|, initially |true|},
344 % },
345 % {
346 % doc name = {nounderbracket},
347 % doc description = {default |true|, inverse of |underbracket|},
348 % },
349 % }
350 % \end{docKeys}
351 % \begin{docKeys}[
352 % doc keypath = bracealign,
353 % doc parameter = {=true\textbar{}false}
354 % ]
355 % {
356 % {
357 % doc name = {overparen},
358 % doc description = {default |true|, initially |true|},
359 % },
360 % {
361 % doc name = {nooverparen},
362 % doc description = {default |true|, inverse of |overparen|},
363 % },
364 % }
365 % \end{docKeys}
366 % \begin{docKeys}[
367 % doc keypath = bracealign,
368 % doc parameter = {=true\textbar{}false}
369 % ]
370 % {
371 % {
372 % doc name = {underparen},
373 % doc description = {default |true|, initially |true|},
374 % },
375 % {
376 % doc name = {nounderparen},
377 % doc description = {default |true|, inverse of |underparen|},
378 % },
379 % }
380 % Activates, or deactivates, the alignment of the corresponding brace-like
381 % command. These boolean keys are defined when the package \pkg{bracealign}
382 % is loaded, whether the commands are defined or not (as they can be defined
383 % later).
384 %
385 % \iffalse
386 %<*example>
387 % \fi
388 \begin{dispExample}
389 \[
390 \begin{bracealign}[underbrace=false]
391 \underbrace{\medcontent}_{1}
392 ~+~ \underbracket{\smallcontent}_{A}
393 ~=~ \underbrace{\hugecontent}_{2}
394 ~+~ \underbracket{\bigcontent}_{B}
395 ~+~ \underbrace{\smallcontent}_{3}
396 \end{bracealign}
397 \]
398 \end{dispExample}
399 % \iffalse
400 %</example>
401 % \fi
402 % \end{docKeys}
403 %
404 % \begin{docKeys}[
405 % doc keypath = bracealign,
406 % ]
407 % {
408 % {
409 % doc name = {add-brace},
410 % doc parameter = {=\textbackslash\meta{command} }
411 % },
412 % {
413 % doc name = {add-braces},
414 % doc parameter = {=\marg{commands list}}
415 % }
416 % }
417 % \refKey{/bracealign/add-brace} adds the support for the new brace-like
418 % command
419 % |\|\meta{command}. This also defines the keys \meta{command}
420 % and |no|\meta{command} to activate or deactivate the alignment of
421 % |\|\meta{command} braces.
422 %
423 % \refKey{/bracealign/add-braces} adds the support for multiple brace-like
424 % commands, given as a comma separated list of commands.
425 %
426 % \iffalse
427 %<*example>
428 % \fi
429 \begin{dispExample}
430 \newcommand*{\mybrace}[1]{\mathop{\overleftrightarrow{#1}}\limits}
431 \bracealignsetup{add-brace=\mybrace}
432
433 \[
434 \begin{bracealign}
435 \mybrace{
436 \begin{bracealign}[mybrace=false]
437 \mybrace{\medcontent}^{1}
438 ~+~ \mybrace{\smallcontent}^{2}
439 \end{bracealign}
440 }^{\text{nested}}
441 ~=~ \mybrace{\hugecontent}^{3}
442 ~+~ \mybrace{\bigcontent}^{4}
443 ~+~ \mybrace{\smallcontent}^{5}
444 \end{bracealign}
445 \]
446 \end{dispExample}
447 % \iffalse
448 %</example>
449 % \fi
450 % \end{docKeys}
451 %
452 % \begin{docKey}[bracealign][before lower=\bigskip\par]{default-braces}
453 % {=\marg{commands list}}
454 % {no default, initially |\{\cs{underbrace}, \cs{overbrace},\par
455 % \cs{underbracket}, \cs{overbracket},\par \cs{underparen}, \cs{overparen}\}|}
456 % Sets the list of brace-like commands that must be supported by
457 % \refEnv{bracealign}. At the beginning of the document (through the
458 % |begindocument| hook) the existence of each command is tested and, if the test
459 % sucesses, the command is passed to \refKey{/bracealign/add-brace}.
460 % \end{docKey}
461 %
462 % \section{Complements}
463 %
464 % \subsection{Known issue: Commands with optional arguments}
465 % \label{sec:issue-command-with-optionnal-arguments}
466 %
467 % The brace-like commands are expected to have only one mandatory argument (this
468 % argument is grabbed and used to align the braces). In particular, if a command
469 % handles optional arguments (such as the commands
470 % \cs{underbracket} and \cs{overbracket} as defined by the \pkg{mathtools}
471 % package), these optional arguments can't be used inside the
472 % \refEnv{bracealign} environment.
473 %
474 % \subsection{Changelog}
475 %
476 % \begin{description}
477 % \item[v1.0] Initial version.
478 % \end{description}
479 %
480 % \MaybeStop{}
481 %
482 % \section{Implementation}
483 %
484 %\iffalse
485 %<*package>
486 %\fi
487 % \setlength{\parindent}{0em}
488 % \setlength{\parskip}{\smallskipamount}
489 %
490 % \iffalse ^^A Not in doc to get the right line numbering
491 % Internal prefix for \pkg{DocStrip}.
492 % \begin{macrocode}
493 %<@@=bracealign>
494 % \end{macrocode}
495 % \fi
496 %
497 % \subsection{Adding brace command}
498 %
499 % The sequence that store the brace-like commands.
500 % \begin{macrocode}
501 \seq_new:N \l_bracealign_brace_seq
502 % \end{macrocode}
503 %
504 % \begin{macro}{\bracealign_add_brace:n}
505 % \begin{macro}{\bracealign_add_brace:e}
506 % \begin{macro}{\bracealign_add_brace:N}
507 % Add the brace command |#1|.
508 % \begin{macrocode}
509 \msg_new:nnn { bracealign } { already-added-brace }
510 { Brace~command~\token_to_str:c #1~has~already~been~added.~Skipped. }
511 \cs_new:Nn \bracealign_add_brace:n
512 {
513 \seq_if_in:NnTF \l_bracealign_brace_seq { #1 }
514 {
515 \msg_warning:nnn { bracealign } { already-added-brace } { #1 }
516 }
517 {
518 \seq_put_right:Nn \l_bracealign_brace_seq { #1 }
519 % \end{macrocode}
520 %
521 % Backup the standard command.
522 % \begin{macrocode}
523 \cs_set_eq:cc { @@_#1_std_cmd:n } { #1 }
524 % \end{macrocode}
525 %
526 % Define switches, if needed (for commands initially in
527 % \cs{l@@_default_brace_clist}, the switches are defined when the
528 % package is loaded, but the commands are added through the hook
529 % |begindocument|).
530 % \begin{macrocode}
531 \bool_if_exist:cF { l@@_#1_bool }
532 { \@@_define_switches:e { #1 } }
533 % \end{macrocode}
534 %
535 % These token lists store the content of braces.
536 % \begin{macrocode}
537 \tl_new:c { g@@_#1_strutcontent_tl }
538 \tl_new:c { l@@_#1_strutcontent_tl }
539 \tl_new:c { l@@_#1_strutcontent_surround_tl }
540 % \end{macrocode}
541 %
542 % Command wrapper to collect the braces content.
543 % \begin{macrocode}
544 \cs_new:cn { @@_#1_collect_strutcontent:n }
545 {
546 \tl_gput_right:cn { g@@_#1_strutcontent_tl } { ##1 }
547 \use:c { @@_#1_std_cmd:n } { }
548 }
549 % \end{macrocode}
550 %
551 % Command wrapper to use the braces content in \cs{vphantom}.
552 % \begin{macrocode}
553 \cs_new:cn { @@_#1_use_strutcontent:n }
554 {
555 \use:c { @@_#1_std_cmd:n }
556 {
557 \vphantom
558 {
559 \tl_use:c { l@@_#1_strutcontent_tl }
560 }
561 ##1
562 }
563 }
564 }
565 }
566 \cs_generate_variant:Nn \bracealign_add_brace:n { e }
567 \cs_new:Nn \bracealign_add_brace:N
568 {
569 \bracealign_add_brace:e { \cs_to_str:N #1 }
570 }
571 % \end{macrocode}
572 % \end{macro}
573 % \end{macro}
574 % \end{macro}
575 %
576 % Keys \refKey{/bracealign/add-brace} and \refKey{/bracealign/add-braces}
577 % (wrapper to \cs{bracealign_add_brace:N}).
578 % \begin{macrocode}
579 \keys_define:nn { bracealign }
580 {
581 add-brace .code:n = { \bracealign_add_brace:N #1 },
582 add-braces .code:n =
583 {
584 \clist_map_function:nN { #1 } \bracealign_add_brace:N
585 },
586 }
587 % \end{macrocode}
588 %
589 % \begin{macro}{\@@_define_switches:n}
590 % \begin{macro}{\@@_define_switches:e}
591 % \begin{macro}{\@@_define_switches:N}
592 % Define the switches for the brace command |#1|.
593 % \begin{macrocode}
594 \cs_new:Nn \@@_define_switches:n
595 {
596 \bool_new:c { l@@_#1_bool }
597 \bool_set_true:c { l@@_#1_bool }
598 \keys_define:nn { bracealign }
599 {
600 #1 .bool_set:c = { l@@_#1_bool },
601 no#1 .bool_set_inverse:c = { l@@_#1_bool },
602 }
603 }
604 \cs_generate_variant:Nn \@@_define_switches:n { e }
605 \cs_new:Nn \@@_define_switches:N
606 {
607 \@@_define_switches:e { \cs_to_str:N #1 }
608 }
609 % \end{macrocode}
610 % \end{macro}
611 % \end{macro}
612 % \end{macro}
613 %
614 % \subsection{Alteration of brace command}
615 %
616 % These three commands are used for each brace. |#1| is the brace name.
617 %
618 % \begin{macro}{\@@_initialize:n}
619 % Sets the brace command to collect its content in |\g@@_#1_strutcontent_tl|.
620 % \begin{macrocode}
621 \cs_new:Nn \@@_initialize:n
622 {
623 \tl_set_eq:cc
624 { l@@_#1_strutcontent_surround_tl }
625 { g@@_#1_strutcontent_tl }
626 \tl_clear:c { g@@_#1_strutcontent_tl }
627 \cs_set_eq:cc
628 { #1 }
629 { @@_#1_collect_strutcontent:n }
630 }
631 % \end{macrocode}
632 % \end{macro}
633 %
634 % \begin{macro}{\@@_use_strutcontent:n}
635 % Set the brace command to use the all braces contents as strut (using
636 % \cs{vphantom}).
637 % \begin{macrocode}
638 \cs_new:Nn \@@_use_strutcontent:n
639 {
640 \tl_set_eq:cc
641 { l@@_#1_strutcontent_tl }
642 { g@@_#1_strutcontent_tl }
643 \cs_set_eq:cc
644 { #1 }
645 { @@_#1_use_strutcontent:n }
646 }
647 % \end{macrocode}
648 % \end{macro}
649 %
650 % \begin{macro}{\@@_finalize:n}
651 % Restore |\g@@_#1_strutcontent_tl| for the surrounding group.
652 % \begin{macrocode}
653 \cs_new:Nn \@@_finalize:n
654 {
655 \tl_set_eq:cc
656 { g@@_#1_strutcontent_tl }
657 { l@@_#1_strutcontent_surround_tl }
658 }
659 % \end{macrocode}
660 % \end{macro}
661 %
662 % \subsection{Main command}
663 %
664 % Sequence of active braces.
665 % \begin{macrocode}
666 \seq_new:N \l@@_active_brace_seq
667 % \end{macrocode}
668 %
669 % \begin{macro}{\@@_update_active_braces:}
670 % Update the sequence of active brace commands.
671 % \begin{macrocode}
672 \cs_new:Nn \@@_update_active_braces:
673 {
674 % \end{macrocode}
675 % Restore standard brace commands (in the case the command is set is the
676 % surrounding group, and unset in the current one).
677 % \begin{macrocode}
678 \seq_map_inline:Nn \l@@_active_brace_seq
679 {
680 \cs_set_eq:cc { ##1 } { @@_##1_std_cmd:n }
681 }
682 % \end{macrocode}
683 % Set \cs{l@@_active_brace_seq}.
684 % \begin{macrocode}
685 \seq_clear:N \l@@_active_brace_seq
686 \seq_map_inline:Nn \l_bracealign_brace_seq
687 {
688 \bool_if:cT { l@@_##1_bool }
689 { \seq_put_right:Nn \l@@_active_brace_seq { ##1 } }
690 }
691 }
692 % \end{macrocode}
693 % \end{macro}
694 %
695 % \begin{macro}{\bracealign_bracealign:n}
696 % Align braces in |#1|.
697 % \begin{macrocode}
698 \cs_new:Nn \bracealign_bracealign:n
699 {
700 % \end{macrocode}
701 %
702 % List active brace commands.
703 % \begin{macrocode}
704 \@@_update_active_braces:
705 % \end{macrocode}
706 %
707 % Set the braces to collect their contents.
708 % \begin{macrocode}
709 \seq_map_inline:Nn \l@@_active_brace_seq
710 { \@@_initialize:n { ##1 } }
711 % \end{macrocode}
712 %
713 % Expand |#1| in an unused box.
714 % \begin{macrocode}
715 \hbox_set:Nn \l_tmpa_box { $ #1 $ }
716 % \end{macrocode}
717 %
718 % Set the braces to automatically use a strut, and align.
719 % \begin{macrocode}
720 \seq_map_inline:Nn \l@@_active_brace_seq
721 { \@@_use_strutcontent:n { ##1 } }
722 % \end{macrocode}
723 %
724 % Typeset |#1|.
725 % \begin{macrocode}
726 #1
727 % \end{macrocode}
728 %
729 % Finalize.
730 % \begin{macrocode}
731 \seq_map_inline:Nn \l@@_active_brace_seq
732 { \@@_finalize:n { ##1 } }
733 }
734 % \end{macrocode}
735 % \end{macro}
736 %
737 % \subsection{User interface}
738 %
739 % \begin{macro}{\bracealignsetup}
740 % Set \pkg{bracealign} keys.
741 % \begin{macrocode}
742 \NewDocumentCommand { \bracealignsetup } { m }
743 {
744 \keys_set:nn { bracealign } { #1 }
745 }
746 % \end{macrocode}
747 % \end{macro}
748 %
749 % \begin{environment}{bracealign}
750 % Main environment.
751 % \begin{macrocode}
752 \NewDocumentEnvironment { bracealign } { O{} b }
753 {
754 \bracealignsetup{ #1 }
755 \bracealign_bracealign:n { #2 }
756 }
757 {
758 }
759 % \end{macrocode}
760 % \end{environment}
761 %
762 % \subsection{Default braces}
763 %
764 % The |clist| that stores the default brace commands.
765 % \begin{macrocode}
766 \clist_new:N \l@@_default_brace_clist
767 \keys_define:nn { bracealign }
768 {
769 default-braces .clist_set:N = \l@@_default_brace_clist,
770 default-braces .initial:n =
771 {
772 \underbrace, \overbrace,
773 \underbracket, \overbracket,
774 \underparen, \overparen
775 },
776 }
777 % \end{macrocode}
778 %
779 % Define the switches for the commands initially in
780 % \cs{l@@_default_brace_clist} to make them available in the preamble
781 % (these commands are added through the hook |begindocument|).
782 % \begin{macrocode}
783 \clist_map_inline:Nn \l@@_default_brace_clist
784 {
785 \@@_define_switches:N #1
786 }
787 % \end{macrocode}
788 %
789 % \subsection{Hook: \texttt{begindocument}}
790 %
791 % All these packages define brace commands. Wait for their commands definition.
792 % \begin{macrocode}
793 \clist_map_inline:nn
794 {
795 mathtools,
796 unicode-math-luatex, unicode-math-xetex,
797 libertinus, libertinust1math,
798 stix2-type1, stix2
799 }
800 { \hook_gset_rule:nnnn { begindocument } { . } { after } { #1 } }
801 % \end{macrocode}
802 %
803 % Add braces in \cs{l@@_default_brace_clist}.
804 % \begin{macrocode}
805 \hook_gput_code:nnn { begindocument } { . }
806 {
807 \clist_map_inline:Nn \l@@_default_brace_clist
808 {
809 \cs_if_exist:NT #1 { \bracealign_add_brace:N #1 }
810 }
811 }
812 % \end{macrocode}
813 %
814 %\iffalse
815 %</package> ^^A End of package implementation.
816 %\fi
817 %
818 % \iffalse % ^^A The following is not for doc
819 %
820 %<*docstyle>
821 %
822 % \section*{bracealign-doc package}
823 %
824 % The following define some styles used for documentation and should not be
825 % included in the documentation itself.
826 %
827 % \subsection*{Packages}
828 %
829 % \begin{macrocode}
830 \RequirePackage{xcolor}
831 \RequirePackage{metalogo}
832 \PassOptionsToPackage{hyperref}{xcolor}
833 \RequirePackage[many]{tcolorbox}
834 \tcbuselibrary{listings}
835 \tcbuselibrary{documentation}
836 \hypersetup{hidelinks}
837 % \end{macrocode}
838 %
839 % \subsection*{Colors}
840 %
841 % \begin{macrocode}
842 \definecolor{bracealign_lavender}{rgb}{0.92,0.92,1}
843 \definecolor{bracealign_darkblue}{rgb}{0.1,0.2,0.5}
844 \definecolor{bracealign_darkgreen}{rgb}{0,0.39,0}
845 \definecolor{bracealign_beige}{rgb}{.96,.96,.86}
846 \colorlet{bracealign_commands}{bracealign_darkblue}
847 \colorlet{bracealign_keys}{bracealign_darkgreen}
848 \colorlet{bracealign_lengths}{violet}
849 \colorlet{bracealign_options}{Definition} % from tcolorbox documentation
850 % \end{macrocode}
851 %
852 % \subsection*{listings styles}
853 %
854 % \begin{macrocode}
855 \lstdefinestyle{lstbracealigndoc}{%
856 language = [LaTeX]TeX,
857 alsoletter = {_,:},% for expl3
858 columns = fullflexible,
859 keepspaces = true,
860 keywordstyle = {\bfseries\color{bracealign_darkblue}},
861 texcsstyle = *{\bfseries\color{bracealign_darkblue}},
862 commentstyle = {\color{gray}},
863 identifierstyle = {\color{bracealign_darkgreen}},
864 morekeywords = {},% keywordsprefix needs a morekeywords before
865 keywordsprefix = {\\},
866 % \end{macrocode}
867 % For literate, the extra braces around the replacement text avoid the error: "Argument of |lst@FillFixed@| has an extra \}."
868 % \begin{macrocode}
869 literate = *{\$}{{\textcolor{red}{\$}}}{1}
870 {\&}{{\textcolor{red}{\&}}}{1}
871 {\}}{{\textcolor{darkgray}{\}}}}{1}
872 {\{}{{\textcolor{darkgray}{\{}}}{1}
873 {\\\\}{{\textcolor{red}{\textbackslash\textbackslash}}}{2}
874 % \begin{macrocode}
875 % One \% and four spaces to remove extra lines added by \cs{macrocode}
876 % \end{macrocode}
877 {\%\ \ \ \ }{}0,
878 basicstyle = \ttfamily\footnotesize,
879 frame = none,
880 framesep = 0pt,
881 aboveskip = 0pt,
882 belowskip = 0pt,
883 }
884 \lstdefinestyle{lstbracealigncode}{%
885 style = lstbracealigndoc,
886 backgroundcolor = \color{bracealign_beige},
887 breakindent = 1cm,
888 numbers = left,
889 numberstyle = \scriptsize\ttfamily\color{gray},
890 aboveskip = \smallskipamount,
891 belowskip = \smallskipamount,
892 }
893 % \end{macrocode}
894 %
895 % \subsection*{tcolorbox}
896 %
897 % \begin{macrocode}
898 \tcbset{% copied and adapted from tcolorbox.doc.s_main.sty
899 documentation listing style=lstbracealigndoc,%
900 doc keypath=bracealign,
901 size=small,%
902 % verbatim ignore percent,
903 %% styles
904 docexample/.style={%
905 bicolor jigsaw,
906 before skip balanced=\medskipamount,
907 after skip balanced=\medskipamount,
908 fonttitle=\bfseries,
909 fontlower=\normalfont,
910 halign lower=center,
911 colframe=bracealign_darkblue,
912 colback=bracealign_lavender,
913 colbacklower=white,
914 drop fuzzy shadow,
915 },
916 color key=bracealign_keys,
917 color command=bracealign_commands,
918 color length=bracealign_lengths,
919 doc head key={fontlower=\footnotesize, collower=darkgray},
920 before doc body={\parskip=\smallskipamount},
921 }
922 % \end{macrocode}
923 %
924 % Inline code
925 %
926 % \begin{macrocode}
927 \DeclareTotalTCBox{\code}{ v }
928 {
929 verbatim,
930 colframe=bracealign_beige,
931 colback=bracealign_beige,
932 sharp corners,
933 size=tight,
934 left=2pt,
935 right=2pt,
936 }
937 {%
938 \strut\lstinline[basicstyle=\ttfamily\small\color{bracealign_darkblue}]!#1!%
939 }
940 % \end{macrocode}
941 %
942 % \subsection*{Index}
943 %
944 % To deal with DocStrip @@ prefix, use '=' as index actual, in place of '@'.
945 % \begin{macrocode}
946 \begin{filecontents*}{\jobname.mst}
947 actual '='
948 \end{filecontents*}
949 % \begin{macrocode}
950 \tcbset{%
951 index actual={=},
952 index colorize=true,
953 index gather all,
954 index format=pgfsection,
955 }
956 % \end{macrocode}
957 % Redefine \cs{tcb@doc@index@pgfsection} to add prologue (adapted from
958 % tcbdocumentation.code.tex).
959 % \begin{macrocode}
960 \def\tcb@doc@index@pgfsection{%
961 \def\index@prologue{%
962 \section*{\kvtcb@text@index}\addcontentsline{toc}{section}{\kvtcb@text@index}
963 {\small%
964 Entries listed in the categories ``commands" and ``internal macros" also
965 include references to package implementation. }
966 \bigskip\par\noindent%
967 }%
968 \tcb@doc@index@pgf@%
969 }
970 % \end{macrocode}
971 % Unset |\lst@UM| before indexing, to deal with comma (avoid |\unhbox \voidb@x
972 % \kern \z@| in index file, see: \url{https://tex.stackexchange.com/a/510108}).
973 % \begin{macrocode}
974 \newcommand{\indexmacro}[1]{%
975 \begingroup
976 \let\lst@UM\@empty%
977 \index{{Commands!#1=\tcbIndexPrintComC {#1}}}%
978 \endgroup
979 }
980 \newcommand{\indexmacrointernal}[1]{%
981 \begingroup
982 \let\lst@UM\@empty%
983 \index{{Internal macros!#1=\tcbIndexPrintComC {#1}}}%
984 \endgroup
985 }
986 \newcommand{\indexlength}[1]{%
987 \begingroup
988 \let\lst@UM\@empty%
989 \index{{Lengths!#1=\tcbIndexPrintLenC {#1}}}%
990 \endgroup
991 }
992 % \end{macrocode}
993 %
994 % \subsection*{Redefinition of macrocode environment}
995 %
996 % \begin{macrocode}
997 \let\macrocode\relax
998 \lstnewenvironment{macrocode}{%
999 \lstset{%
1000 name=macrocode,
1001 firstnumber=auto,
1002 style=lstbracealigncode,
1003 showlines=false,
1004 keepspaces=true,
1005 % \end{macrocode}
1006 % Commands identification and indexing
1007 %
1008 % Note: index works badly with inherited styles. It seems that "texcs" and
1009 % "index" keys should be set together.
1010 % \begin{macrocode}
1011 texcs = [2]{% commands
1012 bracealignsetup
1013 ,bracealign_add_brace:e
1014 ,bracealign_add_brace:n
1015 ,bracealign_add_brace:N
1016 ,bracealign_bracealign:n
1017 },
1018 index = [2][texcs2],%
1019 indexstyle = [2]\indexmacro,%
1020 texcs = [3]{% lengths
1021 },
1022 index = [3][texcs3],%
1023 indexstyle = [3]\indexlength,%
1024 % \end{macrocode}
1025 % Internal macros identification and indexing
1026 % \begin{macrocode}
1027 texcs = [4]{% internal macros (@@@@ → @@ with DocStrip)
1028 @@@@_define_switches:e
1029 ,@@@@_define_switches:n
1030 ,@@@@_define_switches:N
1031 ,@@@@_finalize:n
1032 ,@@@@_initialize:n
1033 ,@@@@_update_active_braces:
1034 ,@@@@_use_strutcontent:n
1035 ,l@@@@_active_brace_seq
1036 ,l@@@@_default_brace_clist
1037 ,l@@@@_overbrace_bool
1038 ,l@@@@_overbracket_bool
1039 ,l@@@@_overparen_bool
1040 ,l@@@@_underbrace_bool
1041 ,l@@@@_underbracket_bool
1042 ,l@@@@_underparen_bool
1043 },
1044 index = [4][texcs4],%
1045 indexstyle = [4]\indexmacrointernal,%
1046 % \end{macrocode}
1047 % Keys identification and indexing ^^A works badly if keys have spaces
1048 % \begin{macrocode}
1049 morekeywords = [2]{%
1050 bracealign/add-brace
1051 ,bracealign/add-braces
1052 ,bracealign/default-braces
1053 ,bracealign/nooverbrace
1054 ,bracealign/nooverbracket
1055 ,bracealign/nooverparen
1056 ,bracealign/nounderbrace
1057 ,bracealign/nounderbracket
1058 ,bracealign/nounderparen
1059 ,bracealign/overbrace
1060 ,bracealign/overbracket
1061 ,bracealign/overparen
1062 ,bracealign/underbrace
1063 ,bracealign/underbracket
1064 ,bracealign/underparen
1065 },
1066 index = [3][keywords2],%
1067 indexstyle = [3]\lstindexmacro,%
1068 }
1069 % \end{macrocode}
1070 % Save and restore the line number (not done by environments defined with
1071 % |\lstnewenvironment|, see \url{https://tex.stackexchange.com/a/95048}):
1072 % \begin{macrocode}
1073 \csname\@lst @SetFirstNumber\endcsname
1074 }{%
1075 \csname \@lst @SaveFirstNumber\endcsname
1076 }
1077 % \end{macrocode}
1078 %
1079 % \subsection*{Redefinition of macro environment}
1080 %
1081 % \begin{macrocode}
1082 \DeclareDocumentEnvironment{macro}{m}{%
1083 % \end{macrocode}
1084 % Extraction of macro name. Save/restore current \cs{escapechar} in \cs{count@}.
1085 % \begin{macrocode}
1086 \count@\escapechar \escapechar=-1
1087 \edef\macroname{\string#1}
1088 \escapechar\count@
1089 \marginpar{%
1090 \parbox{0.88\linewidth}{%
1091 \scriptsize\flushright\ifcsdef{r@com:\macroname}{\refCom*{\macroname}}{\cs{\macroname}}%
1092 }%
1093 }
1094 }{% end of macro environment
1095 }
1096 % \end{macrocode}
1097 %
1098 % \subsection*{Documentation styles}
1099 %
1100 % \subsubsection*{Tool for references}
1101 %
1102 % \begin{macrocode}
1103 \def\refDoc#1{\tcb@ref@doc{#1}}
1104 % \end{macrocode}
1105 %
1106 % \subsubsection*{Package name}
1107 %
1108 % \begin{macrocode}
1109 \newcommand{\pkg}[1]{\textsf{#1}}
1110 % \end{macrocode}
1111 %
1112 %
1113 % \subsubsection*{Redefinition of the \cs{cs} command}
1114 %
1115 % To handle |expl3| syntax.
1116 %
1117 % \begin{macrocode}
1118 \ExplSyntaxOn
1119 \cs_new_protected:Nn \bracealigndoc_cs:n
1120 {
1121 \str_set:Nn \l_tmpa_str { #1 }
1122 \exp_args:Ne \texttt{ \c_backslash_str \str_use:N \l_tmpa_str }
1123 }
1124 \cs_generate_variant:Nn \bracealigndoc_cs:n { e }
1125 \RenewDocumentCommand{\cs}{ m }{\bracealigndoc_cs:e { #1} }
1126 \ExplSyntaxOff
1127 % \end{macrocode}
1128 %
1129 % \subsubsection*{Package options}
1130 %
1131 % Definition of docOption environment to document package options, like keys.
1132 % \begin{macrocode}
1133 \newrobustcmd{\tcbIndexPrintOptionCA}[1]{% adapted from \tcbIndexPrintKeyCA
1134 \tcb@Index@Print@CA{#1}{bracealign_options}{package option}%
1135 }
1136 \newrobustcmd{\tcbIndexPrintOptionC}[1]{% adapted from \tcbIndexPrintKeyCA
1137 \tcb@Index@Print@C{#1}{bracealign_options}%
1138 }
1139 \DeclareDocumentEnvironment{docOption}{ O{} m }{%
1140 \begin{docKey*}[]
1141 [doc name={#2}, doc label={opt:#2}, color key=bracealign_options, #1]
1142 {#2}{}{}%
1143 \kvtcb@index@command{%
1144 \kvtcb@doc@sortindex\idx@actual\tcbIndexPrintOptionCA{#2}%
1145 }%
1146 \kvtcb@index@command{%
1147 {Package options}\idx@level\kvtcb@doc@sortindex\idx@actual%
1148 \tcbIndexPrintOptionC{#2}%
1149 }%
1150 }{%
1151 \end{docKey*}%
1152 }
1153 \def\refOpt{\refDoc{key:opt}}
1154 % \end{macrocode}
1155 %
1156 %</docstyle>
1157 %
1158 % \fi %^^A end of \iffalse
1159 %
1160 % \Finale
1161 %
1162 \endinput