summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/generic/dowith
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-05-10 23:11:16 +0000
committerKarl Berry <karl@freefriends.org>2012-05-10 23:11:16 +0000
commit2b98282d58db23ce342019c8f3aacfa417eb61b1 (patch)
tree593c8bb698dc1539b31ba2bb9296c29c94ede74d /Master/texmf-dist/source/generic/dowith
parentdd4ed517c862a027861583962334b41bf201ce5f (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/dowith')
-rw-r--r--Master/texmf-dist/source/generic/dowith/SrcFILEs.txt15
-rw-r--r--Master/texmf-dist/source/generic/dowith/dowith.tex194
-rw-r--r--Master/texmf-dist/source/generic/dowith/srcfiles.tex14
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]