Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2016-2018 by Richard Grewe <[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.2
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.2 or later is part of all distributions of LaTeX
14 % version 1999/12/01 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{multilang.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
23 %<pkgtags>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
24 %<pkgsect>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
25 %<package>\ProvidesPackage{multilang}
26 %<*package>
27 [2018/11/02 v0.9b Tools for maintaining documents in multiple languages]
28 %</package>
29 %<pkgtags>\ProvidesPackage{multilang-tags}[2018/11/02 v0.9b Filtering of multilingual macros by tags]
30 %<pkgsect>\ProvidesPackage{multilang-sect}[2018/11/02 v0.9b Multilingual sectioning environments]
31 %
32 %<*driver>
33 \documentclass{ltxdoc}
34 \usepackage[columns=2]{idxlayout}
35 \usepackage{xcolor}
36 \usepackage{xspace}
37 \usepackage[inline]{enumitem}
38 \usepackage{showexpl}
39 \lstset{gobble=2,frame=trbl,backgroundcolor=\color{black!5!white},width=0.475\textwidth}
40 \lstset{basicstyle=\footnotesize\fontfamily{pcr}\selectfont}
41 \lstset{explpreset={columns=fixed,numbers=none,language={}}}
42 \lstset{preset={\small\sffamily},overhang=2cm,pos=r,varwidth=false}
43 \usepackage{pbox}
44 \newcommand\NiceDescribeStuff[2]{% #1=margin text, #2=body text
45 \medskip\par\noindent\leavevmode%
46 \marginpar{\hfill\pbox[t]{2\marginparwidth}{\ttfamily #1}%
47 \hspace*{-\marginparsep}}%
48 \ifstrempty{#2}{}{#2\smallskip\\}}
49 \newcommand\NiceDescribeEnv[3][]{% #1=index list, #2=envname, #3=parameters
50 \NiceDescribeStuff{%
51 \textcolor{gray}{\cs{begin}}\string{#2\string}\\
52 \textcolor{gray}{\cs{end}}\string{#2\string}}{#3}%
53 \ifstrempty{#1}
54 {\SpecialEnvIndex{#1}}%
55 {\forcsvlist{\SpecialEnvIndex}{#1}}%
56 \ignorespaces}
57 \newcommand\NiceDescribeMacro[2]{% #1=macro, #2=parameters
58 \NiceDescribeStuff{\hbox to 0pt{\hss\string#1}}{#2}%
59 \SpecialUsageIndex{#1}\ignorespaces}
60 \newcommand\NiceDescribeConstant[1]{% #1=constant
61 \NiceDescribeStuff{\hbox to 0pt{\hss #1\quad}}{}\ignorespaces}
62 \makeatletter
63 \newcommand\SaveSecs{%
64 \@for\SC:=section,subsection,subsubsection\do{%
65 \csedef{SC@\SC}{\the\value{\SC}}%
66 \setcounter{\SC}{0}}}
67 \newcommand\RestoreSecs{%
68 \@for\SC:=section,subsection,subsubsection\do{%
69 \setcounter{\SC}{\csuse{SC@\SC}}}}
70 \makeatother
71 \newcommand\ThisPackage{\textsf{multilang}\xspace}
72 \usepackage{hypdoc}
73 \usepackage[capitalise,nameinlink]{cleveref}
74 % the following packages are for the examples
75 \usepackage[german,english]{babel}
76 \usepackage[languages={english,german}]{multilang}
77 \usepackage[autostyle=true]{csquotes}
78 \usepackage[useregional]{datetime2}
79 \usepackage{sectionbox}
80 \usepackage{translations}
81 \usepackage{multilang-tags}
82 \usepackage{multilang-sect}
83 % end of examples packages
84 \EnableCrossrefs
85 \CodelineIndex
86 \RecordChanges
87 \begin{document}
88 \DocInput{multilang.dtx}
89 \PrintChanges
90 \PrintIndex
91 \end{document}
92 %</driver>
93 % \fi
94 %
95 % \CheckSum{0}
96 %
97 % \CharacterTable
98 % {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
99 % 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
100 % Digits \0\1\2\3\4\5\6\7\8\9
101 % Exclamation \! Double quote \" Hash (number) \#
102 % Dollar \$ Percent \% Ampersand \&
103 % Acute accent \' Left paren \( Right paren \)
104 % Asterisk \* Plus \+ Comma \,
105 % Minus \- Point \. Solidus \/
106 % Colon \: Semicolon \; Less than \<
107 % Equals \= Greater than \> Question mark \?
108 % Commercial at \@ Left bracket \[ Backslash \\
109 % Right bracket \] Circumflex \^ Underscore \_
110 % Grave accent \` Left brace \{ Vertical bar \|
111 % Right brace \} Tilde \~}
112 %
113 % \changes{v0.9}{2017/08/30}{Initial version}
114 % \changes{v0.9b}{2018/11/02}{Package author's name change}
115 %
116 % \GetFileInfo{multilang.dtx}
117 %
118 % \DoNotIndex{\newcommand,\newenvironment,\def,\gdef,\edef}
119 %
120 %
121 % \title{The \ThisPackage package\thanks{This document
122 % corresponds to \ThisPackage~\fileversion, dated \filedate.
123 % The package is available online at
124 % \url{http://www.ctan.org/pkg/multilang} and
125 % \url{https://github.com/Ri-Ga/multilang}.}}
126 % \author{Richard Grewe \\ \texttt{[email protected]}}
127 %
128 % \maketitle
129 %
130 % \begin{abstract}
131 % Maintaining a \LaTeX{} document with translations for multiple languages
132 % can be cumbersome and error-prone.
133 % The \ThisPackage package provides a set of macros for defining macros and
134 % environments as wrappers around existing macros and environments.
135 % These wrappers allow one to clearly specify multiple translations for the
136 % arguments to the wrapped macros and environments while only the
137 % translation of the document's language is actually shown.
138 % Choosing a translation then is as simple as choosing the document's
139 % language via \textsf{babel} or \textsf{polyglossia}.
140 % \end{abstract}
141 %
142 % \section{Introduction}
143 % \label{sec:Introduction}
144 %
145 % The main goal of the \ThisPackage package is to facilitate the
146 % definition of macros and environments with which documents can be
147 % provisioned in multiple languages.
148 % To be more concrete, \ThisPackage facilitates
149 % \begin{enumerate}
150 % \item the specification of content translations:
151 %
152 % \begin{itemize}[noitemsep]
153 % \item Arguments to macros are specified by their name such that multiple
154 % translations do not clutter up the \LaTeX{} code that easily.
155 % \item If you forget to specify a mandatory argument in a language,
156 % \ThisPackage shows an error when you compile for that language.
157 % \end{itemize}
158 %
159 % \item the maintenance of translations:\smallskip
160 %
161 % Translations of content that is passed as an argument to a macro can be kept
162 % closely together such that you can keep track of which units belong together
163 % and can keep consistency among translations across content changes.
164 %
165 % \item the selection of a document language:\smallskip
166 %
167 % You simply specify the language with \textsf{babel} or \textsf{polyglossia}
168 % and \ThisPackage selects the translation you provided for the language.
169 % \end{enumerate}
170 %
171 % The motivating example that lead to the development of this package are CVs
172 % (curricula vitae). Suppose you want to maintain a CV document that contains
173 % the union of all your relevant personal data, education, achievements, etc.
174 % You update the CV from time to time with new achievements. Since you want to
175 % prepare for the possibility that you might apply nationally as well as
176 % internationally, you maintain the CV document in multiple languages (e.g.,
177 % your mother language and English).
178 % When you use the CV in a concrete job application, you
179 % \begin{enumerate*}[label=(\arabic*)]
180 % \item filter out all details that are irrelevant for the position that you
181 % apply for
182 % and
183 % \item select a suitable language for the employer.
184 % \end{enumerate*}
185 %
186 % This package provides a set of basic macros for the definition of
187 % multilingual macros and multilingual environments. The following example
188 % illustrates such a macro and how it could be used.
189 % \SaveSecs
190 %
191 % \begin{LTXexample}[preset={\newcommand\Sec[1]{\section{Foobar}}}]
192 % % ...
193 % \usepackage[german,english]{babel}
194 % \usepackage[languages={english,german}]
195 % {multilang}
196 % % ...
197 % \begin{document}
198 % \Sec{
199 % title/english={Foobar},
200 % title/german ={Dingsda}
201 % }
202 % ...
203 % \end{document}
204 % \end{LTXexample}
205 % \RestoreSecs
206 % \Cref{sec:Usage} describes how a macro such as |\Sec| in the above
207 % example can be defined with \ThisPackage. The \lcnamecref{sec:Usage} also
208 % describes how analogous environments can be defined.
209 % \Cref{sec:Types} describes extensible argument types.
210 % \Cref{sec:Extensions} describes two extension packages,
211 % \textsf{multilang-sect} and \textsf{multilang-tags} for multilingual
212 % sectioning and, respectively, for filtering multilingual macros and
213 % environments.
214 %
215 %
216 % \section{Usage}
217 % \label{sec:Usage}
218 %
219 % \subsection{Package Options}
220 %
221 % \NiceDescribeConstant{languages}
222 % The \ThisPackage package has a single option: |languages|. This option
223 % expects a comma-separated list of language names. The ordering of the list
224 % does not make a difference. Through this option, one sets the languages for
225 % which translations can be provided. By default, the list is empty such that
226 % no translations can be specified.
227 % The example in \cref{sec:Introduction} demonstrates how this option can be
228 % used.
229 %
230 %
231 % \subsection{Multilingual Macros}
232 % \label{sec:Usage-Macros}
233 %
234 % \NiceDescribeMacro{\NewMultilangCmd}{\marg{command}\marg{options}}
235 % A multilingual macro can be defined via the |\NewMultilangCmd| macro.
236 % The macro defines \meta{command} as a macro that accepts a single argument.
237 % That is, the signature of \meta{command} is \meta{command}\marg{kvarg}. The
238 % argument, \meta{kvarg}, is a comma-separated key-value list.
239 % The \meta{options} argument takes the form of a comma-separated key-value
240 % list and specifies what \meta{command} does, including how \meta{kvarg} is
241 % interpreted. The following keys are defined for \meta{options}:
242 % \begin{description}[noitemsep]
243 % \item[|command|:]
244 % This key is to be used in the form ``|command=|\meta{c}'', where \meta{c}
245 % is an already existing command.
246 % The key specifies that \meta{command} is defined to invoke \meta{c} with
247 % some arguments.
248 % Example: see \cref{sec:Usage-margs}.
249 % \item[|margs|:]
250 % This key is to be used in the form ``|margs={|\meta{csvlist}|}|'', where
251 % \meta{csvlist} is a comma-separated list of names.
252 % The key specifies names for the mandatory arguments of \meta{c}, in the
253 % order specified.
254 % If \meta{c} is a macro that takes $n$ mandatory arguments, then
255 % \meta{csvlist} should be a list of $n$ names. If \meta{arg-i} is the
256 % $i$-th entry in \meta{csvlist}, then the $i$-th mandatory
257 % argument to \meta{c} can be specified as \meta{v} in the invocation of
258 % \meta{command} as follows:
259 % ``\meta{command}|{...,|\meta{arg-i}|=|\meta{v}|,...}|''.
260 % Example: see \cref{sec:Usage-margs}.
261 % \item[|oargs|:]
262 % This key is to be used in the form ``|oargs={|\meta{csvlist}|}|'', where
263 % \meta{csvlist} is a comma-separated list of names.
264 % This key is analogous to |margs|, but for optional arguments to \meta{c}.
265 % Example: see \cref{sec:Usage-oargs}.
266 % \item[|starred|:]
267 % This key is to be used simply as
268 % ``|starred=|\meta{bool}'', where \meta{bool} must be |true| or |false|,
269 % or just as ``|starred|'', which is equivalent to ``|starred=true|''.
270 % If \meta{bool} is |true|, then ``\meta{command}|*{...}|'' can be used to
271 % invoke ``\meta{c}|*...|''.
272 % Example: see \cref{sec:Usage-starred}.
273 % \item[|disablable|:]
274 % This key is to be used simply as
275 % ``|disablable=|\meta{bool}'', where \meta{bool} must be |true| or |false|,
276 % or just as ``|disablable|'', which is equivalent to ``|disablable=true|''.
277 % If \meta{bool} is |true|, then the invocation of \meta{c} in
278 % \meta{command} can be suppressed via
279 % ``\meta{command}|{...,disabled,...}|''.
280 % Example: see \cref{sec:Usage-disablable}.
281 % \item[|defaults|:]
282 % This key is to be used as
283 % ``|defaults={...,|\meta{arg}|=|\meta{value}|,...}|''.
284 % Each key \meta{arg} should be the name of an optional or mandatory
285 % argument and \meta{value} should be the intended default value for this
286 % argument.
287 % Example: see \cref{sec:Usage-defaults}.
288 % \item[|alias/...|:]
289 % This key is to be used as ``|alias/|\meta{name}|={|\meta{arglist}|}|'',
290 % where \meta{name} specifies the name of the alias and \meta{arglist} is a
291 % possibly empty comma-separated list of argument names (optional or
292 % mandatory arguments allowed).
293 % Example: see \cref{sec:Usage-alias}.
294 % \end{description}
295 % The remainder of \cref{sec:Usage-Macros} provides examples based on the
296 % |\section| macro.
297 %
298 %
299 % \subsubsection{Basic Usage}
300 % \label{sec:Usage-margs}
301 % The following example shows how the |\Section| macro used in the example of
302 % \cref{sec:Introduction} can be defined. We leave out the \textsf{babel} code
303 % in this \lcnamecref{sec:Usage} for more concise example code.
304 %
305 % \SaveSecs
306 % \begin{LTXexample}[morekeywords={NewMultilangCmd,command,margs}]
307 % \NewMultilangCmd{\Sec}{
308 % command=\section, margs=title}
309 % \Sec{
310 % title/english={Foobar},
311 % title/german ={Dingsda}
312 % }
313 % \end{LTXexample}
314 % \RestoreSecs
315 %
316 %
317 % \paragraph{Language-independent arguments.}
318 % Sometimes, arguments to macros need no translation. For instance, if an
319 % argument is a technical term or a name, it can remain in the original
320 % language. To avoid redundancy, in such instances the language part of a
321 % mandatory or optional argument can be omitted to specify the argument for
322 % all languages.
323 %
324 % \SaveSecs
325 % \begin{LTXexample}[preset={\NewMultilangCmd{\Sec}{margs=title,oargs=short,command=\section}}]
326 % \Sec{title=multilang}
327 % \end{LTXexample}
328 % \RestoreSecs
329 %
330 %
331 % \paragraph{Forced foreign-language arguments.}
332 % \label{sec:Usage-forced-language}
333 % A particular instance of a language-independent argument is the case in which
334 % the argument shall explicitly be typeset in a particular language. For
335 % instance, the argument might use macros that internally determine the
336 % display based on the selected language. The following example shows the case
337 % of forcing German display of the |\enquote| macro.
338 %
339 % \SaveSecs
340 % \begin{LTXexample}[preset={\NewMultilangCmd{\Sec}{margs=title,oargs=short,command=\section}}]
341 % \usepackage[autostyle=true]{csquotes}
342 % %...
343 % \Sec{title/german!=\enquote{multilang}}
344 % \end{LTXexample}
345 % \RestoreSecs
346 %
347 %
348 % \subsubsection{Optional Arguments}
349 % \label{sec:Usage-oargs}
350 % Macros like |\section| don't just have a mandatory argument (the section
351 % title) but also an optional argument (a short title for the table of
352 % contents). We can make this optional argument accessible via the |oargs|
353 % option as follows.
354 % The displayed result does not show any difference as we don't have the table
355 % of contents here.
356 %
357 % \SaveSecs
358 % \begin{LTXexample}[morekeywords={oargs}]
359 % \NewMultilangCmd{\Sec}{
360 % command=\section, margs=title, oargs=short}
361 % \Sec{
362 % title/english={Foobar},
363 % title/german ={Dingsda},
364 % short/english={F},
365 % short/german ={D},
366 % }
367 % \end{LTXexample}
368 % \RestoreSecs
369 %
370 %
371 % \subsubsection{Starred Macros}
372 % \label{sec:Usage-starred}
373 % Some macros can be altered in their behavior with a star (``|*|'') after the
374 % macro. The |\section| command is an example of such a macro: |\section*|
375 % suppresses the display of the section number. The star can be transferred to
376 % the command defined via |\NewMultilangCmd| as the following example
377 % illustrates. Note the exclamation mark after ``|german|''.
378 %
379 % \SaveSecs
380 % \begin{LTXexample}[morekeywords={starred}]
381 % \NewMultilangCmd{\Sec}{starred,
382 % command=\section, margs=title, oargs=short}
383 % \Sec{title=Foo}
384 % \Sec*{title=Bar}
385 % \end{LTXexample}
386 % \RestoreSecs
387 %
388 %
389 % \subsubsection{Disabling Display}
390 % \label{sec:Usage-disablable}
391 % When a macro is defined with the |disablable| option, it can be passed the
392 % |disabled| argument which disables the display of the macro. One might
393 % consider this a nicer way to disable content than commenting out the macro.
394 %
395 % \SaveSecs
396 % \begin{LTXexample}[morekeywords={disablable}]
397 % \NewMultilangCmd{\Sec}{disablable,
398 % command=\section, margs=title, oargs=short}
399 % \Sec{title=Foo}
400 % \Sec{title=Bar,disabled}
401 % \end{LTXexample}
402 % \RestoreSecs
403 %
404 %
405 % \subsubsection{Default Arguments}
406 % \label{sec:Usage-defaults}
407 % When a mandatory or optional argument shall by default assume a particular
408 % value if no value is specified for the argument in the argument to
409 % \meta{command}, this can be specified via the |defaults| key as the
410 % following example demonstrates.
411 %
412 % \SaveSecs
413 % \begin{LTXexample}[morekeywords={defaults}]
414 % \NewMultilangCmd{\Sec}{
415 % command=\section, margs=title,
416 % defaults={title={???}}}
417 % \Sec{}
418 % \end{LTXexample}
419 % \RestoreSecs
420 % Defaults can be particularly useful for mandatory arguments of commands
421 % that take multiple arguments and that can often be left empty.
422 % Essentially, argument defaults turn mandatory arguments of
423 % macros to optional arguments.
424 %
425 %
426 % \subsubsection{Argument Aliases}
427 % \label{sec:Usage-alias}
428 % Aliases allow one to specify argument names of three different kinds:
429 % \begin{description}[nosep]
430 % \item[direct aliases:]
431 % A direct alias declares an argument name that can then be used as a
432 % substitute for some mandatory or optional argument.
433 % The |heading| argument in the following example shows how direct aliases
434 % can be declared.
435 % \item[combiner aliases:]
436 % A combiner alias declares an argument name that acts as a substitute for a
437 % sequence of mandatory or optional arguments.
438 % Such aliases particularly help maintaining concise \LaTeX{} source code
439 % when argument values are rather short, as |both| in the following example
440 % shows.
441 % \item[comment aliases:]
442 % A comment alias declares an argument name that represents no mandatory or
443 % optional argument. That is, a value specified for a comment alias is not
444 % used as an argument to the |command| and can, hence, be used for capturing
445 % comments or values for future use.
446 % \end{description}
447 %
448 % \SaveSecs
449 % \begin{LTXexample}[morekeywords={alias}]
450 % \NewMultilangCmd{\Sec}{
451 % command=\section, margs=title, oargs=short,
452 % alias/heading=title,
453 % alias/both={title,short},
454 % alias/remark}
455 % \Sec{
456 % both/english={Foobar}{Foo},
457 % both/german ={Dingsda}{Dings}}
458 % \Sec{
459 % heading=Baz,
460 % remark={select heading+translate}}
461 % \end{LTXexample}
462 % \RestoreSecs
463 %
464 %
465 % \subsection{Multilingual Environments}
466 %
467 % \NiceDescribeMacro{\NewMultilangEnv}{\marg{environment}\marg{options}}
468 % The usage of the |\NewMultilangEnv| macro is analogous to the usage of
469 % the macro |\NewMultilangCmd|, except for the following differences:
470 % \begin{itemize}[noitemsep]
471 % \item The first argument, \meta{environment}, expects the name of an
472 % environment that shall be defined.
473 % \item In the \meta{options}, the |environment| key substitutes the |command|
474 % key and expects an environment name.
475 % \item The |starred| key is not available. Following standard \LaTeX{}
476 % practices, if you want to define a starred environment, simply use the
477 % starred name for \meta{environment}.
478 % \end{itemize}
479 % Due to the similarity to |\NewMultilangCmd|, we don't provide separate
480 % examples for all the individual features.
481 % Continuing the line of examples started before, we again use an example
482 % about sections -- just now with an environment for section boxes, as
483 % provided by the \textsf{sectionbox} package.
484 %
485 % \SaveSecs
486 % \begin{LTXexample}[morekeywords={NewMultilangEnv}]
487 % \usepackage{sectionbox}
488 % \NewMultilangEnv{SecBox}{
489 % environment=sectionbox,
490 % disablable, margs=title, oargs=width}
491 %
492 % \begin{SecBox}{title=Foo}
493 % content
494 % \end{SecBox}
495 %
496 % \begin{SecBox}{disabled,title=Bar}
497 % disabled content
498 % \end{SecBox}
499 % \end{LTXexample}
500 % \RestoreSecs
501 %
502 %
503 % \section{Extensible Argument Types}
504 % \label{sec:Types}
505 %
506 % By default, an argument |arg| in a multilingual macro can be specified in
507 % three ways: just ``|arg=...|'', ``|arg/|\meta{language}|=...|'', or
508 % ``|arg/|\meta{language}|!=...|''.
509 % The \ThisPackage package enables one to declare further so called `types'.
510 % These types can be used in place of \meta{language} in the argument syntax.
511 % They can be used for uniformly enabling a special formatting if an argument
512 % is of a particular type (rather than just being text).
513 %
514 % \NiceDescribeMacro{\NewMultilangType}{\oarg{argcount}\marg{typename}\marg{format}}
515 % The |\NewMultilangType| macro declares the \meta{typename} type.
516 % Values passed to arguments of this type must consist of \meta{argcount}
517 % arguments (default: 1). The value is then formatted with \meta{format} when
518 % displayed. The \meta{format} can (and should) contain positional parameters
519 % such as ``|#1|'' for the first argument.
520 % The remainder of this \lcnamecref{sec:Types} demonstrates the use of
521 % the macro by examples.
522 %
523 %
524 % \subsection{Dates via \textsf{datetime2}}
525 %
526 % The \textsf{datetime2} package supports regional (language-specific)
527 % formatting of dates. We can build on this feature such that we don't
528 % have to provide translations of dates. To keep the display
529 % smaller, we here use |\textbf| rather than |\section|.
530 %
531 % \begin{LTXexample}[morekeywords={NewMultilangType,date,daterange}]
532 % \usepackage[useregional]{datetime2}
533 %
534 % \NewMultilangType{date}{\DTMdate{#1}}
535 % \NewMultilangType[2]{daterange}
536 % {\DTMdate{#1}--\DTMdate{#2}}
537 %
538 % \NewMultilangCmd{\Bold}
539 % {margs=title, command=\textbf}
540 %
541 % Date: \Bold{title/date={2017-08-01}}\\
542 % Range: \Bold{title/daterange=
543 % {2017-01-01}{2017-08-01}}
544 % \end{LTXexample}
545 %
546 %
547 % \subsection{Nesting Multilingual Macros}
548 %
549 % Multilingual macros can be used in arguments to multilingual macros.
550 % Coming back to the original motivation for developing \ThisPackage
551 % -- CVs -- you might want a translated two-column layout in which the
552 % right column might be filled with translated list items. The following
553 % example shows how this can be realized.
554 %
555 % \begin{LTXexample}
556 % \usepackage{enumitem}% for "nosep"
557 %
558 % \newcommand\entry[2]{%
559 % \begin{tabular}{p{1cm}p{4cm}}#1&#2
560 % \end{tabular}}
561 %
562 % \NewMultilangType{list}{%
563 % \begin{minipage}[t]{4cm}
564 % \begin{itemize}[nosep]#1
565 % \end{itemize}\end{minipage}}
566 % \NewMultilangCmd{\Entry}
567 % {margs={head,text}, command=\entry}
568 % \NewMultilangCmd{\Item}
569 % {margs=name, command=\item}
570 %
571 % \Entry{head=2017,
572 % text/list={
573 % \Item{name/english=foobar,
574 % name/german =Dingsda}
575 % \Item{name=multilang}}}
576 % \end{LTXexample}
577 %
578 %
579 % \section{Extension Packages}
580 % \label{sec:Extensions}
581 %
582 % The \ThisPackage package comes bundled with a few generic packages that build
583 % on \ThisPackage. These packages are described below.
584 %
585 % \subsection{Sectioning Environments}
586 %
587 % Sectioning environments are provided by the \textsf{multilang-sect} package.
588 % That package defines, for each of \LaTeX's sectioning macros (|\section|,
589 % \ldots, |\subparagraph|) an environment and a starred environment.
590 %
591 % \NiceDescribeEnv[Section,Section*]{Section(*)}{\marg{data}}
592 % This environment shows a section.
593 % It has a single, mandatory argument, named |title|.
594 % It is a disablable environment, i.e., the argument |disabled| can be used in
595 % \meta{data} to disable the display of the whole section.
596 % This environment acts as a proxy for the |\section| macro as it is used by
597 % \ThisPackage (i.e., without optional argument and without the star).
598
599 % \NiceDescribeEnv[SubSection,SubSection*]{SubSection(*)}{\marg{data}}
600 % This environment is analogous to the |Section| environment, just for
601 % sub-sections.
602
603 % \NiceDescribeEnv[SubSubSection,SubSubSection*]{SubSubSection(*)}{\marg{data}}
604 % This environment is analogous to the |Section| environment, just for
605 % sub-sub-sections.
606
607 % \NiceDescribeEnv[Paragraph,Paragraph*]{Paragraph(*)}{\marg{data}}
608 % This environment is analogous to the |Section| environment, just for
609 % paragraphs.
610
611 % \NiceDescribeEnv[SubParagraph,SubParagraph*]{SubParagraph(*)}{\marg{data}}
612 % This environment is analogous to the |Section| environment, just for
613 % sub-paragraphs.
614 % Examples:
615 %
616 % \SaveSecs
617 % \begin{LTXexample}[morekeywords={Section,SubSection}]
618 % \usepackage{multilang-sect}
619 %
620 % \begin{Section}{
621 % title/english = Usage,
622 % title/german = Benutzung,
623 % }
624 % (section content)
625 % \begin{SubSection*}{
626 % title/english = Package Options,
627 % title/german = Paketoptionen,
628 % }
629 % (subsection content)
630 % \end{SubSection*}
631 % \end{Section}
632 % \end{LTXexample}
633 % \RestoreSecs
634 %
635 %
636 % \subsection{Tags}
637 %
638 % Tags are an alternative to individually disabling macros or environments.
639 % They are provided by the \textsf{multilang-tags} package.
640 % A tag is just a word and sets of tags can be assigned to individual usages of
641 % multilingual macros and environments.
642 % As long as no tag filter policy is setup, specifying tags does not influence
643 % what is displayed.
644 %
645 % \NiceDescribeMacro{\SetTagFilter}{\oarg{default}\marg{policy}}
646 % The |\SetTagFilter|\oarg{default}\marg{policy} sets up a tag filter policy.
647 % The \meta{policy} is a comma-separated list of |accept|/|deny| rules.
648 % The \meta{default} argument is either |accept| (the default) or |deny| and
649 % specifies the default policy.
650 % The following toy example demonstrates tag filtering:
651 %
652 % \begin{LTXexample}[morekeywords={SetTagFilter,tags}]
653 % \usepackage{multilang-tags}
654 % \NewMultilangCmd{\Item}{disablable,
655 % command=\item,oargs=dd,margs=dt,
656 % alias/both={dd,dt}}
657 % \SetTagFilter{accept={A}, deny={D}}
658 %
659 % \begin{description}
660 % \Item{tags=A, both={1}{tagged A}}
661 % \Item{tags={A,D}, both={2}{tagged A,D}}
662 % \Item{tags=D, both={3}{tagged D}}
663 % \Item{tags={D,X}, both={4}{tagged D,X}}
664 % \Item{tags=!D, both={5}{tagged !D}}
665 % \Item{tags=X, both={6}{tagged X}}
666 % \end{description}
667 % \end{LTXexample}
668 %
669 % When a multilingual macro, such as |\BasicEntry| in the above example, is
670 % used, whether the macro content is displayed is determined as follows:
671 % \begin{itemize}[nosep]
672 % \item If no |tags| are specified or no tag policy is setup, then the macro
673 % content is displayed.
674 % \item Otherwise, the rules of the tag policy are processed in sequential order
675 % until the specified |tags| match a rule.
676 % A |tags| list matches a rule if at least one tag in the |tags| occurs in the
677 % rule (with or without ``|!|'' prefix).
678 % Let $t$ be the last tag in |tags| that occurs in the rule.
679 % \begin{itemize}[nosep]
680 % \item The macro content is displayed if the rule is an |accept| rule and $t$
681 % is not prefixed with ``|!|'', or if the rule is a |deny| rule and $t$ is
682 % prefixed with ``|!|''.
683 % \item Otherwise the display of the macro content is disabled.
684 % \end{itemize}
685 % \item If the specified |tags| match no rule in the \meta{policy}, then the
686 % macro content is displayed if and only if the \meta{default} is |accept|.
687 % \end{itemize}
688 %
689 % Rather than directly setting up a filter policy, one can also use the
690 % following macros to first define filter policies and then select one for use.
691 %
692 % \NiceDescribeMacro{\DefineTagFilter}{\marg{name}\marg{default}\marg{policy}}
693 % This macro defines a tag filter policy with name \meta{name} to represent the
694 % given \meta{policy} and \meta{default}.
695 %
696 % \NiceDescribeMacro{\UseTagFilter}{\marg{name}}
697 % This macro uses the tag filter policy with name \meta{name}.
698 %
699 % Further examples:
700 % \begin{LTXexample}[morekeywords={DefineTagFilter,UseTagFilter,tags},preset={\NewMultilangCmd{\Item}{disablable,command=\item,oargs=dd,margs=dt,alias/both={dd,dt}}}]
701 % \DefineTagFilter{Show}{accept}{}
702 % \DefineTagFilter{Hide}{deny}{}
703 % \DefineTagFilter{OnlyA}{accept}{accept=A,
704 % deny={D,X}}
705 % \begin{description}
706 % \UseTagFilter{Hide}
707 % \Item{ both={1}{no tag}}
708 % \Item{tags=D, both={2}{tagged D}}
709 % \UseTagFilter{OnlyA}
710 % \Item{tags={D,!X},both={3}{tagged D,!X}}
711 % \Item{tags={!X,D},both={4}{tagged !X,D}}
712 % \end{description}
713 % \end{LTXexample}
714 %
715 %
716 % \section{Questions and Answers}
717 %
718 % \begin{description}
719 % \item[Can't I achieve the same thing simpler?]
720 % To some extent, you can.
721 % A variety of ad-hoc solutions to managing translations in \LaTeX{}
722 % documents exist.\footnote{see, e.g.,
723 % \url{https://tex.stackexchange.com/q/5076}}
724 % An obvious approach is the following:
725 % \SaveSecs
726 % \begin{LTXexample}
727 % \newcommand\inEnglish[1]{#1}
728 % \newcommand\inGerman[1]{}
729 %
730 % \inEnglish{\section{Foobar}}
731 % \inGerman{\section{Dingsda}}
732 % % or
733 % \section{\inEnglish{Foobar}
734 % \inGerman{Dingsda}}
735 % \end{LTXexample}
736 % \RestoreSecs
737 % That is, for each translation language you define a macro with one
738 % argument; the macro for the ``selected'' language expands to the argument
739 % while all other macros have an empty expansion.
740 % An obvious advantage of this approach over \ThisPackage is that it does
741 % not require learning how to use \ThisPackage.
742 % However, in my opinion, the approach has the following disadvantages:
743 % \begin{itemize}[nosep]
744 % \item Both the first variant and the second variant in the example make
745 % the code more difficult to read due to the nesting of macros and the
746 % curly braces.
747 % \item The first variant even requires the |\section| macro to be repeated
748 % for each language.
749 % \item The second variant easily gets chaotic if instead of |\section| a
750 % macro with several arguments is used.
751 % \end{itemize}
752 % Solutions with conditionals (e.g., |\ifEnglish ...\else ...\fi|) share the
753 % disadvantages of above approach (except the curly braces) and additionally
754 % have an inherent asymmetry that becomes particularly apparent if more than
755 % two languages are involved.
756 % Similar arguments apply to other ad-hoc solutions I have seen.
757 % That is, I find documents based on such approaches cumbersome to maintain
758 % and, hence, requiring more careful checks for ensuring consistency.
759 %
760 % \item[Can I use \ThisPackage with \textsf{polyglossia} instead of \textsf{babel}?]
761 % Yes, you can use either one for selecting the language of your document.
762 %
763 % \item[Can I switch the language mid-document?]
764 % You can switch the language mid-document (e.g., using Babel's
765 % |selectlanguage| environment), but this does not effect what the
766 % multilingual macros or environments defined via \ThisPackage.
767 % The language that is displayed by a macro or environment is determined at
768 % the time of loading \ThisPackage.
769 % Future versions of \ThisPackage might add support for switching languages
770 % mid-document, though.
771 %
772 % \item[Are language dialects supported?]
773 % No, currently they are not supported.
774 %
775 % \item[Can I store the ``result'' of a multilingual macro in another macro?]
776 % No.
777 % You can store the macro itself (e.g., via |\newcommand|), but storing the
778 % result of the multilingual macro in a macro (e.g., via |\edef|) is not
779 % possible, as the multilingual macros are not expandable.
780 % \end{description}
781 %
782 %
783 % \section{Related Packages}
784 %
785 % I'm not aware of any \LaTeX{} packages that pursue similar goals or
786 % provide similar functionality.
787 % CTAN provides a list of many packages for supporting more than one
788 % language.\footnote{\url{https://www.ctan.org/topic/multilingual}}
789 % In the following, we compare against some of these packages.
790 %
791 % \begin{description}
792 % \item[\textsf{babel}, \textsf{polyglossia}:]
793 % These package provide support for selecting a document language and
794 % switching the document language within a document. The selected language
795 % is then used for hyphenation and other layouting aspects.
796 % Providing multiple translations of pieces of content is not particularly
797 % facilitated by the two packages.
798 %
799 % The \ThisPackage package builds on \textsf{babel} or \textsf{polyglossia}
800 % for determining the selected language and for forced foreign-language
801 % formatting (as illustrated in \cref{sec:Usage-margs}).
802 %
803 % \item[\textsf{translations}:]
804 % This package aims primarily aims at package authors, providing them an
805 % easy interface for providing translations of package-specific terms.
806 % Essentially, one declares translations for terms up-front and then later
807 % can use these translations.
808 %
809 % The separation of translations and the use of terms is beneficial
810 % for the maintenance of packages and documents in which individual terms
811 % occur multiple times. However, I assume that this separation would make it
812 % harder to maintain documents in which most translated units occur only
813 % once and at a particular location in the document.
814 %
815 % One could combine the virtues of \textsf{translations} and \ThisPackage as
816 % follows:
817 % \SaveSecs
818 % \begin{LTXexample}[morekeywords={DeclareTranslation,GetTranslation},preset={\let\DeclareTranslation=\addtranslation}]
819 % % in preamble
820 % \usepackage{translations}
821 % \DeclareTranslation{english}{foo}{Foobar}
822 % \DeclareTranslation{german}{foo}{Dingsda}
823 % \NewMultilangType{translate}
824 % {\GetTranslation{#1}}
825 % \NewMultilangCmd{\Sec}{
826 % margs=title, command=\section}
827 %
828 % % in document
829 % \Sec{title/translate=foo}
830 % \end{LTXexample}
831 % \RestoreSecs
832 %
833 % \item[\textsf{xt\_capts}:]
834 % This package is similar to the \textsf{translations} package, even though
835 % the package's documentation does not explicitly refer to package authors
836 % as the target users. That is, it provides commands for declaring and using
837 % translations of terms.
838 % The main difference to \textsf{translations}, as far as I understand, is
839 % that the user interface of \textsf{translations} is larger and supports
840 % language dialects.
841 % Comparing with \ThisPackage, the same remarks as for \textsf{translations}
842 % apply.
843 % \end{description}
844 %
845 %
846 % \clearpage
847 %
848 % \StopEventually{}
849 %\iffalse
850 %<*package>
851 %\fi
852 %
853 %
854 % \section{Implementation}
855 %
856 % \subsection{Dependencies}
857 %
858 % We use \textsf{pgfkeys} for the options parsing, both for the macros defined
859 % by \ThisPackage and for the macro defined via the macros in \ThisPackage.
860 % We use \textsf{etoolbox} to simplify the internal code.
861 % \begin{macrocode}
862 \RequirePackage{pgfkeys,pgfopts}
863 \RequirePackage{etoolbox}
864 % \end{macrocode}
865 % We use the \textsf{environ} package for scanning and later forgetting the
866 % body of disabled multilingual environments.
867 % \begin{macrocode}
868 \RequirePackage{environ}
869 % \end{macrocode}
870 %
871 %
872 % \subsection{Package Options}
873 %
874 % The ``|languages|'' option selects the languages that \ThisPackage knows
875 % about.
876 % \begin{macrocode}
877 \newcommand\multilang@@langs{}
878 \pgfqkeys{/multilang/pkg}{
879 languages/.code={\forcsvlist{\listadd\multilang@@langs}{#1}},
880 }
881 \ProcessPgfOptions{/multilang/pkg}
882 % \end{macrocode}
883 %
884 % \subsection{Main Macros}
885 %
886 % \begin{macro}{\NewMultilangCmd}
887 % The |\NewMultilangCmd|\marg{command}\marg{options} macro defines
888 % \meta{command} to be a single-argument macro. The argument to \meta{command}
889 % specifies, in a key-value list style, the mandatory and optional arguments
890 % that are passed to a command specified in \meta{options}.
891 % \begin{macrocode}
892 \newcommand\NewMultilangCmd[2]{%
893 \bgroup
894 % \end{macrocode}
895 % The following line processes the \meta{options} given and, as its result,
896 % defines the macros
897 % |\multilang@@actuals|, |\multilang@@checks|, and |\multilang@@keys|.
898 % \begin{macrocode}
899 \multilang@processargs{#1}{/multilang/newcommand}{defaults={},#2}%
900 % \end{macrocode}
901 % To handle starred macros, we store the actual macro code into an auxiliary
902 % macro and define \meta{command} to be an interface to the auxiliary macro.
903 % The next line stores the name of the internal macro.
904 % \begin{macrocode}
905 \expandafter\def\expandafter\multilang@@intcmd\expandafter{%
906 \csname multilang@intcmd@\expandafter\@gobble\string#1\endcsname}%
907 % \end{macrocode}
908 % Finally, we create the \meta{command}. The |\edef| starting with the
909 % |\egroup| shall expand the three macros constructed above but nothing else
910 % such that none of the |\pgfqkeys| result for |#1| spills outside the
911 % |\NewMultilangCmd|.
912 % \begin{macrocode}
913 \edef\do{\egroup
914 \expandonce{\multilang@@keys}%
915 \ifbool{multilang@@starred}{%
916 % \end{macrocode}
917 % The following handles the case of a |starred| macro. We define the macro
918 % that scans for the star (\meta{command}) as well as the internal macro that
919 % does the actual work.
920 % \begin{macrocode}
921 \unexpanded{\newcommand#1}{%
922 \noexpand\@ifstar
923 {\expandonce{\multilang@@intcmd}{*}}%
924 {\expandonce{\multilang@@intcmd}{}}}%
925 }{%
926 % \end{macrocode}
927 % The following handles the case of a non-|starred| macro. Here we make
928 % \meta{command} directly resort to the internal macro.
929 % \begin{macrocode}
930 \unexpanded{\newcommand#1}{\expandonce{\multilang@@intcmd}{}}%
931 }%
932 % \end{macrocode}
933 % The remainder of the macro code defines the internal macro, with signature
934 % \meta{\cs{multilang@@keys}}\marg{decoration}\marg{kvarg}.
935 % The \meta{decoration} can assume any symbols that shall directly be put
936 % after the command encapsulated by |command|. A particular use for the
937 % \meta{decoration} argument is the ``|*|'' symbol for a |starred| macro.
938 % \begin{macrocode}
939 \noexpand\newcommand{\expandonce{\multilang@@intcmd}}[2]{%
940 % \end{macrocode}
941 % First, \meta{command} parses its argument using \textsf{pgfkeys}.
942 % \begin{macrocode}
943 \bgroup
944 \noexpand\boolfalse{multilang@cmd@@disabled}%
945 \noexpand\pgfqkeys{\multilang@keyof{#1}}{%
946 \expandonce{\multilang@@defaults},####2}%
947 \noexpand\ifbool{multilang@cmd@@disabled}%
948 % \end{macrocode}
949 % If the macro is disabled, simply use an empty invocation
950 % |\multilang@@invok|.
951 % \begin{macrocode}
952 {\unexpanded{\def\multilang@@invok{}}}%
953 % \end{macrocode}
954 % Otherwise, first check the arguments and afterwards define
955 % |\multilang@@invok| to contain \meta{command}, \meta{decoration} (in
956 % |####1|), and the actual arguments (in |\multilang@@actuals|).
957 % \begin{macrocode}
958 {\expandonce{\multilang@@checks}%
959 \unexpanded{\edef\multilang@@invok}{%
960 \noexpand\unexpanded{\expandonce{\multilang@@cmd}}####1%
961 \expandonce{\multilang@@actuals}}}%
962 % \end{macrocode}
963 % Finally, \meta{command} invokes the command specified via the |command| key.
964 % The invocation happens outside the local group, just for the case that makes
965 % a difference with the |command|.
966 % \begin{macrocode}
967 \unexpanded{\expandafter\egroup\multilang@@invok}%
968 }%
969 }\do}
970 % \end{macrocode}
971 %
972 %
973 % \begin{macro}{\NewMultilangEnv}
974 % The |\NewMultilangEnv|\marg{environment}\marg{options} macro defines
975 % \meta{environment} to be a single-argument environment. The argument to
976 % \meta{environment} specifies, in a key-value list style, the mandatory and
977 % optional arguments that are passed to an environment specified in
978 % \meta{options}.
979 % \begin{macrocode}
980 \newcommand\NewMultilangEnv[2]{%
981 \bgroup
982 % \end{macrocode}
983 % The following line processes the \meta{options} given and, as its result,
984 % defines the macros
985 % |\multilang@@actuals|, |\multilang@@checks|, and |\multilang@@keys|.
986 % \begin{macrocode}
987 \multilang@processargs{#1}{/multilang/newenvir}{defaults={},#2}%
988 % \end{macrocode}
989 % Finally, we create the \meta{environment}. The |\edef| starting with the
990 % |\egroup| shall expand the three macros constructed above but nothing else
991 % such that none of the |\pgfqkeys| result for |#1| spills outside the
992 % |\NewMultilangEnv|. We also pay attention that as few as possible internal
993 % macros spill into the environment or even the code that begins the
994 % environment.
995 % \begin{macrocode}
996 \edef\do{\egroup
997 \expandonce{\multilang@@keys}%
998 \unexpanded{\newenvironment{#1}}[1]{%
999 % \end{macrocode}
1000 % First, \meta{command} parses its argument using \textsf{pgfkeys}.
1001 % \begin{macrocode}
1002 \bgroup
1003 \noexpand\boolfalse{multilang@cmd@@disabled}%
1004 \noexpand\pgfqkeys{\multilang@keyof{#1}}{####1}%
1005 \noexpand\ifbool{multilang@cmd@@disabled}%
1006 % \end{macrocode}
1007 % If the body shall be disabled, then we don't perform checks on the
1008 % arguments, don't open |environment| but rather collect the body of the
1009 % environment and finally also ignore the code for closing |environment| (via
1010 % |\multilang@noend|). Through this trick, we avoid defining an additional
1011 % macro for switching in the end-block of the environment.
1012 % \begin{macrocode}
1013 {\unexpanded{%
1014 \def\multilang@@invok{\Collect@Body{\multilang@noend}}}}%
1015 % \end{macrocode}
1016 % First check the arguments and afterwards define
1017 % |\multilang@@invok| to contain the opening code for the environment,
1018 % including the actual arguments (in |\multilang@@actuals|).
1019 % \begin{macrocode}
1020 {\expandonce{\multilang@@checks}%
1021 \unexpanded{\edef\multilang@@invok}{%
1022 \noexpand\noexpand\noexpand\begin{\multilang@@env}%
1023 \expandonce{\multilang@@actuals}}}%
1024 % \end{macrocode}
1025 % Finally, \meta{environment} begins the environment specified via the
1026 % |environment| key. This happens outside the local group, such that the
1027 % internal macros set via |\pgfqkeys| are not visible anymore when the
1028 % environment is started.
1029 % \begin{macrocode}
1030 \unexpanded{\expandafter\egroup\multilang@@invok}%
1031 }{%
1032 % \end{macrocode}
1033 % The following implements the closing of the environment.
1034 % \begin{macrocode}
1035 \noexpand\end{\multilang@@env}%
1036 }%
1037 }\do}
1038 % \end{macrocode}
1039 %
1040 %
1041 % \subsubsection{Option Keys}
1042 %
1043 % We first setup the shared keys for the \meta{options} argument of
1044 % |\NewMultilangCmd| and |\NewMultilangEnv|.
1045 % \begin{macrocode}
1046 \pgfqkeys{/multilang/cmd-or-env}{
1047 margs/.store in={\multilang@@margs},
1048 oargs/.store in={\multilang@@oargs},
1049 alias/.is family,
1050 alias/.unknown/.code={%
1051 \listeadd{\multilang@@aliases}{\pgfkeyscurrentname}%
1052 \csdef{multilang@@alias@\pgfkeyscurrentname}{#1}},
1053 defaults/.store in={\multilang@@defaults},
1054 disablable/.is if={multilang@@disablable},
1055 }
1056 \newbool{multilang@@disablable}
1057 \newbool{multilang@cmd@@disabled}
1058 % \end{macrocode}
1059 %
1060 % Next, we setup the specific keys for |\NewMultilangCmd|.
1061 % \begin{macrocode}
1062 \pgfqkeys{/multilang/newcommand}{
1063 .search also={/multilang/cmd-or-env},
1064 command/.store in={\multilang@@cmd},
1065 starred/.is if={multilang@@starred},
1066 alias/.search also={/multilang/cmd-or-env},
1067 }
1068 \newbool{multilang@@starred}
1069 % \end{macrocode}
1070 % \end{macro}
1071 % Finally, the specific keys for |\NewMultilangEnv|.
1072 % \begin{macrocode}
1073 \pgfqkeys{/multilang/newenvir}{
1074 .search also={/multilang/cmd-or-env},
1075 environment/.store in={\multilang@@env},
1076 alias/.search also={/multilang/cmd-or-env},
1077 }
1078 % \end{macrocode}
1079 % \end{macro}
1080 %
1081 %
1082 % \subsection{Registration of Datatypes}
1083 %
1084 % \begin{macro}{\NewMultilangType}
1085 % The |\NewMultilangType|\oarg{argcount}\marg{typename}\marg{format} macro
1086 % registers the name \meta{typename} as a type that can be used for specifying
1087 % \ThisPackage arguments. The type has \meta{argcount} arguments (default: 1)
1088 % and is formatted according to code \meta{format}.
1089 % Note that the definition of types is group-local. That is, if
1090 % |\NewMultilangType| is used within a group, \meta{typename} is only
1091 % available inside that group.
1092 % \begin{macrocode}
1093 \newcommand\NewMultilangType[3][1]{%
1094 % \end{macrocode}
1095 % We first record the new type's name (in |\multilang@@types|) and store both
1096 % \meta{argcount} and \meta{format} in macros.
1097 % \begin{macrocode}
1098 \listadd\multilang@@types{#2}%
1099 \expandafter\newcommand\csname multilang@@typecmd@#2\endcsname[#1]{#3}%
1100 \csdef{multilang@@typeargc@#2}{#1}%
1101 % \end{macrocode}
1102 % Finally, we also store the invocation of the \meta{format} code macro.
1103 % This is a bit cumbersome, as for all possible argument counts we provide the
1104 % respective number of arguments. I did not yet find a more elegant way to
1105 % achieve that the |style n args| code in |\multilang@regfieldtype| invokes
1106 % \meta{format} properly with \meta{argcount} arguments.
1107 % \meta{argcount} and \meta{format} in macros.
1108 % \begin{macrocode}
1109 \ifcase#1\relax
1110 \csdef{multilang@@runcmd@#2}{\csuse{multilang@@typecmd@#2}}%
1111 % \end{macrocode}
1112 % For one argument, we check a special case: \meta{format} is the identity
1113 % function. In this case, we directly expand to the argument itself, i.e., we
1114 % unfold \meta{format}. We do this such that emptiness of optional arguments
1115 % can be checked by a |command| or |environment| without having to expand the
1116 % \meta{format} (which might not work out if \meta{format} is not expansible).
1117 % For instance, KOMA's |\section| macro hides the TOC entry for
1118 % |\section[]{...}| but not for |\section[\X]{...}| even if |\X| expands to an
1119 % empty result.
1120 % \begin{macrocode}
1121 \or\ifcsequal{multilang@@typecmd@#2}{@firstofone}%
1122 {\csdef{multilang@@runcmd@#2}{####1}}%
1123 {\csdef{multilang@@runcmd@#2}{\csuse{multilang@@typecmd@#2}%
1124 {####1}}}%
1125 \or\csdef{multilang@@runcmd@#2}{\csuse{multilang@@typecmd@#2}%
1126 {####1}{####2}}%
1127 \or\csdef{multilang@@runcmd@#2}{\csuse{multilang@@typecmd@#2}%
1128 {####1}{####2}{####3}}%
1129 \or\csdef{multilang@@runcmd@#2}{\csuse{multilang@@typecmd@#2}%
1130 {####1}{####2}{####3}{####4}}%
1131 \or\csdef{multilang@@runcmd@#2}{\csuse{multilang@@typecmd@#2}%
1132 {####1}{####2}{####3}{####4}{####5}}%
1133 \or\csdef{multilang@@runcmd@#2}{\csuse{multilang@@typecmd@#2}%
1134 {####1}{####2}{####3}{####4}{####5}{####6}}%
1135 \or\csdef{multilang@@runcmd@#2}{\csuse{multilang@@typecmd@#2}%
1136 {####1}{####2}{####3}{####4}{####5}{####6}{####7}}%
1137 \or\csdef{multilang@@runcmd@#2}{\csuse{multilang@@typecmd@#2}%
1138 {####1}{####2}{####3}{####4}{####5}{####6}{####7}{####8}}%
1139 \or\csdef{multilang@@runcmd@#2}{\csuse{multilang@@typecmd@#2}%
1140 {####1}{####2}{####3}{####4}{####5}{####6}{####7}{####8}{####9}}%
1141 \else\multilang@error{Argument count expected to be between 0 and 9, %
1142 but is '#1'}\fi}
1143 % \end{macrocode}
1144 % \end{macro}
1145 %
1146 % \begin{macro}{\multilang@@types}
1147 % The |\multilang@@types| macro collects and holds an \textsf{etoolbox} list
1148 % of datatypes defined via |\NewMultilangType|.
1149 % \begin{macrocode}
1150 \newcommand\multilang@@types{}
1151 % \end{macrocode}
1152 % \end{macro}
1153 %
1154 % \begin{macro}{\NewMultilangType@code}
1155 % The |\NewMultilangType@code|\oarg{argcount}\marg{typename}\marg{format}
1156 % macro is an internal counterpart to |\NewMultilangType| with which not
1157 % not the |.style| but the |.code| property of the \meta{typename} key is
1158 % defined. This is indicated by defining the
1159 % |\multilang@@codetype@|\meta{typename} macro here and checking whether this
1160 % macro is defined in |\multilang@regfieldtype|.
1161 % \begin{macrocode}
1162 \newcommand\NewMultilangType@code[3][1]{%
1163 \csdef{multilang@@codetype@#2}{true}%
1164 \NewMultilangType[#1]{#2}{#3}}
1165 % \end{macrocode}
1166 % \end{macro}
1167 %
1168 % \begin{macro}{\multilang@regfield}
1169 % The |\multilang@regfield|\marg{cmd-or-env}\marg{fieldname} macro registers
1170 % the respective \textsf{pgfkeys} keys for \meta{fieldname} for all registered datatypes.
1171 % \begin{macrocode}
1172 \newcommand\multilang@regfield[2]{%
1173 \pgfqkeys{\multilang@keyof{#1}}{%
1174 #2/.code={\csdef{multilang@@val@#2}{##1}}}%
1175 \forlistloop{\multilang@regfieldtype{#1}{#2}}{\multilang@@types}}
1176 % \end{macrocode}
1177 % \end{macro}
1178 %
1179 % \begin{macro}{\multilang@regfieldtype}
1180 % The |\multilang@regfieldtype|\marg{cmd-or-env}\marg{fieldname}\marg{typename}
1181 % macro registers the \textsf{pgfkeys} key for \meta{typename} of
1182 % \meta{fieldname}.
1183 % \begin{macrocode}
1184 \newcommand\multilang@regfieldtype[3]{%
1185 \bgroup
1186 % \end{macrocode}
1187 % In the following, we check whether the number of arguments for the
1188 % \meta{typename} macro is 1, because for some reason |style n args| seems not
1189 % to work as we want it to work if $n=1$.
1190 % \begin{macrocode}
1191 \ifnumequal{\csuse{multilang@@typeargc@#3}}{1}{%
1192 \ifcsdef{multilang@@codetype@#3}{%
1193 \edef\do{\egroup\noexpand\pgfqkeys{\multilang@keyof{#1}}{%
1194 #2/#3/.code={\csexpandonce{multilang@@runcmd@#3}}%
1195 }}%
1196 }{%
1197 \edef\do{\egroup\noexpand\pgfqkeys{\multilang@keyof{#1}}{%
1198 #2/#3/.style={#2={\csexpandonce{multilang@@runcmd@#3}}}%
1199 }}%
1200 }%
1201 }{%
1202 \ifcsdef{multilang@@codetype@#3}{%
1203 \edef\do{\egroup\noexpand\pgfqkeys{\multilang@keyof{#1}}{%
1204 #2/#3/.code n args={\csuse{multilang@@typeargc@#3}}%
1205 {\csexpandonce{multilang@@runcmd@#3}}}}%
1206 }{%
1207 \edef\do{\egroup\noexpand\pgfqkeys{\multilang@keyof{#1}}{%
1208 #2/#3/.style n args={\csuse{multilang@@typeargc@#3}}%
1209 {#2={\csexpandonce{multilang@@runcmd@#3}}}}}%
1210 }%
1211 }\do}
1212 % \end{macrocode}
1213 % \end{macro}
1214 %
1215 %
1216 % \subsubsection{Argument Aliases}
1217 %
1218 % \begin{macro}{\multilang@regcomb}
1219 % The |\multilang@regcomb|\marg{cmd-or-env}\marg{alias}\marg{fields}
1220 % macro registers an \meta{alias} argument for \meta{fields}.
1221 % \begin{macrocode}
1222 \newcommand\multilang@regcomb[3]{%
1223 \multilang@regcombtype{#1}{#2}{#3}{}%
1224 \forlistloop{\multilang@regcomb@i{#1}{#2}{#3}}{\multilang@@types}}
1225 % \end{macrocode}
1226 % \end{macro}
1227 %
1228 % \begin{macro}{\multilang@regcomb@i}
1229 % The
1230 % |\multilang@regcomb@i|\marg{cmd-or-env}\marg{alias}\marg{fields}\marg{type}
1231 % macro is an auxiliary front-end to |\multilang@regcombtype| that transforms
1232 % \meta{type} to a key \meta{suffix} (by prepending a ``|/|'').
1233 % \begin{macrocode}
1234 \newcommand\multilang@regcomb@i[4]{%
1235 \multilang@regcombtype{#1}{#2}{#3}{/#4}}
1236 % \end{macrocode}
1237 % \end{macro}
1238 %
1239 % \begin{macro}{\multilang@regcombtype}
1240 % The
1241 % |\multilang@regcombtype|\marg{cmd-or-env}\marg{alias}\marg{fields}\marg{suffix}
1242 % registers the \meta{alias} with the given type-\meta{suffix}.
1243 % \begin{macrocode}
1244 \newcommand\multilang@regcombtype[4]{%
1245 \bgroup
1246 % \end{macrocode}
1247 % We count the number of field names in \meta{fields} (in |\@tempcnta|) and,
1248 % in the same loop, gather the individual field assignments (in |\toks@|).
1249 % \begin{macrocode}
1250 \toks@{}\@tempcnta=0\relax
1251 \forcsvlist{%
1252 \advance\@tempcnta by1\relax
1253 \expandafter\multilang@regcomb@set\expandafter{\the\@tempcnta}{#4}%
1254 }{#3}%
1255 % \end{macrocode}
1256 % Finally, we set the style for the \meta{alias}\meta{suffix} key. Again we
1257 % separately handle the case of a single field. Additionally, we treat also
1258 % the case of \emph{no} field special: It gets a |style| (with 1 argument),
1259 % but the argument is essentially ignored (as |\toks@| is empty). This makes
1260 % \meta{alias} a ``comment'' field that is not passed to the |command| or
1261 % |environment|.
1262 % \begin{macrocode}
1263 \ifnumgreater{\the\@tempcnta}{1}{%
1264 \edef\do{\egroup\noexpand\pgfqkeys{\multilang@keyof{#1}}{%
1265 #2#4/.style n args={\the\@tempcnta}{\the\toks@}}}%
1266 }{%
1267 \edef\do{\egroup\noexpand\pgfqkeys{\multilang@keyof{#1}}{%
1268 #2#4/.style={\the\toks@}}}%
1269 }%
1270 \do}
1271 % \end{macrocode}
1272 % \end{macro}
1273 %
1274 % \begin{macro}{\multilang@regcomb@set}
1275 % The |\multilang@regcomb@set|\marg{index}\marg{suffix}\marg{field} macro
1276 % appends the sequence ``\meta{field}\meta{suffix}|={#|\meta{index}|}|'' to
1277 % the |toks@| register. When used in a |.style n args| key, this sets the
1278 % ``\meta{field}\meta{suffix}'' key to the \meta{index}-th positional
1279 % parameter.
1280 % \begin{macrocode}
1281 \newcommand\multilang@regcomb@set[3]{%
1282 \toks@\expandafter{\the\toks@,#3#2={###1}}}
1283 % \end{macrocode}
1284 % \end{macro}
1285 %
1286 %
1287 % \subsubsection{Language ``Types''}
1288 %
1289 % \begin{macro}{\multilang@addlanguage}
1290 % The |\multilang@addlanguage|\marg{language} registers \meta{language},
1291 % essentially registering ``\meta{language}'' and ``\meta{language}|!|'' as
1292 % argument datatypes.
1293 % \begin{macrocode}
1294 \newcommand\multilang@addlanguage[1]{%
1295 % \end{macrocode}
1296 % The following checks the current language (|\languagename|) against
1297 % \meta{language}. In the following,
1298 % |##1| is the argument to the key when the key is used.
1299 % \begin{macrocode}
1300 \ifdefstring{\languagename}{#1}%
1301 {\NewMultilangType{#1}{##1}}%
1302 {\NewMultilangType@code{#1}{}}%
1303 % \end{macrocode}
1304 % The following defines the ``\meta{language}|!|'' key for forcing an
1305 % argument to be formatted in language \meta{language}.
1306 % \begin{macrocode}
1307 \NewMultilangType{#1!}{\foreignlanguage{#1}{##1}}}
1308 % \end{macrocode}
1309 % \end{macro}
1310 % Register all languages passed as argument to the package.
1311 % \begin{macrocode}
1312 \forlistloop{\multilang@addlanguage}{\multilang@@langs}
1313 % \end{macrocode}
1314 %
1315 %
1316 % \subsection{Auxiliary Macros}
1317 %
1318 % \begin{macro}{\multilang@keyof}
1319 % The |\multilang@keyof|\marg{cmd-or-env}, when fully expanded such as in the
1320 % first argument of the |\pgfqkeys| macro, represents the key under which the
1321 % parameter keys of the command or environment \meta{cmd-or-env} are stored.
1322 % Note that the branching in the code below checks whether \meta{cmd-or-env}
1323 % is a command sequence (|true| case) or not (|false| case).
1324 % \begin{macrocode}
1325 \newcommand\multilang@keyof[1]{%
1326 \ifcat\relax\noexpand#1%
1327 /multilang/cmd/\expandafter\@gobble\string#1%
1328 \else
1329 /multilang/env/#1%
1330 \fi}
1331 % \end{macrocode}
1332 % \end{macro}
1333 %
1334 % \begin{macro}{\multilang@error}
1335 % The |\multilang@error|\marg{message} macro shows \meta{message} as an error
1336 % message of the \ThisPackage package.
1337 % \begin{macrocode}
1338 \newcommand\multilang@error[1]{\PackageError{multilang}{#1}{}}
1339 % \end{macrocode}
1340 % \end{macro}
1341 %
1342 % \begin{macro}{\multilang@processargs}
1343 % The |\multilang@processargs|\marg{cmd-or-env}\marg{opt-key}\marg{options}
1344 % macro processes the \meta{options} in key \meta{opt-key}. Afterwards, it
1345 % post-processes the arguments |margs|, |oargs|, |alias/...|, and
1346 % |disablable|.
1347 % It stores the result of the post-processing in the macros
1348 % |\multilang@@actuals|, |\multilang@@checks|, and |\multilang@@keys|.
1349 % \begin{macrocode}
1350 \newcommand\multilang@processargs[3]{%
1351 \let\multilang@@aliases=\empty
1352 \pgfqkeys{#2}{#3}%
1353 % \end{macrocode}
1354 % In the following, we iteratively construct three macros:
1355 % |\multilang@@actuals|, |\multilang@@checks|, and |\multilang@@keys|.
1356 % \begin{itemize}[nosep]
1357 % \item In |\multilang@@actuals|, we step by step construct the arguments that
1358 % shall be passed to \meta{cmd-or-env}.
1359 % \item In |\multilang@@checks|, we construct a list of preliminary checks
1360 % that \meta{cmd-or-env} shall perform on its arguments.
1361 % \item In |\multilang@@keys|, we construct a list of |\pgfqkeys| commands
1362 % that set up the keys for \meta{cmd-or-env}'s one argument.
1363 % \end{itemize}
1364 % The following first initializes the three macros.
1365 % \begin{macrocode}
1366 \edef\multilang@@actuals{}%
1367 \def\multilang@@checks{}%
1368 \def\multilang@@keys{}%
1369 % \end{macrocode}
1370 % We first process the optional arguments. We process them before the
1371 % mandatory arguments because they must come first in |\multilang@@actuals|.
1372 % In the following |\do| macro, |##1| iterates over all optional argument
1373 % names in the |margs| list.
1374 % \begin{macrocode}
1375 \ifdefvoid{\multilang@@oargs}{}{%
1376 \def\do##1{%
1377 \appto{\multilang@@actuals}{%
1378 \ifcsmacro{multilang@@val@##1}%
1379 {[\csexpandonce{multilang@@val@##1}]}%
1380 {}%
1381 }%
1382 \appto{\multilang@@keys}{\multilang@regfield{#1}{##1}}%
1383 }%
1384 \expandafter\docsvlist\expandafter{\multilang@@oargs}}%
1385 % \end{macrocode}
1386 % Next, we append the mandatory arguments, specified by the |margs| list.
1387 % In the following |\do| macro, |##1| iterates over all mandatory argument
1388 % names in the |margs| list.
1389 % \begin{macrocode}
1390 \ifdefvoid{\multilang@@margs}{}{%
1391 \def\do##1{%
1392 \appto{\multilang@@actuals}{%
1393 {\csexpandonce{multilang@@val@##1}}%
1394 }%
1395 \appto{\multilang@@checks}{%
1396 \ifcsmacro{multilang@@val@##1}%
1397 {}%
1398 {\multilang@error{mandatory argument ##1 missing}}%
1399 }%
1400 \appto{\multilang@@keys}{\multilang@regfield{#1}{##1}}%
1401 }%
1402 \expandafter\docsvlist\expandafter{\multilang@@margs}}%
1403 % \end{macrocode}
1404 % Afterwards, we handle argument aliases. The list of aliases' names is in
1405 % |\multilang@@aliases| and the list of arguments that a \meta{alias}
1406 % combines is in |\multilang@@alias@|\meta{alias}.
1407 % Note that aliases only modify |\multilang@@keys| -- i.e., not
1408 % |\multilang@@actuals| or |\multilang@@checks|.
1409 % \begin{macrocode}
1410 \def\do##1{%
1411 \eappto{\multilang@@keys}{%
1412 \unexpanded{\multilang@regcomb{#1}{##1}}%
1413 {\csuse{multilang@@alias@##1}}}}%
1414 \expandafter\dolistloop\expandafter{\multilang@@aliases}%
1415 % \end{macrocode}
1416 % To handle |disablable| macros, we simply add the |disabled| key. This key is
1417 % a Boolean key that just sets a conditional.
1418 % \begin{macrocode}
1419 \ifbool{multilang@@disablable}%
1420 {\eappto{\multilang@@keys}{%
1421 \noexpand\pgfqkeys{\multilang@keyof{#1}}{%
1422 disabled/.is if={multilang@cmd@@disabled}}}}%
1423 {}%
1424 % \end{macrocode}
1425 % Invoke the hook. To avoid macro arguments to the hook, we store the command or
1426 % environment name in |\multilang@@cmdorenv| and store the \textsf{pgfkeys} key
1427 % for the command or environment in |\multilang@@cekey|.
1428 % \begin{macrocode}
1429 \def\multilang@@cmdorenv{#1}%
1430 \edef\multilang@@cekey{\multilang@keyof{#1}}%
1431 \multilang@hook@processargs
1432 }
1433 % \end{macrocode}
1434 % \end{macro}
1435 %
1436 % \begin{macro}{\multilang@hook@processargs}
1437 % The |\multilang@hook@processargs| macro is a hook that enables extensions to
1438 % the |\multilang@processargs|.
1439 % \begin{macrocode}
1440 \newcommand\multilang@hook@processargs{}
1441 % \end{macrocode}
1442 % \end{macro}
1443 %
1444 % \begin{macro}{\multilang@noend}
1445 % The |\multilang@noend|\marg{body} macro is intended to be used as the
1446 % argument to |\Collect@Body| (or |\collect@body|) of the \textsf{environ}
1447 % package. In this context, it performs the following:
1448 % Firstly, it ignores the collected \meta{body} of the environment.
1449 % Secondly, it temporarily disables the |\end|-code of the environment in
1450 % which the |\Collect@Body| is expanded.
1451 % \begin{macrocode}
1452 \newcommand\multilang@noend[1]{\cslet{end\@currenvir}{\relax}}
1453 % \end{macrocode}
1454 % \end{macro}
1455 %
1456 %\iffalse
1457 %</package>
1458 %<*pkgtags>
1459 %\fi
1460 %
1461 % \section{Implementation of Tags}
1462 %
1463 % \begin{macro}{\SetTagFilter}
1464 % The |\SetTagFilter|\oarg{default}\marg{policy} sets the tag filter policy
1465 % based on accept/deny rules in \meta{policy}.
1466 % \begin{macrocode}
1467 \newcommand\SetTagFilter[2][accept]{%
1468 \kcvml@parsepolicy{kcvml@@tagfilter}{#1}{#2}}
1469 \newcommand\kcvml@@tagfilter{}
1470 % \end{macrocode}
1471 % \end{macro}
1472 %
1473 % \begin{macro}{\DefineTagFilter}
1474 % The |\DefineTagFilter|\marg{name}\marg{default}\marg{policy} macro defines a
1475 % tag filter policy under name \meta{name}.
1476 % \begin{macrocode}
1477 \newcommand\DefineTagFilter[3]{%
1478 \kcvml@parsepolicy{kcvml@filter@@#1}{#2}{#3}}
1479 % \end{macrocode}
1480 % \end{macro}
1481 %
1482 % \begin{macro}{\UseFilter}
1483 % The |\UseTagFilter|\marg{name} macro uses the previously defined tag filter
1484 % policy with name \meta{name}.
1485 % \begin{macrocode}
1486 \newcommand\UseTagFilter[1]{%
1487 \letcs\kcvml@@tagfilter{kcvml@filter@@#1}}
1488 % \end{macrocode}
1489 % \end{macro}
1490 %
1491 % \begin{macro}{\kcvml@parsepolicy}
1492 % The |\kcvml@parsepolicy|\marg{csname}\marg{default}\marg{policy}
1493 % parses a tag filter policy, \meta{policy} with default \meta{default}, and
1494 % stores the resulting filter in the control sequence \meta{csname}.
1495 % \begin{macrocode}
1496 \newcommand\kcvml@parsepolicy[3]{%
1497 % \end{macrocode}
1498 % We first reset the temporary filter variable |\kcvml@@tmptagfilter| then
1499 % populate it via |\pgfqkeys|, first with the \meta{policy} list and
1500 % subsequently with the \meta{default} policy.
1501 % \begin{macrocode}
1502 \bgroup
1503 \def\kcvml@@tmptagfilter{}%
1504 \pgfqkeys{kcvml/tagfilter}{#3,default/#2}%
1505 % \end{macrocode}
1506 % Now we export the temporary |\kcvml@@tmptagfilter| to outside the local group
1507 % and into the control sequence \meta{csname}.
1508 % \begin{macrocode}
1509 \edef\do{\egroup
1510 \unexpanded{\csdef{#1}}{\expandonce{\kcvml@@tmptagfilter}}}%
1511 \do}
1512 % \end{macrocode}
1513 % The following lines specify how |\kcvml@@tmptagfilter| is modified when
1514 % |accept| or |deny| filter rules are specified.
1515 % \begin{macrocode}
1516 \pgfqkeys{kcvml/tagfilter}{%
1517 accept/.code={\kcvml@appendrule{#1}{\boolfalse}{\booltrue}},
1518 deny/.code ={\kcvml@appendrule{#1}{\booltrue}{\boolfalse}},
1519 default/accept/.code n args={0}{\appto\kcvml@@tmptagfilter{%
1520 \kcvml@applydefault{\boolfalse}}},
1521 default/deny/.code n args={0}{\appto\kcvml@@tmptagfilter{%
1522 \kcvml@applydefault{\booltrue}}},
1523 }
1524 % \end{macrocode}
1525 % \end{macro}
1526 %
1527 % \begin{macro}{\kcvml@appendrule}
1528 % The |\kcvml@appendrule|\marg{ruletags}\marg{flagmacro}\marg{invmacro} macro
1529 % appends a filter rule to the overall tag filter. The rule filters for the
1530 % given comma-separated list \meta{ruletags}.
1531 % The \meta{flagmacro} specifies whether a match shall be disabled (if
1532 % |\booltrue|) or enabled (if |\boolfalse|).
1533 % The \meta{invmacro} must be the inverse of \meta{flagmacro}.
1534 % \begin{macrocode}
1535 \newcommand\kcvml@appendrule[3]{%
1536 \bgroup
1537 % \end{macrocode}
1538 % For simplified later processing, we turn \meta{ruletags} into an
1539 % \textsf{etoolbox} list (in |\kcvml@@ruletags|) first.
1540 % \begin{macrocode}
1541 \def\kcvml@@ruletags{}%
1542 \forcsvlist{\listadd{\kcvml@@ruletags}}{#1}%
1543 % \end{macrocode}
1544 % Now we append to the overall filter (in |\kcvml@@tmptagfilter|) outside the
1545 % local group and use the cascade of |\expandafter|s to get |\cvmkl@@ruletags|
1546 % out of the group without polluting the outer scope.
1547 % \begin{macrocode}
1548 \expandafter\egroup
1549 \expandafter\listadd\expandafter\kcvml@@tmptagfilter\expandafter{%
1550 \expandafter\kcvml@applyrule\expandafter{\kcvml@@ruletags}{#2}{#3}}}
1551 % \end{macrocode}
1552 % \end{macro}
1553 %
1554 % We add the additional |tags| key to every disablable multilingual macro and
1555 % environment. For this, we use \textsf{multilang}'s
1556 % |\multilang@hook@processargs| hook.
1557 % \begin{macrocode}
1558 \appto\multilang@hook@processargs{%
1559 \ifbool{multilang@@disablable}%
1560 {\eappto{\multilang@@keys}{%
1561 % \end{macrocode}
1562 % Note that in |\multilang@@cekey|, the parent key of the command or environment
1563 % is stored. Whenever the |tags| argument is used, we make it invoke
1564 % |\kcvml@applyfilter| with the given \meta{tags} (|##1|).
1565 % \begin{macrocode}
1566 \noexpand\pgfqkeys{\multilang@@cekey}{%
1567 tags/.code={\noexpand\kcvml@applyfilter{##1}}}}}
1568 {}}
1569 % \end{macrocode}
1570 %
1571 % \begin{macro}{\kcvml@applyfilter}
1572 % The |\kcvml@applyfilter|\marg{tags} macro applies the current filter, which is
1573 % in the |\kcvml@@tagfilter| \textsf{etoolbox} list, to the comma-separated list
1574 % \meta{tags} of tags to check whether the entity with the \meta{tags} should be
1575 % disabled or not. The result of the check is stored in the Boolean flag
1576 % |multilang@cmd@@disabled| for further use in with \textsf{multilang} code.
1577 % \begin{macrocode}
1578 \newcommand\kcvml@applyfilter[1]{%
1579 \ifbool{multilang@cmd@@disabled}{}{%
1580 % \end{macrocode}
1581 % We check the filter only if the entry has not already explicitly been marked
1582 % as disabled. I.e., explicit disabling takes precedence, no matter whether it
1583 % is specified before or after a |tags| element.
1584 % In the Boolean flag |kcvml@@match|, we store whether a tag in \meta{tags}
1585 % matched one of the accept/deny filters already. After initializing this flag,
1586 % we iterate through |\kcvml@@tagfilter| with |\do|\marg{rule}, and
1587 % we stop iterating after a match has been found.
1588 % \begin{macrocode}
1589 \boolfalse{kcvml@@match}%
1590 \def\do##1{%
1591 % \end{macrocode}
1592 % Note that \meta{rule} is a curried macro whose missing last argument,
1593 % \meta{tags}, is added here.
1594 % \begin{macrocode}
1595 ##1{#1}%
1596 \ifbool{kcvml@@match}{\listbreak}{}}%
1597 \dolistloop{\kcvml@@tagfilter}}}
1598 \newbool{kcvml@@match}
1599 % \end{macrocode}
1600 % \end{macro}
1601 %
1602 % \begin{macro}{\kcvml@applyrule}
1603 % The
1604 % |\kcvml@applyrule|\marg{ruletags}\marg{flagmacro}\marg{invmacro}\marg{tags}
1605 % macro applies a single filter rule to the given \meta{tags}.
1606 % The \meta{flagmacro} must be either |\booltrue| or |\boolfalse|.
1607 % If it is |\booltrue|, this specifies that a match of \meta{tags} against
1608 % \meta{ruletags} disables the display of the respective entity;
1609 % If it is |\boolfalse|, this specifies that a match enables the display.
1610 % The \meta{invmacro} must be the inverse of \meta{flagmacro}.
1611 % We just check each tag in \meta{tags} individually.
1612 % \begin{macrocode}
1613 \newcommand\kcvml@applyrule[4]{%
1614 \forcsvlist{\kcvml@applyrule@i{#1}{#2}{#3}}{#4}}
1615 % \end{macrocode}
1616 %
1617 % \begin{macro}{\kcvml@applyrule@i}
1618 % The
1619 % |\kcvml@applyrule@i|\marg{ruletags}\marg{flagmacro}\marg{invmacro}\marg{tag}
1620 % macro applies a single filter rule to the given \meta{tag}.
1621 % It checks whether the \meta{tag} is inverted (i.e., starting with ``|!|'') and
1622 % hands over the actual check to |\kcvml@applyrule@ii|.
1623 % \begin{macrocode}
1624 \newcommand\kcvml@applyrule@i[4]{%
1625 \if !\@car#4\@nil
1626 \expandafter\kcvml@applyrule@ii\expandafter{\@cdr#4\@nil}{#1}{#3}%
1627 \else
1628 \kcvml@applyrule@ii{#4}{#1}{#2}\fi}
1629 % \end{macrocode}
1630 % \begin{macro}{\kcvml@applyrule@ii}
1631 % The
1632 % |\kcvml@applyrule@ii|\marg{tag}\marg{ruletags}\marg{flagmacro}
1633 % macro applies a single filter rule to the given \meta{tag}.
1634 % We check whether \meta{tag} in in the \textsf{etoolbox} list \meta{ruletags}.
1635 % Since |\ifinlist| expects a list macro for its second argument (which it then
1636 % expands once), we just give it |\empty| to eat (expand) and then use
1637 % \meta{ruletags} as it is.
1638 % \begin{macrocode}
1639 \newcommand\kcvml@applyrule@ii[3]{%
1640 \ifinlist{#1}{\empty #2}%
1641 % \end{macrocode}
1642 % If we have a match, we apply \meta{flagmacro} to |multilang@cmd@@disabled| and
1643 % then record, in |kcvml@@match|, that we found a match.
1644 % \begin{macrocode}
1645 {#3{multilang@cmd@@disabled}\booltrue{kcvml@@match}}{}}
1646 % \end{macrocode}
1647 % \end{macro}
1648 % \end{macro}
1649 % \end{macro}
1650 %
1651 % \begin{macro}{\kcvml@applydefault}
1652 % The |\kcvml@applydefault|\marg{flagmacro}\marg{tags} macro applies a default
1653 % filter to \meta{tags}. A \meta{flagmacro} of |\booltrue| corresponds to a
1654 % ``default deny''; |\boolfalse| corresponds to ``default accept''.
1655 % \begin{macrocode}
1656 \newcommand\kcvml@applydefault[2]{%
1657 #1{multilang@cmd@@disabled}}
1658 % \end{macrocode}
1659 % \end{macro}
1660 %
1661 %\iffalse
1662 %</pkgtags>
1663 %<*pkgsect>
1664 %\fi
1665 %
1666 % \section{Implementation of Sectioning Environments}
1667 %
1668 % The sectioning environments are proxies for the corresponding sectioning
1669 % macros. They are defined as environments such that the whole environments
1670 % rather than just the headings can be disabled.
1671 % Each of the environments has one optional argument, |short| (for a short
1672 % title), and one mandatory argument, |title| (for the actual title).
1673 %
1674 % \begin{environment}{Section}
1675 % \begin{environment}{Section*}
1676 % The |Section| and |Section*| environments are
1677 % multilingual proxies to |\section| and, respectively, |\section*|.
1678 % \begin{macrocode}
1679 \NewMultilangEnv{Section}{disablable,
1680 environment=section, oargs=short, margs=title}
1681 \NewMultilangEnv{Section*}{disablable,
1682 environment=multilang@secstar, oargs=short, margs=title}
1683 \newenvironment{multilang@secstar}{\section*}{}
1684 % \end{macrocode}
1685 % \end{environment}
1686 % \end{environment}
1687 %
1688 % \begin{environment}{SubSection}
1689 % \begin{environment}{SubSection*}
1690 % The |SubSection| and |SubSection*| environments are
1691 % multilingual proxies to |\subsection| and, respectively, |\subsection*|.
1692 % \begin{macrocode}
1693 \NewMultilangEnv{SubSection}{disablable,
1694 environment=subsection, oargs=short, margs=title}
1695 \NewMultilangEnv{SubSection*}{disablable,
1696 environment=multilang@ssecstar, oargs=short, margs=title}
1697 \newenvironment{multilang@ssecstar}{\subsection*}{}
1698 % \end{macrocode}
1699 % \end{environment}
1700 % \end{environment}
1701 %
1702 % \begin{environment}{SubSubSection}
1703 % \begin{environment}{SubSubSection*}
1704 % The |SubSubSection| and |SubSubSection*| environments are
1705 % multilingual proxies to |\subsubsection| and, respectively, |\subsubsection*|.
1706 % \begin{macrocode}
1707 \NewMultilangEnv{SubSubSection}{disablable,
1708 environment=subsubsection, oargs=short, margs=title}
1709 \NewMultilangEnv{SubSubSection*}{disablable,
1710 environment=multilang@sssecstar, oargs=short, margs=title}
1711 \newenvironment{multilang@sssecstar}{\subsubsection*}{}
1712 % \end{macrocode}
1713 % \end{environment}
1714 % \end{environment}
1715 %
1716 % \begin{environment}{Paragraph}
1717 % \begin{environment}{Paragraph*}
1718 % The |Paragraph| and |Paragraph*| environments are
1719 % multilingual proxies to |\paragraph| and, respectively, |\paragraph*|.
1720 % \begin{macrocode}
1721 \NewMultilangEnv{Paragraph}{disablable,
1722 environment=paragraph, oargs=short, margs=title}
1723 \NewMultilangEnv{Paragraph*}{disablable,
1724 environment=multilang@parstar, oargs=short, margs=title}
1725 \newenvironment{multilang@parstar}{\paragraph*}{}
1726 % \end{macrocode}
1727 % \end{environment}
1728 % \end{environment}
1729 %
1730 % \begin{environment}{SubParagraph}
1731 % \begin{environment}{SubParagraph*}
1732 % The |SubParagraph| and |SubParagraph*| environments are
1733 % multilingual proxies to |\subparagraph| and, respectively, |\subparagraph*|.
1734 % \begin{macrocode}
1735 \NewMultilangEnv{SubParagraph}{disablable,
1736 environment=subparagraph, oargs=short, margs=title}
1737 \NewMultilangEnv{SubParagraph*}{disablable,
1738 environment=multilang@sparstar, oargs=short, margs=title}
1739 \newenvironment{multilang@sparstar}{\subparagraph*}{}
1740 % \end{macrocode}
1741 % \end{environment}
1742 % \end{environment}
1743 %
1744 %
1745 %\iffalse
1746 %</pkgsect>
1747 %\fi
1748 % \Finale
1749 \endinput