summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/withargs
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-10-14 22:31:43 +0000
committerKarl Berry <karl@freefriends.org>2013-10-14 22:31:43 +0000
commit9778d89f9f3ed407031c3116ba1e3d621c7e0da4 (patch)
tree8b9012f12ae2e12ef1bdb925e191d283b3bc2eed /Master/texmf-dist/doc/latex/withargs
parent24530adc39b721401c8037360aea53c67cc968fa (diff)
withargs (14oct13)
git-svn-id: svn://tug.org/texlive/trunk@31906 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/withargs')
-rw-r--r--Master/texmf-dist/doc/latex/withargs/README37
-rw-r--r--Master/texmf-dist/doc/latex/withargs/withargs.pdfbin0 -> 471742 bytes
-rw-r--r--Master/texmf-dist/doc/latex/withargs/withargs.tex219
3 files changed, 256 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/withargs/README b/Master/texmf-dist/doc/latex/withargs/README
new file mode 100644
index 00000000000..e3df5955260
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/withargs/README
@@ -0,0 +1,37 @@
+LaTeX Package : withargs 0.0.2
+
+Last Modified : 2013-10-07
+
+Author : Michiel Helvensteijn (www.mhelvens.net)
+
+===== Prerequisites =====
+
+To use this package, you need the following expl3 packages:
+* expl3
+* l3regex
+* xparse
+
+To generate the documentation some extra packages are needed.
+
+===== Installation =====
+
+withargs.sty is provided directly in the package archive. Put
+it in a place where your LaTeX distribution can find it.
+
+(withargs.sty is not generated, but manually maintained; you
+ may use docstrip to remove the documentation, but you don't
+ have to; it will just work the way it is)
+
+===== Documentation =====
+
+withargs.pdf is provided directly in the package archive. To
+generate the documentation yourself, run LaTeX on withargs.tex.
+
+(withargs.tex does not contain the package code itself; it inputs
+ withargs.sty directly to document the implementation)
+
+===== License =====
+
+This material is subject to the LaTeX Project Public License. See
+http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html
+for the details of that license.
diff --git a/Master/texmf-dist/doc/latex/withargs/withargs.pdf b/Master/texmf-dist/doc/latex/withargs/withargs.pdf
new file mode 100644
index 00000000000..9c07ddcf128
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/withargs/withargs.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/withargs/withargs.tex b/Master/texmf-dist/doc/latex/withargs/withargs.tex
new file mode 100644
index 00000000000..7301260a9c4
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/withargs/withargs.tex
@@ -0,0 +1,219 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \iffalse %%%%
+% %
+% Copyright (c) 2013 - Michiel Helvensteijn (www.mhelvens.net) %
+% %
+% This work may be distributed and/or modified under the conditions %
+% of the LaTeX Project Public License, either version 1.3 of this %
+% license or (at your option) any later version. The latest version %
+% of this license is in http://www.latex-project.org/lppl.txt %
+% and version 1.3 or later is part of all distributions of LaTeX %
+% version 2005/12/01 or later. %
+% %
+% This work has the LPPL maintenance status `maintained'. %
+% %
+% The Current Maintainer of this work is Michiel Helvensteijn. %
+% %
+% This work consists of the files withargs.tex and withargs.sty. %
+% %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \fi %%%%
+
+\documentclass[a4paper]{withargs-packagedoc}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Setup %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\moretexcs{
+ withargs,foo,bar,bas,expectedResult,
+ actualResult,MyPost,A,uniquecsname,NewPost,
+ cs_generate_variant:Nn,
+ withargs:nn,withargs:cn
+}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Global Changes %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\changes{0.0.1}{2013/10/01}
+ {initial version}
+
+\changes{0.0.2}{2013/10/11}
+ {renamed package to \texttt{withargs}}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\begin{document} %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\maketitle
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Introduction} %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+An example is worth a thousand words:
+
+\begin{latex-example-show}
+\withargs [!] [Hello] [world] { #2 #3#1 }
+\end{latex-example-show}
+
+A quick explanation: we're passing three pieces of \LaTeX\ code in the form
+of optional arguments to the final argument, which forms the output. We're
+defining a new anonymous macro and invoking it right away.
+Up to seven optional arguments are supported.
+
+
+
+\subsection{Why is this useful?} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+One of the main use-cases for this package is to insert the expanded
+result of a computation into the middle of a big
+blob of code that \emph{shouldn't} be expanded. This is possible because
+argument substitution bypasses the expansion process:
+
+\begin{latex-example-show}
+\def \expectedResult {\bar}
+\def \actualResult {\bas}
+\withargs (oo) [\actualResult] [\expectedResult] {
+ \texttt{\detokenize{
+ The \foo variable resulted in `#1' instead of `#2'!
+ }}
+}
+\end{latex-example-show}
+
+`|(oo)|' indicates that both arguments should be expanded `once'.
+Any optional \LaTeX3 style argument specification between parentheses
+may be specified to control expansion.
+
+\needspace{10\baselineskip}
+You can define your own commands accepting `templates'
+with \TeX-style parameters:
+
+\begin{latex-example-show}
+\newcommand{\NewPost}[4]{
+ % #1: author % #2: title
+ % #3: content % #4: template
+ \withargs (xnn) [#1] [#2] [#3] {#4}
+}
+
+\def\MyPost{ \NewPost{Author}{Title}
+ {Boy, do I have some important stuff to say!} }
+
+\begin{tabular}{p{3.5cm}p{3.5cm}p{3.5cm}}
+ \MyPost{\textbf{#2\hfill#1}\vskip1mm\hrule\vskip1mm\textit{#3}} &
+ \MyPost{\fbox{#1: ``#2''}\par#3\vskip1mm\hrule} &
+ \MyPost{#2: #3\hfill\textit{(#1)}}
+\end{tabular}
+\end{latex-example-show}
+
+Generally, if speed is not a concern, |\withargs| can be used
+to make \LaTeX\ code more readable in a variety of situations.
+
+
+
+%\vskip-.4\baselineskip
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Document Level Commands} %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%\vskip-.5\baselineskip
+
+\def\mystrut{\rule{0pt}{4mm}}
+
+\describemacro{\withargs}{
+ \texttt{\bfseries(}%
+ \(\overbrace{\mystrut\hbox{\meta{argument specification}}}^x\)%
+ \texttt{\bfseries)}
+ \(\overbrace{\mystrut\hbox{\oarg{1} \oarg{2} \oarg{3} \oarg{4} \oarg{5} \oarg{6} \oarg{7}}}^x\)
+ \marg{body}
+}
+
+Leaves \meta{body} in the output with |#1|\ldots|#7| replaced
+by optional arguments \meta{1}\ldots\!\meta{7}.
+
+An optional \LaTeX3 style \meta{argument specification} between parentheses
+can be provided, in which case the arguments undergo expansion as specified
+before being placed in the \meta{body}.
+%%
+Here is an example demonstrating the possible expansion types:
+
+\begin{latex-example-show}
+\def\foo{\bar} \def\s{s} \def\bar{ba\s} \def\bas{FOO-BAR-BAS}
+
+\withargs (n o f x c v )
+ [\foo][\foo][\foo][\foo][\foo][\foo] {
+ \begin{tabular}{llll}
+ n: & \texttt{\detokenize{#1}} & % no expansion
+ o: & \texttt{\detokenize{#2}} \\ % expand once
+ f: & \texttt{\detokenize{#3}} & % expand until unexpandable
+ x: & \texttt{\detokenize{#4}} \\ % exhaustive expansion
+ c: & \texttt{\detokenize{#5}} & % \csname conversion
+ v: & \texttt{\detokenize{#6}} % `c', then `o'
+ \end{tabular}
+}
+\end{latex-example-show}
+
+Note that all spaces in the \meta{argument specification} are ignored.
+For details about \LaTeX3 argument specifications, have a look at the
+following documentation:
+
+\begin{center}
+ \url{http://www.ctan.org/pkg/expl3}
+\end{center}
+
+
+\describemacro{\uniquecsname}{}\vskip-2\baselineskip
+
+Perhaps a bit misleading, |\uniquecsname| is not actually defined as a command,
+but |\withargs| recognizes it as a special marker. If an optional |\withargs|
+argument consists entirely of |\uniquecsname|, it is replaced by a
+command sequence name which is guaranteed to be unique\ldots unless
+you look at the source code (Section~\ref{sec:implementation})
+and intentionally replicate the naming scheme.
+
+\begin{latex-example-show}
+\withargs (ccc) [\uniquecsname][\uniquecsname][\uniquecsname] {
+ \def#1{A} \let\A#1
+ \def#2{B}
+ \def#3{C}
+ #3#2#1%
+}%
+(\A)
+\end{latex-example-show}
+
+\vskip5mm
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{\LaTeX3 Functions} %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+The \LaTeX3 functions underlying the functionality of |\withargs| are
+also available as is.
+
+\describeanymacro{\texttt{\textbackslash withargs:\smash{\(\overbrace{\mystrut\hbox{nnnnnnnn}\!}^x\,\)}n}}{
+ \(\overbrace{\mystrut\hbox{\marg{1} \marg{2} \marg{3} \marg{4} \marg{5} \marg{6} \marg{7} \marg{8}}}^x\)
+ \marg{body}
+}
+
+These functions do pretty much the same thing as the main |\withargs| macro,
+except that the argument specification is embedded in the function name
+as per \LaTeX3 coding convention, so a parameter slot is freed up for
+custom use. They are slightly faster than |\withargs|, as there is no
+need to gather optional arguments or do any error checking.
+The downside is that the |\uniquecsname| marker doesn't work for these.
+
+To use a specific expansion scheme, you have to define a variant:
+
+\begin{latex-example-show}
+\ExplSyntaxOn
+ \cs_generate_variant:Nn \withargs:nn {cn}
+ \withargs:cn {LaTeX} {#1}
+\ExplSyntaxOff
+\end{latex-example-show}
+
+Read the \LaTeX3 documentation for details.
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\end{document} %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%