diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/toolbox')
| -rw-r--r-- | Master/texmf-dist/doc/latex/toolbox/toolbox.tex | 20 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/toolbox/toolbox.txt | 787 |
2 files changed, 807 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/toolbox/toolbox.tex b/Master/texmf-dist/doc/latex/toolbox/toolbox.tex new file mode 100644 index 00000000000..b55e64f6009 --- /dev/null +++ b/Master/texmf-dist/doc/latex/toolbox/toolbox.tex @@ -0,0 +1,20 @@ +\documentclass{ltxdoc} +\OnlyDescription%% Comment this out, or +%%\AlsoImplementation%% uncomment this line, if you want to see the source. + +%% If you want an index, uncomment one of the following lines. +%% After running latex a first time, you have to use +%% makeindex -s gind.ist toolbox +%% Then run latex again. +%%\CodelineIndex% comment this out if you want an index referring to codelines +%%\PageIndex% comment this out if you want an index referring to pages +%%\OldMakeindex% uncomment this line, if your MakeIndex is pre-v2.9 + +\setlength\hfuzz{15pt} +\hbadness=7000 +\begin{document} +\DocInput{toolbox.dtx} +\end{document} +\endinput +%% +%% End of file `toolbox.tex'. diff --git a/Master/texmf-dist/doc/latex/toolbox/toolbox.txt b/Master/texmf-dist/doc/latex/toolbox/toolbox.txt new file mode 100644 index 00000000000..cb0b08f9e74 --- /dev/null +++ b/Master/texmf-dist/doc/latex/toolbox/toolbox.txt @@ -0,0 +1,787 @@ + +%%# +%%# Author: +%%# +%%# M. V\"ath vaeth@mathematik.uni-wuerzburg.de +%%# +%%# The author thanks +%%# David Kastrup <David.Kastrup@neuroinformatik.ruhr-uni-bochum.de> +%%# + +%%############################################################################# +%%# +%%# The TeX programmer's toolbox; enhanced version. +%%# This (La)TeX package provides some macros which are convenient for +%%# writing indices, glossaries, or other macros. +%%# It contains macros which support +%%# +%%# - implicit macros - a useful supplement to \index or varindex for +%%# writing glossaries or indices +%%# - fancy optional arguments +%%# - loops over tokenlists and itemlists +%%# - searching, splitting, and replacing +%%# - controlled expansion +%%# - redefinition of macros +%%# - concatenated macro names +%%# +%%############################################################################# + +%%# +%%# This package was tested with plain TeX, LaTeX 2.09, and LaTeX 2e, +%%# and it should actually run with all TeX formats. +%%# + + +%%# To use toolbox, you have to put `toolbox.sty' in a path where TeX looks +%%# for its input files. The TeX documents using toolbox need the +%%# following modifications in their header: +%%# +%%# a) If you use LaTeX2.09, use toolbox as a style option, e.g. +%%# \documentstyle[toolbox]{article} +%%# or +%%# \documentstyle[toolbox,12pt]{article} +%%# b) If you use LaTeX2e, put in the preamble the command +%%# \usepackage{toolbox} +%%# c) If you use some other (non-LaTeX) format, you will probably have to +%%# insert a line like +%%# \catcode`\@=11\input toolbox.sty\catcode`\@=12\relax +%%# +%%# The only LaTeX-specific commands used in `toolbox.sty' are: +%%# +%%# \newcommand (only in the form \newcommand{\command}{} to ensure that +%%# \command was not defined before) +%%# \ProvidesPackage +%%# \typeout +%%# +%%# The above commands are used only if they are defined. +%%# + +%%# +%%# Description of the provided macros: +%%# + +%%# General remark: Many macros could appear in several sections. +%%# For example, \toolboxMakeDef and \toolboxSourround might be considered +%%# as macros which support redefinitions of macros. However, we put them +%%# in different sections which perhaps explain better their nature. + +%%# +%%# Implicit macro definitions +%%# -------------------------- + +%%# What we mean by implicit macro definitions is probably best explained by +%%# the following examples which show the intended usage: +%%# +%%# (In the following examples, we always refer to the \index command. Note +%%# that it may be more convenient to use for indices the varindex package in +%%# addition - the documentation of varindex (release 2.3 or newer) gives +%%# additional hints and examples how these two (essentially independent) +%%# approaches can be combined in practice). +%%# +%%# Assume that you want to write an index for a book which has rather +%%# long and complicated \index entries. The first idea that one might have in +%%# this connection is to put the various \index commands at the beginning of +%%# the document into several macros (one for each \index entry), and to use +%%# just these macros in the main text. For example, one might want to write +%%# near the beginning of the document commands like +%%# \newcommand{\Start}{\index{finish or end}} +%%# \newcommand{\End}{\index{finish or end}} +%%# and then to use in the main text \Start and \End whenever a reference +%%# in the corresponding index to the current place is desired. +%%# However, this has two major disadvantages: +%%# 1. Unless you are very disciplinary with your macro names, it is easy to +%%# forget that \End writes an index entry. So the \End in the main text +%%# might be very confusing. +%%# 2. You cannot choose short and intuitive macro names for common phrases, +%%# because they are usually already reserved by TeX, LaTeX, or some +%%# packages. +%%# +%%# To avoid these problems, one may be very disciplinary and call the +%%# involved macros systematically e.g. \GlossaryStart \GlossaryEnd etc. +%%# However, this produces terrible long and unreadable macro names in the +%%# main text. +%%# +%%# The implicit macro definitions of "toolbox" provide a more convenient +%%# solution. The idea is that you do not use the corresponding macros directly +%%# but only implicitly by a call of other macros where your "macro name" is +%%# just an argument. +%%# Moreover, "toolbox" assists you in writing the corresponding definitions. +%%# For example, if you know that you want a set of macros which all expand +%%# into something of the form \index{...}, you can give a ``mask'' which +%%# contains this form, and you only have to fill in the changing content +%%# (similarly as for usual TeX macros with arguments, but the level of +%%# abstraction is one step higher). +%%# For the above task, you might use the command: +%%# +%%# \toolboxMakeDef{Glossary}{\index{#1}} +%%# +%%# The argument `Glossary' serves to distinguish independent definitions +%%# (this will become clear later). Its effect visible now is that it +%%# determines the name of the following macros which you can use after +%%# the above call: +%%# +%%# \NewGlossary{start-1}{start} +%%# \NewGlossary{start-2}{start or beginning} +%%# \NewGlossary{end}{finish or end} +%%# +%%# These command are now similar to the \newcommand definitions explained +%%# above. However, there is no name collision with the TeX-internal command +%%# \end. Of course, this means that you cannot just write \end in the main +%%# text to get the desired index entry. Instead, you have to write the more +%%# intuitive commands +%%# +%%# \Glossary{start-1} +%%# \Glossary{start-2} +%%# \Glossary{end} +%%# +%%# (again, the name \Glossary stems from our first call of \toolboxMakeDef). +%%# Note that e.g. \Glossary{start-1} expands not only to `start' but +%%# actually to \index{start} (because of our first call of \toolboxMakeDef). +%%# Note also that you can use symbols like - or numbers which are usually +%%# not allowed in TeX macro names. +%%# +%%# Of course, similarly as for \newcommand, you can also do other things with +%%# the macros. For example, +%%# +%%# \LetGlossary\tempname{end} +%%# \NewGlossary*{finish}\tempname +%%# +%%# will first define \tempname to expand to the same text as \Glossary{end}, +%%# and then defines a new entry \Glossary{finish} to expand to the same text +%%# as \tempname. Hence, the above new lines make the calls \Glossary{end} and +%%# \Glossary{finish} equivalent. +%%# +%%# At the end of your list of \NewGlossary commands, you might want to put +%%# +%%# \toolboxFreeDef*{Glossary} +%%# +%%# The purpose of this command is that \NewGlossary cannot be used anymore +%%# (unless, of course, you define it again). So you cannot unintentionally +%%# add new entries to your glossary list (but you still can use \Glossary{...} +%%# to reference to the already produced entries). +%%# Moreover, the above command frees some memory which was needed for +%%# \NewGlossary to work. +%%# +%%# If you additionally want to free the memory used by \Glossary, you can use +%%# +%%# \toolboxFreeDef{Glossary} +%%# +%%# (without the `*'). This may be necessary, if you want to call again e.g. +%%# +%%# \toolboxMakeDef{Glossary}{\emph{#1}\index{#1}} +%%# +%%# (if you have not freed the memory for \Glossary before this repeated call, +%%# TeX will complain that \Glossary is already defined). +%%# +%%# Of course, it is possible to call \toolboxMakeDef with several different +%%# names, for example, for \Glossary, \SymbolList etc. Another application +%%# might be to use a different command to mark e.g.\ the main occurrence of +%%# some index entry or to output additionally the entry into the running text. +%%# We do this in the following example which simultaneously +%%# demonstrates that the names can also be constructed in another way: +%%# +%%# \toolboxMakeDef[Ind]{}{\index{#1}} +%%# \toolboxMakeDef[Ind]{Main}{\index{#1|textbf}} +%%# \toolboxMakeDef{OutInd}{#1} +%%# +%%# \IndNew{A}{A is a letter} +%%# \IndNewMain{A}{A is a letter} +%%# \NewOutInd{A}{\textbf{The letter A}\Ind{A}} +%%# +%%# After the above commands, you can use \Ind{A}, \IndMain{A}, and +%%# \OutInd{A} to produce the corresponding \index entry, the "main" \index +%%# entry (with a boldface page number), and the text \textbf{The letter A} +%%# with an additional entry into the index, respectively. +%%# Of course, it might usually be more convenient to define the \Ind and +%%# \IndMain" entries simultaneously, e.g. as follows +%%# +%%# \toolboxMakeDef[Ind]{}{#1} +%%# \toolboxMakeDef[Ind]{Main}{#1} +%%# \newcommand{\NewStandardInd}[2]{% +%%# \IndNew{#1}{\index{#2}}% +%%# \IndNewMain{#1}{\index{#2|textbf}}} +%%# +%%# \NewStandardInd{A}{A is a letter} +%%# +%%# This approach has the additional advantage that you can define exceptional +%%# cases "by hand" (e.g. if you want that for certain "main" index +%%# entries the page number is printed with "\textsl" instead of "\textbf"). + +%%# Since the motivation for implicit definitions now is hopefully clear, +%%# let us now describe in detail which commands are provided by "toolbox" +%%# for this purpose. +%%# As explained in the example, the main generic macro provided to this +%%# purpose is \toolboxMakeDef. Its call syntax is as follows: +%%# +%%# \toolboxMakeDef[Prefix]{Name}{ReplacementMask} +%%# +%%# (the argument [Prefix] is optional and by default empty). +%%# The above command generates new macros +%%# +%%# \PrefixNewName +%%# \PrefixRenewName +%%# \PrefixProvideName +%%# \PrefixDefName +%%# \PrefixLetName +%%# \PrefixName +%%# +%%# which in turn can be called as follows +%%# +%%# \PrefixNewName{something}{RememberText} +%%# \PrefixRenewName{something}{RememberText} +%%# \PrefixProvideName{something}{RememberText} +%%# \PrefixDefName{something}{RememberText} +%%# \PrefixNewName*{something}{\SomeMacro} +%%# \PrefixRenewName*{something}{\SomeMacro} +%%# \PrefixProvideName*{something}{\SomeMacro} +%%# \PrefixDefName*{something}{\SomeMacro} +%%# \PrefixLetName{\SomeMacro}{something} +%%# \PrefixName{something} +%%# \PrefixName*{something} +%%# +%%# These calls are in a sense similar to the respective commands +%%# +%%# \newcommand{\something}{RememberText} +%%# \renewcommand{\something}{RememberText} +%%# \providecommand{\something}{RememberText} +%%# \def\something{RememberText} +%%# \newcommand{\something}{}\let\something\SomeMacro +%%# \renewcommand{\something}{}\let\something\SomeMacro +%%# \@ifundefined\something{\let\something\SomeMacro}{} +%%# \let\something\SomeMacro +%%# \let\SomeMacro{\something} +%%# \something +%%# \something (but without error if \something is undefined). +%%# +%%# with the differences already pointed out before: +%%# 1. The macro name actually used is not \something. Instead, it is a name +%%# which does not conflict with any existing macro (except one +%%# generated previously by another \PrefixNewName, but in this case a +%%# descriptive error is reported). For this reason, it is not possible to +%%# use this macro directly but only indirectly by the call +%%# \PrefixName{something} (or with \PrefixLetName). +%%# 2. The replacement text is not `RememberText' but determined by +%%# ReplacementMask where every occurrence of #1 in ReplacementMask is +%%# replaced by RememberText (recall the examples). If you want to have the +%%# plain RememberText, use {#1} as ReplacementMask. +%%# +%%# Since toolbox 4.2 there is another slight difference: The symbol '#' +%%# is treated as usual and not as in a macro definition. +%%# +%%# \toolboxMakeDef gives an error message if the commands +%%# \Prefix... are already defined. If you intentionally want to +%%# change a previous definition, you have to call the command +%%# +%%# \toolboxFreeDef[Prefix]{Name} +%%# +%%# before. The latter not only lets all of the macros \Prefix... be +%%# \undefined, but also frees all other memory internally used by the +%%# corresponding call of \toolboxMakeDef +%%# (note, however, that the above command does not free the +%%# memory allocated before by calls of \PrefixNew... - to free the latter, +%%# you have to call subsequently e.g. +%%# +%%# \PrefixNewName*{...}{\undefined} +%%# +%%% before). There is also the command +%%# +%%# \toolboxFreeDef*[Prefix]{Name} +%%# +%%# which acts similarly as \toolboxFreeDef but which does not undefine the +%%# two macros \PrefixName and \PrefixLetName. +%%# + +%%# +%%# Fancy optional argument parsing +%%# ------------------------------- + +%%# This section contains macros which are convenient if you e.g. write a +%%# package that contains macros which contain a lot of optional arguments +%%# and flags (like "*"). +%%# Typically, to read such an optional argument or flag, you save +%%# the next token with \futurelet and then call a macro which decides what to +%%# do with the token read. Thus, a typical use of \futurelet looks like +%%# +%%# \def\MacroWithOptionalFlag{\futurelet\tokread\myscan} +%%# +%%# which will define \tokread to be the token *following* the macro +%%# \MacroWithOptionalFlag in the token stream and then execute \myscan. +%%# In this context, it is not very convenient that you are *forced* +%%# to define a macro \myscan: It could be more convenient if you could just +%%# write the *content* of \tokread (in braces) into the above definition. +%%# You can indeed do this if you replace \futurelet by \toolboxFuturelet: +%%# +%%# \toolboxFuturelet\token{argument} +%%# +%%# The call \toolboxFuturelet\token{\command} has precisely the same effect as +%%# \futurelet\token\command. The advantage of \toolboxFuturelet is that +%%# instead of a single \command one may use also a sequence of commands. + +%%# Let us consider \MacroWithOptionalFlag as above. Assume that the user +%%# has called this macro in the form "\MacroWithOptionalFlag*" where the +%%# "*" is a flag which should cause your macro to do something slightly +%%# different. On some place in your macro definition you will have recognized +%%# (e.g. with \futurelet or \toolboxFuturelet) that a "*" is following +%%# in the calling sequence. So you now want to execute your action +%%# (whatever \MacroWithOptionalFlag is supposed to do). +%%# However, if you do not take special care, after this action, TeX will +%%# print a "*", because this is the next token on the token stream: \futurelet +%%# does not delete any tokens. So you have to "gobble" this token away. +%%# A rude way to do this is by using the macro \gobblenext as the last token +%%# in you macro which can be defined by +%%# \begin{verbatim} +%%# \def\gobblenext#1{}\end{verbatim} +%%# However, this has two major drawbacks: +%%# +%%# 1. This works for "*", but not for "{" or space tokens. +%%# For space tokens the situation is even worse, since TeX eats spaces +%%# around arguments, so sometimes space tokens might unexpectedly +%%# disappear. +%%# 2. It is not possible in this way to read another argument following +%%# the "*": Recall that \gobblenext must be the *last* token in your +%%# macro expansion, i.e. you have "lost control" after this call. +%%# +%%# The solution to these problems is instead of calling \gobblenext to use +%%# \toolboxGobbleNext as the last command in your call: +%%# You can pass it an argument which describes the action that +%%# you want to do *after* gobbling the next token ("*" in the above example) +%%# from the token stream. Thus +%%# +%%# \toolboxGobbleNext{cmd} +%%# +%%# erases the token following that command from the token stream and +%%# then executes cmd. This is similar to +%%# \def\toolboxGobbleNext#1#2{#1} +%%# with the difference that #2 is considered as a token and that no spaces +%%# are eaten. +%%# The effect is that e.g. the call +%%# +%%# Example: +%%# \toolboxGobbleNext{\foo}{{arg} +%%# is the same as \foo{arg} (the brace "{" is eaten in this example). + +%%# As described earlier, the commands "\futurelet" or "\toolboxFuturelet" can +%%# be used to check for optional flags. Frequently you will only want +%%# to test for one particular flag and decide the next action on this flag. +%%# Of course, you can test the token found with \ifx...\f", but this has the +%%# disadvantage that some tokens (e.g. \fi) follow your action, which might +%%# be bad (recall that e.g. \toolboxGobbleNext must be the last command of +%%# your action, i.e. it would in the above examples not gobble the "*" but +%%# the "\fi" which is probably not what you want). +%%# The simplest solution is to use the command \toolboxIfNextToken which +%%# already has the test included. For example, to test for an optional "[", +%%# you can simply write +%%# +%%# \def\MacroWithOptionalBrace{\toolboxIfNextToken[{\yes}{\no}} +%%# +%%# and then the call "\MacroWithOptionalBrace[...]" will expand to "\yes[...]" +%%# while "\MacroWithOptionalBrace x" will expand to "\no x" +%%# (note that the brace is not gobbled - if you want the latter, +%%# use "\toolboxIfNextGobbling" described below). + +%%# More precisely, the calling syntax of "\toolboxIfNextToken" is +%%# +%%# \toolboxIfNextToken{token}{IfPart}{ElsePart} +%%# +%%# The semantic is the following: +%%# If the token following this command is `token', then IfPart is executed, +%%# otherwise ElsePart. It is explicitly admissible that `token' is a space. +%%# To support further tests, \toolboxToken is \let to the token which follows +%%# the command. \toolboxToken is only a temporary token, i.e. +%%# it may also be modified by other commands of this package; in particular, +%%# you may also freely to modify \toolboxToken. +%%# The token \toolboxSpaceToken which is described later may be handy +%%# in connection with this command. +%%# +%%# In contrast to similar LaTeX2e macros much care has been taken +%%# that spaces are not eaten. This solves the following problem: +%%# +%%# Assume that you want to write a macro which should have the calling syntax +%%# "\mymacro{arg1}" or "\mymacro{arg1}[arg2]". You will probably implement +%%# \mymacro to read the first argument and then to look whether the next +%%# token is a "[". If you use the LaTeX2e macro to test for "[", +%%# then all spaces until the next non-space token would be gobbled which means +%%# that if you would use the LaTeX2e macros for the test, then the call +%%# "\mymacro{arg1} Text" would behave like "\mymacro{arg1}Text", +%%# i.e. the space is `mysteriously' lost. With the "toolbox" macros this +%%# does not happen. The `disadvantage' is that "\mymacro{arg1} [arg2]" +%%# is not the same as "\mymacro{arg1}[arg2]" (which is reasonable IMHO). +%%# +%%# Example: +%%# +%%# \def\mycmd#1{\toolboxIfNextToken[{\ParseOpt{#1}}{\NoOpt{#1}}} +%%# \def\ParseOpt#1[#2]{\OptAtEnd{#1}{#2}} +%%# +%%# After the above definition, \mycmd{arg} executes \NoOpt{arg} while +%%# \mycmd{arg}[optional] executes \OptAtEnd{arg}{optional} +%%# We point out once more that in the first call a space following +%%# \mycmd{arg} does not vanish (as would be the case if the LaTeX 2e macros +%%# would have been used). + +%%# If \toolboxIfNextToken has found the required token, it does *not* +%%# gobble that token from the token stream. Of course, you can do this by +%%# yourself using the earlier described macro \toolboxGobbleNext. However, +%%# it is simpler to use +%%# +%%# \toolboxIfNextGobbling{token}{IfPart}{ElsePart} +%%# +%%# This command is analogous to \toolboxIfNextToken with the difference that +%%# in the case that the next token is the desired token, it is gobbled before +%%# IfPart is executed. +%%# +%%# Example: +%%# +%%# \def\myloop{\toolboxIfNextGobbling*\toolboxTokenLoop\toolboxLoop} +%%# +%%# This makes \myloop*... behave like \toolboxTokenLoop, and +%%# \myloop... (without *) behave like \toolboxLoop. + +%%# The following macro is one which you may want to use in connection with +%%# LaTeX 2e optional arguments: +%%# +%%# \toolboxIfEmpty{arg}{IfPart}{ElsePart} +%%# +%%# The argument is not expand; it is only used to decide whether the +%%# {IfPart} or the {ElsePart} will be expanded. +%%# For further tests there are more involved macros: +%%# +%%# \toolboxIfx{arg}\macro{IfPart}{ElsePart} +%%# +%%# This tests via \ifx whether \def\Macro{arg} would give the definition +%%# of \macro. +%%# +%%# \toolboxIfX{arga}{argb}{IfPart}{ElsePart} +%%# +%%# This tests whether "arga" and "argb" are the same token sequences. +%%# If you want to avoid the \else and \fi commands to avoid certain side +%%# effects, you can use instead: +%%# +%%# \toolboxIfElse{ifcmd}{IfPart}{ElsePart} +%%# +%%# This is rather analogous to "ifcmd" IfPart \else ElsePart \fi +%%# but has everything in this line already eliminated from the tokenlist +%%# when IfPart resp. ElsePart are expanded. + +%%# +%%# Loops over tokenlists and itemlists +%%# ----------------------------------- + +%%# \toolboxLoop{items}{action} +%%# +%%# This calls iteratively "action{#1}", where #1 runs over each item in the +%%# argument items. Here, an item is either a token or a group braced by {...}. +%%# In the latter case, the braces are lost. Spaces in items are ignored +%%# (unless they are braced). It is admissible that \action is not a single +%%# macro but instead a sequence of tokens. +%%# Examples follow below. +%%# +%%# The counterintuitive order of arguments is explained by the fact that the +%%# typical usage is +%%# \expandafter\toolboxLoop\expandafter{\MacroExpandingToItems}{action} +%%# which for swapped order of arguments could hardly be written. + +%%# \toolboxLoop is not reentrant i.e. "action" may not expand +%%# to something which contains a call to \toolboxLoop. To enable such calls +%%# anyway, the command +%%# +%%# \toolboxLoopName{name}{items}{\action} +%%# +%%# is provided which is analogous to \toolboxLoop. This is also not reentrant, +%%# but in contrast to \toolboxLoop, calls with different `name' arguments can +%%# be used independently of each other, i.e. in the `action' part of a +%%# \toolboxLoop (or \toolboxLoopName) can be a call to \toolboxLoopName with +%%# a *different* `name'. +%%# In particular, using a counter in `name' one could easily implement +%%# even recursive calls. In this connection, it should be noted that +%%# `name' is expanded via \csname ... \endcsname, and so you may use +%%# constructs like \the\namecounter there. + +%%# \toolboxTokenLoop{tokens}{\action} +%%# +%%# This is similar to \toolboxLoop: The command \action\toolboxToken +%%# is executed iteratively where \toolboxToken runs over each token in tokens. +%%# The important difference is that \toolboxToken is a token (instead of an +%%# item). In particular, \toolboxToken runs through every single token +%%# including spaces and braces. +%%# The token \toolboxSpaceToken which is described later may be handy +%%# in connection with this command. +%%# +%%# Example: +%%# +%%# \toolboxTokenLoop{Some text}{\kern0.1em} +%%# +%%# is the similar to "\kern0.1em S\kern0.1em o\kern0.1em m...", i.e. you +%%# get wider spacing between the letters of "Some text" (I do not claim that +%%# this is typographically a good idea). +%%# +%%# Note that you do not have to take special care about the space. +%%# With \toolboxLoop, you would have to mask the space e.g. with +%%# +%%# \toolboxLoop{Some{ }text}{\kern0.1em} or +%%# \toolboxLoop{Some\toolboxSpace text}{\kern0.1em} +%%# +%%# In contrast, \toolboxTokenLoop would behave differently here: +%%# +%%# \toolboxTokenLoop{Some{ }text}{\kern0.1em} +%%# +%%# would produce \kern0.1em S...\kern0.1em{\kern0.1em <space>\kern0.1em}... +%%# because the braces are simply considered as tokens. + +%%# \toolboxTokenLoop is not reentrant. Analogously to \toolboxLoopName, +%%# independent versions can be generated by +%%# +%%# \toolboxTokenName{name}{tokens}{\action} + +%%# +%%# Controlled expansion +%%# -------------------- + +%%# There are some occasions when you want more control over the expansion. +%%# E.g. you might want to concatenate the contents of two macros to a +%%# further macro or you want to expand a macro by one level but no full +%%# expansion. Usually you can get this effects with \expandafter, but if +%%# you expand several concatenated tokens in this way you either have to +%%# write a lot of \expandafter's or you have to define subsidiary macros +%%# that help you to \expandafter certain parts of macros. The macros in +%%# this section allow you to do this in the most generic way that I could +%%# implement. + +%%# \toolboxDef\macrotodefine{argumentlist} +%%# +%%# This call is similar to +%%# \def\macrotodefine{argumentlist} +%%# with two important differences: +%%# +%%# For \toolboxDef, the argumentlist is expanded precisely by one level. +%%# argumentlist may not contain macros with parameters, and spaces on the +%%# highest level are ignored. If you want to force a space on a particular +%%# place, use the macro \toolboxSpace at this place +%%# (which is described later). Contrary to the usual \def, the symbol # is +%%# treated as a usual symbol. +%%# +%%# Example of usage: +%%# \toolboxDef\chain{\chain\toolboxSpace\after} +%%# This modifies the macro \chain such that a space and the content of the +%%# macro \after is appended at the end. + +%%# \toolboxAppend\macrotodefine{arglist} +%%# +%%# This is equivalent to \toolboxDef\macrotodefine{\macrotodefine arglist} +%%# + +%%# \toolboxSurround{ContentBefore}{ContentAfter}\macro +%%# +%%# This redefines \macro such that ContentBefore is put at the beginning +%%# and ContentAfter after the definition of \macro. So this is equivalent to +%%# \def\macro{ContentBefore * ContentAfter} +%%# where * is the old content of \macro. It is required that \macro is a +%%# usual macro without any arguments. If you want to patch more complicated +%%# macros, use the patch.doc package instead. +%%# The order of the arguments may appear strange, but it is convenient if +%%# ContentBefore or ContentAfter are macros which should be expanded with +%%# \expandafter. + +%%# There is some subsidiary macro used in the implementation of the above +%%# macros which might be useful also in some other situations: +%%# +%%# \toolboxTokDef{argumentlist}\macrotodefine +%%# +%%# This call is similar to +%%# \def\macrotodefine{argumentlist} +%%# with the difference that the symbol # is stored as such. +%%# The order of the arguments has been swapped in order to simplify the +%%# application of \expandafter to the argumentlist. + +%%# +%%# Searching, splitting, and replacing +%%# ---------------------------------- + +%%# \toolboxSplitAt{argument}{search}{\beforestring}{\afterstring} +%%# +%%# Here, \beforestring and \afterstring are arbitrary macro names, +%%# and search and argument are any sequences of tokens (which are in +%%# the following considered as `strings'). +%%# +%%# This call scans the string `argument' for the first occurrence of `search'. +%%# The macros \beforestring and \afterstring are defined correspondingly +%%# such that \beforestring expands to the part before the first occurrence, +%%# and \afterstring to the part following the first occurrence. +%%# If `search' does not occur in `argument', \beforestring is defined to +%%# `argument', and \afterstring is \let \undefined. +%%# +%%# If \beforestring or \afterstring had already been defined before the +%%# call, the previous definition is tacitly overridden. +%%# It is explicitly allowed that \beforestring and \afterstring are the +%%# same names. In this case, the result has the meaning of \afterstring. +%%# +%%# It is guaranteed that braces {...} are *not* lost in `argument'. +%%# However, `search' may not contain any braces, and `argument' may contain +%%# only matching pairs of braces. Moreover, occurrences of `search' within a +%%# pair of braces in `argument' are not recognized. +%%# +%%# (The order of the arguments has been chosen in order to simplify the +%%# use of \expandafter). +%%# +%%# There are some restrictions for the strings in search. For example, +%%# the symbol '#' is not allowed. +%%# +%%# In the above call, the arguments may not run over several paragraphs. +%%# If you want the latter, you have to use the alternative call +%%# +%%# \toolboxSplitAt*{argument}{search}{\beforestring}{\afterstring} +%%# +%%# Example of usage: +%%# +%%# \def\examplemacro#1{\toolboxSplitAt{#1}{@}\testme\testme +%%# \ifx\testme\undefined +%%# ... (do this when #1 contains no `@' token) +%%# \fi} +%%# + +%%# \toolboxMakeSplit{search}{command} +%%# +%%# If \toolboxSplitAt should be used several times with the same search +%%# string, it is much more effective to use the above call: This call +%%# defines a new macro \command (the name is determined by the second argument +%%# of \toolboxMakeSplit) which can be called in the form +%%# +%%# \command{argument}{\beforestring}{\afterstring} +%%# +%%# and which has the analogous meaning as \toolboxSplitAt (the argument +%%# {search} is implicitly fixed and taken from the call of +%%# \toolboxMakeSplit). +%%# It is explicitly admissible that the above macro \toolboxMakeSplit is +%%# used with an already existing command name. In this case, the previous +%%# definition of \command is tacitly overridden. +%%# +%%# The command created by \toolboxMakeSplit does not accept arguments which +%%# run over several paragraphs. If you want the latter, you have to create +%%# this command by the alternative call +%%# +%%# \toolboxMakeSplit*{search}{command} + +%%# +%%# The command +%%# \toolboxFreeSplit{command} +%%# frees the memory used by a previous \toolboxMakeSplit (and lets \command +%%# again be undefined). + +%%# The command +%%# \toolboxReplace{search}{replace}\macro +%%# replaces in \macro all occurences of {search} by {replace}. +%%# The same matches are found as in \toolboxSplitAt. +%%# If you need to search for the same text several times, it is faster +%%# to use the command +%%# \toolboxReplaceSplit{replace}\SplitCmd\macro +%%# where \SplitCmd is a command previously generated with \toolboxMakeSplit* +%%# according to your search string. (You could also use \toolboxMakeSplit +%%# to generate \SplitCmd, but then \macro should not contain any \par's). + +%%# +%%# Redefinition of macros +%%# ---------------------- + +%%# \toolboxMakeHarmless{\macro} +%%# +%%# The above call redefines \macro such that it expands to an ASCII text +%%# containing the previous definition of \macro (i.e. the catcodes of \macro +%%# are changed). + +%%# \toolboxDropBrace\variable +%%# +%%# drops possible outer braces in \variable. More precisely, +%%# if \variable expands to {content}, then \variable is redefined to +%%# content (without braces). Otherwise, nothing happens. + +%%# +%%# \toolboxIf\comparison{DefinitionCommand}{\macro}... +%%# +%%# The above command allows conditional definitions. +%%# Here, {DefinitionCommand} is either \def, {\long\def}, \let, or some +%%# similar command like the LaTeX \newcommand. If the test +%%# \ifx\comparison\macro evaluates positive, then \macro is defined +%%# correspondingly. Otherwise, \macro is not changed. +%%# +%%# Examples: +%%# +%%# \toolboxIf\undefined\def\macro{....} +%%# \toolboxIf\undefined\let\macro... +%%# \toolboxIf\undefined{\long\def}\macro{....} +%%# \toolboxIf\undefined\newcommand{\macro}{....} +%%# +%%# are similar to \def\macro{...} resp. \let\macro... resp. +%%# \long\def\macro{...} resp. \newcommand{\macro}{...} with the difference +%%# that \macro is not changed if it was already defined. +%%# In this sense, \toolboxIf is a more flexible variant of \providecommand. +%%# + +%%# \toolboxNewiftrue{name} or \toolboxNewiffalse{name} +%%# +%%# If the command \ifname was already introduced with \newif, then +%%# nothing happens. Otherwise \ifname is introduced similarly to +%%# \newif\ifname and set to `true' respectively `false'. +%%# In contrast to the corresponding command in TeX or LaTeX 2.09, this macro +%%# is not \outer! + +%%# \toolboxNewifTrue{name} or \toolboxNewifFalse{name} +%%# +%%# are similar to \toolboxNewiftrue{name} and \toolboxNewiffalse{name}, +%%# respectively, with the difference that \ifname is set unconditionally +%%# to `true' respectively `false'. + +%%# +%%# Concatenated macro names +%%# ------------------------ + +%%# \toolboxLet\variable{macroname} +%%# +%%# The above command is analogous to \let\variable\macroname with the +%%# difference that macroname can also contain other tokens like numbers +%%# (it is obtained via \csname). Some converse to this command is +%%# +%%# \toolboxWithNr {number}\cmd{macro} +%%# +%%# which translates into \cmd\macronumber (here, `macro' and `number' +%%# are just concatenated and evaluated via \csname). +%%# Examples: +%%# \toolboxWithNr 1\let{name}\toolboxEmpty +%%# This is the same as \let\name1\toolboxEmpty +%%# (but such that \name1 is considered as a name, not as \name 1) +%%# \toolboxWithNr {10}\def{name}{Foo} +%%# This corresponds analogously to \def\name10{Foo}. +%%# \toolboxLet \mymacro{name\the\mycount} +%%# This is similar to \let\mymacro\namexx where xx is the content +%%# of the counter \mycount. + +%%# +%%# Various +%%# ------- + +%%# The following macros have equivalents in most formats (like LaTeX2e). +%%# However, we do not want to rely too much on these formats, so we provide +%%# our own definitions. +%%# The macro +%%# \toolboxEmpty +%%# expands to nothing (usually, this is the same as \empty). +%%# Similarly, the macro +%%# \toolboxSpace +%%# expands to a space symbol (usually, this is the same as \space). +%%# The token +%%# \toolboxSpaceToken +%%# is \let a space token (usually, this is the same as \@sptoken). +%%# This token is convenient in tests of tokens +%%# (because it is hard to get a space there which is not eaten by the TeX +%%# parser, although sometimes also constructions like +%%# \expandafter\ifx\toolboxSpace\token can be used). +%%# Also the macros +%%# \toolboxFirstOfTwo +%%# \toolboxSecondOfTwo +%%# are provided which read two arguments and return only the first +%%# respectively second argument (usually, this is the same as +%%# \@firstoftwo respectively \@secondoftwo). Similarly, +%%# \toolboxGobbleArg{argument} +%%# just reads its argument and expands to nothing. + +\endinput +%% +%% End of file `toolbox.txt'. |