diff options
Diffstat (limited to 'macros/generic/commado')
-rw-r--r-- | macros/generic/commado/README | 67 | ||||
-rw-r--r-- | macros/generic/commado/commado.sty | 90 | ||||
-rw-r--r-- | macros/generic/commado/doc/SrcFILEs.txt | 19 | ||||
-rw-r--r-- | macros/generic/commado/doc/commado.RLS | 4 | ||||
-rw-r--r-- | macros/generic/commado/doc/commado.pdf | bin | 0 -> 594760 bytes | |||
-rw-r--r-- | macros/generic/commado/docsrc/commado.tex | 205 | ||||
-rw-r--r-- | macros/generic/commado/docsrc/srcfiles.tex | 19 | ||||
-rw-r--r-- | macros/generic/commado/filesdo.sty | 55 |
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 Binary files differnew file mode 100644 index 0000000000..231917bc79 --- /dev/null +++ b/macros/generic/commado/doc/commado.pdf 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 |