From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/asciilist/README.md | 78 ++ macros/latex/contrib/asciilist/asciilist.dtx | 1540 ++++++++++++++++++++++++++ macros/latex/contrib/asciilist/asciilist.ins | 40 + macros/latex/contrib/asciilist/asciilist.pdf | Bin 0 -> 386568 bytes 4 files changed, 1658 insertions(+) create mode 100644 macros/latex/contrib/asciilist/README.md create mode 100644 macros/latex/contrib/asciilist/asciilist.dtx create mode 100644 macros/latex/contrib/asciilist/asciilist.ins create mode 100644 macros/latex/contrib/asciilist/asciilist.pdf (limited to 'macros/latex/contrib/asciilist') 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 +% ------------------------------------------------------- +% +% 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} +% +%\NeedsTeXFormat{LaTeX2e}[1999/12/01] +%\ProvidesPackage{asciilist} +%<*package> + [2018/11/01 v2.2b Package for quickly creating nested lists] +% +% +%<*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} +% +% \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 +% +% \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]{-,*,+} +% - 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 +% +% \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 +% +%\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 +%% +%% 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 + +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 Binary files /dev/null and b/macros/latex/contrib/asciilist/asciilist.pdf differ -- cgit v1.2.3