1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
\documentclass[
use-a4-paper,
use-10pt-font,
final-version,
use-UK-English,
fancy-section-headings,
frame-section-numbers,
para-abstract-style,
input-config-file,
no-hyperref-messages,
wrapquote
]{amltxdoc}
\makeatletter
\hfuzz1pt
\makeindex
\usepackage{makeidx}
\subtitlefont{\bf\sf}
\useshortdoccmds
\begin{document}
\begin{frontmatter}
\title{The \texttt{\color{blue}storecmd} Package\titleref{t1}}
\titlenotes[t1]{%
The package is available at \url{\titleurltext}.
This user manual corresponds to version~0.0.2 of the package.
}
\subtitle{Define command and save its name in a container file or macro}
\titleurl{http://www.ctan.org/tex-archive/macros/latex/contrib/storecmd/}
\author{Ahmed Musa\Email{amusa22@gmail.com}\\Preston, Lancashire, UK}
\end{frontmatter}
\hrule height.5pt depth.5pt width\textwidth
\vskip 1ex plus 1pt minus 1pt
\begingroup
\hypersetup{linkcolor=blue}\tableofcontents
\endgroup
\hrule height.5pt depth.5pt width\textwidth
\docsection(sec:intro){Introduction}
This package provides macros for command definition that save the name of the command being defined in a file or a macro container. For ease of reference, we refer to macros for command definition as \quoted{master macros}, and the macro that stores the defined commands as the \quoted{container macro}. The file that stores the defined commands is the \quoted{container file}. In this package there are two categories of master macros for command definition: one category has a syntax similar to that of \tex's \hx{\def} while the other category has the syntax of \latex's \hx{\newcommand}. Only one master macro is available in the first category. Naturally, commands defined by the master macro of the first category can have their parameters delimited in the usual way. When the user uses one of the master macros for command definition from the second category (\ie, one of those that have a syntax similar to that of \hx{\newcommand}), some or all of the parameters of the defined command can be delimited, as desired by the command author. Normally, parameters of commands defined by \latex's \hx{\newcommand} can't be delimited.
The package can also be used as a debugging tool, or at least as a command location tool: namely, to store the names of defined commands and the sources in which they are defined. This can be realized by using the \fx{showsource} package option. However, this will track only the commands defined by the master macros of this package. It is safe to assign \hhx'{\newcommand, \renewcommand} to \ffx'{\newsavecmd, \renewsavecmd}, respectively. But, for rather obvious reasons, it is not advisable to simply replace the native \hhx'{\global,\long,\protected,\def,\gdef} by the master macros of this package\footnote{One reason for this is that, for example, you can't do \ftfx{\stcglobal\let\x\y} or \ftfx{\stcglobal\@tempswatrue} because \ftffx'{\stcprotected,\stcglobal} are tailor made for the commands \ftffx'{\defsavecmd, \newsavecmd, \renewsavecmd}.}.
\docsection{Motivation}
The package was written in response to a post on \ltshref{https://groups.google.com/forum/
#!topic/comp.text.tex/o14P2e83o4A}{comp.text.tex} for a macro that will define commands and also save the commands being defined in a file or a container macro, \eg, for spelling exceptions on editors that don't support \tex syntax.
\docsection{Package options}
The package options are described in \sref{tab:pkgoptions}.
\extrarowheight=2pt
\arrayrulecolor{yellow}
\begin{tabularx}{\linewidth}{|m{3cm}|m{2.5cm}|X|}
\caption{Package options\label{tab:pkgoptions}}\\\hline
\rowcolor{pink}
\bfseries Option&\bfseries Default&\bfseries Meaning\\\hline
\endfirsthead
\hline
\multicolumn{3}{|l|}{\emph{Continued from last page}}\\\hline
\bfseries Option&\bfseries Default&\bfseries Meaning\\\hline
\endhead
\multicolumn{3}{|r|}{\emph{Continued on next page}}\\\hline
\endfoot
\hline
\endlastfoot
\fxi{neversave} & \texttt{false} & Never save/store the new command name in the container file or container macro. The new commands will still be defined.\\\hline
\fxi{storerenew} & \texttt{false} & Allow the storage of a command name that has already been stored. This is used by \fx{\renewsavecmd}.\\\hline
\fxi{overwrite} & \texttt{false} & Allow overwrite of an existing container file or container macro.\\\hline
\fxi{storefile} & \fxi{containerfile} & Container file name.\\\hline
\fxi{storecmd} & \fxi{containermacro} & Container macro name.\\\hline
\fxi{showsource} & \texttt{false} & Show the name of the source file of the command.\\\hline
\fxi{verbose} & \texttt{true} & Give extra information in the transcript file. Turn this option off if you don't like or need such information, but only minimal information is actually logged.\\\hline
\end{tabularx}
When a boolean option is given without value, its value is assumed to be \hx{true}.
\docsection{User commands}
Three master macros are provided for storing command names:
\start{newmacro}[\defsavecmd,\newsavecmd,\renewsavecmd]
\defsavecmd|A(cmd)|A(param){|A(defn)}
\newsavecmd|A(cmd)[|A(nparam)][|A(default)]{|A(defn)}
\renewsavecmd|A(cmd)[|A(nparam)][|A(default)]{|A(defn)}
\finish{newmacro}
\fxi*{\defsavecmd,\newsavecmd,\renewsavecmd}
Here \ang{cmd} is the command name, \ang{param} is the parameter list, \ang{nparam} is the number of parameters, \ang{default} is the default value of the first parameter/argument, and \ang{defn} is the replacement text. In \fx{\defsavecmd}, the \ang{param} list is as in \tex's \hx{\def}; in \ffx'{\newsavecmd, \renewsavecmd}, the \ang{nparam} and \ang{default} are as in \hx{\newcommand}. Both \ffx'{\defsavecmd, \renewsavecmd} will overwrite an existing command, but \fx{\newsavecmd} will not do so.
The commands \ffx'{\defsavecmd, \newsavecmd, \renewsavecmd} may be prefixed by \fx{\stcglobal} and/or \fx{\stcprotected} to yield global or robust definitions, respectively. For example,
\start{example}[\stcglobal,\stcprotected]
\defsavecmd\cmda#1#2{xxx#1#2}
|R(\stcglobal)\defsavecmd\cmdb#1#2{xxx#1#2}
|R(\stcglobal)\newsavecmd\cmdc[2]{xxx#1#2}
|R(\stcprotected\stcglobal)\renewsavecmd*\cmda[2][zz]{\def\y##1{##1xxx}}
\finish{example}
\fxi*{\stcglobal,\stcprotected}
\docsubsection{Delimited parameters}
The parameters of \fx{\defsavecmd} can readily be delimited as in the case of \tex's \hx{\def}. The parameters of \ffx'{\newsavecmd, \renewsavecmd} can be delimited as follows:
\start'{newmacro}[Delimited parameters]
\newsavecmd|A(cmd)[|A(param)][|A(default)]|(|A(delimiters)|){|A(defn)}
\renewsavecmd|A(cmd)[|A(param)][|A(default)]|(|A(delimiters)|){|A(defn)}
\finish{newmacro}
The \ang{delimiters}, given here in parenthesis, have the syntax
\start'{newmacro}[Delimited parameters]
1|A(delim1) 2|A(delim2) ... 9|A(delim9)
\finish{newmacro}
where \ang{delim1} is the delimiter for the first parameter, etc. Only the parameters with delimiters are to be specified in \ang{delimiters}. For example,
\start'{example}[Delimited parameters]
\newsavecmd\cmda[2]|(1\@nil 2\@mil|){xxx#1#2}
\newsavecmd\cmdb[9][yy]|(3\@nil 4\@mil 6\@nnil|){xxx#1#2#3...#9}
\finish{example}
When the first argument is optional, then it can't have a delimiter, since the delimiter for that parameter is already \quotedfx{[]}.
\docsection{Examples}
The following example is available in the accompanying \file{storecmd-example} file:
\start{example}[\defsavecmd,\newsavecmd,\stcglobal, etc]
\documentclass{article}
% Container commands are also accepted as package options, but in this
% case `catoptions' must be loaded before \usepackage{storecmd}.
% Eg,
% \usepackage{catoptions}
% \usepackage[storecmd=\mycommands]{storecmd}
%
% Uncomment the next line to test what happens when an existing container
% command is being refilled:
% \def\mycommands{}
\usepackage[
storerenew=true,storecmd=mycommands,storefile=mycommands
]{storecmd}
\defsavecmd\cmda#1#2{xxx#1#2}
\stcglobal\defsavecmd\cmdb#1#2{xxx#1#2}
\stcglobal\newsavecmd\cmdc[2]{xxx#1#2}
\stcglobal\newsavecmd\cmdd[2][yy]{xxx#1#2}
\stcprotected\stcglobal\renewsavecmd*\cmda[2][zz]{\def\y##1{##1xxx}}
\stcprotected\newsavecmd\cmde[2]|(1\@nil 2\@mil|){xxx#1#2}
\newsavecmd\cmdf[9][yy]|(3\@nil 9\@mil|){xxx#1#2#3...#9}
% Try \show\mycommands or see file `mycommands.tex'.
\begin{document}
Blackberry lily.
\end{document}
\finish{example}
\fxi*{\defsavecmd,\newsavecmd,\renewsavecmd}
\docsection(sec:version-hist){Version history}
The \stsign on the right-hand side of the following lists means the subject features in the package but is not reflected anywhere in this user guide.
\begin{versionhist}
\begin{version}{0.0.2}{2011/10/22}
\item User guide completed.\vsecref*
\end{version}
\begin{version}{0.0.1}{2011/10/17}
\item First public release.\vsecref*
\end{version}
\end{versionhist}
\newpage
\ltsindexpreamble{Index numbers refer to page numbers.}
\ltsindexpreambleformat{\centering}
\ltsindexcolumns\tw@
\printindex
\end{document}
|
