macroswap (18aug13)

git-svn-id: svn://tug.org/texlive/trunk@31462 c570f23f-e606-0410-a88d-b1316a301751

9 files changed, 352 insertions, 1 deletions

diff --git a/Master/texmf-dist/doc/latex/macroswap/Makefile b/Master/texmf-dist/doc/latex/macroswap/Makefile
new file mode 100644
index 00000000000..a2665fe38a5
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/macroswap/Makefile
@@ -0,0 +1,20 @@
+all:	clean macroswap.pdf
+
+clean:
+	rm -f *.log *.bbl *.blg *.dvi *.glo *.idx *.ilg *.ind *.sty *.aux *.gls *.zip *~
+
+dist:	clean
+	cd .. && zip -r macroswap/macroswap.zip macroswap/
+
+macroswap.sty : macroswap.ins macroswap.dtx
+	latex macroswap.ins
+
+macroswap.pdf : macroswap.sty macroswap.glo macroswap.ind
+	pdflatex macroswap.dtx
+
+# Glossary contains the changelist(?)
+macroswap.glo : macroswap.dtx
+	pdflatex macroswap.dtx && makeindex -s gglo.ist -o macroswap.gls macroswap.glo
+
+macroswap.ind : macroswap.idx
+	makeindex -s gind.ist -o macroswap.ind macroswap.idx
diff --git a/Master/texmf-dist/doc/latex/macroswap/README b/Master/texmf-dist/doc/latex/macroswap/README
new file mode 100644
index 00000000000..be4f550bae0
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/macroswap/README
@@ -0,0 +1,20 @@
+Copyright (C) 2013 by Robert J Lee
+
+This file may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either
+version 1.2 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.2 or later is part of all distributions of
+LaTeX version 1999/12/01 or later.
+
+
+This archive provides the macroswap package, providing simple utility
+methods to swap the meaning (token expansion) of two macros by name.
+
+
+
+This package uses the standard TeX ins+dtx install mechanism, althogh
+a UNIX Makefile is also provided for convenience to generate all files.
\ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/macroswap/macroswap.pdf b/Master/texmf-dist/doc/latex/macroswap/macroswap.pdf
new file mode 100644
index 00000000000..304741e95f1
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/macroswap/macroswap.pdf
diff --git a/Master/texmf-dist/source/latex/macroswap/macroswap.dtx b/Master/texmf-dist/source/latex/macroswap/macroswap.dtx
new file mode 100644
index 00000000000..c0fd61c4db1
--- /dev/null
+++ b/Master/texmf-dist/source/latex/macroswap/macroswap.dtx
@@ -0,0 +1,214 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2013 by Robert J Lee
+%
+% This file may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either
+% version 1.2 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.2 or later is part of all distributions of
+% LaTeX version 1999/12/01 or later.
+%
+% \fi
+%
+% \iffalse
+% <package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+% <package>\ProvidesPackage{macroswap}
+% <package>   [2013/09/16 v1.0 dtx macro swapper]
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{macroswap}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+  \DocInput{macroswap.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \CharacterTable
+%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+%   Digits        \0\1\2\3\4\5\6\7\8\9
+%   Exclamation   \!     Double quote  \"     Hash (number) \#
+%   Dollar        \$     Percent       \%     Ampersand     \&
+%   Acute accent  \'     Left paren    \(     Right paren   \)
+%   Asterisk      \*     Plus          \+     Comma         \,
+%   Minus         \-     Point         \.     Solidus       \/
+%   Colon         \:     Semicolon     \;     Less than     \<
+%   Equals        \=     Greater than  \>     Question mark \?
+%   Commercial at \@     Left bracket  \[     Backslash     \\
+%   Right bracket \]     Circumflex    \^     Underscore    \_
+%   Grave accent  \`     Left brace    \{     Vertical bar  \|
+%   Right brace   \}     Tilde         \~}
+%
+% \CheckSum{54}
+%
+% \changes{v1.0}{2013/09/18}{Initial version}
+%
+% \GetFileInfo{macroswap.sty}
+%
+% \DoNotIndex{\let, \edef, \xdef, \relax, \newcommand}
+% \DoNotIndex{\csname, \endcsname}
+% \DoNotIndex{\makeatletter, \makeatother}
+%
+% \title{The Macroswap Package\thanks{This document corresponds to \textsf{Macroswap}~\fileversion, dated \filedate.}}
+% \author{Robert J Lee \\ latex@rjlee.homelinux.org}
+%
+% \maketitle
+%
+% \begin{abstract}
+%
+% This package provides macros to allow the user to redefine a pair of
+% macros so that the token lists they expand to will be swapped.
+%
+% \end{abstract}
+%
+% \section{Introduction}
+%
+% This package was written to allaw a simple, readable syntax for
+% swapping the values within macros, used as program variables.
+%
+%
+% \section*{Usage}
+%
+% \DescribeMacro{\macroswap}
+%
+% The |\macroswap| macro allows you to temporarily swap two macro
+% definitions; for example:
+%
+% \begin{verbatim}
+% \newcommand{\myfirst}{1}
+% \newcommand{\myend}{2}
+% \begingroup
+%  \macroswap{myfirst}{myend}
+%  \myfirst\myend % prints ``21''
+% \endgroup
+% \myfirst\myend % prints ``12'' (swapped defininions were local)
+% \end{verbatim}
+%
+% This local swap is often unwanted, and can use up TeX's stack memory.
+% So you may prefer the global version:
+%
+% \DescribeMacro{\gmacroswap}
+%
+% The |\gmacroswap| macro allows you to globally swap two macro
+% definitions; for example:
+%
+% \begin{verbatim}
+% \newcommand{\myfirst}{1}
+% \newcommand{\myend}{2}
+% \begingroup
+%  \gmacroswap{myfirst}{myend}
+%  \myfirst\myend % prints ``21''
+% \endgroup
+% \myfirst\myend % prints ``21'' (swapped defininions are global)
+% \end{verbatim}
+%
+% \section*{Usage with arrayjobx}
+%
+% To globally swap two elements of an array declared with the |arrayjobx|
+% package, you need to arrange to swap the macros used by that
+% package. This is not part of the public interface and may change at
+% any time; unfortunately, it does not seem possible to do this with
+% only the public interface, especially if you do not want to expand
+% the tokens in the array.
+%
+% Assuming arrayjobx version~1.04~(labelled ``05/03/2010''), it is
+% only necessary to swap the values of the underlying macros using the
+% following syntax:
+%
+% \begin{verbatim}
+% \newarray{arr}
+% \readarray{arr}{A&C&B}
+% \gmacroswap{arr2\string~}{arr3\string~}
+% \arr(1)\par % prints ``A''
+% \arr(2)\par % prints ``B''
+% \arr(3)\par % prints ``C''
+% \end{verbatim}
+% 
+%
+% \section*{Implementation}
+%\StopEventually{\PrintChanges \pagebreak[4] \PrintIndex}
+%
+% First we make the @ symbol a letter so wo can use it internally
+%    \begin{macrocode}
+\makeatletter
+%    \end{macrocode}
+%
+% \begin{macro}{\gmacroswap}
+% given the name of two macros, swap their definitions.
+% Produces no output.
+% This version is global.
+%    \begin{macrocode}
+\newcommand{\gmacroswap}[2]{%
+%    \end{macrocode}
+% NB: we don't use ifcsname, because there's no guarantee that |#1| or
+% |#2| will be a single token
+% |macro@swap@left| and |macro@swap@right| are the contents of the
+% passed-in macro names. The |edef| would normally fully expand its
+% parameter but the |csexpandonce| prevents the full expansion and
+% returns only the token list that we want.
+%    \begin{macrocode}
+  \edef\macro@swap@left{\csexpandonce{#1}}%
+  \edef\macro@swap@right{\csexpandonce{#2}}%
+%    \end{macrocode}
+% Having taken a copy of the passed-in macro, we then reassign it to
+% the values in our tokens, which we get using |expandonce| to strip
+% off our temporary macro names. Again, |xdef| would normally expand
+% its macros as well as being a global assignment; however, the
+% |expandonce| prevents the full expansion.
+%
+% |expandafter| is used to evaluate the |csname|\dots|\endcsname|
+% become the |xdef|, as |xdef| will only redefine its first parameter.
+%    \begin{macrocode}
+  \expandafter\xdef\csname#2\endcsname{\expandonce{\macro@swap@left}}%
+  \expandafter\xdef\csname#1\endcsname{\expandonce{\macro@swap@right}}%
+%    \end{macrocode}
+%
+% Finally, we throw away our temporary macros:
+%    \begin{macrocode}
+  \let\macroswap@left\relax%
+  \let\macroswap@right\relax%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\macroswap}
+% given the name of two macros, swap their definitions.
+% Produces no output.
+% This version is local.
+%    \begin{macrocode}
+\newcommand{\macroswap}[2]{%
+%    \end{macrocode}
+% NB: we don't use ifcsname, because there's no guarantee that |#1| or |#2| will be a single token
+%    \begin{macrocode}
+  \edef\macro@swap@left{\csexpandonce{#1}}%
+  \edef\macro@swap@right{\csexpandonce{#2}}%
+%    \end{macrocode}
+% The only difference here is the use of |edef| instead of |xdef|,
+% which expands its second argument and overwrites its first argument
+% locally, so the original values will be restored at the end of the
+% current group or environment.
+%    \begin{macrocode}
+  \expandafter\edef\csname#2\endcsname{\expandonce{\macro@swap@left}}%
+  \expandafter\edef\csname#1\endcsname{\expandonce{\macro@swap@right}}%
+  \let\macroswap@left\relax%
+  \let\macroswap@right\relax%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% Leave @ as another character
+%    \begin{macrocode}
+\makeatother
+%    \end{macrocode}
+%
+% That is all
+% \Finale
+\endinput
diff --git a/Master/texmf-dist/source/latex/macroswap/macroswap.ins b/Master/texmf-dist/source/latex/macroswap/macroswap.ins
new file mode 100644
index 00000000000..3e8915e1a81
--- /dev/null
+++ b/Master/texmf-dist/source/latex/macroswap/macroswap.ins
@@ -0,0 +1,53 @@
+%%
+%% Copyright (C) 2013 by Robert J Lee
+%%
+%% This file may be distributed and/or modified under the
+%% conditions of the LaTeX Project Public License, either
+%% version 1.2 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.2 or later is part of all distributions of
+%% LaTeX version 1999/12/01 or later.
+%
+\input docstrip.tex
+\keepsilent
+\usedir{tex/latex/macroswap}
+\preamble
+
+This is a generated file.
+
+Copyright (C) 2013 by Robert J Lee
+
+This file may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either
+version 1.2 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.2 or later is part of all distributions of
+LaTeX version 1999/12/01 or later.
+
+\endpreamble
+
+\generate{\file{macroswap.sty}{\from{macroswap.dtx}{package}}}
+
+\obeyspaces
+
+\Msg{****************************************************}
+\Msg{*                                                  *}
+\Msg{* To finish the installation you have to move the  *}
+\Msg{* following file into a directory searched by TeX: *}
+\Msg{*                                                  *}
+\Msg{* macroswap.sty                                    *}
+\Msg{*                                                  *}
+\Msg{* To produce the documentation run the file        *}
+\Msg{* macroswap.dtx through LaTeX.                     *}
+\Msg{*                                                  *}
+\Msg{* Happy TeXing!                                    *}
+\Msg{*                                                  *}
+\Msg{****************************************************}
+
+\endbatchfile
diff --git a/Master/texmf-dist/tex/latex/macroswap/macroswap.sty b/Master/texmf-dist/tex/latex/macroswap/macroswap.sty
new file mode 100644
index 00000000000..6d719cde5a0
--- /dev/null
+++ b/Master/texmf-dist/tex/latex/macroswap/macroswap.sty
@@ -0,0 +1,43 @@
+%%
+%% This is file `macroswap.sty',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% macroswap.dtx  (with options: `package')
+%% 
+%% This is a generated file.
+%% 
+%% Copyright (C) 2013 by Robert J Lee
+%% 
+%% This file may be distributed and/or modified under the
+%% conditions of the LaTeX Project Public License, either
+%% version 1.2 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.2 or later is part of all distributions of
+%% LaTeX version 1999/12/01 or later.
+%% 
+\makeatletter
+\newcommand{\gmacroswap}[2]{%
+  \edef\macro@swap@left{\csexpandonce{#1}}%
+  \edef\macro@swap@right{\csexpandonce{#2}}%
+  \expandafter\xdef\csname#2\endcsname{\expandonce{\macro@swap@left}}%
+  \expandafter\xdef\csname#1\endcsname{\expandonce{\macro@swap@right}}%
+  \let\macroswap@left\relax%
+  \let\macroswap@right\relax%
+}
+\newcommand{\macroswap}[2]{%
+  \edef\macro@swap@left{\csexpandonce{#1}}%
+  \edef\macro@swap@right{\csexpandonce{#2}}%
+  \expandafter\edef\csname#2\endcsname{\expandonce{\macro@swap@left}}%
+  \expandafter\edef\csname#1\endcsname{\expandonce{\macro@swap@right}}%
+  \let\macroswap@left\relax%
+  \let\macroswap@right\relax%
+}
+\makeatother
+\endinput
+%%
+%% End of file `macroswap.sty'.
diff --git a/Master/tlpkg/bin/tlpkg-ctan-check b/Master/tlpkg/bin/tlpkg-ctan-check
index eea5cf4decf..18ad50a7c2a 100755
--- a/Master/tlpkg/bin/tlpkg-ctan-check
+++ b/Master/tlpkg/bin/tlpkg-ctan-check
@@ -288,7 +288,7 @@ my @TLP_working = qw(
     luamplib luaotfload
     luasseq luatexbase luatexja luatexko luatextra luaxml
     lxfonts ly1
-  m-tx macros2e mafr magaz mailing mailmerge
+  m-tx macros2e macroswap mafr magaz mailing mailmerge
     makebarcode makebox makecell makecirc makecmds makedtx makeglos makeplot
     makeshape mandi manuscript margbib
     marginfix marginnote marvosym
diff --git a/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc b/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc
index 1747409892f..98f1b6e17d8 100644
--- a/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc
+++ b/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc
@@ -455,6 +455,7 @@ depend ltxindex
 depend ltxkeys
 depend ltxnew
 depend ltxtools
+depend macroswap
 depend magaz
 depend mailing
 depend mailmerge
diff --git a/Master/tlpkg/tlpsrc/macroswap.tlpsrc b/Master/tlpkg/tlpsrc/macroswap.tlpsrc
new file mode 100644
index 00000000000..e69de29bb2d
--- /dev/null
+++ b/Master/tlpkg/tlpsrc/macroswap.tlpsrc