summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/asciilist
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/asciilist
Initial commit
Diffstat (limited to 'macros/latex/contrib/asciilist')
-rw-r--r--macros/latex/contrib/asciilist/README.md78
-rw-r--r--macros/latex/contrib/asciilist/asciilist.dtx1540
-rw-r--r--macros/latex/contrib/asciilist/asciilist.ins40
-rw-r--r--macros/latex/contrib/asciilist/asciilist.pdfbin0 -> 386568 bytes
4 files changed, 1658 insertions, 0 deletions
diff --git a/macros/latex/contrib/asciilist/README.md b/macros/latex/contrib/asciilist/README.md
new file mode 100644
index 0000000000..37d6f2479a
--- /dev/null
+++ b/macros/latex/contrib/asciilist/README.md
@@ -0,0 +1,78 @@
+The asciilist Package
+=====================
+
+Copyright (C) 2014-2018 Richard Grewe
+
+Released under the [LaTeX Project Public License](http://www.latex-project.org/lppl/) version 1.2 or later
+
+## Purpose
+
+This package provides the environments `AsciiList` and `AsciiDocList`,
+which enable quickly typesetting nested lists in LaTeX without having to
+type individual item macros or opening/closing list environments.
+The package provides auxiliary functionality for loading such lists from
+files and provides macros for configuring the use of the list
+environments and the appearance of the typeset results.
+
+## Availability
+
+The `asciilist` package is on [CTAN](http://www.ctan.org/pkg/asciilist),
+where you can also find the [documentation](http://mirrors.ctan.org/macros/latex/contrib/asciilist/asciilist.pdf),
+as well as on [github](https://github.com/Ri-Ga/asciilist).
+Since November 2015, `asciilist` is part of TeX Live (package `texlive-latex-extra`) and
+is included in [MiKTeX](http://miktex.org/packages/asciilist).
+
+## Manual Installation
+
+The `asciilist` package comes with (at least) the following files
+* asciilist.ins
+* asciilist.dtx
+* README.md
+
+and possibly also with
+* Makefile
+* asciilist.pdf (generated from asciilist.dtx)
+* asciilist.sty (generated from asciilist.dtx)
+
+To install the `asciilist` package, you additionally need
+* docstrip.tex
+
+To build the package (`asciilist.sty`), run one of the following
+```
+ latex asciilist.ins
+ make package (needs Makefile)
+```
+
+Put the resulting `asciilist.sty` somewhere where LaTeX can find it.
+Read the documentation of your LaTeX system to find out where this
+might be.
+
+## Building Documentation
+
+To build the documentation of the `asciilist` package, you additionally
+need
+* ltxdoc.cls
+* idxlayout.sty
+* xcolor.sty
+* showexpl.sty
+* paralist.sty
+* trimspaces.sty
+* etoolbox.sty
+* hypdoc.sty
+* makeindex
+* pdflatex
+
+To build the documentation (`asciilist.pdf`), either run
+```
+ make docs
+```
+or the following sequence of commands
+```
+ pdflatex asciilist.dtx
+ makeindex -s gind.ist -o asciilist.ind asciilist.idx
+ makeindex -s gglo.ist -o asciilist.gls asciilist.glo
+ pdflatex asciilist.dtx
+ pdflatex asciilist.dtx
+```
+
+Happy TeX'ing
diff --git a/macros/latex/contrib/asciilist/asciilist.dtx b/macros/latex/contrib/asciilist/asciilist.dtx
new file mode 100644
index 0000000000..59302b8670
--- /dev/null
+++ b/macros/latex/contrib/asciilist/asciilist.dtx
@@ -0,0 +1,1540 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2014-2018 by Richard Grewe <r-g+tex@posteo.net>
+% -------------------------------------------------------
+%
+% This file may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.2
+% of this license or (at your option) any later version.
+% The latest version of this license is in:
+%
+% http://www.latex-project.org/lppl.txt
+%
+% and version 1.2 or later is part of all distributions of LaTeX
+% version 1999/12/01 or later.
+%
+% \fi
+%
+% \iffalse
+%<*driver>
+\ProvidesFile{asciilist.dtx}
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+%<package>\ProvidesPackage{asciilist}
+%<*package>
+ [2018/11/01 v2.2b Package for quickly creating nested lists]
+%</package>
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage[columns=2]{idxlayout}
+\usepackage{xcolor}
+\usepackage{showexpl}
+\lstset{gobble=2,frame=trbl,backgroundcolor=\color{black!5!white}}
+\lstset{explpreset={numbers=none,columns=flexible,basicstyle=\footnotesize\ttfamily}}
+\lstset{preset={\small\sffamily},overhang=2cm,pos=r}
+\usepackage{asciilist}
+\usepackage{paralist}
+\usepackage{hypdoc}
+\makeatletter
+\newcommand\SaveSecs{%
+ \@for\SC:=section,subsection,subsubsection\do{%
+ \csedef{SC@\SC}{\the\value{\SC}}%
+ \setcounter{\SC}{0}}}
+\newcommand\RestoreSecs{%
+ \@for\SC:=section,subsection,subsubsection\do{%
+ \setcounter{\SC}{\csuse{SC@\SC}}}}
+\makeatother
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+ \DocInput{asciilist.dtx}
+ \PrintChanges
+ \PrintIndex
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{0}
+%
+% \CharacterTable
+% {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
+% 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
+% Digits \0\1\2\3\4\5\6\7\8\9
+% Exclamation \! Double quote \" Hash (number) \#
+% Dollar \$ Percent \% Ampersand \&
+% Acute accent \' Left paren \( Right paren \)
+% Asterisk \* Plus \+ Comma \,
+% Minus \- Point \. Solidus \/
+% Colon \: Semicolon \; Less than \<
+% Equals \= Greater than \> Question mark \?
+% Commercial at \@ Left bracket \[ Backslash \\
+% Right bracket \] Circumflex \^ Underscore \_
+% Grave accent \` Left brace \{ Vertical bar \|
+% Right brace \} Tilde \~}
+%
+%
+% \changes{v1.0}{2014/09/17}{Initial version}
+% \changes{v1.7b}{2015/08/04}{Fixed superfluous whitespaces}
+% \changes{v2.2b}{2018/11/01}{Package author's name change}
+%
+% \GetFileInfo{asciilist.dtx}
+%
+% \DoNotIndex{\newcommand,\newenvironment,\def,\gdef,\edef}
+%
+%
+% \title{The \textsf{asciilist} package\thanks{This document
+% corresponds to \textsf{asciilist}~\fileversion, dated \filedate.
+% The package is available online at
+% \url{http://www.ctan.org/pkg/asciilist} and
+% \url{https://github.com/Ri-Ga/asciilist}.}}
+% \author{Richard Grewe \\ \texttt{r-g+tex@posteo.net}}
+%
+% \maketitle
+%
+% \begin{abstract}
+% This package provides two environments for \emph{quickly typesetting
+% nested lists} in \LaTeX{} without having to type the individual
+% |\item| macros or opening/closing nested list environments.
+% \end{abstract}
+%
+% \section{Usage}
+%
+% We document the functionality of the package by examples in this
+% section. The package provides two main environments: |AsciiList| and
+% |AsciiDocList|.
+%
+% The |AsciiList| environment (Section~\ref{sec:AsciiList}) provides a
+% list environment in which a single character at the beginning of a
+% line can be used to typeset an item at a particular list level. The
+% mapping between these characters and list levels is fixed for the
+% whole list.
+%
+% The |AsciiDocList| environment (Section~\ref{sec:AsciiDocList})
+% provides a list environment in which a sequence of characters at the
+% beginning of a line can be used to typeset an item at a particular
+% list level. The mapping between individual characters and list
+% environments is fixed for the whole list. This environment, thus, uses
+% a syntax that is close to the asciidoc syntax.
+%
+% \subsection{Lists with Fixed Nesting Layout}\label{sec:AsciiList}
+%
+% \DescribeEnv{AsciiList}
+% Use the |AsciiList|\oarg{environments}\marg{item-chars} environment
+% to quickly create \LaTeX{} lists, possibly nested ones, without too
+% much \LaTeX{} interference. The following example might illustrate
+% the environment best:
+%
+% \begin{LTXexample}
+% \begin{AsciiList}{-,*,+,=}
+% - first item
+% * first sub-item
+% * second sub-item,
+% which is multi-line
+% + a sub-sub item
+% = a sub-sub-sub item
+% - back up by three levels
+% * end at a sub-item
+% \end{AsciiList}
+% \end{LTXexample}
+% Note that in this example, the indentation with spaces is for
+% demonstration purposes only. The package itself does not require a
+% proper/uniform indentation of the items at the different levels.
+% Item levels are solely recognized by the first character of a line.
+%
+% \DescribeMacro{\AsciiListFromFile}
+% Instead of having the list content inline in the \LaTeX{} file, one
+% can also choose to put the list into a separate file. A list of
+% such file can then be produced via the
+% |\AsciiListFromFile|\oarg{environments}\marg{item-chars}\marg{file-name}
+% macro. The first two parameters of the macro are the same as the
+% parameters of the |AsciiList| environment. The \meta{file-name}
+% parameter specifies the name of the file to include.
+% \iffalse
+%<*ALexample>
+ * item
+ - sub-item
+ * another item
+%</ALexample>
+% \fi
+% \begin{LTXexample}
+% \AsciiListFromFile{auto}{AsciiList.example}
+% \end{LTXexample}
+% In the above example, the used input file has the following content:
+% \lstinputlisting{AsciiList.example}
+% Using |\input|, you can include the content of a file into an
+% |AsciiList| environment. The formatting of the environment is then
+% applied also to the content of the included file.
+% \begin{LTXexample}
+% \begin{AsciiList}{+,*,-}
+% + main item
+% \input{AsciiList.example}
+% \end{AsciiList}
+% \end{LTXexample}
+%
+% \DescribeMacro{\AsciiListFromFiles}
+% The |\AsciiListFromFiles| macro is the same as |\AsciiListFromFile|,
+% except that a comma-separated list is accepted for the
+% \meta{file-name} parameter and that the files are input in the listed
+% order.
+%
+% \subsubsection{Choosing List Environments}
+%
+% If you do not want to use the |itemize| environment for the lists,
+% you can change it to |enumerate|, |compactitem| or other list-like
+% environments (which should use |\item| for their items) you prefer
+% by setting the optional \meta{environments} parameter. For example,
+% you can set the \meta{environments} to |itemize,compactitem| in
+% order to have the top level list as an |itemize| and the second as
+% well as all deeper levels as |compactitem| lists.
+%
+% The |AsciiList| environment allows you to use more than just list
+% environments like |itemize|, |enumerate|, or |description|. You can
+% even use sectioning command names (|chapter|, |section|, |section*|,
+% |subsection|, |paragraph| etc.), which have been enabled already
+% with the |\NewAsciiListEnv| macro. If you use such ``environments'',
+% every list entry will be produced using the respective |\chapter|,
+% |\section|, |\section*|, |\subsection|, |\paragraph|, etc.{} macro.
+% Note, however, that only the first line of such an item will then be
+% used for the name of the section/subsection/etc.
+% \SaveSecs
+% \begin{LTXexample}
+% \begin{AsciiList}[section,subsection]{-,*}
+% - first section
+% * a subsection
+% - second section
+% \end{AsciiList}
+% \end{LTXexample}
+%
+% If you do not want to manually specify the nesting levels, you can
+% also use the list environment |Heading|\oarg{initial}, as the
+% following example demonstrates.\medskip
+% \begin{LTXexample}
+% \begin{AsciiList}[Heading<subsection>]{-,*,+}
+% - a sub-section
+% * a sub-sub-section
+% + a paragraph
+% and some text
+% \end{AsciiList}
+% \end{LTXexample}
+% \RestoreSecs
+% The |Heading| list environment produces numbered sections.
+% Correspondingly, |Heading*| produces unnumbered sections.
+%
+% List environments with optional parameters are also supported,
+% including their parameters. For instance, the |compactenum|
+% environment of the \textsf{paralist} package has an optional parameter
+% configuring the appearance of the individual items. The following
+% example shows how to specify the optional parameters:\medskip
+% \begin{LTXexample}
+% \begin{AsciiList}[compactenum<1.>,
+% compactenum<(a)>]{auto}
+% - item number 1.
+% * item (a)
+% * item (b)
+% - item number 2.
+% \end{AsciiList}
+% \end{LTXexample}
+% Care has to be taken when the optional argument contains a comma. In
+% this case, the optional argument must be enclosed in parentheses such
+% that \LaTeX{} does not confuse the comma with a comma that separates
+% the list environments.
+%
+% \subsubsection{Automatic Item Detection}
+%
+% If you want to be more flexible regarding the characters for the
+% list items, you can use |auto| as the parameter to the environment.
+% The |AsciiList| then makes an attempt to automatically identify the
+% list items from a predefined list (preset to ``-'', ``*'', ``+'').
+% \DescribeMacro{\AsciiListSetAutochars}
+% You can change this list using the
+% |\AsciiListSetAutochars|\marg{chars} macro, which expects
+% \meta{chars} to be a comma-separated list of chars. The ordering of
+% this list does not matter. What matters is the ordering in which the
+% characters appear in the environment.
+% \begin{LTXexample}
+% \AsciiListSetAutochars{+,*,-,=}
+% \begin{AsciiList}[enumerate,itemize,
+% compactitem]{auto}
+% - first item
+% * first sub-item
+% * second sub-item,
+% which is multi-line
+% + a sub-sub item
+% - back up by three levels
+% * end at a sub-item
+% \end{AsciiList}
+% \end{LTXexample}
+%
+% \subsubsection{Navigating Upwards}
+% \changes{v2.1}{2016/03/05}{Documentation of \cs{UP} and \cs{UPTO}}
+%
+% If you want to typeset a list in which a list item is continued after
+% sub-items of that item, you can use the |\UP| and |\UPTO| macros.
+% \DescribeMacro{\UP}
+% The |\UP|\oarg{N} macro goes back \meta{N} levels (default: 1) without
+% starting a new item at the resulting level.
+% \DescribeMacro{\UPTO}
+% The |\UPTO|\marg{N} macro goes back to level \meta{N} (where the
+% topmost level is 0) without starting a new item at the resulting
+% level.
+% The following example illustrates the use of the two macros.
+% \begin{LTXexample}
+% \begin{AsciiList}{auto}
+% - first item
+% * sub-item
+% \UP[1]
+% continuation one level higher
+% * another sub-item
+% + a sub-sub-item
+% \UPTO{1}
+% continuation on first-item level
+% \end{AsciiList}
+% \end{LTXexample}
+%
+%
+% \subsection{Lists with AsciiDoc-Like Notation}\label{sec:AsciiDocList}
+%
+% \DescribeEnv{AsciiDocList}
+% Use the |AsciiDocList|\oarg{environments} environment to quickly create
+% \LaTeX{} lists, possibly nested ones, without too much \LaTeX{}
+% interference. The following example might illustrate the environment
+% best:
+% \begin{LTXexample}
+% \begin{AsciiDocList}
+% * first item (itemized)
+% *+ first sub-item (enumerated)
+% *+ second sub-item (enumerated),
+% which is multi-line
+% *+* a sub-sub item
+% * back up by three levels
+% ** end at a sub-item (itemized)
+% \end{AsciiDocList}
+% \end{LTXexample}
+% Note that in this example, the indentation with spaces is for
+% demonstration purposes only. The package itself does not require a
+% proper/uniform indentation of the items at the different levels.
+%
+% By default, the |*| character maps to an |itemize| item, the |+|
+% character maps to an |enumerate| item, and the |;| character maps to a
+% description item (where the item label follows in the line after the
+% |;| and the item text follows in the subsequent line).
+%
+% \DescribeMacro{\AsciiDocListFromFile}
+% Instead of having the list content inline in the \LaTeX{} file, one
+% can also choose to put the list into a separate file. A list of
+% such file can then be produced via the
+% |\AsciiDocListFromFile|\oarg{environments}\marg{file-name}
+% macro. The optional parameter of the macro is the same as the
+% parameter of the |AsciiDocList| environment. The \meta{file-name}
+% parameter specifies the name of the file to include.
+% \iffalse
+%<*ADLexample>
+ * item
+ *+ sub-item
+ * another item
+%</ADLexample>
+% \fi
+% \begin{LTXexample}
+% \AsciiDocListFromFile{AsciiDocList.example}
+% \end{LTXexample}
+% In the above example, the used input file has the following content:
+% \lstinputlisting{AsciiDocList.example}
+% Using |\input|, you can include the content of a file into an
+% |AsciiDocList| environment. The formatting of the environment is then
+% applied also to the content of the included file.
+% \begin{LTXexample}
+% \begin{AsciiDocList}
+% * first item
+% \input{AsciiDocList.example}
+% \end{AsciiDocList}
+% \end{LTXexample}
+%
+% \DescribeMacro{\AsciiDocListFromFiles}
+% The |\AsciiDocListFromFiles| macro is the same as
+% |\AsciiDocListFromFile|, except that a comma-separated list is
+% accepted for the \meta{file-name} parameter and that the files are
+% input in the listed order.
+%
+% \subsubsection{Choosing List Environments}
+%
+% If you do not want to use the pre-defined mapping of |*| to |itemize|
+% etc., you can change the mapping to other list-like environments
+% (which should use |\item| for their items) you prefer by setting the
+% optional \meta{environments} parameter. For example, you can set the
+% \meta{environments} to |*=itemize,-=compactitem,!=enumerate|.
+%
+% The |AsciiDocList| environment allows you to use more than just list
+% environments like |itemize|, |enumerate|, or |description|. The range
+% of supported environments is for |AsciiDocList| is the same as for
+% |AsciiList|.
+% \SaveSecs
+% \begin{LTXexample}
+% \begin{AsciiDocList}[/=section,
+% *=subsection]
+% / first section
+% /* first subsection
+% /* second subsection
+% / second section
+% \end{AsciiDocList}
+% \end{LTXexample}
+% \RestoreSecs
+%
+% \subsubsection{Navigating Upwards}
+% \changes{v2.1}{2016/03/05}{Documentation of \cs{UPTO}}
+%
+% If you want to typeset a list in which a list item is continued after
+% sub-items of that item, you can use the |\UPTO| macro.
+% \DescribeMacro{\UPTO}
+% The |\UPTO|\marg{chars} macro goes back the level identified by
+% \meta{chars} without starting a new item at the resulting level.
+% The following example illustrates the use of the macro.
+% \begin{LTXexample}
+% \begin{AsciiDocList}
+% ; description
+% beginning of description
+% ;+ item
+% ;+* sub-item
+% \UPTO{;}
+% continuation of description
+% \end{AsciiDocList}
+% \end{LTXexample}
+%
+%
+% \section{Customizing List Environments}\label{sec:config}
+%
+% \DescribeMacro{\AsciiListRegisterEnv}
+% You can register additional environment names for use with
+% |AsciiList| or |AsciiDocList| by using the
+% |\AsciiListRegisterEnv|\marg{envname}\marg{begin}\marg{end}\marg{item}
+% macro, by which the \meta{begin}, \meta{end}, and \meta{item} code
+% can be specified.
+% \DescribeMacro{\AsciiListEndArg}
+% If you want to use a command for the \meta{item}
+% code that takes a single parameter (e.g., |\section|), then you can
+% use |\AsciiListEndArg|\marg{command} for the \meta{item} to pass the
+% whole line of the item to \meta{command}.
+% \DescribeMacro{\AsciiListEndOArg}
+% If the \meta{item} takes a single \emph{optional} parameter (like
+% |\item|), then use |\AsciiListEndOArg|\marg{command} instead of
+% |\AsciiListEndArg|.
+% For example to register an environment |TTEnum| for enumerating
+% items in typewriter font, you can use the following command:
+% \begin{LTXexample}
+% \AsciiListRegisterEnv{TTEnum}
+% {\enumerate}{\endenumerate}
+% {\AsciiListEndArg{\item\texttt}}
+% \begin{AsciiList}[TTEnum]{-}
+% - items are typewriter
+% (though only in the first line)
+% - and enumerated
+% \end{AsciiList}
+% \end{LTXexample}
+%
+% \subsection{Customizing \texttt{AsciiList}}
+%
+% \DescribeMacro{\AsciiListSetEnvironments}
+% You can also change the default list environments for |AsciiList| from
+% |itemize| to a comma-separated list of \meta{environments}. This
+% allows you to omit the optional parameter to the |AsciiList|
+% environment for such default configurations. For this, use the
+% |\AsciiListSetEnvironments|\marg{environments} macro.
+% \begin{LTXexample}
+% \AsciiListSetEnvironments{enumerate,
+% compactitem<!>}
+% \begin{AsciiList}{-,*}
+% - first
+% * sub
+% - second
+% \end{AsciiList}
+% \end{LTXexample}
+%
+% \DescribeMacro{\NewAsciiListEnv}
+% If particular kinds of nested lists occur several times in your
+% document, you can also define abbreviation environments, as
+% demonstrated in the following (which also shows how to use
+% |description| environments in an |AsciiList|):
+% \begin{LTXexample}
+% \NewAsciiListEnv[description,compactitem]
+% {auto}{TopicIdeas}
+% \begin{TopicIdeas}
+% + food:
+% - cheese
+% - nuts
+% + beverages:
+% - water
+% - milk
+% \end{TopicIdeas}
+% \end{LTXexample}
+%
+% \subsection{Customizing \texttt{AsciiDocList}}
+%
+% \DescribeMacro{\AsciiDocListSetEnvironments}
+% You can also change the default list environments for |AsciiDocList|
+% from |*=itemize,+=enumerate| to another comma-separated list of
+% \meta{environments}. This allows you to omit the optional parameter to
+% the |AsciiDocList| environment for such default configurations. For this,
+% use the |\AsciiDocListSetEnvironments|\marg{environments} macro.
+% \begin{LTXexample}
+% \AsciiDocListSetEnvironments{?=enumerate,
+% !=compactitem<!>}
+% \begin{AsciiDocList}
+% ? item?
+% ?! sub!
+% ? second
+% \end{AsciiDocList}
+% \end{LTXexample}
+%
+% \DescribeMacro{\NewAsciiDocListEnv}
+% The analogous macro to |\NewAsciiListEnv| for the |AsciiDocList|
+% environment is |\NewAsciiDocListEnv|. Its use is as the following
+% example illustrates:
+% \begin{LTXexample}
+% \NewAsciiDocListEnv[!=Description,
+% *=compactitem]{TopicDoc}
+% \begin{TopicDoc}
+% ! food:
+% !* cheese
+% !* nuts
+% ! beverages:
+% !* water
+% !* milk
+% \end{TopicDoc}
+% \end{LTXexample}
+%
+% \section{Noteworthy Features}
+%
+% \begin{itemize}
+% \item This package can be used together with Sync\TeX{}. That is,
+% for a point in the |AsciiList| of a generated PDF, one can obtain
+% the position in the |AsciiList|'s source code.
+% \item Some initial tests show that |AsciiList| can be used in a
+% |p|-column of a |tabular| environment.
+% \end{itemize}
+%
+% \section{Known Limitations}
+%
+% \begin{itemize}
+% \item Currently, the |AsciiList| and |AsciiDocList| environments
+% cannot be used in a ``moving argument'', such as in a |\footnote|.
+% If you really want such lists in footnotes, you might consider
+% using |\AsciiListFromFile| and friends.
+% \item Not all chars can directly be used as item chars. This probably
+% is some character code issue that so far has not been investigated
+% further.
+% \end{itemize}
+%
+% \section{Related Packages}
+%
+% The following \LaTeX{} packages provide similar functionalities to
+% the \textsf{asciilist} package.
+%
+% \begin{description}
+% \item[\textsf{easylist}:]
+% This package is probably closest to \textsf{asciilist}. The package
+% ``is designed for typesetting lists of numbered items [...] with a
+% single active character acting as the only command'' (cited from
+% the package documentation). The package provides a lot of
+% possibilities for configuring the appearance of items at the
+% individual levels.
+% Compared to \textsf{asciilist}, the package differs in two main
+% points. Firstly, the package uses a single character for the items.
+% This character can be used in the middle of a line to begin a new
+% item and, hence, must not occur in the text itself. The character
+% must be repeated for indicating the depth of the item, rather than
+% having separate characters for different levels. Secondly, the
+% package is focused on list environments and does not support using
+% sectioning macros for items at selected levels.
+% Finally, the package does not provide convenience functionality
+% similar to that described in Section~\ref{sec:config} of this
+% documentation.
+% \item[\textsf{iitem}:]
+% This package provides macros |\iitem|..|\ivtem|, which can be used
+% within |enumerate| and |itemize| environments for changing list
+% levels without explicitly starting nested |enumerate| and |itemize|
+% environments. The list type (|enumerate|, |itemize|, \ldots) is
+% the same for all nested list levels.
+% Compared to \textsf{asciilist}, the package has the main drawback
+% that the list type is the same for all levels. Moreover, the package
+% uses \LaTeX-ish enumeration macros rather than nice symbols. The
+% package does not provide convenience functionality similar to that
+% described in Section~\ref{sec:config} of this documentation.
+% Finally, the package has the limitation that items below the first
+% level must be placed within a single line.
+% \item[\textsf{outlines}:]
+% This package provides an |outline| environment, in which multiple
+% list levels can be accessed. The individual levels can be reached
+% via |\1|..|\4| macros, which substitute the |\item| of the
+% respective level. The list environments that |outline| uses
+% for the individual levels are configurable.
+% Compared to \textsf{asciilist}, the package has the slight drawback
+% that it uses \LaTeX-ish enumeration macros rather than nice symbols.
+% Moreover, the package does not offer convenience functionality
+% similar to that described in Section~\ref{sec:config} of this
+% documentation.
+% \end{description}
+%
+% \clearpage
+%
+% \StopEventually{}
+%\iffalse
+%<*package>
+%\fi
+%
+% \section{Implementation}
+%
+% The \textsf{etoolbox} package is used for processing comma-separated
+% lists easily.
+% \begin{macrocode}
+\RequirePackage{etoolbox}
+% \end{macrocode}
+% The \textsf{trimspaces} package is used for trimming leading spaces
+% in a robust manner.
+% \begin{macrocode}
+\RequirePackage{trimspaces}
+% \end{macrocode}
+%
+% \subsection{The \texttt{AsciiList} Environment}
+%
+% \begin{environment}{AsciiList}
+% The |AsciiList|\oarg{environments}\marg{item-chars} creates an
+% environment in which nested lists can be typeset without much
+% \LaTeX{} interference. The \meta{item-chars} must specify of
+% comma-separated list of characters. The special value |auto| makes
+% the environment try to auto-detect the \meta{item-chars}.
+% The \meta{environments} specifies an optional, comma-separated list
+% of environments to be used to create the lists at the individual
+% levels.
+% \changes{v1.2}{2014/09/18}{Allow auto-detection of item-chars}
+% \changes{v2.1b}{2016/03/31}{Eliminated expansion of optional argument}
+% \begin{macrocode}
+\newenvironment{AsciiList}[2][]{%
+ \bgroup
+% \end{macrocode}
+% Setup the environment by storing the list \meta{environments} to use
+% and -- most importantly -- setting up the newline character such
+% that it scans for the \meta{item-chars} to find new list items.
+% \begin{macrocode}
+ \ifstrempty{#1}%
+ {\let\asclst@listenv=\asclst@defaultenvs}%
+ {\def\asclst@listenv{#1}}%
+% \end{macrocode}
+% Convert the given \meta{item-chars} to an internal list of
+% \textsf{etoolbox}, because this makes working with the list easier.
+% \begin{macrocode}
+ \gdef\asclst@itemchars{}%
+ \ifstrequal{#2}{auto}%
+ {\asclst@autocharstrue}%
+ {\asclst@autocharsfalse\forcsvlist{\listadd\asclst@itemchars}{#2}}%
+ \asclst@nlsetup\asclst@newline
+% \end{macrocode}
+% We re-define |\input|\marg{filename} such that it becomes possible
+% to include |AsciiList|-formatted input files.
+% \begin{macrocode}
+ \def\input##1{%
+% \end{macrocode}
+% We input the file using the |\@@input| primitive, because this
+% primitive can be expanded via |\expandafter| such that the
+% |\asclst@newline| can parse the first line of the file already.
+% \begin{macrocode}
+ \everyeof{\noexpand}%
+ \expandafter\asclst@newline\@@input##1\relax}%
+% \end{macrocode}
+% Initialize to nesting level $0$. And make the macro |\UP| available
+% for switching to an upper level.
+% \changes{v1.5}{2014/09/21}{Avoid missing item error in empty
+% environment}
+% \changes{v1.5}{2014/09/21}{Add command to explicitly changle levels
+% upwards}
+% \begin{macrocode}
+ \global\asclst@curlevel=0\relax%
+ \let\UP=\asclst@levelsup%
+ \let\UPTO=\asclst@levelsupto%
+% \end{macrocode}
+% Ensure that the scanning for an item char starts with the very first
+% line of the environment.
+% \changes{v2.0a}{2016/02/23}{Improved first-line handling.}
+% \begin{macrocode}
+ \asclst@ifnextnewline{}{\asclst@newline}%
+}{%
+% \end{macrocode}
+% Ensure that all remaining open list environments are closed before
+% the end of the |AsciiList| environment.
+% \begin{macrocode}
+ \asclst@changelistlevel{\asclst@curlevel}{0}%
+ \asclst@restorenewline%
+ \egroup}
+% \end{macrocode}
+% \end{environment}
+%
+% \begin{macro}{\AsciiListFromFile}
+% The |\AsciiListFromFile|\oarg{environments}\marg{item-chars}\marg{file-name}
+% macro produces a result like the |AsciiList| environment does,
+% but takes the content of the list from \meta{file-name}.
+% \changes{v1.8}{2015/08/19}{Added this macro}
+% \begin{macrocode}
+\newcommand\AsciiListFromFile[3][]{%
+ \AsciiList[#1]{#2}%
+ \input{#3}%
+ \endAsciiList}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\AsciiListFromFiles}
+% The |\AsciiListFromFiles|\oarg{environments}\marg{item-chars}\marg{file-list}
+% macro produces a result like the |AsciiList| environment does,
+% but takes the content of the list from the comma-separated
+% \meta{file-list}.
+% \changes{v1.8b}{2015/08/24}{Added this macro}
+% \begin{macrocode}
+\newcommand\AsciiListFromFiles[3][]{%
+ \AsciiList[#1]{#2}%
+% \end{macrocode}
+% We do the same here as for the |\AsciiListFromFile| macro,
+% just in a loop over the \meta{file-list}. Note that |\dolistloop|
+% is to be avoided here, because there is quite some chance that
+% the |\do| macro gets redefined in the included code.
+% \begin{macrocode}
+ \forcsvlist{\input}{#3}%
+ \endAsciiList}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsubsection{Handling of Line Breaks}
+%
+% For our code, line breaks are important to be tracked, because an
+% item-indicating char at the beginning of a line (i.e., after a line
+% break) is crucial.
+% \begin{macrocode}
+{\catcode`\^^M=\active%
+% \end{macrocode}
+%
+% \begin{macro}{\asclst@checknext}
+% The |\asclst@checknext|\marg{first-char}\marg{item-char} checks
+% whether \meta{first-char} (used with the first char of a line after
+% a line break) is equal to a given \meta{item-char} (a character that
+% indicates the beginning of a new list item) and, if so, sets the
+% counter |\asclst@newlevel| to the value of |\@tempcntb|. This is used
+% in |\asclst@newline| to store the index of a found \meta{item-char} in
+% the list of \meta{item-chars} of the |AsciiList| environment.
+% \begin{macrocode}
+ \gdef\asclst@checknext#1#2{%
+ \ifstrequal{#1}{#2}{\asclst@newlevel=\@tempcntb}{}}%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\asclst@newline}
+% The |\asclst@newline|\marg{first-char} macro is executed whenever a
+% newline character occurs in the |AsciiList| environment. The
+% \meta{first-char} then is the first character (or, rather, token)
+% after the newline.
+% Important in this macro: all lines must end with a percent char, to
+% not introduce new newline chars in the macro itself (this would
+% yield an endless recursion).
+% \begin{macrocode}
+ \gdef\asclst@newline#1{%
+% \end{macrocode}
+% First, we find out whether the next char is in list
+% \meta{item-chars} (i.e., in |\asclst@itemchars|) and return the
+% position in the list in
+% |\asclst@newlevel| (or $0$ if not found).
+% \begin{macrocode}
+ \asclst@newlevel=0\@tempcntb=0\relax%
+ \forlistloop{\advance\@tempcntb by 1\asclst@checknext{#1}}%
+ {\asclst@itemchars}%
+% \end{macrocode}
+% If the next char is not in the \meta{item-chars}, but the
+% |AsciiList| was given the |auto| parameter for \meta{item-chars},
+% then we check whether we can automatically determine the character
+% for a new nesting level. The char for this new nesting level is then
+% (globally) added to the list of known \meta{item-chars} in
+% |\asclst@itemchars|. Note that in the following code, the value
+% of |\@tempcntb| still is the length of the |\asclst@itemchars| list.
+% \begin{macrocode}
+ \ifnum\asclst@newlevel=0\ifasclst@autochars%
+ \ifinlist{#1}{\asclst@autocharlist}{%
+ \listgadd\asclst@itemchars{#1}%
+ \asclst@newlevel=\@tempcntb%
+ \advance\asclst@newlevel by 1\relax%
+ }{}%
+ \fi\fi%
+% \end{macrocode}
+% If we found a character from \meta{item-chars}, then we ensure to
+% change to the nesting level of this character (which is in
+% |\asclst@newlevel|) and then trigger a new |\item|.
+% \changes{v1.5b}{2014/09/24}{Fix item spacing for in-paragraph lists}
+% \changes{v1.8b}{2015/08/24}{Robustified by not using \cs{do}}
+% \begin{macrocode}
+ \ifnum\asclst@newlevel>0\relax%
+ \def\asclst@@do{%
+ \asclst@changelistlevel{\asclst@curlevel}{\asclst@newlevel}%
+ \ifhmode\unskip\space\fi\asclst@@item}%
+ \else%
+% \end{macrocode}
+% If no character from \meta{item-chars} is found, we check whether
+% the newline causing |\asclst@newline| to be invoked is followed by
+% another newline character. In this case, we insert a |\par|.
+% \changes{v1.5b}{2014/09/24}{Empty lines captured}
+% \begin{macrocode}
+ \def\asclst@@tmpone{#1}\def\asclst@@test{^^M}%
+ \ifx\asclst@@test\asclst@@tmpone%
+ \def\asclst@@do{\par #1}%
+% \end{macrocode}
+% Otherwise, we just use a |\space| for the newline character and
+% flush out the token |#1| that we captured after the newline
+% character.
+% \begin{macrocode}
+ \else\def\asclst@@do{\space #1}\fi%
+ \fi\asclst@@do}%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\asclst@ifnextnewline}
+% The |\asclst@ifnextnewline|\marg{iftrue}\marg{iffalse} macro checks
+% whether the next character is a newline. If the check succeeds, then
+% the macro expands to \meta{iftrue}. Otherwise, the macro expands to
+% \meta{iffalse}.
+% \begin{macrocode}
+ \gdef\asclst@ifnextnewline{\@ifnextchar^^M}
+% \end{macrocode}
+% \end{macro}
+%
+% The following ends the group with active line break catcode.
+% \begin{macrocode}
+}
+% \end{macrocode}
+%
+% \subsubsection{Level-Changing Macros}
+%
+% \begin{macro}{\asclst@curlevel}
+% We use the |\asclst@curlevel| counter to capture the current nesting
+% depth of list environments within an |AsciiList|. We also use a
+% counter for changing the level to a new one.
+% \begin{macrocode}
+\newcount\asclst@curlevel
+\newcount\asclst@newlevel
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\asclst@changelistlevel}
+% The |\asclst@changelistlevel|\marg{from}\marg{to} changes the list
+% nesting level from level \meta{from} (a number) to level \meta{to}
+% (a number), by issuing the right number of |\begin| or |\end|
+% environments.
+% \changes{v1.1}{2014/09/18}{Allow list of list environments}
+% \begin{macrocode}
+\newcommand\asclst@changelistlevel[2]{%
+ \def\asclst@@envchanger{}%
+ \ifnum#2<#1\relax
+% \end{macrocode}
+% If $\meta{to}<\meta{from}$, then we must change to a lower list nesting
+% level. We do this by inserting $\meta{from}-\meta{to}$
+% |\end|-environments, which we store in |\asclst@@envchanger|.
+% \begin{macrocode}
+ \def\asclst@@last{}%
+% \end{macrocode}
+% First, we collect all affected environment names from the given
+% \meta{environments} parameter to |AsciiList| (which at this point is
+% in |\asclst@listenv|): We take all those from list index $\meta{to}+1$
+% until list index $\meta{from}$, in reverse order (hence |\preto|),
+% which are actually in the list.
+% \begin{macrocode}
+ \@tempcnta=0\relax
+ \@tempcntb=#2 \advance\@tempcntb by 1\relax
+ \def\do##1{\advance\@tempcnta by1\relax
+ \ifnum\@tempcnta<\@tempcntb\else
+ \ifnum\@tempcnta>#1\else
+ \preto\asclst@@envchanger{\asclst@end ##1<>\@undefined}\fi\fi
+ \def\asclst@@last{##1}}%
+ \expandafter\docsvlist\expandafter{\asclst@listenv}%
+% \end{macrocode}
+% Second, for all indices from $\meta{to}+1$ until $\meta{from}$ that
+% are \emph{not} in the \meta{environments} list, we just take the
+% last list entry (stored in |\asclst@@last| by the above code) and
+% repeat it sufficiently often, i.e., from
+% $\max(\mathrm{len}\meta{environments},\meta{from})+1$ until
+% $\meta{to}$ times.
+% \begin{macrocode}
+ \advance\@tempcnta by1\ifnum\@tempcnta<\@tempcntb
+ \@tempcnta=\@tempcntb\fi
+ \loop \ifnum\@tempcnta>#1\else
+ \advance\@tempcnta by 1%
+ \epreto\asclst@@envchanger{\noexpand
+ \asclst@end\expandonce\asclst@@last<>\noexpand\@undefined}%
+ \repeat%
+ \else\ifnum#2>#1\relax%
+% \end{macrocode}
+% The following does the same as the above, except that:
+% |\begin| instead of |\end| of environments are collected;
+% they are collected in the ordering as in \meta{environments} (hence
+% |\appto|); and
+% entries are collected from $\meta{from}+1$ to $\meta{to}$.
+% \begin{macrocode}
+ \def\asclst@@last{}%
+ \@tempcnta=0\relax
+ \@tempcntb=#1\relax\advance\@tempcntb by 1\relax
+ \def\do##1{\advance\@tempcnta by1\relax
+ \ifnum\@tempcnta<\@tempcntb\else
+ \ifnum\@tempcnta>#2\else
+ \appto\asclst@@envchanger{\asclst@begin ##1<>\@undefined}\fi\fi
+ \def\asclst@@last{##1}}%
+ \expandafter\docsvlist\expandafter{\asclst@listenv}%
+ \advance\@tempcnta by1\ifnum\@tempcnta<\@tempcntb
+ \@tempcnta=\@tempcntb\fi
+ \loop \ifnum\@tempcnta>#2\else
+ \advance\@tempcnta by 1%
+ \eappto\asclst@@envchanger{%
+ \noexpand\asclst@begin
+ \expandonce\asclst@@last<>\noexpand\@undefined}%
+ \repeat%
+ \fi\fi%
+% \end{macrocode}
+% Update the current level to the new value, \meta{to}. Then write out
+% the begin/end environments collected in |\asclst@@envchanger|.
+% \begin{macrocode}
+ \global\asclst@curlevel=#2%
+ \asclst@@envchanger}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\asclst@levelsup}
+% The |\asclst@levelsup|\oarg{number} macro allows switching to a
+% nesting level that is \meta{number} levels upwards (default:
+% $\meta{number}=1$). In the |AsciiList| environment, this macro is
+% accessible via the |\UP| command.
+% \begin{macrocode}
+\newcommand*\asclst@levelsup[1][1]{%
+ \asclst@newlevel=\asclst@curlevel
+ \advance\asclst@newlevel by-#1\relax
+ \asclst@changelistlevel{\asclst@curlevel}{\asclst@newlevel}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\asclst@levelsupto}
+% The |\asclst@levelsupto|\marg{number} macro allows switching to
+% list nesting level \meta{number}. In the |AsciiList| environment,
+% this macro is accessible via the |\UPTO| command.
+% \begin{macrocode}
+\newcommand*\asclst@levelsupto[1]{%
+ \ifnum\asclst@curlevel<#1\relax
+ \PackageError{asciilist}{Cannot change level downwards!}{}%
+ \else
+ \asclst@changelistlevel{\asclst@curlevel}{#1}%
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \subsection{The \texttt{AsciiDocList} Environment}
+%
+% \begin{environment}{AsciiDocList}
+% The |AsciiDocList|\oarg{environments} creates an environment in which
+% nested lists can be typeset without much \LaTeX{} interference. The
+% \meta{environments} must be a comma-separated list of
+% ``\meta{char}=\meta{environment}'' entries.
+% \changes{v2.0}{2015/11/13}{Added \texttt{AsciiDocList} environment}
+% \begin{macrocode}
+\newenvironment{AsciiDocList}[1][]{%
+ \bgroup
+% \end{macrocode}
+% Modify the newline character to scan for characters that trigger
+% items.
+% \changes{v2.2}{2016/04/15}{Enabled \cs{input} in the macros and environments}
+% \begin{macrocode}
+ \def\asclst@curnestlvl{}%
+ \asclst@nlsetup\asclst@docnewline%
+% \end{macrocode}
+% We re-define |\input|\marg{filename} such that it becomes possible
+% to include |AsciiDocList|-formatted input files.
+% \begin{macrocode}
+ \def\input##1{%
+% \end{macrocode}
+% We input the file using the |\@@input| primitive, because this
+% primitive can be expanded via |\expandafter| such that the
+% |\asclst@docnewline| can parse the first line of the file already.
+% \begin{macrocode}
+ \expandafter\asclst@docnewline\@@input##1\relax}%
+% \end{macrocode}
+% Now setup the characters that trigger items.
+% \begin{macrocode}
+ \def\asclst@levelchrs{}%
+ \def\do##1{\asclst@parsechmapentry##1\@undefined}%
+ \ifstrempty{#1}%
+ {\expandafter\docsvlist\expandafter{\asclst@docdefaultenvs}}%
+ {\docsvlist{#1}}%
+% \end{macrocode}
+% And make the macro |\UPTO| available for switching to an upper level.
+% \changes{v2.1}{2016/03/04}{Add \cs{UPTO} to explicitly changle levels
+% upwards}
+% \begin{macrocode}
+ \let\UPTO=\asclst@changedoclistlevel%
+% \end{macrocode}
+% Ensure that the scanning for an item char starts with the very first
+% line of the environment.
+% \changes{v2.0a}{2016/02/23}{Improved first-line handling.}
+% \begin{macrocode}
+ \asclst@ifnextnewline{}{\asclst@docnewline}%
+}{%
+% \end{macrocode}
+% Ensure that all remaining open list environments are closed before the
+% end of the |AsciiDocList| environment.
+% \begin{macrocode}
+ \asclst@changedoclistlevel{}%
+ \asclst@restorenewline%
+ \egroup}
+% \end{macrocode}
+% \end{environment}
+%
+% \begin{macro}{\AsciiDocListFromFile}
+% The |\AsciiDocListFromFile|\oarg{environments}\marg{file-name}
+% macro produces a result like the |AsciiDocList| environment does,
+% but takes the content of the list from \meta{file-name}.
+% \begin{macrocode}
+\newcommand\AsciiDocListFromFile[2][]{%
+ \AsciiDocList[#1]%
+ \input{#2}%
+ \endAsciiDocList}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\AsciiDocListFromFiles}
+% The |\AsciiDocListFromFiles|\oarg{environments}\marg{file-list}
+% macro produces a result like the |AsciiDocList| environment does,
+% but takes the content of the list from the comma-separated
+% \meta{file-list}.
+% \begin{macrocode}
+\newcommand\AsciiDocListFromFiles[2][]{%
+ \AsciiDocList[#1]%
+% \end{macrocode}
+% We do the same here as for the |\AsciiDocListFromFile| macro,
+% just in a loop over the \meta{file-list}. Note that |\dolistloop|
+% is to be avoided here, because there is quite some chance that
+% the |\do| macro gets redefined in the included code.
+% \begin{macrocode}
+ \forcsvlist{\input}{#2}%
+ \endAsciiDocList}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsubsection{Handling of Line Breaks}
+%
+% For our code, line breaks are important to be tracked, because an
+% item-indicating char at the beginning of a line (i.e., after a line
+% break) is crucial.
+% \begin{macrocode}
+{\catcode`\^^M=\active%
+% \end{macrocode}
+%
+% \begin{macro}{\asclst@docnewline}
+% The |\asclst@docnewline|\marg{first-char} macro is executed whenever a
+% newline character occurs in the |AsciiDocList| environment. The
+% \meta{first-char} then is the first character (or, rather, token)
+% after the newline.
+% \changes{v2.2}{2016/04/15}{Robustified file inputs against \cs{everyeof} changes}
+% \begin{macrocode}
+ \gdef\asclst@docnewline{%
+% \end{macrocode}
+% The following is a bit of a hack to ensure that there is some
+% parameter to |\asclst@docnewline| even if the input file ends with
+% a newline directly afterwards.
+% \begin{macrocode}
+ \everyeof{\noexpand}%
+ \asclst@docnewline@i{}}%
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\asclst@docnewline@i}
+% The |\asclst@docnewline@i|\marg{char-seq}\marg{test-char} macro
+% recursively collects characters (tokens) until a token is found that
+% is not in |\asclst@levelchrs|.
+% \begin{macrocode}
+ \gdef\asclst@docnewline@i#1#2{%
+ \ifinlist{#2}{\asclst@levelchrs}%
+ {\asclst@docnewline@i{#1#2}}%
+ {\asclst@docnewline@ii{#1}{#2}}}%
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\asclst@docnewline@ii}
+% The |\asclst@docnewline@ii|\marg{char-seq}\marg{next} macro creates a
+% new list item (in the right environment), if \meta{char-seq} is
+% non-empty. The \meta{next} character must not be in the
+% |\asclst@levelchrs| and is inserted after the new item.
+% \begin{macrocode}
+ \gdef\asclst@docnewline@ii#1#2{%
+ \ifstrempty{#1}{%
+% \end{macrocode}
+% If \meta{char-seq} is empty, this means there was no item char at the
+% beginning of the line. Hence, no item shall be put here, but the
+% \meta{next} char must be inserted again. If \meta{next} is another
+% newline character, then we insert a |\par| instead.
+% \begin{macrocode}
+ \def\asclst@@tmpone{#2}\def\asclst@@test{^^M}%
+ \ifx\asclst@@test\asclst@@tmpone%
+ \def\asclst@@do{\par #2}%
+ \else%
+ \def\asclst@@do{\space #2}\fi%
+ \asclst@@do%
+ }{%
+% \end{macrocode}
+% If \meta{char-seq} is non-empty, then change the nesting level
+% to \meta{char-seq} and then trigger a new |\item|.
+% \begin{macrocode}
+ \asclst@changedoclistlevel{#1}%
+ \ifhmode\unskip\space\fi\asclst@@item #2%
+ }}%
+% \end{macrocode}
+% \end{macro}
+% The following ends the group with active line break catcode.
+% \begin{macrocode}
+}
+% \end{macrocode}
+%
+% \begin{macro}{\asclst@parsechmapentry}
+% The |\asclst@parsechmap|\meta{char}|=|\meta{env}|\@undefined| macro
+% adds a \meta{char} to the list of level characters and defines a
+% mapper macro from the \meta{char} to the \meta{env}.
+% \begin{macrocode}
+\def\asclst@parsechmapentry#1=#2\@undefined{%
+ \listadd\asclst@levelchrs{#1}%
+ \csdef{asclst@levelchr@#1}{#2}}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsubsection{Level-Changing Macros}
+%
+% \begin{macro}{\asclst@changedoclistlevel}
+% The |\asclst@changedoclistlevel|\marg{to} changes the list nesting level
+% from level |\asclst@curnestlvl| (a character sequence) to level
+% \meta{to} (a character sequence), by issuing the right number of
+% |\begin| or |\end| environments.
+% \begin{macrocode}
+\newcommand\asclst@changedoclistlevel[1]{%
+ \def\asclst@@envchanger{}%
+ \expandafter\asclst@changedoclistlevel@i\asclst@curnestlvl{}{}\@undefined
+ #1{}{}\@undefined
+ \asclst@@envchanger
+ \gdef\asclst@curnestlvl{#1}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\asclst@changedoclistlevel@i}
+% The
+% |\asclst@changedoclistlevel@i|\meta{ohd}\meta{otl}|\@undefined|\meta{nhd}\meta{ntl}|\@undefined|
+% macro recursively strips off the common prefixes from the old
+% environment list (with head \meta{ohd} and tail \meta{otl}) and the
+% new environment list (with head \meta{nhd} and tail \meta{ntl}).
+% Afterwards, the macro uses |\asclst@changedoclistlevel@ii| to construct
+% the |\asclst@@envchanger|.
+% \begin{macrocode}
+\def\asclst@changedoclistlevel@i#1#2\@undefined#3#4\@undefined{%
+% \end{macrocode}
+% If both environment lists have been processed, then \meta{ohd} and
+% \meta{nhd} are empty and nothing needs to be done.
+% \begin{macrocode}
+ \ifstrempty{#1#3}{}{%
+% \end{macrocode}
+% Otherwise, if the heads are equal, go to the recursive case for
+% further stripping off the common prefix. If the
+% heads differ, proceed with |\asclst@changedoclistlevel@ii|.
+% \begin{macrocode}
+ \ifstrequal{#1}{#3}%
+ {\asclst@changedoclistlevel@i#2{}\@undefined#4{}\@undefined}%
+ {\asclst@changedoclistlevel@ii#1#2{}\@undefined#3#4{}\@undefined}%
+ }}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\asclst@changedoclistlevel@ii}
+% The
+% |\asclst@changedoclistlevel@ii|\meta{ohd}\meta{otl}|\@undefined|\meta{nhd}\meta{ntl}|\@undefined|
+% macro recursively decomposes the old environment list (with head
+% \meta{ohd} and tail \meta{otl}) and the new environment list (with
+% head \meta{nhd} and tail \meta{ntl}). In the process, the macro
+% constructs the |\asclst@@envchanger| macro by prepending a closing
+% environment for \meta{ohd} and appending an opening environment for
+% \meta{nhd}. After the construction, the change of environment is
+% performed by expanding |\asclst@@envchanger|.
+% \begin{macrocode}
+\def\asclst@changedoclistlevel@ii#1#2\@undefined#3#4\@undefined{%
+% \end{macrocode}
+% If both environment lists have been processed, then \meta{ohd} and
+% \meta{nhd} are empty and nothing needs to be done further.
+% \begin{macrocode}
+ \ifstrempty{#1#3}{}{%
+% \end{macrocode}
+% Otherwise, first process \meta{ohd} by prepending a closing
+% environment.
+% \begin{macrocode}
+ \ifstrempty{#1}{}{%
+ \epreto\asclst@@envchanger{%
+ \noexpand\asclst@end
+ \csuse{asclst@levelchr@#1}<>\noexpand\@undefined}}%
+% \end{macrocode}
+% Second, process \meta{nhd} by appending an opening environment.
+% \begin{macrocode}
+ \ifstrempty{#3}{}{%
+ \eappto\asclst@@envchanger{%
+ \noexpand\asclst@begin
+ \csuse{asclst@levelchr@#3}<>\noexpand\@undefined}}%
+% \end{macrocode}
+% Third, recurse with the remainders of the lists.
+% \begin{macrocode}
+ \asclst@changedoclistlevel@ii#2{}\@undefined#4{}\@undefined}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \subsection{Shared Code between \texttt{AsciiList} and \texttt{AsciiDocList}}
+%
+% \begin{macro}{\asclst@begin}
+% \begin{macro}{\asclst@end}
+% The macro
+% |\asclst@begin|\marg{env}|<|\meta{opt}|>|\meta{ignored}|\@undefined|
+% corresponds to \LaTeX's |\begin|\oarg{opt}
+% and
+% |\asclst@end|\marg{env}|<|\meta{ignored}|>|\meta{ignored}|\@undefined|
+% corresponds to \LaTeX's |\end|.
+% If \meta{env} was
+% not registered by |\AsciiListRegisterEnv|, then the macros are even
+% identical to |\begin| and |\end|. Otherwise, the macros expand to
+% the \meta{begin} and \meta{end} code registered for \meta{env}. In
+% addition, |\asclst@begin| sets up the |\asclst@@item| macro that is used
+% to create a list item.
+% \changes{v1.7}{2015/06/03}{Optional parameters for list environments}
+% \begin{macrocode}
+\long\def\asclst@begin#1<#2>#3\@undefined{%
+ \ifinlist{#1}{\asclst@registeredenvs}%
+ {\bgroup
+ \ifstrempty{#2}%
+ {\@nameuse{asclst@env@#1@begin}}%
+ {\@nameuse{asclst@env@#1@begin}[#2]}%
+ \edef\asclst@@item{\csexpandonce{asclst@env@#1@item}}}%
+ {%
+ \ifstrempty{#2}%
+ {\begin{#1}}%
+ {\begin{#1}[#2]}%
+ \def\asclst@@item{\item}}}
+\long\def\asclst@end#1<#2>#3\@undefined{%
+ \ifinlist{#1}{\asclst@registeredenvs}%
+ {\@nameuse{asclst@env@#1@end}\egroup}%
+ {\end{#1}}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% For our code, line breaks are important to be tracked, because an
+% item-indicating char at the beginning of a line (i.e., after a line
+% break) is crucial.
+% \begin{macrocode}
+{\catcode`\^^M=\active%
+% \end{macrocode}
+%
+% \begin{macro}{\asclst@nlsetup}
+% The |\asclst@nlsetup|\marg{nl-macro} macro sets up the newline
+% character such that it runs the \meta{nl-macro} upon every newline.
+% \begin{macrocode}
+ \gdef\asclst@nlsetup#1{%
+% \end{macrocode}
+% Save the current newline, make it active, and set the newline
+% to expand to our \meta{nl-macro} macro, which does the main job of
+% this whole package at every newline.
+% \begin{macrocode}
+ \let\asclst@orignewline=^^M%
+ \catcode`\^^M\active%
+ \let^^M=#1}%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\asclst@restorenewline}
+% The |\asclst@restorenewline| restores the meaning of the newline
+% character that is changed by |\asclst@nlsetup|.
+% \begin{macrocode}
+ \gdef\asclst@restorenewline{\let^^M=\asclst@orignewline}%
+% \end{macrocode}
+% \end{macro}
+% The following ends the group with active line break catcode.
+% \begin{macrocode}
+}
+% \end{macrocode}
+%
+%
+% \subsection{Configuration}
+%
+% \begin{macro}{\AsciiListSetAutochars}
+% \begin{macro}{\ifasclst@autochars}
+% \begin{macro}{\asclst@autocharlist}
+% The |\asclst@autochars| conditional is used to store whether the
+% \meta{item-chars} are to be auto-detected. In this case, the
+% \meta{item-chars} are attempted to be derived from the candidates in
+% |\asclst@autocharlist|. The |\AsciiListSetAutochars|\marg{chars}
+% allows one to specify a user-defined list of characters for the
+% auto-detection.
+% \begin{macrocode}
+\newif\ifasclst@autochars
+\newcommand*\AsciiListSetAutochars[1]{%
+ \def\asclst@autocharlist{}%
+ \forcsvlist{\listadd\asclst@autocharlist}{#1}}
+\AsciiListSetAutochars{-,*,+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\AsciiListSetEnvironments}
+% \begin{macro}{\asclst@defaultenvs}
+% The |\AsciiListSetEnvironments|\marg{environments} macro sets the
+% default list environment. This default is used when the optional
+% \meta{environments} argument is not given to |AsciiList|.
+% \changes{v1.3}{2014/09/18}{Allow setting default list environment}
+% \begin{macrocode}
+\newcommand*\AsciiListSetEnvironments[1]{%
+ \def\asclst@defaultenvs{#1}}
+\AsciiListSetEnvironments{itemize}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\AsciiDocListSetEnvironments}
+% \begin{macro}{\asclst@docdefaultenvs}
+% The |AsciiDocListSetEnvironments|\marg{environments} macro sets the
+% default \meta{environments} argument for the |AsciiDocList|
+% environment.
+% \begin{macrocode}
+\newcommand*\AsciiDocListSetEnvironments[1]{%
+ \def\asclst@docdefaultenvs{#1}}
+\AsciiDocListSetEnvironments{*=itemize,+=enumerate,;=Description}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\NewAsciiListEnv}
+% The
+% |\NewAsciiListEnv|\oarg{environments}\marg{item-chars}\marg{envname}
+% macro creates a new environment named \meta{envname}. The use of
+% this environment then is equivalent to using
+% |AsciiList[|\meta{environments}|]{|\meta{item-chars}|}|.
+% Moreover, the macro creates a new macro
+% \cs{\meta{envname}FromFile}\marg{file-name}, which is equivalent to
+% |\AsciiListFromFile[|\meta{environments}|]{|\meta{item-chars}|}{|\meta{file-name}|}|.
+% Analogously, the macro \cs{\meta{envname}FromFiles} is defined.
+% \changes{v1.3}{2014/09/18}{Allow creating list environments that use
+% given parameters}
+% \changes{v1.8b}{2015/08/24}{Registered list environments can now be
+% loaded from files}
+% \begin{macrocode}
+\newcommand*\NewAsciiListEnv[3][]{%
+ \newenvironment{#3}%
+ {\begin{AsciiList}[#1]{#2}}%
+ {\end{AsciiList}}%
+ \csdef{#3FromFile}##1{\AsciiListFromFile[#1]{#2}{##1}}%
+ \csdef{#3FromFiles}##1{\AsciiListFromFiles[#1]{#2}{##1}}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\NewAsciiDocListEnv}
+% The
+% |\NewAsciiDocListEnv|\oarg{environments}\marg{envname}
+% macro creates a new environment named \meta{envname}. The use of
+% this environment then is equivalent to using
+% |AsciiDocList[|\meta{environments}|]|.
+% Moreover, the macro creates a new macro
+% \cs{\meta{envname}FromFile}\marg{file-name}, which is defined
+% to be equivalent to
+% |\AsciiDocListFromFile[|\meta{environments}|]{|\meta{file-name}|}|.
+% Analogously, the macro \cs{\meta{envname}FromFiles} is defined.
+% \begin{macrocode}
+\newcommand*\NewAsciiDocListEnv[2][\asclst@docdefaultenvs]{%
+ \newenvironment{#2}%
+ {\begin{AsciiDocList}[#1]}%
+ {\end{AsciiDocList}}%
+ \csdef{#2FromFile}##1{\AsciiDocListFromFile[#1]{##1}}%
+ \csdef{#2FromFiles}##1{\AsciiDocListFromFiles[#1]{##1}}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\AsciiListRegisterEnv}
+% \begin{macro}{\asclst@registeredenv}
+% The
+% |\AsciiListRegisterEnv|\marg{envname}\marg{begin}\marg{end}\marg{item}
+% macro registers a new environment name for use with |AsciiList| and
+% |AsciiDocList|.
+% After such a registration, one may use the \meta{envname} as an
+% element in the \meta{environments} parameter to |AsciiList| or
+% |AsciiDocList|. The \meta{begin}, \meta{end}, and \meta{item} code is
+% used whenever such a newly defined environment is begun or ended, or a
+% list entry is started, respectively. Note that by using the
+% |\AsciiListRegisterEnv|, no real \LaTeX{} environment is created. All
+% registered environments are collected in the |\asclst@registeredenvs|
+% list.
+% \changes{v1.4}{2014/09/19}{Allow registering additional
+% environments}
+% \begin{macrocode}
+\def\asclst@registeredenvs{}
+\newcommand*\AsciiListRegisterEnv[4]{%
+ \listadd\asclst@registeredenvs{#1}%
+ \csdef{asclst@env@#1@begin}{#2}%
+ \csdef{asclst@env@#1@end}{#3}%
+ \csdef{asclst@env@#1@item}{#4}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\AsciiListRegisterDescEnv}
+% The |\AsciiListRegisterDescEnv|\marg{envname} is a macro that can be
+% used as a shorthand for |\AsciiListRegisterEnv| to declare existing
+% description environments. The environment \meta{envname} must exist
+% and must be a description environment, i.e., one whose entries are
+% specified via |\item|\oarg{text}.
+% \begin{macrocode}
+\newcommand*\AsciiListRegisterDescEnv[1]{%
+ \AsciiListRegisterEnv{#1}{\csuse{#1}}{\csuse{end#1}}%
+ {\AsciiListEndOArg{\item}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\AsciiListEndArg}
+% The |\AsciiListEndArg|\marg{command} macro is equal to the given
+% \meta{command}, except that the first argument passed to
+% \meta{command} is the remainder of the line in which the macro is
+% used.
+% \begin{macrocode}
+{\catcode`\^^M=\active%
+ \gdef\AsciiListEndArg#1#2^^M{%
+% \end{macrocode}
+% Note the line break at the end of the following line. This line
+% break is important, because the definition of |\AsciiListEndArg|
+% swallows one line break. By having the line break below, we
+% essentially re-insert the line break, such that |AsciiList| or
+% |AsciiDocList| can use it again to check for list items in the
+% subsequent line.
+% \changes{v1.5b}{2014/09/24}{Ignore initial spaces in argument}
+% \changes{v1.6}{2014/10/12}{Robustified ignoring initial spaces}
+% \changes{v1.6b}{2014/10/14}{Robustified ignoring initial spaces}
+% \changes{v1.6c}{2014/10/16}{Robustified ignoring initial spaces}
+% \changes{v2.1b}{2016/03/31}{Robustified ignoring initial spaces}
+% \begin{macrocode}
+ \begingroup%
+ \def\asclst@@result{#2}\trim@pre@space@in{\asclst@@result}%
+ \edef\asclst@@result{%
+ \endgroup\unexpanded{#1}{\expandonce{\asclst@@result}}}%
+ \asclst@@result
+ }%
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\AsciiListEndOArg}
+% The |\AsciiListEndOArg|\marg{command} macro constitutes the
+% counterpart to the |\AsciiListEndArg| macro for the case of a
+% \meta{command} that takes an \emph{optional} argument (like the
+% |\item| of a |description| environment).
+% \changes{v1.5b}{2014/09/24}{Ignore initial spaces in argument}
+% \changes{v1.6}{2014/10/12}{Robustified ignoring initial spaces}
+% \changes{v1.6b}{2014/10/14}{Robustified ignoring initial spaces}
+% \changes{v1.6c}{2014/10/16}{Robustified ignoring initial spaces}
+% \changes{v2.1b}{2016/03/31}{Robustified against nested square brackets}
+% \begin{macrocode}
+ \gdef\AsciiListEndOArg#1#2^^M{%
+ \begingroup%
+ \def\asclst@@result{#2}\trim@pre@space@in{\asclst@@result}%
+ \edef\asclst@@result{%
+ \endgroup\unexpanded{#1}[{\expandonce{\asclst@@result}}]}%
+ \asclst@@result
+ }%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Pre-Defined List Environments}
+%
+% In the following, we define some environment names that allow one to
+% use sectioning commands for list items. When using these
+% environments, one should be aware that list entries in these
+% environments must fit into a single line (i.e., everything after a
+% line break is not put into the argument of the sectioning command).
+% \begin{macrocode}
+\AsciiListRegisterEnv{chapter}{}{}{\AsciiListEndArg{\chapter}}
+\AsciiListRegisterEnv{section}{}{}{\AsciiListEndArg{\section}}
+\AsciiListRegisterEnv{subsection}{}{}{\AsciiListEndArg{\subsection}}
+\AsciiListRegisterEnv{subsubsection}{}{}%
+ {\AsciiListEndArg{\subsubsection}}
+\AsciiListRegisterEnv{section*}{}{}{\AsciiListEndArg{\section*}}
+\AsciiListRegisterEnv{subsection*}{}{}{\AsciiListEndArg{\subsection*}}
+\AsciiListRegisterEnv{subsubsection*}{}{}%
+ {\AsciiListEndArg{\subsubsection*}}
+\AsciiListRegisterEnv{paragraph}{}{}{\AsciiListEndArg{\paragraph}}
+% \end{macrocode}
+% For nesting sections with sub-sections etc., the |Heading| and
+% |Heading*| environments can be used.
+% \changes{v2.2}{2016/04/14}{Added ``Heading'' environment}
+% \begin{macrocode}
+\AsciiListRegisterEnv{Heading}{\asclst@Heading}{\endasclst@Heading}%
+ {\AsciiListEndArg{\csuse{\asclst@@sec}}}
+\AsciiListRegisterEnv{Heading*}{\asclst@Heading}{\endasclst@Heading}%
+ {\AsciiListEndArg{\csuse{\asclst@@sec}*}}
+% \end{macrocode}
+% \begin{environment}{asclst@Heading}
+% The |asclst@Heading|\oarg{initial} environment is an auxiliary
+% environment for the |Heading| list environment usable in |AsciiList|
+% and |AsciiDocList|. Inside the environment, one can use
+% |\csuse{\asclst@@sec}|\marg{title} to produce a heading at a
+% particular level. The initial level is provided by the optional
+% \meta{initial} argument. When the |asclst@Heading| environment is
+% nested, the heading level decreases (for instance, going from
+% ``section'' to ``subsection'').
+% \begin{macrocode}
+\newenvironment{asclst@Heading}[1][section]%
+ {\bgroup\ifdefmacro{\asclst@@sec}%
+% \end{macrocode}
+% If |\asclst@@sec| is already defined, use the |\asclst@Sec@...| macros
+% to determine the next sub-level (next line). Otherwise, initialize the
+% |\asclst@@sec| macro using the \meta{initial} argument.
+% \begin{macrocode}
+ {\edef\asclst@@sec{\csuse{asclst@Sec@\asclst@@sec}}}%
+ {\def\asclst@@sec{#1}}}%
+ {\egroup}
+\newcommand\asclst@Sec@part{chapter}
+\newcommand\asclst@Sec@chapter{section}
+\newcommand\asclst@Sec@section{subsection}
+\newcommand\asclst@Sec@subsection{subsubsection}
+\newcommand\asclst@Sec@subsubsection{paragraph}
+\newcommand\asclst@Sec@paragraph{subparagraph}
+% \end{macrocode}
+% \end{environment}
+% To simplify the use of the |description| environment as well as
+% other common description environments (the packages defining these
+% environments need not be loaded until the environments are actually
+% used).
+% \begin{macrocode}
+\AsciiListRegisterDescEnv{description}
+\AsciiListRegisterDescEnv{compactdesc}
+% \end{macrocode}
+% It often looks less appealing to have the first item of an |itemize|
+% or |enumerate| environment in the same line as the parent item in a
+% description environment. As an alternative to this default behavior
+% of \LaTeX{}, we offer the following |Description| and |CompactDesc|
+% environments, with which the child items start in a new line (but
+% if the environment starts with text, then this will still be placed
+% in the same line as the description item).
+% \changes{v1.5b}{2014/09/24}{Added alternative description
+% environments}
+% \begin{macrocode}
+\AsciiListRegisterEnv{Description}{\description}{\enddescription}%
+ {\AsciiListEndOArg{\asclst@BreakingDescItem}}
+\AsciiListRegisterEnv{CompactDesc}{\compactdesc}{\endcompactdesc}%
+ {\AsciiListEndOArg{\asclst@BreakingDescItem}}
+% \end{macrocode}
+% \begin{macro}{\asclst@BreakingDescItem}
+% The |\asclst@BreakingDescItem|\oarg{item} macro is the same as
+% |\item[|\meta{item}|]| except that it is additionally ensured that
+% the first item of a contained list environment is not displayed on
+% the same line.
+% \changes{v2.1b}{2016/03/31}{Robustified against nested square brackets}
+% \begin{macrocode}
+\newcommand\asclst@BreakingDescItem[1][]{\item[{#1}]\leavevmode}
+% \end{macrocode}
+% \end{macro}
+%\iffalse
+%</package>
+%\fi
+% \Finale
+\endinput
diff --git a/macros/latex/contrib/asciilist/asciilist.ins b/macros/latex/contrib/asciilist/asciilist.ins
new file mode 100644
index 0000000000..45a71e14a5
--- /dev/null
+++ b/macros/latex/contrib/asciilist/asciilist.ins
@@ -0,0 +1,40 @@
+%%
+%% Copyright (C) 2014-2018 by Richard Grewe <r-g+tex@posteo.net>
+%%
+%% This file may be distributed and/or modified under the conditions of
+%% the LaTeX Project Public License, either version 1.2 of this license
+%% or (at your option) any later version. The latest version of this
+%% license is in:
+%%
+%% http://www.latex-project.org/lppl.txt
+%%
+%% and version 1.2 or later is part of all distributions of LaTeX version
+%% 1999/12/01 or later.
+%%
+\input docstrip.tex
+\keepsilent
+
+\usedir{tex/latex/asciilist}
+\preamble
+
+Copyright (C) 2014-2018 by Richard Grewe <r-g+tex@posteo.net>
+
+This file may be distributed and/or modified under the conditions of
+the LaTeX Project Public License, either version 1.2 of this license
+or (at your option) any later version. The latest version of this
+license is in:
+
+ http://www.latex-project.org/lppl.txt
+
+and version 1.2 or later is part of all distributions of LaTeX version
+1999/12/01 or later.
+
+\endpreamble
+
+\generate{\file{asciilist.sty}{\from{asciilist.dtx}{package}}}
+
+\nopreamble\nopostamble
+\generate{\file{AsciiList.example}{\from{asciilist.dtx}{ALexample}}}
+\generate{\file{AsciiDocList.example}{\from{asciilist.dtx}{ADLexample}}}
+
+\endbatchfile
diff --git a/macros/latex/contrib/asciilist/asciilist.pdf b/macros/latex/contrib/asciilist/asciilist.pdf
new file mode 100644
index 0000000000..c33a7610b2
--- /dev/null
+++ b/macros/latex/contrib/asciilist/asciilist.pdf
Binary files differ