\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} 