diff options
author | Karl Berry <karl@freefriends.org> | 2012-05-10 23:11:16 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2012-05-10 23:11:16 +0000 |
commit | 2b98282d58db23ce342019c8f3aacfa417eb61b1 (patch) | |
tree | 593c8bb698dc1539b31ba2bb9296c29c94ede74d /Master/texmf-dist/source/generic | |
parent | dd4ed517c862a027861583962334b41bf201ce5f (diff) |
new generic package dowith (10may12)
git-svn-id: svn://tug.org/texlive/trunk@26292 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/generic')
-rw-r--r-- | Master/texmf-dist/source/generic/dowith/SrcFILEs.txt | 15 | ||||
-rw-r--r-- | Master/texmf-dist/source/generic/dowith/dowith.tex | 194 | ||||
-rw-r--r-- | Master/texmf-dist/source/generic/dowith/srcfiles.tex | 14 |
3 files changed, 223 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/generic/dowith/SrcFILEs.txt b/Master/texmf-dist/source/generic/dowith/SrcFILEs.txt new file mode 100644 index 00000000000..48f98f04414 --- /dev/null +++ b/Master/texmf-dist/source/generic/dowith/SrcFILEs.txt @@ -0,0 +1,15 @@ + + *File List* + dowith.sty 2011/11/19 v0.2 simple list loop (UL) + dowith.tex 2012/05/10 -- documenting dowith.sty +fifinddo.sty 2012/01/20 v0.51 filtering TeX(t) files by TeX (UL) + makedoc.sty 2011/11/19 v0.42 TeX input from *.sty (UL) +niceverb.sty 2011/12/05 v0.44 minimize doc markup (UL) + makedoc.cfg 2012/05/10 -- documentation settings +mdoccorr.cfg 2011/12/03 -- makedoc local typographical corrections +srcfiles.tex 2012/12/10 -- file infos -> SrcFILEs.txt + *********** + + List made at 2012/05/10, 11:48 + from script file srcfiles.tex + diff --git a/Master/texmf-dist/source/generic/dowith/dowith.tex b/Master/texmf-dist/source/generic/dowith/dowith.tex new file mode 100644 index 00000000000..de7b4c5aa7f --- /dev/null +++ b/Master/texmf-dist/source/generic/dowith/dowith.tex @@ -0,0 +1,194 @@ +\ProvidesFile{dowith.tex}[2012/05/10 documenting dowith.sty] +\title{\kern-\baselineskip + \textsf{\huge dowith.sty}\\---\\Apply Command + to Elements of Lists without Separators\,---\, + and without Iterator\thanks{This + document describes version + \textcolor{blue}{\UseVersionOf{\jobname.sty}} + of \textsf{\jobname.sty} as of \UseDateOf{\jobname.sty}.}} +{ \RequirePackage{makedoc} \ProcessLineMessage{} + \renewcommand*\mdSectionLevelOne{\string\subsection} + \renewcommand*\mdSectionLevelTwo{\string\subsubsection} + \MakeJobDoc{16}%% 2011/09/06 + {\SectionLevelTwoParseInput} } +\documentclass[fleqn]{article}%% TODO paper dimensions!? +\input{makedoc.cfg} %% shared formatting settings +\ReadPackageInfos{dowith} +% \usepackage{dowith} +\sloppy +\MDkeywords{macro programming, loops, list macros} +\hypersetup{% + pdftitle=dowith.sty handles lists without separators, + pdfsubject=documenting dowith.sty +}%% /2011/08/22 +\begin{document} +\maketitle +\begin{MDabstract}\noindent +This package provides macros for applying a command +to all elements of a list without separators, such as +`\DoWithAllIn{<cmd>}{<list-macro>}', and also for extending +and reducing macros storing such lists. Applications in mind belonged +to \LaTeX, but the package should work with other formats as well. +Loop and list macros in other packages are discussed. +%% 2012/05/09: +There is an emphasis on expandability +(no \Wikienref{iterator}), %% 2012/05/10 +without relying on \CtanPkgRef{e-tex}{$\varepsilon$-\TeX}. +\MDaddtoabstract{Related packages} +\pkg{etextools}, \pkg{etoolbox}, \pkg{forarray}, +\pkg{forloop}, \pkg{multido}, \pkg{moredefs}, \pkg{lmake}, +\pkg{texapi}, \pkg{xfor}, \pkg{xspace} +\end{MDabstract} +\tableofcontents + +% \newpage +% \section{Features and Usage} +\section{Usage} + +% \subsection{Installing and Calling} +The file 'dowith.sty' is provided ready, installation only requires +putting it somewhere where \TeX\ finds it +(which may need updating the filename data + base).\urlfoot{ukfaqref}{inst-wlcf} %% corr. 2011/02/08 + +With \LaTeX, +you load 'dowith.sty' (as usually) by +\begin{verbatim} + \usepackage{dowith} +\end{verbatim} +below the `\documentclass' line(s) and above `\begin{document}'. +However, the package can also be used with other formats, just +\begin{verbatim} + \input dowith.sty +\end{verbatim} +The single commands that the package provides are described below +together with their implementation. + +% \section{Example} + +\section{Similar Commands in other Packages} +The \CtanPkgRef{etex}{$\varepsilon$-TeX}-related %% e->... 2012/05/09 +packages \ctanpkgref{etextools} +(Florent Chervet), \ctanpkgref{etoolbox} (Philipp Lehman), +and \ctanpkgref{texapi} (Paul Isambert) seem to include and +(very much) extend the functionality of 'dowith'. +Also the `\ForEach'\texttt{\dots\unkern} macros of +\ctanpkgref{forarray} (Christian Schr\"oppel) seem to extend +the present `\DoWith'\texttt{\dots\unkern} commands. +\ctanpkgref{moredefs} (Matt Swift) provides list handling commands +like the few that are here.\footnote{\ctanpkgref{arrayjobx} + provides somewhat ``exotic" handling of ``lists".} %% 2012/05/10 +(I~do not want to load that much.) + +Regarding \LaTeX\ macros in `latex.ltx', the basic macro `\DoWith' of +the present package resembles `\@tfor' very much, which likewise deals +with lists without separators. By contrast, \LaTeX's `\@for' deals with +comma-separated lists (such as lists of options). + +A major difference between `\DoWith' and `\@tfor' is that the latter +uses a ``loop variable" or rather ``\Wikienref{iterator}" +to which the elements of the list are +assigned. `\DoWith<cmd>' does not use such a loop variable +or such assignments and thus is ``expandable" at least when <cmd> +(and the elements, depending on <cmd>) are expandable. +On the other hand, `\@tfor' applies some procedure to the list +elements without needing a \emph{name} for the procedure +(or a \emph{macro} storing the procedure). + +What about \ctanpkgref{forloop} (Nick Setzer), +\ctanpkgref{multido} (Timothy Van Zandt, Rolf Niepraksch, Herbert +Vo\ss), and \ctanpkgref{xfor} (Nicola Talbot)? + +'xfor' is just a reimplementation of `\@for'. +'forloop' and 'multido' are more close to ``real \qtd{for} loops" +(cf.\ \wikienref{for loop}{\meta{Wikipedia}}). +Loops of the latter kind go through a certain set as well, +but such sets rather consist of \emph{numbers} and are exhausted +by incrementing (or also decrementing) variables (counters). +This is essentially not needed when a list literally is +\emph{enumerated}---such loops are distinguished as +``\wikienref{Foreach loop}{foreach loops}." %% W -> w 2012/05/10 +I wondered whether behind \LaTeX's +`\@tfor' (and `\@for') there was an ``ideological" consideration +such as ``A loop must have a loop variable!" However, +avoiding usage of a macro name and a macro parameter may have been +a good reason. + +Commands like `\DoWith' also save tokens thinking of list macros +(in \LaTeX/`latex.ltx') that use a \emph{separator macro} +which may be used as a \emph{command} to be applied to the list +elements. One example is +`\dospecials' that already is in Plain \TeX\ and expands to +\[`\do\ \do\\\do\{\do\}\do\$\do\&\do\#\do\^\do\_\do\%\do\~'\] +% \begin{verbatim} +% `\do\ \do\\\do\{\do\}\do\$\do\&\do\#\do\^\do\_\do\%\do\~' +% \end{verbatim} +An important application of `\dospecials' is temporarily +switching off the ``special" functionality of the ``elements" +in `\dospecials'. With \LaTeX, this may happen thus: +\[`\let\do\@makeother\dospecials'\] +% \begin{verbatim} +% `\let\do\@makeother +% \end{verbatim} +With 'dowith', you can do the same with a shorter variant +`\specials' of `\dospecials', defined by +\[`\def\specials{\ \\\{\}\$\&\#\^\_\%\~}'\] +and then +\[`\DoWithAllIn\@makeother\specials'\] +`latex.ltx' uses `\@elt' instead of `\do' for its own list macros. + +%% added 2011/11/03: +There also is |\loop<loop-body>\repeat| in Plain \TeX\ and a +refined version of it in `latex.ltx'. It is \emph{not} expandable +since it starts with an assignment for `\body' (Plain \TeX) or +`\iterate' (`latex.ltx'). As to the programming structure, +it is so simple and general that you cannot immediately see +what kind of loops it addresses. However, the applications +I have seen have been ``for" or (rather) ``while" loops. +``While" loops can ``emulate" ``for" and ``foreach" loops +by having the ``incrementation" method or the ``enumeration" method in +their body. This is quite obvious for ``for" loops, not quite so for +``foreach" loops; which for practical application (in my view) means +that neither \LaTeX/\TeX's `\loop' macro nor in general ``while" loops +is/are very helpful for implementing ``foreach" loops, +as rather `\DoWith' and similar constructions are. +The reason for this is (as it seems to me) is that you +(a human being) can much more easily enumerate (``list") +the items of a list (you have in mind) than define the \emph{method} +that (allegedly) is behind your enumeration. \ \meta{Example:} +\[`\DoWithAllOf{\printsamplearea}{\red\green\blue}'\] +---\emph{how} (according to what ``method"?) did you ``proceed" from +`\red' to `\green' and from `\green' to `\blue'? + +%% 2011/11/07: +In \LaTeX's \ctanpkgref{tools} bundle, \ctanpkgref{xspace} +has a list macro `\@xpspace@exceptions@tlp' without separators. +It is handled like here, except that it ``breaks" the loop +when an item is found that applies. +% %% 2011/11/10: +% Also Heiko Oberdiek's \ctanpkgref{zref} deals with ``lists" of +% ``properties" of ``entities," +%% 2011/11/11: comma separated! + +%% 2012/05/09f.: +The more recent \ctanpkgref{lmake} provides a key-value syntax +for printing lists of complex mathematical expressions easily +(using some assignments) +as well as defining commands according to a pattern from a list. + + \pagebreak %% 2011/11/03 +\section{Implementation} %% 2012/05/10 +\subsection{Package File Header (Legalese)} %% sub 2012/05/10 +\input{dowith.doc} +\end{document} + +VERSION HISTORY + +2011/11/02 for v0.1 very first +2011/11/03 discussing \loop; \pagebreak +2011/11/07 xspace +2011/11/10f. zref added/removed +2012/05/09 for v0.2 $\varepsilon$-\TeX +2012/05/10 "iterator", \MDkeywords, \hypersetup, + Legalize -> Legalese, "Related packages", + tighter sectioning diff --git a/Master/texmf-dist/source/generic/dowith/srcfiles.tex b/Master/texmf-dist/source/generic/dowith/srcfiles.tex new file mode 100644 index 00000000000..0db90229e0a --- /dev/null +++ b/Master/texmf-dist/source/generic/dowith/srcfiles.tex @@ -0,0 +1,14 @@ +\RequirePackage{nicefilelist} +\MFfieldtemplate{f-base}{dowithxx} +\RequirePackage{myfilist} +\ProvidesFile{srcfiles.tex}[2012/12/10 file infos -> SrcFILEs.txt] +\EmptyFileList %%% [readprov.sty,myfilist.sty] +%% packages: +\ReadPackageInfos{dowith} +%% documentation: +\ReadFileInfos{dowith} +%% documentation settings and auxiliaries: +\ReadPackageInfos{fifinddo,makedoc,niceverb} +\ReadFileInfos{makedoc.cfg,mdoccorr.cfg} +\ReadFileInfos{srcfiles} +\ListInfos[SrcFILEs.txt] |