diff options
Diffstat (limited to 'macros/generic/commado/docsrc/commado.tex')
| -rw-r--r-- | macros/generic/commado/docsrc/commado.tex | 205 |
1 files changed, 205 insertions, 0 deletions
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 |