Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2014-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{asciilist.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
23 %<package>\ProvidesPackage{asciilist}
24 %<*package>
25 [2018/11/01 v2.2b Package for quickly creating nested lists]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \usepackage[columns=2]{idxlayout}
31 \usepackage{xcolor}
32 \usepackage{showexpl}
33 \lstset{gobble=2,frame=trbl,backgroundcolor=\color{black!5!white}}
34 \lstset{explpreset={numbers=none,columns=flexible,basicstyle=\footnotesize\ttfamily}}
35 \lstset{preset={\small\sffamily},overhang=2cm,pos=r}
36 \usepackage{asciilist}
37 \usepackage{paralist}
38 \usepackage{hypdoc}
39 \makeatletter
40 \newcommand\SaveSecs{%
41 \@for\SC:=section,subsection,subsubsection\do{%
42 \csedef{SC@\SC}{\the\value{\SC}}%
43 \setcounter{\SC}{0}}}
44 \newcommand\RestoreSecs{%
45 \@for\SC:=section,subsection,subsubsection\do{%
46 \setcounter{\SC}{\csuse{SC@\SC}}}}
47 \makeatother
48 \EnableCrossrefs
49 \CodelineIndex
50 \RecordChanges
51 \begin{document}
52 \DocInput{asciilist.dtx}
53 \PrintChanges
54 \PrintIndex
55 \end{document}
56 %</driver>
57 % \fi
58 %
59 % \CheckSum{0}
60 %
61 % \CharacterTable
62 % {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
63 % 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
64 % Digits \0\1\2\3\4\5\6\7\8\9
65 % Exclamation \! Double quote \" Hash (number) \#
66 % Dollar \$ Percent \% Ampersand \&
67 % Acute accent \' Left paren \( Right paren \)
68 % Asterisk \* Plus \+ Comma \,
69 % Minus \- Point \. Solidus \/
70 % Colon \: Semicolon \; Less than \<
71 % Equals \= Greater than \> Question mark \?
72 % Commercial at \@ Left bracket \[ Backslash \\
73 % Right bracket \] Circumflex \^ Underscore \_
74 % Grave accent \` Left brace \{ Vertical bar \|
75 % Right brace \} Tilde \~}
76 %
77 %
78 % \changes{v1.0}{2014/09/17}{Initial version}
79 % \changes{v1.7b}{2015/08/04}{Fixed superfluous whitespaces}
80 % \changes{v2.2b}{2018/11/01}{Package author's name change}
81 %
82 % \GetFileInfo{asciilist.dtx}
83 %
84 % \DoNotIndex{\newcommand,\newenvironment,\def,\gdef,\edef}
85 %
86 %
87 % \title{The \textsf{asciilist} package\thanks{This document
88 % corresponds to \textsf{asciilist}~\fileversion, dated \filedate.
89 % The package is available online at
90 % \url{http://www.ctan.org/pkg/asciilist} and
91 % \url{https://github.com/Ri-Ga/asciilist}.}}
92 % \author{Richard Grewe \\ \texttt{[email protected]}}
93 %
94 % \maketitle
95 %
96 % \begin{abstract}
97 % This package provides two environments for \emph{quickly typesetting
98 % nested lists} in \LaTeX{} without having to type the individual
99 % |\item| macros or opening/closing nested list environments.
100 % \end{abstract}
101 %
102 % \section{Usage}
103 %
104 % We document the functionality of the package by examples in this
105 % section. The package provides two main environments: |AsciiList| and
106 % |AsciiDocList|.
107 %
108 % The |AsciiList| environment (Section~\ref{sec:AsciiList}) provides a
109 % list environment in which a single character at the beginning of a
110 % line can be used to typeset an item at a particular list level. The
111 % mapping between these characters and list levels is fixed for the
112 % whole list.
113 %
114 % The |AsciiDocList| environment (Section~\ref{sec:AsciiDocList})
115 % provides a list environment in which a sequence of characters at the
116 % beginning of a line can be used to typeset an item at a particular
117 % list level. The mapping between individual characters and list
118 % environments is fixed for the whole list. This environment, thus, uses
119 % a syntax that is close to the asciidoc syntax.
120 %
121 % \subsection{Lists with Fixed Nesting Layout}\label{sec:AsciiList}
122 %
123 % \DescribeEnv{AsciiList}
124 % Use the |AsciiList|\oarg{environments}\marg{item-chars} environment
125 % to quickly create \LaTeX{} lists, possibly nested ones, without too
126 % much \LaTeX{} interference. The following example might illustrate
127 % the environment best:
128 %
129 % \begin{LTXexample}
130 % \begin{AsciiList}{-,*,+,=}
131 % - first item
132 % * first sub-item
133 % * second sub-item,
134 % which is multi-line
135 % + a sub-sub item
136 % = a sub-sub-sub item
137 % - back up by three levels
138 % * end at a sub-item
139 % \end{AsciiList}
140 % \end{LTXexample}
141 % Note that in this example, the indentation with spaces is for
142 % demonstration purposes only. The package itself does not require a
143 % proper/uniform indentation of the items at the different levels.
144 % Item levels are solely recognized by the first character of a line.
145 %
146 % \DescribeMacro{\AsciiListFromFile}
147 % Instead of having the list content inline in the \LaTeX{} file, one
148 % can also choose to put the list into a separate file. A list of
149 % such file can then be produced via the
150 % |\AsciiListFromFile|\oarg{environments}\marg{item-chars}\marg{file-name}
151 % macro. The first two parameters of the macro are the same as the
152 % parameters of the |AsciiList| environment. The \meta{file-name}
153 % parameter specifies the name of the file to include.
154 % \iffalse
155 %<*ALexample>
156 * item
157 - sub-item
158 * another item
159 %</ALexample>
160 % \fi
161 % \begin{LTXexample}
162 % \AsciiListFromFile{auto}{AsciiList.example}
163 % \end{LTXexample}
164 % In the above example, the used input file has the following content:
165 % \lstinputlisting{AsciiList.example}
166 % Using |\input|, you can include the content of a file into an
167 % |AsciiList| environment. The formatting of the environment is then
168 % applied also to the content of the included file.
169 % \begin{LTXexample}
170 % \begin{AsciiList}{+,*,-}
171 % + main item
172 % \input{AsciiList.example}
173 % \end{AsciiList}
174 % \end{LTXexample}
175 %
176 % \DescribeMacro{\AsciiListFromFiles}
177 % The |\AsciiListFromFiles| macro is the same as |\AsciiListFromFile|,
178 % except that a comma-separated list is accepted for the
179 % \meta{file-name} parameter and that the files are input in the listed
180 % order.
181 %
182 % \subsubsection{Choosing List Environments}
183 %
184 % If you do not want to use the |itemize| environment for the lists,
185 % you can change it to |enumerate|, |compactitem| or other list-like
186 % environments (which should use |\item| for their items) you prefer
187 % by setting the optional \meta{environments} parameter. For example,
188 % you can set the \meta{environments} to |itemize,compactitem| in
189 % order to have the top level list as an |itemize| and the second as
190 % well as all deeper levels as |compactitem| lists.
191 %
192 % The |AsciiList| environment allows you to use more than just list
193 % environments like |itemize|, |enumerate|, or |description|. You can
194 % even use sectioning command names (|chapter|, |section|, |section*|,
195 % |subsection|, |paragraph| etc.), which have been enabled already
196 % with the |\NewAsciiListEnv| macro. If you use such ``environments'',
197 % every list entry will be produced using the respective |\chapter|,
198 % |\section|, |\section*|, |\subsection|, |\paragraph|, etc.{} macro.
199 % Note, however, that only the first line of such an item will then be
200 % used for the name of the section/subsection/etc.
201 % \SaveSecs
202 % \begin{LTXexample}
203 % \begin{AsciiList}[section,subsection]{-,*}
204 % - first section
205 % * a subsection
206 % - second section
207 % \end{AsciiList}
208 % \end{LTXexample}
209 %
210 % If you do not want to manually specify the nesting levels, you can
211 % also use the list environment |Heading|\oarg{initial}, as the
212 % following example demonstrates.\medskip
213 % \begin{LTXexample}
214 % \begin{AsciiList}[Heading<subsection>]{-,*,+}
215 % - a sub-section
216 % * a sub-sub-section
217 % + a paragraph
218 % and some text
219 % \end{AsciiList}
220 % \end{LTXexample}
221 % \RestoreSecs
222 % The |Heading| list environment produces numbered sections.
223 % Correspondingly, |Heading*| produces unnumbered sections.
224 %
225 % List environments with optional parameters are also supported,
226 % including their parameters. For instance, the |compactenum|
227 % environment of the \textsf{paralist} package has an optional parameter
228 % configuring the appearance of the individual items. The following
229 % example shows how to specify the optional parameters:\medskip
230 % \begin{LTXexample}
231 % \begin{AsciiList}[compactenum<1.>,
232 % compactenum<(a)>]{auto}
233 % - item number 1.
234 % * item (a)
235 % * item (b)
236 % - item number 2.
237 % \end{AsciiList}
238 % \end{LTXexample}
239 % Care has to be taken when the optional argument contains a comma. In
240 % this case, the optional argument must be enclosed in parentheses such
241 % that \LaTeX{} does not confuse the comma with a comma that separates
242 % the list environments.
243 %
244 % \subsubsection{Automatic Item Detection}
245 %
246 % If you want to be more flexible regarding the characters for the
247 % list items, you can use |auto| as the parameter to the environment.
248 % The |AsciiList| then makes an attempt to automatically identify the
249 % list items from a predefined list (preset to ``-'', ``*'', ``+'').
250 % \DescribeMacro{\AsciiListSetAutochars}
251 % You can change this list using the
252 % |\AsciiListSetAutochars|\marg{chars} macro, which expects
253 % \meta{chars} to be a comma-separated list of chars. The ordering of
254 % this list does not matter. What matters is the ordering in which the
255 % characters appear in the environment.
256 % \begin{LTXexample}
257 % \AsciiListSetAutochars{+,*,-,=}
258 % \begin{AsciiList}[enumerate,itemize,
259 % compactitem]{auto}
260 % - first item
261 % * first sub-item
262 % * second sub-item,
263 % which is multi-line
264 % + a sub-sub item
265 % - back up by three levels
266 % * end at a sub-item
267 % \end{AsciiList}
268 % \end{LTXexample}
269 %
270 % \subsubsection{Navigating Upwards}
271 % \changes{v2.1}{2016/03/05}{Documentation of \cs{UP} and \cs{UPTO}}
272 %
273 % If you want to typeset a list in which a list item is continued after
274 % sub-items of that item, you can use the |\UP| and |\UPTO| macros.
275 % \DescribeMacro{\UP}
276 % The |\UP|\oarg{N} macro goes back \meta{N} levels (default: 1) without
277 % starting a new item at the resulting level.
278 % \DescribeMacro{\UPTO}
279 % The |\UPTO|\marg{N} macro goes back to level \meta{N} (where the
280 % topmost level is 0) without starting a new item at the resulting
281 % level.
282 % The following example illustrates the use of the two macros.
283 % \begin{LTXexample}
284 % \begin{AsciiList}{auto}
285 % - first item
286 % * sub-item
287 % \UP[1]
288 % continuation one level higher
289 % * another sub-item
290 % + a sub-sub-item
291 % \UPTO{1}
292 % continuation on first-item level
293 % \end{AsciiList}
294 % \end{LTXexample}
295 %
296 %
297 % \subsection{Lists with AsciiDoc-Like Notation}\label{sec:AsciiDocList}
298 %
299 % \DescribeEnv{AsciiDocList}
300 % Use the |AsciiDocList|\oarg{environments} environment to quickly create
301 % \LaTeX{} lists, possibly nested ones, without too much \LaTeX{}
302 % interference. The following example might illustrate the environment
303 % best:
304 % \begin{LTXexample}
305 % \begin{AsciiDocList}
306 % * first item (itemized)
307 % *+ first sub-item (enumerated)
308 % *+ second sub-item (enumerated),
309 % which is multi-line
310 % *+* a sub-sub item
311 % * back up by three levels
312 % ** end at a sub-item (itemized)
313 % \end{AsciiDocList}
314 % \end{LTXexample}
315 % Note that in this example, the indentation with spaces is for
316 % demonstration purposes only. The package itself does not require a
317 % proper/uniform indentation of the items at the different levels.
318 %
319 % By default, the |*| character maps to an |itemize| item, the |+|
320 % character maps to an |enumerate| item, and the |;| character maps to a
321 % description item (where the item label follows in the line after the
322 % |;| and the item text follows in the subsequent line).
323 %
324 % \DescribeMacro{\AsciiDocListFromFile}
325 % Instead of having the list content inline in the \LaTeX{} file, one
326 % can also choose to put the list into a separate file. A list of
327 % such file can then be produced via the
328 % |\AsciiDocListFromFile|\oarg{environments}\marg{file-name}
329 % macro. The optional parameter of the macro is the same as the
330 % parameter of the |AsciiDocList| environment. The \meta{file-name}
331 % parameter specifies the name of the file to include.
332 % \iffalse
333 %<*ADLexample>
334 * item
335 *+ sub-item
336 * another item
337 %</ADLexample>
338 % \fi
339 % \begin{LTXexample}
340 % \AsciiDocListFromFile{AsciiDocList.example}
341 % \end{LTXexample}
342 % In the above example, the used input file has the following content:
343 % \lstinputlisting{AsciiDocList.example}
344 % Using |\input|, you can include the content of a file into an
345 % |AsciiDocList| environment. The formatting of the environment is then
346 % applied also to the content of the included file.
347 % \begin{LTXexample}
348 % \begin{AsciiDocList}
349 % * first item
350 % \input{AsciiDocList.example}
351 % \end{AsciiDocList}
352 % \end{LTXexample}
353 %
354 % \DescribeMacro{\AsciiDocListFromFiles}
355 % The |\AsciiDocListFromFiles| macro is the same as
356 % |\AsciiDocListFromFile|, except that a comma-separated list is
357 % accepted for the \meta{file-name} parameter and that the files are
358 % input in the listed order.
359 %
360 % \subsubsection{Choosing List Environments}
361 %
362 % If you do not want to use the pre-defined mapping of |*| to |itemize|
363 % etc., you can change the mapping to other list-like environments
364 % (which should use |\item| for their items) you prefer by setting the
365 % optional \meta{environments} parameter. For example, you can set the
366 % \meta{environments} to |*=itemize,-=compactitem,!=enumerate|.
367 %
368 % The |AsciiDocList| environment allows you to use more than just list
369 % environments like |itemize|, |enumerate|, or |description|. The range
370 % of supported environments is for |AsciiDocList| is the same as for
371 % |AsciiList|.
372 % \SaveSecs
373 % \begin{LTXexample}
374 % \begin{AsciiDocList}[/=section,
375 % *=subsection]
376 % / first section
377 % /* first subsection
378 % /* second subsection
379 % / second section
380 % \end{AsciiDocList}
381 % \end{LTXexample}
382 % \RestoreSecs
383 %
384 % \subsubsection{Navigating Upwards}
385 % \changes{v2.1}{2016/03/05}{Documentation of \cs{UPTO}}
386 %
387 % If you want to typeset a list in which a list item is continued after
388 % sub-items of that item, you can use the |\UPTO| macro.
389 % \DescribeMacro{\UPTO}
390 % The |\UPTO|\marg{chars} macro goes back the level identified by
391 % \meta{chars} without starting a new item at the resulting level.
392 % The following example illustrates the use of the macro.
393 % \begin{LTXexample}
394 % \begin{AsciiDocList}
395 % ; description
396 % beginning of description
397 % ;+ item
398 % ;+* sub-item
399 % \UPTO{;}
400 % continuation of description
401 % \end{AsciiDocList}
402 % \end{LTXexample}
403 %
404 %
405 % \section{Customizing List Environments}\label{sec:config}
406 %
407 % \DescribeMacro{\AsciiListRegisterEnv}
408 % You can register additional environment names for use with
409 % |AsciiList| or |AsciiDocList| by using the
410 % |\AsciiListRegisterEnv|\marg{envname}\marg{begin}\marg{end}\marg{item}
411 % macro, by which the \meta{begin}, \meta{end}, and \meta{item} code
412 % can be specified.
413 % \DescribeMacro{\AsciiListEndArg}
414 % If you want to use a command for the \meta{item}
415 % code that takes a single parameter (e.g., |\section|), then you can
416 % use |\AsciiListEndArg|\marg{command} for the \meta{item} to pass the
417 % whole line of the item to \meta{command}.
418 % \DescribeMacro{\AsciiListEndOArg}
419 % If the \meta{item} takes a single \emph{optional} parameter (like
420 % |\item|), then use |\AsciiListEndOArg|\marg{command} instead of
421 % |\AsciiListEndArg|.
422 % For example to register an environment |TTEnum| for enumerating
423 % items in typewriter font, you can use the following command:
424 % \begin{LTXexample}
425 % \AsciiListRegisterEnv{TTEnum}
426 % {\enumerate}{\endenumerate}
427 % {\AsciiListEndArg{\item\texttt}}
428 % \begin{AsciiList}[TTEnum]{-}
429 % - items are typewriter
430 % (though only in the first line)
431 % - and enumerated
432 % \end{AsciiList}
433 % \end{LTXexample}
434 %
435 % \subsection{Customizing \texttt{AsciiList}}
436 %
437 % \DescribeMacro{\AsciiListSetEnvironments}
438 % You can also change the default list environments for |AsciiList| from
439 % |itemize| to a comma-separated list of \meta{environments}. This
440 % allows you to omit the optional parameter to the |AsciiList|
441 % environment for such default configurations. For this, use the
442 % |\AsciiListSetEnvironments|\marg{environments} macro.
443 % \begin{LTXexample}
444 % \AsciiListSetEnvironments{enumerate,
445 % compactitem<!>}
446 % \begin{AsciiList}{-,*}
447 % - first
448 % * sub
449 % - second
450 % \end{AsciiList}
451 % \end{LTXexample}
452 %
453 % \DescribeMacro{\NewAsciiListEnv}
454 % If particular kinds of nested lists occur several times in your
455 % document, you can also define abbreviation environments, as
456 % demonstrated in the following (which also shows how to use
457 % |description| environments in an |AsciiList|):
458 % \begin{LTXexample}
459 % \NewAsciiListEnv[description,compactitem]
460 % {auto}{TopicIdeas}
461 % \begin{TopicIdeas}
462 % + food:
463 % - cheese
464 % - nuts
465 % + beverages:
466 % - water
467 % - milk
468 % \end{TopicIdeas}
469 % \end{LTXexample}
470 %
471 % \subsection{Customizing \texttt{AsciiDocList}}
472 %
473 % \DescribeMacro{\AsciiDocListSetEnvironments}
474 % You can also change the default list environments for |AsciiDocList|
475 % from |*=itemize,+=enumerate| to another comma-separated list of
476 % \meta{environments}. This allows you to omit the optional parameter to
477 % the |AsciiDocList| environment for such default configurations. For this,
478 % use the |\AsciiDocListSetEnvironments|\marg{environments} macro.
479 % \begin{LTXexample}
480 % \AsciiDocListSetEnvironments{?=enumerate,
481 % !=compactitem<!>}
482 % \begin{AsciiDocList}
483 % ? item?
484 % ?! sub!
485 % ? second
486 % \end{AsciiDocList}
487 % \end{LTXexample}
488 %
489 % \DescribeMacro{\NewAsciiDocListEnv}
490 % The analogous macro to |\NewAsciiListEnv| for the |AsciiDocList|
491 % environment is |\NewAsciiDocListEnv|. Its use is as the following
492 % example illustrates:
493 % \begin{LTXexample}
494 % \NewAsciiDocListEnv[!=Description,
495 % *=compactitem]{TopicDoc}
496 % \begin{TopicDoc}
497 % ! food:
498 % !* cheese
499 % !* nuts
500 % ! beverages:
501 % !* water
502 % !* milk
503 % \end{TopicDoc}
504 % \end{LTXexample}
505 %
506 % \section{Noteworthy Features}
507 %
508 % \begin{itemize}
509 % \item This package can be used together with Sync\TeX{}. That is,
510 % for a point in the |AsciiList| of a generated PDF, one can obtain
511 % the position in the |AsciiList|'s source code.
512 % \item Some initial tests show that |AsciiList| can be used in a
513 % |p|-column of a |tabular| environment.
514 % \end{itemize}
515 %
516 % \section{Known Limitations}
517 %
518 % \begin{itemize}
519 % \item Currently, the |AsciiList| and |AsciiDocList| environments
520 % cannot be used in a ``moving argument'', such as in a |\footnote|.
521 % If you really want such lists in footnotes, you might consider
522 % using |\AsciiListFromFile| and friends.
523 % \item Not all chars can directly be used as item chars. This probably
524 % is some character code issue that so far has not been investigated
525 % further.
526 % \end{itemize}
527 %
528 % \section{Related Packages}
529 %
530 % The following \LaTeX{} packages provide similar functionalities to
531 % the \textsf{asciilist} package.
532 %
533 % \begin{description}
534 % \item[\textsf{easylist}:]
535 % This package is probably closest to \textsf{asciilist}. The package
536 % ``is designed for typesetting lists of numbered items [...] with a
537 % single active character acting as the only command'' (cited from
538 % the package documentation). The package provides a lot of
539 % possibilities for configuring the appearance of items at the
540 % individual levels.
541 % Compared to \textsf{asciilist}, the package differs in two main
542 % points. Firstly, the package uses a single character for the items.
543 % This character can be used in the middle of a line to begin a new
544 % item and, hence, must not occur in the text itself. The character
545 % must be repeated for indicating the depth of the item, rather than
546 % having separate characters for different levels. Secondly, the
547 % package is focused on list environments and does not support using
548 % sectioning macros for items at selected levels.
549 % Finally, the package does not provide convenience functionality
550 % similar to that described in Section~\ref{sec:config} of this
551 % documentation.
552 % \item[\textsf{iitem}:]
553 % This package provides macros |\iitem|..|\ivtem|, which can be used
554 % within |enumerate| and |itemize| environments for changing list
555 % levels without explicitly starting nested |enumerate| and |itemize|
556 % environments. The list type (|enumerate|, |itemize|, \ldots) is
557 % the same for all nested list levels.
558 % Compared to \textsf{asciilist}, the package has the main drawback
559 % that the list type is the same for all levels. Moreover, the package
560 % uses \LaTeX-ish enumeration macros rather than nice symbols. The
561 % package does not provide convenience functionality similar to that
562 % described in Section~\ref{sec:config} of this documentation.
563 % Finally, the package has the limitation that items below the first
564 % level must be placed within a single line.
565 % \item[\textsf{outlines}:]
566 % This package provides an |outline| environment, in which multiple
567 % list levels can be accessed. The individual levels can be reached
568 % via |\1|..|\4| macros, which substitute the |\item| of the
569 % respective level. The list environments that |outline| uses
570 % for the individual levels are configurable.
571 % Compared to \textsf{asciilist}, the package has the slight drawback
572 % that it uses \LaTeX-ish enumeration macros rather than nice symbols.
573 % Moreover, the package does not offer convenience functionality
574 % similar to that described in Section~\ref{sec:config} of this
575 % documentation.
576 % \end{description}
577 %
578 % \clearpage
579 %
580 % \StopEventually{}
581 %\iffalse
582 %<*package>
583 %\fi
584 %
585 % \section{Implementation}
586 %
587 % The \textsf{etoolbox} package is used for processing comma-separated
588 % lists easily.
589 % \begin{macrocode}
590 \RequirePackage{etoolbox}
591 % \end{macrocode}
592 % The \textsf{trimspaces} package is used for trimming leading spaces
593 % in a robust manner.
594 % \begin{macrocode}
595 \RequirePackage{trimspaces}
596 % \end{macrocode}
597 %
598 % \subsection{The \texttt{AsciiList} Environment}
599 %
600 % \begin{environment}{AsciiList}
601 % The |AsciiList|\oarg{environments}\marg{item-chars} creates an
602 % environment in which nested lists can be typeset without much
603 % \LaTeX{} interference. The \meta{item-chars} must specify of
604 % comma-separated list of characters. The special value |auto| makes
605 % the environment try to auto-detect the \meta{item-chars}.
606 % The \meta{environments} specifies an optional, comma-separated list
607 % of environments to be used to create the lists at the individual
608 % levels.
609 % \changes{v1.2}{2014/09/18}{Allow auto-detection of item-chars}
610 % \changes{v2.1b}{2016/03/31}{Eliminated expansion of optional argument}
611 % \begin{macrocode}
612 \newenvironment{AsciiList}[2][]{%
613 \bgroup
614 % \end{macrocode}
615 % Setup the environment by storing the list \meta{environments} to use
616 % and -- most importantly -- setting up the newline character such
617 % that it scans for the \meta{item-chars} to find new list items.
618 % \begin{macrocode}
619 \ifstrempty{#1}%
620 {\let\asclst@listenv=\asclst@defaultenvs}%
621 {\def\asclst@listenv{#1}}%
622 % \end{macrocode}
623 % Convert the given \meta{item-chars} to an internal list of
624 % \textsf{etoolbox}, because this makes working with the list easier.
625 % \begin{macrocode}
626 \gdef\asclst@itemchars{}%
627 \ifstrequal{#2}{auto}%
628 {\asclst@autocharstrue}%
629 {\asclst@autocharsfalse\forcsvlist{\listadd\asclst@itemchars}{#2}}%
630 \asclst@nlsetup\asclst@newline
631 % \end{macrocode}
632 % We re-define |\input|\marg{filename} such that it becomes possible
633 % to include |AsciiList|-formatted input files.
634 % \begin{macrocode}
635 \def\input##1{%
636 % \end{macrocode}
637 % We input the file using the |\@@input| primitive, because this
638 % primitive can be expanded via |\expandafter| such that the
639 % |\asclst@newline| can parse the first line of the file already.
640 % \begin{macrocode}
641 \everyeof{\noexpand}%
642 \expandafter\asclst@newline\@@input##1\relax}%
643 % \end{macrocode}
644 % Initialize to nesting level $0$. And make the macro |\UP| available
645 % for switching to an upper level.
646 % \changes{v1.5}{2014/09/21}{Avoid missing item error in empty
647 % environment}
648 % \changes{v1.5}{2014/09/21}{Add command to explicitly changle levels
649 % upwards}
650 % \begin{macrocode}
651 \global\asclst@curlevel=0\relax%
652 \let\UP=\asclst@levelsup%
653 \let\UPTO=\asclst@levelsupto%
654 % \end{macrocode}
655 % Ensure that the scanning for an item char starts with the very first
656 % line of the environment.
657 % \changes{v2.0a}{2016/02/23}{Improved first-line handling.}
658 % \begin{macrocode}
659 \asclst@ifnextnewline{}{\asclst@newline}%
660 }{%
661 % \end{macrocode}
662 % Ensure that all remaining open list environments are closed before
663 % the end of the |AsciiList| environment.
664 % \begin{macrocode}
665 \asclst@changelistlevel{\asclst@curlevel}{0}%
666 \asclst@restorenewline%
667 \egroup}
668 % \end{macrocode}
669 % \end{environment}
670 %
671 % \begin{macro}{\AsciiListFromFile}
672 % The |\AsciiListFromFile|\oarg{environments}\marg{item-chars}\marg{file-name}
673 % macro produces a result like the |AsciiList| environment does,
674 % but takes the content of the list from \meta{file-name}.
675 % \changes{v1.8}{2015/08/19}{Added this macro}
676 % \begin{macrocode}
677 \newcommand\AsciiListFromFile[3][]{%
678 \AsciiList[#1]{#2}%
679 \input{#3}%
680 \endAsciiList}
681 % \end{macrocode}
682 % \end{macro}
683 %
684 % \begin{macro}{\AsciiListFromFiles}
685 % The |\AsciiListFromFiles|\oarg{environments}\marg{item-chars}\marg{file-list}
686 % macro produces a result like the |AsciiList| environment does,
687 % but takes the content of the list from the comma-separated
688 % \meta{file-list}.
689 % \changes{v1.8b}{2015/08/24}{Added this macro}
690 % \begin{macrocode}
691 \newcommand\AsciiListFromFiles[3][]{%
692 \AsciiList[#1]{#2}%
693 % \end{macrocode}
694 % We do the same here as for the |\AsciiListFromFile| macro,
695 % just in a loop over the \meta{file-list}. Note that |\dolistloop|
696 % is to be avoided here, because there is quite some chance that
697 % the |\do| macro gets redefined in the included code.
698 % \begin{macrocode}
699 \forcsvlist{\input}{#3}%
700 \endAsciiList}
701 % \end{macrocode}
702 % \end{macro}
703 %
704 % \subsubsection{Handling of Line Breaks}
705 %
706 % For our code, line breaks are important to be tracked, because an
707 % item-indicating char at the beginning of a line (i.e., after a line
708 % break) is crucial.
709 % \begin{macrocode}
710 {\catcode`\^^M=\active%
711 % \end{macrocode}
712 %
713 % \begin{macro}{\asclst@checknext}
714 % The |\asclst@checknext|\marg{first-char}\marg{item-char} checks
715 % whether \meta{first-char} (used with the first char of a line after
716 % a line break) is equal to a given \meta{item-char} (a character that
717 % indicates the beginning of a new list item) and, if so, sets the
718 % counter |\asclst@newlevel| to the value of |\@tempcntb|. This is used
719 % in |\asclst@newline| to store the index of a found \meta{item-char} in
720 % the list of \meta{item-chars} of the |AsciiList| environment.
721 % \begin{macrocode}
722 \gdef\asclst@checknext#1#2{%
723 \ifstrequal{#1}{#2}{\asclst@newlevel=\@tempcntb}{}}%
724 % \end{macrocode}
725 % \end{macro}
726 %
727 % \begin{macro}{\asclst@newline}
728 % The |\asclst@newline|\marg{first-char} macro is executed whenever a
729 % newline character occurs in the |AsciiList| environment. The
730 % \meta{first-char} then is the first character (or, rather, token)
731 % after the newline.
732 % Important in this macro: all lines must end with a percent char, to
733 % not introduce new newline chars in the macro itself (this would
734 % yield an endless recursion).
735 % \begin{macrocode}
736 \gdef\asclst@newline#1{%
737 % \end{macrocode}
738 % First, we find out whether the next char is in list
739 % \meta{item-chars} (i.e., in |\asclst@itemchars|) and return the
740 % position in the list in
741 % |\asclst@newlevel| (or $0$ if not found).
742 % \begin{macrocode}
743 \asclst@newlevel=0\@tempcntb=0\relax%
744 \forlistloop{\advance\@tempcntb by 1\asclst@checknext{#1}}%
745 {\asclst@itemchars}%
746 % \end{macrocode}
747 % If the next char is not in the \meta{item-chars}, but the
748 % |AsciiList| was given the |auto| parameter for \meta{item-chars},
749 % then we check whether we can automatically determine the character
750 % for a new nesting level. The char for this new nesting level is then
751 % (globally) added to the list of known \meta{item-chars} in
752 % |\asclst@itemchars|. Note that in the following code, the value
753 % of |\@tempcntb| still is the length of the |\asclst@itemchars| list.
754 % \begin{macrocode}
755 \ifnum\asclst@newlevel=0\ifasclst@autochars%
756 \ifinlist{#1}{\asclst@autocharlist}{%
757 \listgadd\asclst@itemchars{#1}%
758 \asclst@newlevel=\@tempcntb%
759 \advance\asclst@newlevel by 1\relax%
760 }{}%
761 \fi\fi%
762 % \end{macrocode}
763 % If we found a character from \meta{item-chars}, then we ensure to
764 % change to the nesting level of this character (which is in
765 % |\asclst@newlevel|) and then trigger a new |\item|.
766 % \changes{v1.5b}{2014/09/24}{Fix item spacing for in-paragraph lists}
767 % \changes{v1.8b}{2015/08/24}{Robustified by not using \cs{do}}
768 % \begin{macrocode}
769 \ifnum\asclst@newlevel>0\relax%
770 \def\asclst@@do{%
771 \asclst@changelistlevel{\asclst@curlevel}{\asclst@newlevel}%
772 \ifhmode\unskip\space\fi\asclst@@item}%
773 \else%
774 % \end{macrocode}
775 % If no character from \meta{item-chars} is found, we check whether
776 % the newline causing |\asclst@newline| to be invoked is followed by
777 % another newline character. In this case, we insert a |\par|.
778 % \changes{v1.5b}{2014/09/24}{Empty lines captured}
779 % \begin{macrocode}
780 \def\asclst@@tmpone{#1}\def\asclst@@test{^^M}%
781 \ifx\asclst@@test\asclst@@tmpone%
782 \def\asclst@@do{\par #1}%
783 % \end{macrocode}
784 % Otherwise, we just use a |\space| for the newline character and
785 % flush out the token |#1| that we captured after the newline
786 % character.
787 % \begin{macrocode}
788 \else\def\asclst@@do{\space #1}\fi%
789 \fi\asclst@@do}%
790 % \end{macrocode}
791 % \end{macro}
792 %
793 % \begin{macro}{\asclst@ifnextnewline}
794 % The |\asclst@ifnextnewline|\marg{iftrue}\marg{iffalse} macro checks
795 % whether the next character is a newline. If the check succeeds, then
796 % the macro expands to \meta{iftrue}. Otherwise, the macro expands to
797 % \meta{iffalse}.
798 % \begin{macrocode}
799 \gdef\asclst@ifnextnewline{\@ifnextchar^^M}
800 % \end{macrocode}
801 % \end{macro}
802 %
803 % The following ends the group with active line break catcode.
804 % \begin{macrocode}
805 }
806 % \end{macrocode}
807 %
808 % \subsubsection{Level-Changing Macros}
809 %
810 % \begin{macro}{\asclst@curlevel}
811 % We use the |\asclst@curlevel| counter to capture the current nesting
812 % depth of list environments within an |AsciiList|. We also use a
813 % counter for changing the level to a new one.
814 % \begin{macrocode}
815 \newcount\asclst@curlevel
816 \newcount\asclst@newlevel
817 % \end{macrocode}
818 % \end{macro}
819 %
820 % \begin{macro}{\asclst@changelistlevel}
821 % The |\asclst@changelistlevel|\marg{from}\marg{to} changes the list
822 % nesting level from level \meta{from} (a number) to level \meta{to}
823 % (a number), by issuing the right number of |\begin| or |\end|
824 % environments.
825 % \changes{v1.1}{2014/09/18}{Allow list of list environments}
826 % \begin{macrocode}
827 \newcommand\asclst@changelistlevel[2]{%
828 \def\asclst@@envchanger{}%
829 \ifnum#2<#1\relax
830 % \end{macrocode}
831 % If $\meta{to}<\meta{from}$, then we must change to a lower list nesting
832 % level. We do this by inserting $\meta{from}-\meta{to}$
833 % |\end|-environments, which we store in |\asclst@@envchanger|.
834 % \begin{macrocode}
835 \def\asclst@@last{}%
836 % \end{macrocode}
837 % First, we collect all affected environment names from the given
838 % \meta{environments} parameter to |AsciiList| (which at this point is
839 % in |\asclst@listenv|): We take all those from list index $\meta{to}+1$
840 % until list index $\meta{from}$, in reverse order (hence |\preto|),
841 % which are actually in the list.
842 % \begin{macrocode}
843 \@tempcnta=0\relax
844 \@tempcntb=#2 \advance\@tempcntb by 1\relax
845 \def\do##1{\advance\@tempcnta by1\relax
846 \ifnum\@tempcnta<\@tempcntb\else
847 \ifnum\@tempcnta>#1\else
848 \preto\asclst@@envchanger{\asclst@end ##1<>\@undefined}\fi\fi
849 \def\asclst@@last{##1}}%
850 \expandafter\docsvlist\expandafter{\asclst@listenv}%
851 % \end{macrocode}
852 % Second, for all indices from $\meta{to}+1$ until $\meta{from}$ that
853 % are \emph{not} in the \meta{environments} list, we just take the
854 % last list entry (stored in |\asclst@@last| by the above code) and
855 % repeat it sufficiently often, i.e., from
856 % $\max(\mathrm{len}\meta{environments},\meta{from})+1$ until
857 % $\meta{to}$ times.
858 % \begin{macrocode}
859 \advance\@tempcnta by1\ifnum\@tempcnta<\@tempcntb
860 \@tempcnta=\@tempcntb\fi
861 \loop \ifnum\@tempcnta>#1\else
862 \advance\@tempcnta by 1%
863 \epreto\asclst@@envchanger{\noexpand
864 \asclst@end\expandonce\asclst@@last<>\noexpand\@undefined}%
865 \repeat%
866 \else\ifnum#2>#1\relax%
867 % \end{macrocode}
868 % The following does the same as the above, except that:
869 % |\begin| instead of |\end| of environments are collected;
870 % they are collected in the ordering as in \meta{environments} (hence
871 % |\appto|); and
872 % entries are collected from $\meta{from}+1$ to $\meta{to}$.
873 % \begin{macrocode}
874 \def\asclst@@last{}%
875 \@tempcnta=0\relax
876 \@tempcntb=#1\relax\advance\@tempcntb by 1\relax
877 \def\do##1{\advance\@tempcnta by1\relax
878 \ifnum\@tempcnta<\@tempcntb\else
879 \ifnum\@tempcnta>#2\else
880 \appto\asclst@@envchanger{\asclst@begin ##1<>\@undefined}\fi\fi
881 \def\asclst@@last{##1}}%
882 \expandafter\docsvlist\expandafter{\asclst@listenv}%
883 \advance\@tempcnta by1\ifnum\@tempcnta<\@tempcntb
884 \@tempcnta=\@tempcntb\fi
885 \loop \ifnum\@tempcnta>#2\else
886 \advance\@tempcnta by 1%
887 \eappto\asclst@@envchanger{%
888 \noexpand\asclst@begin
889 \expandonce\asclst@@last<>\noexpand\@undefined}%
890 \repeat%
891 \fi\fi%
892 % \end{macrocode}
893 % Update the current level to the new value, \meta{to}. Then write out
894 % the begin/end environments collected in |\asclst@@envchanger|.
895 % \begin{macrocode}
896 \global\asclst@curlevel=#2%
897 \asclst@@envchanger}
898 % \end{macrocode}
899 % \end{macro}
900 %
901 % \begin{macro}{\asclst@levelsup}
902 % The |\asclst@levelsup|\oarg{number} macro allows switching to a
903 % nesting level that is \meta{number} levels upwards (default:
904 % $\meta{number}=1$). In the |AsciiList| environment, this macro is
905 % accessible via the |\UP| command.
906 % \begin{macrocode}
907 \newcommand*\asclst@levelsup[1][1]{%
908 \asclst@newlevel=\asclst@curlevel
909 \advance\asclst@newlevel by-#1\relax
910 \asclst@changelistlevel{\asclst@curlevel}{\asclst@newlevel}}
911 % \end{macrocode}
912 % \end{macro}
913 % \begin{macro}{\asclst@levelsupto}
914 % The |\asclst@levelsupto|\marg{number} macro allows switching to
915 % list nesting level \meta{number}. In the |AsciiList| environment,
916 % this macro is accessible via the |\UPTO| command.
917 % \begin{macrocode}
918 \newcommand*\asclst@levelsupto[1]{%
919 \ifnum\asclst@curlevel<#1\relax
920 \PackageError{asciilist}{Cannot change level downwards!}{}%
921 \else
922 \asclst@changelistlevel{\asclst@curlevel}{#1}%
923 \fi}
924 % \end{macrocode}
925 % \end{macro}
926 %
927 %
928 %
929 % \subsection{The \texttt{AsciiDocList} Environment}
930 %
931 % \begin{environment}{AsciiDocList}
932 % The |AsciiDocList|\oarg{environments} creates an environment in which
933 % nested lists can be typeset without much \LaTeX{} interference. The
934 % \meta{environments} must be a comma-separated list of
935 % ``\meta{char}=\meta{environment}'' entries.
936 % \changes{v2.0}{2015/11/13}{Added \texttt{AsciiDocList} environment}
937 % \begin{macrocode}
938 \newenvironment{AsciiDocList}[1][]{%
939 \bgroup
940 % \end{macrocode}
941 % Modify the newline character to scan for characters that trigger
942 % items.
943 % \changes{v2.2}{2016/04/15}{Enabled \cs{input} in the macros and environments}
944 % \begin{macrocode}
945 \def\asclst@curnestlvl{}%
946 \asclst@nlsetup\asclst@docnewline%
947 % \end{macrocode}
948 % We re-define |\input|\marg{filename} such that it becomes possible
949 % to include |AsciiDocList|-formatted input files.
950 % \begin{macrocode}
951 \def\input##1{%
952 % \end{macrocode}
953 % We input the file using the |\@@input| primitive, because this
954 % primitive can be expanded via |\expandafter| such that the
955 % |\asclst@docnewline| can parse the first line of the file already.
956 % \begin{macrocode}
957 \expandafter\asclst@docnewline\@@input##1\relax}%
958 % \end{macrocode}
959 % Now setup the characters that trigger items.
960 % \begin{macrocode}
961 \def\asclst@levelchrs{}%
962 \def\do##1{\asclst@parsechmapentry##1\@undefined}%
963 \ifstrempty{#1}%
964 {\expandafter\docsvlist\expandafter{\asclst@docdefaultenvs}}%
965 {\docsvlist{#1}}%
966 % \end{macrocode}
967 % And make the macro |\UPTO| available for switching to an upper level.
968 % \changes{v2.1}{2016/03/04}{Add \cs{UPTO} to explicitly changle levels
969 % upwards}
970 % \begin{macrocode}
971 \let\UPTO=\asclst@changedoclistlevel%
972 % \end{macrocode}
973 % Ensure that the scanning for an item char starts with the very first
974 % line of the environment.
975 % \changes{v2.0a}{2016/02/23}{Improved first-line handling.}
976 % \begin{macrocode}
977 \asclst@ifnextnewline{}{\asclst@docnewline}%
978 }{%
979 % \end{macrocode}
980 % Ensure that all remaining open list environments are closed before the
981 % end of the |AsciiDocList| environment.
982 % \begin{macrocode}
983 \asclst@changedoclistlevel{}%
984 \asclst@restorenewline%
985 \egroup}
986 % \end{macrocode}
987 % \end{environment}
988 %
989 % \begin{macro}{\AsciiDocListFromFile}
990 % The |\AsciiDocListFromFile|\oarg{environments}\marg{file-name}
991 % macro produces a result like the |AsciiDocList| environment does,
992 % but takes the content of the list from \meta{file-name}.
993 % \begin{macrocode}
994 \newcommand\AsciiDocListFromFile[2][]{%
995 \AsciiDocList[#1]%
996 \input{#2}%
997 \endAsciiDocList}
998 % \end{macrocode}
999 % \end{macro}
1000 %
1001 % \begin{macro}{\AsciiDocListFromFiles}
1002 % The |\AsciiDocListFromFiles|\oarg{environments}\marg{file-list}
1003 % macro produces a result like the |AsciiDocList| environment does,
1004 % but takes the content of the list from the comma-separated
1005 % \meta{file-list}.
1006 % \begin{macrocode}
1007 \newcommand\AsciiDocListFromFiles[2][]{%
1008 \AsciiDocList[#1]%
1009 % \end{macrocode}
1010 % We do the same here as for the |\AsciiDocListFromFile| macro,
1011 % just in a loop over the \meta{file-list}. Note that |\dolistloop|
1012 % is to be avoided here, because there is quite some chance that
1013 % the |\do| macro gets redefined in the included code.
1014 % \begin{macrocode}
1015 \forcsvlist{\input}{#2}%
1016 \endAsciiDocList}
1017 % \end{macrocode}
1018 % \end{macro}
1019 %
1020 %
1021 % \subsubsection{Handling of Line Breaks}
1022 %
1023 % For our code, line breaks are important to be tracked, because an
1024 % item-indicating char at the beginning of a line (i.e., after a line
1025 % break) is crucial.
1026 % \begin{macrocode}
1027 {\catcode`\^^M=\active%
1028 % \end{macrocode}
1029 %
1030 % \begin{macro}{\asclst@docnewline}
1031 % The |\asclst@docnewline|\marg{first-char} macro is executed whenever a
1032 % newline character occurs in the |AsciiDocList| environment. The
1033 % \meta{first-char} then is the first character (or, rather, token)
1034 % after the newline.
1035 % \changes{v2.2}{2016/04/15}{Robustified file inputs against \cs{everyeof} changes}
1036 % \begin{macrocode}
1037 \gdef\asclst@docnewline{%
1038 % \end{macrocode}
1039 % The following is a bit of a hack to ensure that there is some
1040 % parameter to |\asclst@docnewline| even if the input file ends with
1041 % a newline directly afterwards.
1042 % \begin{macrocode}
1043 \everyeof{\noexpand}%
1044 \asclst@docnewline@i{}}%
1045 % \end{macrocode}
1046 % \end{macro}
1047 % \begin{macro}{\asclst@docnewline@i}
1048 % The |\asclst@docnewline@i|\marg{char-seq}\marg{test-char} macro
1049 % recursively collects characters (tokens) until a token is found that
1050 % is not in |\asclst@levelchrs|.
1051 % \begin{macrocode}
1052 \gdef\asclst@docnewline@i#1#2{%
1053 \ifinlist{#2}{\asclst@levelchrs}%
1054 {\asclst@docnewline@i{#1#2}}%
1055 {\asclst@docnewline@ii{#1}{#2}}}%
1056 % \end{macrocode}
1057 % \end{macro}
1058 % \begin{macro}{\asclst@docnewline@ii}
1059 % The |\asclst@docnewline@ii|\marg{char-seq}\marg{next} macro creates a
1060 % new list item (in the right environment), if \meta{char-seq} is
1061 % non-empty. The \meta{next} character must not be in the
1062 % |\asclst@levelchrs| and is inserted after the new item.
1063 % \begin{macrocode}
1064 \gdef\asclst@docnewline@ii#1#2{%
1065 \ifstrempty{#1}{%
1066 % \end{macrocode}
1067 % If \meta{char-seq} is empty, this means there was no item char at the
1068 % beginning of the line. Hence, no item shall be put here, but the
1069 % \meta{next} char must be inserted again. If \meta{next} is another
1070 % newline character, then we insert a |\par| instead.
1071 % \begin{macrocode}
1072 \def\asclst@@tmpone{#2}\def\asclst@@test{^^M}%
1073 \ifx\asclst@@test\asclst@@tmpone%
1074 \def\asclst@@do{\par #2}%
1075 \else%
1076 \def\asclst@@do{\space #2}\fi%
1077 \asclst@@do%
1078 }{%
1079 % \end{macrocode}
1080 % If \meta{char-seq} is non-empty, then change the nesting level
1081 % to \meta{char-seq} and then trigger a new |\item|.
1082 % \begin{macrocode}
1083 \asclst@changedoclistlevel{#1}%
1084 \ifhmode\unskip\space\fi\asclst@@item #2%
1085 }}%
1086 % \end{macrocode}
1087 % \end{macro}
1088 % The following ends the group with active line break catcode.
1089 % \begin{macrocode}
1090 }
1091 % \end{macrocode}
1092 %
1093 % \begin{macro}{\asclst@parsechmapentry}
1094 % The |\asclst@parsechmap|\meta{char}|=|\meta{env}|\@undefined| macro
1095 % adds a \meta{char} to the list of level characters and defines a
1096 % mapper macro from the \meta{char} to the \meta{env}.
1097 % \begin{macrocode}
1098 \def\asclst@parsechmapentry#1=#2\@undefined{%
1099 \listadd\asclst@levelchrs{#1}%
1100 \csdef{asclst@levelchr@#1}{#2}}
1101 % \end{macrocode}
1102 % \end{macro}
1103 %
1104 % \subsubsection{Level-Changing Macros}
1105 %
1106 % \begin{macro}{\asclst@changedoclistlevel}
1107 % The |\asclst@changedoclistlevel|\marg{to} changes the list nesting level
1108 % from level |\asclst@curnestlvl| (a character sequence) to level
1109 % \meta{to} (a character sequence), by issuing the right number of
1110 % |\begin| or |\end| environments.
1111 % \begin{macrocode}
1112 \newcommand\asclst@changedoclistlevel[1]{%
1113 \def\asclst@@envchanger{}%
1114 \expandafter\asclst@changedoclistlevel@i\asclst@curnestlvl{}{}\@undefined
1115 #1{}{}\@undefined
1116 \asclst@@envchanger
1117 \gdef\asclst@curnestlvl{#1}}
1118 % \end{macrocode}
1119 % \end{macro}
1120 % \begin{macro}{\asclst@changedoclistlevel@i}
1121 % The
1122 % |\asclst@changedoclistlevel@i|\meta{ohd}\meta{otl}|\@undefined|\meta{nhd}\meta{ntl}|\@undefined|
1123 % macro recursively strips off the common prefixes from the old
1124 % environment list (with head \meta{ohd} and tail \meta{otl}) and the
1125 % new environment list (with head \meta{nhd} and tail \meta{ntl}).
1126 % Afterwards, the macro uses |\asclst@changedoclistlevel@ii| to construct
1127 % the |\asclst@@envchanger|.
1128 % \begin{macrocode}
1129 \def\asclst@changedoclistlevel@i#1#2\@undefined#3#4\@undefined{%
1130 % \end{macrocode}
1131 % If both environment lists have been processed, then \meta{ohd} and
1132 % \meta{nhd} are empty and nothing needs to be done.
1133 % \begin{macrocode}
1134 \ifstrempty{#1#3}{}{%
1135 % \end{macrocode}
1136 % Otherwise, if the heads are equal, go to the recursive case for
1137 % further stripping off the common prefix. If the
1138 % heads differ, proceed with |\asclst@changedoclistlevel@ii|.
1139 % \begin{macrocode}
1140 \ifstrequal{#1}{#3}%
1141 {\asclst@changedoclistlevel@i#2{}\@undefined#4{}\@undefined}%
1142 {\asclst@changedoclistlevel@ii#1#2{}\@undefined#3#4{}\@undefined}%
1143 }}
1144 % \end{macrocode}
1145 % \end{macro}
1146 % \begin{macro}{\asclst@changedoclistlevel@ii}
1147 % The
1148 % |\asclst@changedoclistlevel@ii|\meta{ohd}\meta{otl}|\@undefined|\meta{nhd}\meta{ntl}|\@undefined|
1149 % macro recursively decomposes the old environment list (with head
1150 % \meta{ohd} and tail \meta{otl}) and the new environment list (with
1151 % head \meta{nhd} and tail \meta{ntl}). In the process, the macro
1152 % constructs the |\asclst@@envchanger| macro by prepending a closing
1153 % environment for \meta{ohd} and appending an opening environment for
1154 % \meta{nhd}. After the construction, the change of environment is
1155 % performed by expanding |\asclst@@envchanger|.
1156 % \begin{macrocode}
1157 \def\asclst@changedoclistlevel@ii#1#2\@undefined#3#4\@undefined{%
1158 % \end{macrocode}
1159 % If both environment lists have been processed, then \meta{ohd} and
1160 % \meta{nhd} are empty and nothing needs to be done further.
1161 % \begin{macrocode}
1162 \ifstrempty{#1#3}{}{%
1163 % \end{macrocode}
1164 % Otherwise, first process \meta{ohd} by prepending a closing
1165 % environment.
1166 % \begin{macrocode}
1167 \ifstrempty{#1}{}{%
1168 \epreto\asclst@@envchanger{%
1169 \noexpand\asclst@end
1170 \csuse{asclst@levelchr@#1}<>\noexpand\@undefined}}%
1171 % \end{macrocode}
1172 % Second, process \meta{nhd} by appending an opening environment.
1173 % \begin{macrocode}
1174 \ifstrempty{#3}{}{%
1175 \eappto\asclst@@envchanger{%
1176 \noexpand\asclst@begin
1177 \csuse{asclst@levelchr@#3}<>\noexpand\@undefined}}%
1178 % \end{macrocode}
1179 % Third, recurse with the remainders of the lists.
1180 % \begin{macrocode}
1181 \asclst@changedoclistlevel@ii#2{}\@undefined#4{}\@undefined}}
1182 % \end{macrocode}
1183 % \end{macro}
1184 %
1185 %
1186 %
1187 % \subsection{Shared Code between \texttt{AsciiList} and \texttt{AsciiDocList}}
1188 %
1189 % \begin{macro}{\asclst@begin}
1190 % \begin{macro}{\asclst@end}
1191 % The macro
1192 % |\asclst@begin|\marg{env}|<|\meta{opt}|>|\meta{ignored}|\@undefined|
1193 % corresponds to \LaTeX's |\begin|\oarg{opt}
1194 % and
1195 % |\asclst@end|\marg{env}|<|\meta{ignored}|>|\meta{ignored}|\@undefined|
1196 % corresponds to \LaTeX's |\end|.
1197 % If \meta{env} was
1198 % not registered by |\AsciiListRegisterEnv|, then the macros are even
1199 % identical to |\begin| and |\end|. Otherwise, the macros expand to
1200 % the \meta{begin} and \meta{end} code registered for \meta{env}. In
1201 % addition, |\asclst@begin| sets up the |\asclst@@item| macro that is used
1202 % to create a list item.
1203 % \changes{v1.7}{2015/06/03}{Optional parameters for list environments}
1204 % \begin{macrocode}
1205 \long\def\asclst@begin#1<#2>#3\@undefined{%
1206 \ifinlist{#1}{\asclst@registeredenvs}%
1207 {\bgroup
1208 \ifstrempty{#2}%
1209 {\@nameuse{asclst@env@#1@begin}}%
1210 {\@nameuse{asclst@env@#1@begin}[#2]}%
1211 \edef\asclst@@item{\csexpandonce{asclst@env@#1@item}}}%
1212 {%
1213 \ifstrempty{#2}%
1214 {\begin{#1}}%
1215 {\begin{#1}[#2]}%
1216 \def\asclst@@item{\item}}}
1217 \long\def\asclst@end#1<#2>#3\@undefined{%
1218 \ifinlist{#1}{\asclst@registeredenvs}%
1219 {\@nameuse{asclst@env@#1@end}\egroup}%
1220 {\end{#1}}}
1221 % \end{macrocode}
1222 % \end{macro}
1223 % \end{macro}
1224 %
1225 % For our code, line breaks are important to be tracked, because an
1226 % item-indicating char at the beginning of a line (i.e., after a line
1227 % break) is crucial.
1228 % \begin{macrocode}
1229 {\catcode`\^^M=\active%
1230 % \end{macrocode}
1231 %
1232 % \begin{macro}{\asclst@nlsetup}
1233 % The |\asclst@nlsetup|\marg{nl-macro} macro sets up the newline
1234 % character such that it runs the \meta{nl-macro} upon every newline.
1235 % \begin{macrocode}
1236 \gdef\asclst@nlsetup#1{%
1237 % \end{macrocode}
1238 % Save the current newline, make it active, and set the newline
1239 % to expand to our \meta{nl-macro} macro, which does the main job of
1240 % this whole package at every newline.
1241 % \begin{macrocode}
1242 \let\asclst@orignewline=^^M%
1243 \catcode`\^^M\active%
1244 \let^^M=#1}%
1245 % \end{macrocode}
1246 % \end{macro}
1247 %
1248 % \begin{macro}{\asclst@restorenewline}
1249 % The |\asclst@restorenewline| restores the meaning of the newline
1250 % character that is changed by |\asclst@nlsetup|.
1251 % \begin{macrocode}
1252 \gdef\asclst@restorenewline{\let^^M=\asclst@orignewline}%
1253 % \end{macrocode}
1254 % \end{macro}
1255 % The following ends the group with active line break catcode.
1256 % \begin{macrocode}
1257 }
1258 % \end{macrocode}
1259 %
1260 %
1261 % \subsection{Configuration}
1262 %
1263 % \begin{macro}{\AsciiListSetAutochars}
1264 % \begin{macro}{\ifasclst@autochars}
1265 % \begin{macro}{\asclst@autocharlist}
1266 % The |\asclst@autochars| conditional is used to store whether the
1267 % \meta{item-chars} are to be auto-detected. In this case, the
1268 % \meta{item-chars} are attempted to be derived from the candidates in
1269 % |\asclst@autocharlist|. The |\AsciiListSetAutochars|\marg{chars}
1270 % allows one to specify a user-defined list of characters for the
1271 % auto-detection.
1272 % \begin{macrocode}
1273 \newif\ifasclst@autochars
1274 \newcommand*\AsciiListSetAutochars[1]{%
1275 \def\asclst@autocharlist{}%
1276 \forcsvlist{\listadd\asclst@autocharlist}{#1}}
1277 \AsciiListSetAutochars{-,*,+}
1278 % \end{macrocode}
1279 % \end{macro}
1280 % \end{macro}
1281 % \end{macro}
1282 %
1283 % \begin{macro}{\AsciiListSetEnvironments}
1284 % \begin{macro}{\asclst@defaultenvs}
1285 % The |\AsciiListSetEnvironments|\marg{environments} macro sets the
1286 % default list environment. This default is used when the optional
1287 % \meta{environments} argument is not given to |AsciiList|.
1288 % \changes{v1.3}{2014/09/18}{Allow setting default list environment}
1289 % \begin{macrocode}
1290 \newcommand*\AsciiListSetEnvironments[1]{%
1291 \def\asclst@defaultenvs{#1}}
1292 \AsciiListSetEnvironments{itemize}
1293 % \end{macrocode}
1294 % \end{macro}
1295 % \end{macro}
1296 % \begin{macro}{\AsciiDocListSetEnvironments}
1297 % \begin{macro}{\asclst@docdefaultenvs}
1298 % The |AsciiDocListSetEnvironments|\marg{environments} macro sets the
1299 % default \meta{environments} argument for the |AsciiDocList|
1300 % environment.
1301 % \begin{macrocode}
1302 \newcommand*\AsciiDocListSetEnvironments[1]{%
1303 \def\asclst@docdefaultenvs{#1}}
1304 \AsciiDocListSetEnvironments{*=itemize,+=enumerate,;=Description}
1305 % \end{macrocode}
1306 % \end{macro}
1307 % \end{macro}
1308 %
1309 % \begin{macro}{\NewAsciiListEnv}
1310 % The
1311 % |\NewAsciiListEnv|\oarg{environments}\marg{item-chars}\marg{envname}
1312 % macro creates a new environment named \meta{envname}. The use of
1313 % this environment then is equivalent to using
1314 % |AsciiList[|\meta{environments}|]{|\meta{item-chars}|}|.
1315 % Moreover, the macro creates a new macro
1316 % \cs{\meta{envname}FromFile}\marg{file-name}, which is equivalent to
1317 % |\AsciiListFromFile[|\meta{environments}|]{|\meta{item-chars}|}{|\meta{file-name}|}|.
1318 % Analogously, the macro \cs{\meta{envname}FromFiles} is defined.
1319 % \changes{v1.3}{2014/09/18}{Allow creating list environments that use
1320 % given parameters}
1321 % \changes{v1.8b}{2015/08/24}{Registered list environments can now be
1322 % loaded from files}
1323 % \begin{macrocode}
1324 \newcommand*\NewAsciiListEnv[3][]{%
1325 \newenvironment{#3}%
1326 {\begin{AsciiList}[#1]{#2}}%
1327 {\end{AsciiList}}%
1328 \csdef{#3FromFile}##1{\AsciiListFromFile[#1]{#2}{##1}}%
1329 \csdef{#3FromFiles}##1{\AsciiListFromFiles[#1]{#2}{##1}}%
1330 }
1331 % \end{macrocode}
1332 % \end{macro}
1333 %
1334 % \begin{macro}{\NewAsciiDocListEnv}
1335 % The
1336 % |\NewAsciiDocListEnv|\oarg{environments}\marg{envname}
1337 % macro creates a new environment named \meta{envname}. The use of
1338 % this environment then is equivalent to using
1339 % |AsciiDocList[|\meta{environments}|]|.
1340 % Moreover, the macro creates a new macro
1341 % \cs{\meta{envname}FromFile}\marg{file-name}, which is defined
1342 % to be equivalent to
1343 % |\AsciiDocListFromFile[|\meta{environments}|]{|\meta{file-name}|}|.
1344 % Analogously, the macro \cs{\meta{envname}FromFiles} is defined.
1345 % \begin{macrocode}
1346 \newcommand*\NewAsciiDocListEnv[2][\asclst@docdefaultenvs]{%
1347 \newenvironment{#2}%
1348 {\begin{AsciiDocList}[#1]}%
1349 {\end{AsciiDocList}}%
1350 \csdef{#2FromFile}##1{\AsciiDocListFromFile[#1]{##1}}%
1351 \csdef{#2FromFiles}##1{\AsciiDocListFromFiles[#1]{##1}}%
1352 }
1353 % \end{macrocode}
1354 % \end{macro}
1355 %
1356 % \begin{macro}{\AsciiListRegisterEnv}
1357 % \begin{macro}{\asclst@registeredenv}
1358 % The
1359 % |\AsciiListRegisterEnv|\marg{envname}\marg{begin}\marg{end}\marg{item}
1360 % macro registers a new environment name for use with |AsciiList| and
1361 % |AsciiDocList|.
1362 % After such a registration, one may use the \meta{envname} as an
1363 % element in the \meta{environments} parameter to |AsciiList| or
1364 % |AsciiDocList|. The \meta{begin}, \meta{end}, and \meta{item} code is
1365 % used whenever such a newly defined environment is begun or ended, or a
1366 % list entry is started, respectively. Note that by using the
1367 % |\AsciiListRegisterEnv|, no real \LaTeX{} environment is created. All
1368 % registered environments are collected in the |\asclst@registeredenvs|
1369 % list.
1370 % \changes{v1.4}{2014/09/19}{Allow registering additional
1371 % environments}
1372 % \begin{macrocode}
1373 \def\asclst@registeredenvs{}
1374 \newcommand*\AsciiListRegisterEnv[4]{%
1375 \listadd\asclst@registeredenvs{#1}%
1376 \csdef{asclst@env@#1@begin}{#2}%
1377 \csdef{asclst@env@#1@end}{#3}%
1378 \csdef{asclst@env@#1@item}{#4}}
1379 % \end{macrocode}
1380 % \end{macro}
1381 % \end{macro}
1382 %
1383 % \begin{macro}{\AsciiListRegisterDescEnv}
1384 % The |\AsciiListRegisterDescEnv|\marg{envname} is a macro that can be
1385 % used as a shorthand for |\AsciiListRegisterEnv| to declare existing
1386 % description environments. The environment \meta{envname} must exist
1387 % and must be a description environment, i.e., one whose entries are
1388 % specified via |\item|\oarg{text}.
1389 % \begin{macrocode}
1390 \newcommand*\AsciiListRegisterDescEnv[1]{%
1391 \AsciiListRegisterEnv{#1}{\csuse{#1}}{\csuse{end#1}}%
1392 {\AsciiListEndOArg{\item}}}
1393 % \end{macrocode}
1394 % \end{macro}
1395 %
1396 % \begin{macro}{\AsciiListEndArg}
1397 % The |\AsciiListEndArg|\marg{command} macro is equal to the given
1398 % \meta{command}, except that the first argument passed to
1399 % \meta{command} is the remainder of the line in which the macro is
1400 % used.
1401 % \begin{macrocode}
1402 {\catcode`\^^M=\active%
1403 \gdef\AsciiListEndArg#1#2^^M{%
1404 % \end{macrocode}
1405 % Note the line break at the end of the following line. This line
1406 % break is important, because the definition of |\AsciiListEndArg|
1407 % swallows one line break. By having the line break below, we
1408 % essentially re-insert the line break, such that |AsciiList| or
1409 % |AsciiDocList| can use it again to check for list items in the
1410 % subsequent line.
1411 % \changes{v1.5b}{2014/09/24}{Ignore initial spaces in argument}
1412 % \changes{v1.6}{2014/10/12}{Robustified ignoring initial spaces}
1413 % \changes{v1.6b}{2014/10/14}{Robustified ignoring initial spaces}
1414 % \changes{v1.6c}{2014/10/16}{Robustified ignoring initial spaces}
1415 % \changes{v2.1b}{2016/03/31}{Robustified ignoring initial spaces}
1416 % \begin{macrocode}
1417 \begingroup%
1418 \def\asclst@@result{#2}\trim@pre@space@in{\asclst@@result}%
1419 \edef\asclst@@result{%
1420 \endgroup\unexpanded{#1}{\expandonce{\asclst@@result}}}%
1421 \asclst@@result
1422 }%
1423 % \end{macrocode}
1424 % \end{macro}
1425 % \begin{macro}{\AsciiListEndOArg}
1426 % The |\AsciiListEndOArg|\marg{command} macro constitutes the
1427 % counterpart to the |\AsciiListEndArg| macro for the case of a
1428 % \meta{command} that takes an \emph{optional} argument (like the
1429 % |\item| of a |description| environment).
1430 % \changes{v1.5b}{2014/09/24}{Ignore initial spaces in argument}
1431 % \changes{v1.6}{2014/10/12}{Robustified ignoring initial spaces}
1432 % \changes{v1.6b}{2014/10/14}{Robustified ignoring initial spaces}
1433 % \changes{v1.6c}{2014/10/16}{Robustified ignoring initial spaces}
1434 % \changes{v2.1b}{2016/03/31}{Robustified against nested square brackets}
1435 % \begin{macrocode}
1436 \gdef\AsciiListEndOArg#1#2^^M{%
1437 \begingroup%
1438 \def\asclst@@result{#2}\trim@pre@space@in{\asclst@@result}%
1439 \edef\asclst@@result{%
1440 \endgroup\unexpanded{#1}[{\expandonce{\asclst@@result}}]}%
1441 \asclst@@result
1442 }%
1443 }
1444 % \end{macrocode}
1445 % \end{macro}
1446 %
1447 % \subsection{Pre-Defined List Environments}
1448 %
1449 % In the following, we define some environment names that allow one to
1450 % use sectioning commands for list items. When using these
1451 % environments, one should be aware that list entries in these
1452 % environments must fit into a single line (i.e., everything after a
1453 % line break is not put into the argument of the sectioning command).
1454 % \begin{macrocode}
1455 \AsciiListRegisterEnv{chapter}{}{}{\AsciiListEndArg{\chapter}}
1456 \AsciiListRegisterEnv{section}{}{}{\AsciiListEndArg{\section}}
1457 \AsciiListRegisterEnv{subsection}{}{}{\AsciiListEndArg{\subsection}}
1458 \AsciiListRegisterEnv{subsubsection}{}{}%
1459 {\AsciiListEndArg{\subsubsection}}
1460 \AsciiListRegisterEnv{section*}{}{}{\AsciiListEndArg{\section*}}
1461 \AsciiListRegisterEnv{subsection*}{}{}{\AsciiListEndArg{\subsection*}}
1462 \AsciiListRegisterEnv{subsubsection*}{}{}%
1463 {\AsciiListEndArg{\subsubsection*}}
1464 \AsciiListRegisterEnv{paragraph}{}{}{\AsciiListEndArg{\paragraph}}
1465 % \end{macrocode}
1466 % For nesting sections with sub-sections etc., the |Heading| and
1467 % |Heading*| environments can be used.
1468 % \changes{v2.2}{2016/04/14}{Added ``Heading'' environment}
1469 % \begin{macrocode}
1470 \AsciiListRegisterEnv{Heading}{\asclst@Heading}{\endasclst@Heading}%
1471 {\AsciiListEndArg{\csuse{\asclst@@sec}}}
1472 \AsciiListRegisterEnv{Heading*}{\asclst@Heading}{\endasclst@Heading}%
1473 {\AsciiListEndArg{\csuse{\asclst@@sec}*}}
1474 % \end{macrocode}
1475 % \begin{environment}{asclst@Heading}
1476 % The |asclst@Heading|\oarg{initial} environment is an auxiliary
1477 % environment for the |Heading| list environment usable in |AsciiList|
1478 % and |AsciiDocList|. Inside the environment, one can use
1479 % |\csuse{\asclst@@sec}|\marg{title} to produce a heading at a
1480 % particular level. The initial level is provided by the optional
1481 % \meta{initial} argument. When the |asclst@Heading| environment is
1482 % nested, the heading level decreases (for instance, going from
1483 % ``section'' to ``subsection'').
1484 % \begin{macrocode}
1485 \newenvironment{asclst@Heading}[1][section]%
1486 {\bgroup\ifdefmacro{\asclst@@sec}%
1487 % \end{macrocode}
1488 % If |\asclst@@sec| is already defined, use the |\asclst@Sec@...| macros
1489 % to determine the next sub-level (next line). Otherwise, initialize the
1490 % |\asclst@@sec| macro using the \meta{initial} argument.
1491 % \begin{macrocode}
1492 {\edef\asclst@@sec{\csuse{asclst@Sec@\asclst@@sec}}}%
1493 {\def\asclst@@sec{#1}}}%
1494 {\egroup}
1495 \newcommand\asclst@Sec@part{chapter}
1496 \newcommand\asclst@Sec@chapter{section}
1497 \newcommand\asclst@Sec@section{subsection}
1498 \newcommand\asclst@Sec@subsection{subsubsection}
1499 \newcommand\asclst@Sec@subsubsection{paragraph}
1500 \newcommand\asclst@Sec@paragraph{subparagraph}
1501 % \end{macrocode}
1502 % \end{environment}
1503 % To simplify the use of the |description| environment as well as
1504 % other common description environments (the packages defining these
1505 % environments need not be loaded until the environments are actually
1506 % used).
1507 % \begin{macrocode}
1508 \AsciiListRegisterDescEnv{description}
1509 \AsciiListRegisterDescEnv{compactdesc}
1510 % \end{macrocode}
1511 % It often looks less appealing to have the first item of an |itemize|
1512 % or |enumerate| environment in the same line as the parent item in a
1513 % description environment. As an alternative to this default behavior
1514 % of \LaTeX{}, we offer the following |Description| and |CompactDesc|
1515 % environments, with which the child items start in a new line (but
1516 % if the environment starts with text, then this will still be placed
1517 % in the same line as the description item).
1518 % \changes{v1.5b}{2014/09/24}{Added alternative description
1519 % environments}
1520 % \begin{macrocode}
1521 \AsciiListRegisterEnv{Description}{\description}{\enddescription}%
1522 {\AsciiListEndOArg{\asclst@BreakingDescItem}}
1523 \AsciiListRegisterEnv{CompactDesc}{\compactdesc}{\endcompactdesc}%
1524 {\AsciiListEndOArg{\asclst@BreakingDescItem}}
1525 % \end{macrocode}
1526 % \begin{macro}{\asclst@BreakingDescItem}
1527 % The |\asclst@BreakingDescItem|\oarg{item} macro is the same as
1528 % |\item[|\meta{item}|]| except that it is additionally ensured that
1529 % the first item of a contained list environment is not displayed on
1530 % the same line.
1531 % \changes{v2.1b}{2016/03/31}{Robustified against nested square brackets}
1532 % \begin{macrocode}
1533 \newcommand\asclst@BreakingDescItem[1][]{\item[{#1}]\leavevmode}
1534 % \end{macrocode}
1535 % \end{macro}
1536 %\iffalse
1537 %</package>
1538 %\fi
1539 % \Finale
1540 \endinput