summaryrefslogtreecommitdiff
path: root/macros/generic/commado
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/generic/commado
Initial commit
Diffstat (limited to 'macros/generic/commado')
-rw-r--r--macros/generic/commado/README67
-rw-r--r--macros/generic/commado/commado.sty90
-rw-r--r--macros/generic/commado/doc/SrcFILEs.txt19
-rw-r--r--macros/generic/commado/doc/commado.RLS4
-rw-r--r--macros/generic/commado/doc/commado.pdfbin0 -> 594760 bytes
-rw-r--r--macros/generic/commado/docsrc/commado.tex205
-rw-r--r--macros/generic/commado/docsrc/srcfiles.tex19
-rw-r--r--macros/generic/commado/filesdo.sty55
8 files changed, 459 insertions, 0 deletions
diff --git a/macros/generic/commado/README b/macros/generic/commado/README
new file mode 100644
index 0000000000..75ceed7fbf
--- /dev/null
+++ b/macros/generic/commado/README
@@ -0,0 +1,67 @@
+
+ README for the `commado' bundle
+
+ Iterate on comma-separated and filename lists
+
+ (C) Uwe Lueck 2012/11/29
+
+
+`commado.sty' provides
+
+ \DoWithCSL{<cmd>}{<list>}
+
+to apply an existing one-parameter macro <cmd> to each item
+in a list <list> in which items are separated by commas.
+
+`filesdo.sty' provides
+
+ \DoWithBasesExts{<cmd>}{<bases>}{<exts>}
+
+to run <cmd>{<base>.<ext>} for some (at most) one-parameter
+macro <cmd>, each base filename <base> in the comma-separated
+list <bases> and each extension <ext> in the comma-separated
+list <exts>.
+
+As opposed to LaTeX’s internal \@for, no assignments are
+involved (unless <cmd> uses assignments, "expandability" in
+"TeX’s gullet").
+
+Both packages are "generic," i.e., should work with Plain
+TeX, LaTeX or even other formats, relying on the `plainpkg'
+package for some minimal LaTeX-like behaviour.
+
+RELATED PACKAGES: `loops' and others mentioned in the
+ `dowith' package documentation.
+
+KEYWORDS: macro programming, programming structures, loops,
+ lists
+
+REQUIRED PACKAGES: `plainpkg', `stacklet'
+
+LICENSE: The package files `commado.sty', `filesdo.sty' and
+ the files `commado.pdf' and `commado.tex' documenting
+ both package files can be redistributed and/or modified
+ under the terms of the LaTeX Project Public License;
+ either version 1.3c of the License, or any later version,
+ see
+
+ http://www.latex-project.org/lppl.txt
+
+ There is NO WARRANTY, indeed this still is somewhat
+ experimental.
+
+ The `commado' package is author-maintained in the sense
+ of the license.
+
+The latest public version of the package is available at
+
+ http://mirror.ctan.org/macros/latex/contrib/commado/
+
+A TDS version of the package is available as
+
+ http://mirror.ctan.org/install/macros/latex/contrib/commado.tds.zip
+
+Please report bugs, problems, suggestions, and bad English via
+
+ http://www.contact-ednotes.sty.de.vu
+
diff --git a/macros/generic/commado/commado.sty b/macros/generic/commado/commado.sty
new file mode 100644
index 0000000000..25f5b687ad
--- /dev/null
+++ b/macros/generic/commado/commado.sty
@@ -0,0 +1,90 @@
+ \input plainpkg
+% \NeedsTeXFormat{LaTeX2e}[1994/12/01]
+\ProvidesPackage{commado}[2012/11/30 v0.11 iterate on CSL (UL)]
+%%
+%% Copyright (C) 2012 Uwe Lueck,
+%% http://www.contact-ednotes.sty.de.vu
+%% -- author-maintained in the sense of LPPL below --
+%%
+%% This file can be redistributed and/or modified under
+%% the terms of the LaTeX Project Public License; either
+%% version 1.3c of the License, or any later version.
+%% The latest version of this license is in
+%% http://www.latex-project.org/lppl.txt
+%% We did our best to help you, but there is NO WARRANTY.
+%%
+%% Please report bugs, problems, and suggestions via
+%%
+%% http://www.contact-ednotes.sty.de.vu
+%%
+\PushCatMakeLetterAt
+%% == Auxiliaries ==
+\ifltx \else %% unless provided by LaTeX already
+ \long\def\@firstoftwo#1#2{#1}
+ \long\def\@secondoftwo#1#2{#1}
+\fi
+%% ... 4 less than
+% \long\def\@firstsecondofthree#1#2#3{#1#2}
+% \long\def\@firstthirdofthree#1#2#3{#1#3}
+%%
+%% == Processing a Comma-Separated List ==
+%% Most of the following code aims at removing the final
+%% space in the comma-separated list.
+%% % `\<cmd>' usually may either refer to a string starting
+%% % with a backslash or to the \emph{token} with the name
+%% % \qtdcode{<cmd>}
+%% % (cf. "\TeX's Tokens" in the \ctanpkgref{dowith} documentation).
+%% A variant of parsing as in 'fifinddo.sty'
+%% (\ctanpkgdref{nicetext} bundle) and
+%% \ctanpkgstyref{bitelist}\urlfoot{CtanPkgRef}{bitelist}
+%% package is employed %% ^ 2012/11/30
+%% (while I am about to use different approaches there,
+%% one may see here how, inspired by `\@ifblank' in
+%% \ctanpkgstyref{url}).\urlfoot{CtanPkgRef}{url}
+%% The purpose of the following `\edef' of
+%% |\DoWithCSL{<cmd>}{<list>}|
+%% is to get a space token after `\@firstoftwo' in the parameter text.
+%% \pagebreak[3]
+\let\CD@final@comma\relax
+\edef\DoWithCSL#1#2{%
+ \CD@final@comma#2\CD@final@comma %% 2nd \ 2012/11/30
+ \noexpand\@firstoftwo
+% \noexpand\@firstsecondofthree
+ \space\CD@final@comma
+ \noexpand\@secondoftwo
+% \noexpand\@firstthirdofthree
+ \noexpand\end{#1}{#2}}
+\def\CD@final@comma#1 \CD@final@comma#2#3\end#4#5{%
+% \expandafter\@secondfirstoftwo\expandafter{%
+% #2{#1}#5}{\do@with@csl#4}%
+ #2{\do@with@csl{#4}#1}{\do@with@csl{#4}#5}%
+%% ... 15 vs.\ 13:
+% #2{\do@with@csl{#4}}{#1}{#5}%
+ ,\StopDoing,}
+\catcode`\Q=3 %% not in #1
+\def\do@with@csl#1#2#3,{%
+%% #1 is <cmd>. #2 takes the first token from (remaining) <list>
+%% that is not a space token. Trying to enter a blank
+%% list item would result in using the
+%% \emph{next comma as a list item!}---The following
+%% is an alternative to the analogue in 'domore.sty':
+ \unless@stop@doing#2#3\StopDoing
+ #1{#2#3}\do@with@csl{#1}\StopDoing Q}
+\def\unless@stop@doing#1\StopDoing#2\StopDoing#3Q{#2}
+%% ... somewhat replaces `\@secondfirstoftwo'---but will the
+%% latter be dropped? `\unless@stop@doing' is specific
+%% for `\StopDoing'---but can be used with `\DoWith' too.
+%% TODO %% 2012/11/24
+\catcode`\Q=11
+%%
+%% == Leaving the Package File ==
+\PopLetterCatAt
+\endinput
+%%
+%% == \acro{VERSION HISTORY} ==
+
+v0.1 2012/11/24f. started
+ 2012/11/26 code ready
+ 2012/11/27 documented
+v0.11 2012/11/30 code typo corrected, removing final space,
+ doc. \urlfoot's
diff --git a/macros/generic/commado/doc/SrcFILEs.txt b/macros/generic/commado/doc/SrcFILEs.txt
new file mode 100644
index 0000000000..4236cde316
--- /dev/null
+++ b/macros/generic/commado/doc/SrcFILEs.txt
@@ -0,0 +1,19 @@
+
+ *File List*
+ commado.RLS 2015/11/16 r0.11a doc. `AllOf' in dowith
+ commado.sty 2012/11/30 v0.11 iterate on CSL (UL)
+ filesdo.sty 2012/11/27 v0.1 iterate on files (UL)
+ commado.tex 2015/11/16 -- documenting commado.sty
+srcfiles.tex 2015/11/16 -- file infos -> SrcFILEs.txt
+ ---USED.--- -- -- -- -- ----
+fifinddo.sty 2012/11/17 v0.61 filtering TeX(t) files by TeX (UL)
+ makedoc.sty 2012/08/28 v0.52 TeX input from *.sty (UL)
+niceverb.sty 2015/11/09 v0.61 minimize doc markup (UL)
+texlinks.sty 2015/07/20 v0.83 TeX-related links (UL)
+ makedoc.cfg 2013/03/25 -- documentation settings
+mdoccorr.cfg 2012/11/13 -- `makedoc' local typographical corrections
+ ***********
+
+ List made at 2015/11/16, 06:27
+ from script file srcfiles.tex
+
diff --git a/macros/generic/commado/doc/commado.RLS b/macros/generic/commado/doc/commado.RLS
new file mode 100644
index 0000000000..4134b7c277
--- /dev/null
+++ b/macros/generic/commado/doc/commado.RLS
@@ -0,0 +1,4 @@
+\ProvidesFile{commado.RLS} %%%% RELEASE INFO %%%%
+ [2015/11/16 r0.11a doc. `AllOf' in dowith]
+ [2012/11/30 v0.11 fix final trimming ]
+ [2012/11/27 v0.1 initial ]
diff --git a/macros/generic/commado/doc/commado.pdf b/macros/generic/commado/doc/commado.pdf
new file mode 100644
index 0000000000..231917bc79
--- /dev/null
+++ b/macros/generic/commado/doc/commado.pdf
Binary files differ
diff --git a/macros/generic/commado/docsrc/commado.tex b/macros/generic/commado/docsrc/commado.tex
new file mode 100644
index 0000000000..e7ba43d9d8
--- /dev/null
+++ b/macros/generic/commado/docsrc/commado.tex
@@ -0,0 +1,205 @@
+\ProvidesFile{commado.tex}[2015/11/16 documenting commado.sty]
+\title{\pkg{\huge commado.sty} and \pkg{\huge filesdo.sty}\\---\\%
+ Immediately Extend a One-Argument Macro\\
+ to Comma-Separated Lists and Combinations\\
+ of Filename Bases and Extensions\thanks{This document describes
+ \textcolor{blue}{\UseVersionOf{\jobname.sty}}
+ of \textsf{\jobname.sty} as of \UseDateOf{\jobname.sty}
+ and version \textcolor{blue}{\UseVersionOf{filesdo.sty}}
+ as of \UseDateOf{filesdo.sty} of \pkg{filesdo.sty}..}}
+% \RequirePackage[wrap]{nicefilelist} \listfiles
+\RequirePackage{makedoc} \ProcessLineMessage{}
+\renewcommand*{\mdSectionLevelOne}{\string\subsection}
+\MakeJobDoc{19}{\SectionLevelOneParseInput} %% 2012/11/26
+\documentclass[fleqn]{article}%% TODO paper dimensions!?
+% \documentclass{article} %% TODO paper dimensions!?
+\usepackage{catchdq} %% TODO earlier than `langcode'
+\input{makedoc.cfg} %% shared formatting settings
+\ifpdf\else \errhelp{hyperref v6.83m option [draft] bad with \begin{equation}}
+ \errmessage{run this with pdflatex only}\fi
+\ReadPackageInfos{commado,filesdo}
+% \usepackage{commado}
+\MDkeywords{macro programming, programming structures, loops, lists}
+\sloppy \catchdqs
+\begin{document}
+\maketitle
+\begin{MDabstract}
+'commado.sty' provides \[`\DoWithCSL{<cmd>}{<list>}'\]
+in order to apply an existing one-parameter macro <cmd>
+to each item in a list <list> in which items are
+\wikienref{comma-separated list}{separated by commas.}
+'filesdo.sty' provides \[`\DoWithBasesExts{<cmd>}{<bases>}{<exts>}'\]
+in order to run `<cmd>{<base>.<ext>}' for some (at most)
+one-parameter macro <cmd>, each base filename <base> in the
+comma-separated list <bases> and each filename extension <ext>
+in the comma-separated list <exts>.
+As opposed to \LaTeX's internal `\@for', no assignments are involved
+(unless <cmd> uses assignments---"expandability" in "\TeX's gullet").
+
+Both packages are "generic," i.e., should work with Plain \TeX,
+\LaTeX\ or even other formats, relying on the \ctanpkgref{plainpkg}
+package for some minimal \LaTeX-like behaviour.
+
+\MDaddtoabstract{Related packages} \ctanpkgref{loops} and others
+mentioned in the \ctanpkgref{dowith} package documentation.
+\end{MDabstract}
+\newpage
+\tableofcontents
+% \newpage
+\section{Installing and Calling}
+The files 'commado.sty' and 'filesdo.sty'
+are provided ready, installation just requires
+putting them somewhere where \TeX\ finds them
+(which may need updating the filename data
+ base).\urlfoot{ukfaqref}{inst-wlcf}
+However, installation of the package \ctanpkgdref{plainpkg}
+and the package 'stacklet.sty' (\ctanpkgdref{catcodes} bundle)
+is required additionally.
+
+As to calling (loading): 'commado.sty' and 'filesdo.sty' are
+"\pkg{plainpkg} packages" in the sense of the 'plainpkg'
+documentation that you may consult for details.
+So roughly,
+\begin{itemize}
+ \item load it by \ |\usepackage{<pkg>}| \ if you can,
+ \item otherwise by \ |\RequirePackage{<pkg>}| \\
+ (perhaps from within another "\pkg{plainpkg} package"),
+ \item or by \ |\input <pkg>.sty|
+ \item or even by \ |\input{<pkg>.sty}|~\dots
+\end{itemize}
+---where <pkg> is \qtdcode{commado} or \qtdcode{filesdo}.
+
+% \pagebreak
+\section{Syntax and Relation to the 'dowith' Package}
+In <list> with |\DoWithCSL{<cmd>}{<list>}|, blank spaces %% boxed 2015/11/15
+before entries or after commas as well as preceding the
+closing brace are ignored. So
+\[`\DoWithCSL{<cmd>}{ cfg, sty, tex }'\]
+works like
+\[`\DoWithAllOf{<cmd>}{{cfg}{sty}{tex}}'\] %% added `AllOf' 2015/11/15
+from \ctanpkgstyref{dowith}.\urlfoot{CtanPkgRef}{dowith} %% foot 2012/11/30
+With `\DoWithCSL'
+(at present), %% 2012/11/27
+an item cannot be empty or consist of blank spaces only.
+Empty or blank items can be handled by `\DoWith'\-`AllOf'.
+%% <- was not wrong without `AllOf', however ... 2015/11/15
+%% ... hyphenation is a great compromise! without hyphen?
+\par %% 2015/11/15
+\begingroup \footnotesize
+As to \strong{relevance}, the previous remark addresses those
+who want to understand what I am doing, such as me.
+The two commands provide a rather obvious ``link'' between the 'commado'
+and the 'dowith' bundle. But neither of them is a command that
+``you shouldn't miss.'' 'commado.sty' is mainly a programming tool
+(and I isolate it as an object of study).
+% similar to a chess diagram to demonstrate how to trap a lonely king
+% with king and rook only, the actual task being expandability,
+% in my case to generate \acro{HTML} with \TeX's `\write' primitive).
+ \par\strong{Choosing between 'dowith' and 'commado'.}\quad What I
+\strong{really use} in the case of comma-separated lists is
+\strong{'filesdo.sty'} as described in the next section. %% TODO really?
+It is great to keep certain files or file sections small (\strong{readability}),
+actually in describing package bundles, on \acro{CTAN} as well as
+with a complex book at which I am working. However,
+the comma feature is a little more complex than the 'dowith' way,
+and I like to avoid unnecessarily complex things.
+The real advantage of 'filesdo', as I feel it,
+is the readability of the code with combinations of file \emph{basenames}
+and \emph{extensions}, similar to \emph{brace expansion} in the
+\Wikidisambref{Bash}{Unix shell} shell.
+The braces make obvious which are the basenames and which are the
+extensions, and the commas structure each of these two lists.
+
+In applications of \strong{'dowith'}, saving \strong{tokens} and
+\strong{expansion} steps is more important to me (a kind of sports).
+\emph{Tokens} actually are saved with 'dowith' when <list> consists of
+single tokens rather than ``\strong{brace groups},''
+and the former is the application of 'dowith' in my \ctanpkgdref{langcode} package
+(in the 'dowith' discussion, I compare this with the \ctanpkgdref{xspace} package).
+On the other hand, a <list> of brace groups even needs more tokens than a comma-separated list.
+% (Due to \TeX's tokenization, readability and parsimony are opposite and
+% incompatible goals.)
+The number of tokens or expansion steps is relevant when a list is stored
+as a macro or in a token register. It is less relevant when a list
+is processed once only at the moment the input file is read
+and then is not stored any longer.
+
+There is a situation where I prefer lists of \emph{brace groups}
+to comma-separated lists although the former need more tokens
+and their readablility is worse: I use something like
+\begin{equation}
+ `\autrefs{{apples}{oranges}{pears}}'
+\end{equation}
+to generate a list of internal links in a \acro{HTML} file.
+`\autrefs' this way rests on `\DoSeparateWith' from 'domore.sty'.
+`\DoSeparateWith' is based on `\DoWith'. Sometimes I use the former
+one directly as an \emph{author}. The alternative
+\begin{equation}
+ `\autrefs{apples,oranges,pears}'
+\end{equation}
+would need less tokens (which is absolutely irrelevant in this case
+because the line is in \TeX's memory for a moment only)
+and may be easier to read. However, often I want to change the order
+of the items. When I try this by cut\&paste in a comma-separated list,
+I always wonder whether I should cut/copy the right-hand comma
+of a list item or the left-hand comma; and at the next moment,
+I have forgotten whether I cut the right-hand comma
+or the other one. With the 'dowith' approach, I just cut\&paste
+a brace group. A function key opens an empty brace group in my
+favorite editor.
+
+\par \endgroup
+
+\section{Example for 'filesdo.sty'}
+In the file `srcfiles.tex' for the \ctanpkgdref{nicetext} bundle,
+there is a line
+\begin{quote}
+`\DoWithBasesExts\ReadFileInfos{fifinddo,niceverb}{sty,tex}'\kern-10pt
+\end{quote}
+This works like
+\begin{quote}
+`\ReadFileInfos{fifinddo.sty}'\\
+`\ReadFileInfos{niceverb.sty}'\\
+`\ReadFileInfos{fifinddo.tex}'\\
+`\ReadFileInfos{niceverb.tex}'
+\end{quote}
+or actually
+(a special feature of \ctanpkgref{readprov}'s\urlfoot{CtanPkgRef}{readprov}
+ %% <- foot 2012/11/30
+ `\ReadFileInfos' is that its argument may be
+ a comma-separated list already)
+\begin{quote}
+`\ReadFileInfos{fifinddo.sty,niceverb.sty,'\\
+\null\texttt{ ~ ~ ~ ~ ~ ~ ~ }`fifinddo.tex,niceverb.tex}'
+\end{quote}
+I ponder providing a shorthand `\ReadBaseExtInfos' for
+\begin{quote}
+`\DoWithBasesExts\ReadFileInfos'
+\end{quote}
+and reimplementing `\ReadFileInfos' using `\DoWithCLS' in 'myfilist.sty'
+(2012-11-27).
+
+\pagebreak
+\section{The File 'commado.sty'}
+\subsection{Package File Header (Legalese and 'plainpkg')}
+\input{commado.doc}
+
+\newpage
+
+\section{The File 'filesdo.sty'}
+\subsection{Package File Header (Legalese and 'plainpkg')}
+\ResetCodeLineNumbers
+\renewcommand*{\mdJobName}{filesdo}
+\MakeInputJobDoc{19}{\SectionLevelOneParseInput}
+\end{document}
+
+VERSION HISTORY
+
+2012/11/24 for v0.1 very first
+2012/11/30 for v0.11 \ctanpkgdref moves to `makedoc.cfg',
+ 2 more link footnotes
+2015/11/15f. `AllOf' was missing in the description of
+ the relation to the `dowith' bundle --
+ added an "essay"
+2015/11/15 error message to deal with hyperref's
+ draft/equation problem as in dowith.tex
diff --git a/macros/generic/commado/docsrc/srcfiles.tex b/macros/generic/commado/docsrc/srcfiles.tex
new file mode 100644
index 0000000000..1bffd26663
--- /dev/null
+++ b/macros/generic/commado/docsrc/srcfiles.tex
@@ -0,0 +1,19 @@
+\ProvidesFile{srcfiles.tex}[2015/11/16 file infos -> SrcFILEs.txt]
+\RequirePackage[r,wrap]{nicefilelist}
+\RequirePackage{stacklet,filedate}
+\MaxBaseEmptyList*
+%% release:
+\ReadFileInfos{commado.RLS} %% tested below
+\ModDates \FileDateAutoChecks
+%% packages:
+\ReadPackageInfos{commado,filesdo}
+%% documentation:
+\ReadFileInfos{commado,srcfiles}
+%% documentation settings and auxiliaries:
+\FileListRemark[ ----]{---USED.---}
+\ReadPackageInfos{fifinddo,makedoc,niceverb,texlinks}
+\ReadFileInfos{makedoc.cfg,mdoccorr.cfg}
+\DatesDiffWarnings
+\CheckDateOfToday{commado.RLS}
+\ListInfos[SrcFILEs.txt]
+
diff --git a/macros/generic/commado/filesdo.sty b/macros/generic/commado/filesdo.sty
new file mode 100644
index 0000000000..728334419a
--- /dev/null
+++ b/macros/generic/commado/filesdo.sty
@@ -0,0 +1,55 @@
+ \input plainpkg
+% \NeedsTeXFormat{LaTeX2e}[1994/12/01]
+\ProvidesPackage{filesdo}[2012/11/27 v0.1 iterate on files (UL)]
+%%
+%% Copyright (C) 2012 Uwe Lueck,
+%% http://www.contact-ednotes.sty.de.vu
+%% -- author-maintained in the sense of LPPL below --
+%%
+%% This file can be redistributed and/or modified under
+%% the terms of the LaTeX Project Public License; either
+%% version 1.3c of the License, or any later version.
+%% The latest version of this license is in
+%% http://www.latex-project.org/lppl.txt
+%% We did our best to help you, but there is NO WARRANTY.
+%%
+%% Please report bugs, problems, and suggestions via
+%%
+%% http://www.contact-ednotes.sty.de.vu
+%%
+%% == Documentation ==
+%% For documentation in \acro{PDF} format, see `commado.pdf'.
+%%
+%% == 'commado' Required ==
+%% 'filesdo' is based on 'commado':
+\RequirePackage{commado}
+%%
+%% == Category Code ==
+%% Use `@' as part of ``command names'' ('plainpkg', 'stacklet'):
+\PushCatMakeLetterAt
+%%
+%% == User Commands ==
+%% |\DoWithExtBases{<cmd>}{<ext>}{<basenames>}| \
+%% runs `<cmd>{<base>.<ext>}' for all items <base>
+%% in <basenames> and a single filename extension <ext>:
+\def\DoWithExtBases#1#2{\DoWithCSL{\do@with@ext@base{#1}{#2}}}
+\def\do@with@ext@base#1#2#3{#1{#3.#2}}
+%% |\DoWithBasesExts{<cmd>}{<basenames>}{<exts>}| \
+%% runs `<cmd>{<base>.<ext>}' for all items <base>
+%% in <basenames> and all items <ext> in <exts>:
+\def\DoWithBasesExts#1#2{\DoWithCSL{\distrib@basenames@do{#1}{#2}}}
+%% `\distrib@basenames@do' exchanges arguments in order to reduce
+%% the task to `\DoWithCSL' and `\DoWithCSL':
+\def\distrib@basenames@do#1#2#3{%
+ \DoWithCSL{\DoWithExtBases{#1}{#3}}{#2}}
+%%
+%% == Leaving the Package File ==
+\PopLetterCatAt
+\endinput
+%%
+%% == \acro{VERSION HISTORY} ==
+
+v0.1 2012/11/24f. started
+ 2012/11/26 code ready
+ 2012/11/27 documented,
+ \DoWithBaseExts -> \DoWithBasesExts