| 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 |