path: root/Master/texmf-dist/source/latex/asciilist/asciilist.dtx

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