summaryrefslogtreecommitdiff
path: root/macros/generic/commado/docsrc/commado.tex
blob: e7ba43d9d831301200af7a10273d038bc02cd02a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
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