\documentclass{article}
\usepackage[utf8x]{inputenc}
\usepackage[ngerman,english]{babel}
\usepackage[dvipsnames]{xcolor}
\usepackage{amssymb}
\usepackage{fancyvrb}
\usepackage{newverbs}
\newverbcommand{\cverb}{\color{Plum}}{}

\usepackage{newnotation}

\newcommand{\decorate}[1]{\textcolor{Plum}{#1}}
\newcommand{\paren}[1]{(#1)}

\title{The \textsf{newnotation} package}
\author{Gaetano Geck}

\begin{document}
	\maketitle

	\begin{abstract}
	This package implements a \verb#\newnotation# command that allows definition of macros in the style of \verb#\newcommand#. The table of all macros defined this way can be printed by \verb#\tableofnotation# or, with additional information, by \verb#\detailedtableofnotation#. For relation symbols, there is a designated \verb#\newrelation# command. Tables can be grouped, saved, loaded and reset.
	\end{abstract}

	\tableofcontents

	\newpage
	\section{Example}
	\label{sec:example}
	%==========================================================================

	\subsection{Example code: define groups and notation}
	Consider the following \LaTeX-file.
	\begin{Verbatim}[frame=single,fontsize=\footnotesize,tabsize=4,commandchars=+()]
\documentclass{article}
\usepackage{newnotation}

\begin{document}
% COMMAND DEFINITIONS (AND DESCRIPTIONS) -----------------
+decorate(\newnotation){\powerset}{\mathcal{P}}[powerset]
+decorate(\newnotation){\pair}[2]{\left(#1,#2\right)}

+decorate(\notationnewgroup){Logics}
+decorate(\newrelation*){\satisfies}{\models}
+decorate(\newnotation){\interpretation}{\alpha}[interpretation]
+decorate(\newnotation){\bigand}[2]{\bigwedge^{#2}_{#1=1}}
+decorate(\newnotation){\disclause}[3]{(#1 \lor #2 \lor #3)}
	[OR-clause containing literals 1, 2 and 3]

+decorate(\notationnewgroup){Calculus}
+decorate(\newnotation){\mylimit}{\lim_{n \to \infty}}
+decorate(\newnotation){\xintegral}[1]{\int^\infty_0 {#1} dx}



% TEXT CONTENT -------------------------------------------
Let $\phi=\disclause{x_1}{x_2}{x_3} \land \disclause{\lnot x_1}
{x_2}{\lnot x_3}$ be a formula and let $\interpretation$ be an
interpretation that satisfies formula~$\phi$ (i.e. $\alpha \satisfies \phi$),
then $\interpretation+paren(x_2)=1$ or $\interpretation+paren(x_1) \neq
\interpretation+paren(x_3)$.

+decorate(\detailedtableofnotation)
\end{document}
\end{Verbatim}

	\newpage
	\subsection{Example output (with detailed table of notation)}

	The \LaTeX-code above results in the following output (displayed in brown).

	% Definitions --------------------------------------------
	\newnotation{\powerset}{\mathcal{P}}[powerset]
	\newnotation{\pair}[2]{\left(#1,#2\right)}

	\notationnewgroup{Logics}
	\newrelation*{\satisfies}{\models}
	\newnotation{\interpretation}{\alpha}[interpretation]
	\newnotation{\bigand}[2]{\bigwedge^{#2}_{#1=1}}
	\newnotation{\disclause}[3]{(#1 \lor #2 \lor #3)}[OR-clause containing literals 1, 2 and 3]

	\notationnewgroup{Calculus}
	\newnotation{\mylimit}{\lim_{n \to \infty}}
	\newnotation{\xintegral}[1]{\int^\infty_0 {#1} dx}

	% Text ---------------------------------------------------

	\medskip
	\noindent
	{\color{teal}
	Let $\phi=\disclause{x_1}{x_2}{x_3} \land \disclause{\lnot x_1}{x_2}{\lnot x_3}$ be a formula and let $\interpretation$ be an interpretation that satisfies formula~$\phi$ (i.e. $\alpha \satisfies \phi$), then $\interpretation(x_2)=1$ or $\interpretation(x_1) \neq \interpretation(x_3)$.

	\detailedtableofnotation
	}

	\paragraph*{Remark.}
	Using \cverb#\tableofnotation# instead of \verb#\detailedtableofnotation# will result in a table that lists only the symbols with their descriptions. 

	\newpage
	\section{Defining notation}
	\label{sec:defining}
	%==========================================================================
	Macros for specific notation can be defined with \cverb#\newnotation# in the same fashion as with \verb#\newcommand#.\footnote{Internally, however, \texttt{\textbackslash{}newrobustcmd} is used. This way, a counter recording the number of uses of a command defined via \texttt{\textbackslash{}newnotation} also work in section titles and the like.} In particular, \verb#\newnotation# has two \textbf{mandatory arguments}:
	\begin{itemize}
		\setlength{\itemsep}{0em}
		\setlength{\parsep}{0em}
		\setlength{\parskip}{0em}
		\item the macro name (position~2) and
		\item its replacement (position~5).
	\end{itemize}
	Furthermore, \verb#\newnotation# can handle some \textbf{optional arguments}:
	\begin{itemize}
		\setlength{\itemsep}{0em}
		\setlength{\parsep}{0em}
		\setlength{\parskip}{0em}
		\item a class name (position~1);
		\item a number of arguments for the macro definition (position~3);
		\item a default value (position~4)), in case the first argument is unspecified; and
		\item a description for the table of notation (position~6),
		\item with possibly detailed description of the arguments (position~7).
	\end{itemize}
	Disregarding the possible definition of a default value, this results in a total of four variants of the \verb#\newnotation# command. The general scheme

	\begin{Verbatim}[tabsize=4,commandchars=+()]
	+decorate(\newnotation)[class]{macro name}[number of arguments]
                [default value]{replacement}
                [description][argument description]
	\end{Verbatim}
	is illustrated by the four commands from the introductory example:
	\begin{enumerate}
		\item {No arguments, no description:}\\
			\verb#\newrelation*{\satisfies}{\models}#

		\item {No arguments but description:}\\
			\verb#\newnotation{\interpretation}{\alpha}[interpretation]#

		\item {Arguments, no description:}\\
			\verb+\newnotation{\bigand}[2]{\bigwedge^{#2}_{#1=1}}+

		\item {Arguments and description:}\\
			\verb+\newnotation{\disclause}[3]{(1 \lor #2 \lor #3)}+\\
			\verb+    [OR-clause containing literals 1, 2 and 3]+
	\end{enumerate}

	\paragraph*{Starred and non-starred version.}
	Every replacement text is wrapped in an \verb#\ensuremath#, with an \verb#\xspace# appended. Therefore you can, for instance, safely write
	\begin{Verbatim}[tabsize=4]
	Interpretation~\interpretation satisfies \dots 
\end{Verbatim}
	resulting in
	\textcolor{teal}{Interpretation~\interpretation satisfies \dots}.

	Using the non-starred version \verb#\newnotation#, an additional pair of curly braces added to the replacment allows the command to be used in a sub- or superscript. For example, writing \verb#$a_\pair{i}{j}$# results in \textcolor{teal}{$a_\pair{i}{j}$}.

	\newcommand{\badpair}[2]{\ensuremath{}\xspace}

	Note, however, that this wrapping prevents extra spaces (like those surrounding relation or operator symbols, defined by \verb#\mathrel# or \verb#\mathop#, for example). If you want these extra spaces, you can avoid the additional pair of braces by using the starred version \cverb#\newnotation*#; like for the binary satisfaction relation \verb#\satisfies# above.
	
	\paragraph*{Default value for first argument.} As for \verb#\newcommand#, you can specify a default value for the first argument, which will be considered as an optional argument then.
	For example, the definition
	\begin{Verbatim}[tabsize=4,commandchars=+()]
	\newnotation{\myfunc}[2]+decorate([\mathbb{R}]){#2: #1 \to #1}
	\end{Verbatim}
	\newnotation{\myfunc}[2][\mathbb{R}]{#2: #1 \to #1}
	leads to output
	\begin{itemize}
			\item \textcolor{teal}{$\myfunc{f}$} when using \verb#\myfunc{f}# and
			\item \textcolor{teal}{$\myfunc[\mathbb{N}]{g}$} when using \verb#\myfunc[\mathbb{N}]{g}#.
	\end{itemize}

	\paragraph*{Redefinition.}
	Of course, you can also redefine a command, whether previously defined via \verb#\newnotation# or not. If you want the new definition to be contained in the table of notation, simply use \cverb#\renewnotation# in one of the flavors described above.

	For the purpose of illustration, we redefine our \verb#\myfunc# macro. This time, we interpret the first argument as the optional mapping's name (default name $f$) and the following two arguments restrict the mapping's domain and range:
	\begin{Verbatim}[tabsize=4,commandchars=+()]
	+decorate(\renewnotation){\myfunc}[3][f]{#1: #2 \to #3}
	\end{Verbatim}
	\renewnotation{\myfunc}[3][f]{#1: #2 \to #3}

	After this redefinition, we get output
	\begin{itemize}
		\item \textcolor{teal}{$\myfunc{X \times Y}{Z}$} when using \verb#\myfunc{X \times Y}{Z}# and
		\item \textcolor{teal}{$\myfunc[f^{-1}]{Z}{X \times Y}$} when using \verb#\myfunc[f^{-1}]{Z}{X \times Y}#.
	\end{itemize}

	\paragraph*{Remark.}
	Indeed, there's a sixth argument that can optionally be supplied to both \verb#\newnotation# and \verb#\renewnotation#. This argument, which is explained in detail in Section~\ref{sec:listing}, specifies the replacement for potential arguments of a macro in the table of notation.


	\paragraph*{Classes.}
	Often, entitites of a certain type are formatted in a particular way, just to indicate that type. For instance, set names may always be bold, problem names in small caps \dots It is desirable to separate the choice of layout for some type from the choice of type for the entity (or its denotation, more precisely). To this end, the \cverb#\newnotation# command supports classes.

	They can be used like in the following example.
	\begin{Verbatim}[tabsize=4,commandchars=+()]
	+decorate(\newnotationclass){set}{\boldsymbol}
	+decorate(\newnotationclass){problem}{\textsc}

	\newnotation+decorate([set]){\setX}{X}
	\newnotation+decorate([set]){\setY}{Y}
	\newnotation+decorate([set]){\setZ}{Z}
	\newnotation+decorate([problem]){\HC}{HamiltonCircuit}
	\newnotation+decorate([problem]){\ThreeSat}{3-Sat}

	\begin{itemize}
		\item sets: $\setX$, $\setY$, $\setZ$
		\item problems: $\HC$ and $\ThreeSat$
	\end{itemize}
	\end{Verbatim}


	\notationsavetable{beforeClasses}
	\notationnewtable
	\newnotationclass{set}{\boldsymbol}
	\newnotationclass{problem}{\textsc}

	\newnotation[set]{\setX}{X}
	\newnotation[set]{\setY}{Y}
	\newnotation[set]{\setZ}{Z}
	\newnotation[problem]{\HC}{HamiltonCircuit}
	\newnotation[problem]{\ThreeSat}{3-Sat}

	\notationloadtable{beforeClasses}

	The output produced will be:

	{\color{teal}
	\begin{itemize}
		\setlength{\itemsep}{0em}
		\setlength{\parsep}{0em}
		\setlength{\parskip}{0em}
		\item sets: $\setX$, $\setY$, $\setZ$
		\item problems: $\HC$ and $\ThreeSat$
	\end{itemize}
	}

	The \cverb#\newnotationclass# has two mandatory arguments:
	\begin{itemize}
		\item class name and
		\item a macro \emph{that expects exactly one argument}.
	\end{itemize}
	When defining notation for an entity that should belong to a specific class, the name of this class can be passed to the \cverb#\newnotation# command as a first optional argument (right before the name of the new macro).

	\paragraph*{Relation symbols.}
	Relation symbols require some extra space around them. Using \cverb#\newcommand# this can be achieved with \cverb#\mathrel#. This is done implicitly, when \cverb#\newrelation# (or \cverb#\newrelation*#) is used instead of \cverb#\newnotation#.

	\newpage
	\section{Grouping notation}
	\label{sec:grouping}
	%==========================================================================
	Even for a single paper, it is not uncommon to define several dozen notational macros. For ease of maintenance and look-up, it therefore seems desirable to group such definitions.

	This package supports (one-level) grouping of macro definitions. Simply set a new group name by
	\begin{Verbatim}[tabsize=4,commandchars=+()]
	+decorate(\notationnewgroup)[output level]{group name}
	\end{Verbatim}
	Every use of \verb#\newnotation# will add an entry to the list of the group that was most recently added to the active table. If no group was specified explicitly before, the entry is added to the (unnamed) default group.

	When printing a table, groups are filtered based on their output level. You can provide an integer value as the group's output level. By default, the output level is set to 0. See Section~\ref{sec:listing} for more information.

	\paragraph*{Remark.}
	You can use the same group name several times, but every use will create an own list, even if immediately following a group of the same name.

	\newpage
	\section{Listing notation}
	\label{sec:listing}
	%==========================================================================
	If you do not want to use \verb#\newnotation# as an abbreviation for
	\begin{Verbatim}[tabsize=4,commandchars=+()]
	\newrobustcmd{macro name}{{\ensuremath{replacement}}\xspace}
	\end{Verbatim}
	or its argument-variant
	only, then you want eventually a table of the notational macros to be printed. To this end, simply use
	\begin{Verbatim}[tabsize=4,commandchars=+()]
	+decorate(\tableofnotation)[table output level]
	\end{Verbatim}
	where you want to print a table of the macros defined \emph{so far}. Each entry in this table contains the symbol with its description. While writing a document, a more informative variant,
	\begin{Verbatim}[tabsize=4,commandchars=+()]
	+decorate(\detailedtableofnotation)[table output level],
	\end{Verbatim}
	which also displays the macro name and the number of uses, might be interesting.

	\paragraph*{Remark.}
	You can use this command several times. The column `uses' shows the number of times a macro has been expanded up to the moment where the table is printed. Possible expansions within the table itself are \emph{not}  counted.

	\medskip\noindent
	Each command is expanded with an appropriate number of arguments in the `symbol' column. By default, value `1' is used for the first argument, value `2' for the second and so on. Sometimes, a different replacement is more meaningful. In this case, you can supply a fifth argument to \verb#\newnotation# or \verb#\renewnotation#, respectively. This argument should contain a sequence of \verb#\notationarg# commands. Command \verb#\notationarg# expects two arguments: the first argument is the number of the argument whose replacement is to be changed, the second argument is the new replacement for this argument. The following example illustrates its use:

	\begin{Verbatim}[frame=single,fontsize=\footnotesize,tabsize=4,commandchars=+()]
\newnotation{\problem}[1]{\textsc{#1}}[layout for problems]
	+decorate([\notationarg{1}{Name}])
\newnotation{\bigor}[2]{\bigvee^{#2}_{#1=1}}
	[provide (1) variable~$i$; (2) upper bound~$n$]
	+decorate([\notationarg{1}{i}\notationarg{2}{n}])
\detailedtableofnotation
	\end{Verbatim}
	This code procduces the following output:

	{\color{teal}
	\notationsavetable{main}
	\notationnewtable
	\newnotation{\problem}[1]{\textsc{#1}}[layout for problems][\notationarg{1}{Name}]
	\newnotation{\bigor}[2]{\bigvee^{#2}_{#1=1}}[provide (1) variable~$i$; (2) upper bound~$n$][\notationarg{1}{i}\notationarg{2}{n}]
	\detailedtableofnotation
	\notationloadtable{main}
	}

	\newpage
	\medskip\noindent
	Both variants, \verb#\tableofnotation# and \verb#\detailedtableofnotation# can handle an optional integer argument, the \emph{table output level}. This argument allows to control which of the groups in the table are to be printed, namely those with an output level at least as high the table output level.

	Consider the following example.
	\begin{Verbatim}[frame=single,fontsize=\footnotesize,tabsize=4,commandchars=+()]
\newnotation{\cmdA}{a}
\notationnewgroup[2]{For the interested reader}
\newnotation{\cmdB}{b}
\notationnewgroup[3]{For everyone}
\newnotation{\cmdC}{c}

Show content for interested readers:\\
+decorate(\detailedtableofnotation[2])

Show content for the average reader:\\
+decorate(\detailedtableofnotation[3])
	\end{Verbatim}

	The corresponding output is:

	\medskip
	{\color{teal}
	\notationsavetable{main}
	\notationnewtable
	\newnotation{\cmdA}{a}
	\notationnewgroup[2]{For the interested reader}
	\newnotation{\cmdB}{b}
	\notationnewgroup[3]{For the average reader}
	\newnotation{\cmdC}{c}

	\noindent
	Show content for interested readers:\\
	\detailedtableofnotation[2]

	Show content for the average reader:\\
	\detailedtableofnotation[3]
	\notationloadtable{main}
	}

	\newpage
	\section{Saving, loading and resetting tables}
	\label{sec:saving}
	%==========================================================================
	If you use \verb#\tableofnotation# or its variant \verb#\detailedtableofnotation# more than once, chances are you do not want to list notation already listed previously. Simply use \verb#\notationnewtable# before the next \verb#\newnotation# that should be contained in the new table (a good place might be directly after the last \verb#\tableofnotation#).

	\paragraph*{Remark.}
	Use of \verb#\notationnewtable# only clears the contents of the table; it does \emph{not} undefine the commands defined by \verb#\newnotation#.

	\medskip
	\noindent
	Maybe you want to use \verb#\newnotation# and its companions locally, for a single section or an involved proof that requires very specific notation. As usual, you can restrict the definition of a command via \verb#\newnotation# by grouping (using curly braces or \verb#\begingroup# and \verb#\endgroup#).

	The following example demonstrates that. After opening the new group, the current contents of the table are saved by \cverb#\notationsavetable{mytable}#. Then, the table is reset by \cverb#\notationnewtable# and finally, after printing it, the previous contents are restored by \cverb#\notationloadtable#.

	
	\bigskip
	\noindent	
	Think of the following \LaTeX-code being inserted just before \verb#\end{document}# in the example code on page~1.

	\begin{Verbatim}[frame=single,fontsize=\footnotesize,tabsize=4,commandchars=+()]
% GROUP: group theory ----------------------------------------------
{
	+decorate(\notationsavetable){mytable}
	+decorate(\notationnewtable)
	\notationnewgroup{Group theory}
	\newnotation*{\composition}{\circ}[composition of elements]
	\newnotation{\identity}{e}[identity element]
	\newnotation{\inverse}[1]{{#1}^{-1}}[inverse of element~1]

	For every element~$g$ in a group~$G$ it holds $g \composition \inverse{g}
	= \inverse{g} \composition g = \identity$, where $\identity$ is the identity
	element of~$\composition$.

	\tableofnotation
	+decorate(\notationloadtable){mytable}
}
%!GROUP: group theory ----------------------------------------------

\bigskip\noindent
Enough group theory, let's return to our old table:
\tableofnotation
	\end{Verbatim}

	This code leads to the additional output shown below:
	\newpage\noindent
	\medskip
	{\color{teal}
	% GROUP: group theory ----------------------------------------------
	{
		\notationsavetable{mytable}
		\notationnewtable
		\notationnewgroup{Group theory}
		\newnotation*{\composition}{\circ}[composition of elements]
		\newnotation{\identity}{e}[identity element]
		\newnotation{\inverse}[1]{{#1}^{-1}}[inverse of element~1]

		\noindent
		For every element~$g$ in a group~$G$ it holds $g \composition \inverse{g} = \inverse{g} \composition g = \identity$, where $\identity$ is the identity element of~$\composition$.

		\tableofnotation
		\notationloadtable{mytable}
	}
	%!GROUP: group theory ----------------------------------------------

	\bigskip\noindent
	Enough group theory, let's return to our old table:
	\tableofnotation
	}

	\paragraph*{Remark.}
	Even though the command definitions via \verb#\newnotation# are lost when leaving the group and so are the locally added entries in the table, use of \verb#\notationloadtable# is required to reset internal counters (otherwise newly defined commands are added to the last local group, which won't be printed).

	\newpage
	\section{Customization}
	\label{sec:customization}
	%==========================================================================

	\subsection{Right-to-left}
	If you want the columns to be printed in reverse order, then simply pass option \verb#rtl# to the package: \verb#\usepackage[rtl]{newnotation}#. 

	\subsection{Translations}
	This package uses the \textsf{translations} package in combination with \textsf{babel}. You can provide your own translations in a fashion analogous to the example below.\\
	(This German translation is already provided by the \textsf{newnotation} package.)

	\begin{Verbatim}[frame=single,fontsize=\footnotesize,tabsize=4,commandchars=+()]
\DeclareTranslation{German}{List of notation}{Notationstabelle}
\DeclareTranslation{German}{symbol}{Symbol}
\DeclareTranslation{German}{macro name}{Makroname}
\DeclareTranslation{German}{uses}{Verw.}
\DeclareTranslation{German}{description}{Beschreibung}
\DeclareTranslation{German}{no entries}{keine Einträge}
	\end{Verbatim}

	When printing the table of notation, \textsf{newnotation} uses the active language, as determined by \textsf{babel}. For instance, this document uses \textsf{babel} with options \texttt{[ngerman,english]}, that is, English as it's main language and German as an additional one. Therefore the previous tables used English translations whereas the following \LaTeX-code
	\begin{Verbatim}[frame=single,fontsize=\footnotesize,tabsize=4,commandchars=+()]
\selectlanguage{ngerman}
\tableofnotation
	\end{Verbatim}
	results in a table headers translated to German:

	{\color{teal}
		\selectlanguage{ngerman}
		\tableofnotation
		%\selectlanguage{english}
	}

	\subsection{Layout}
	You can specify the layout for the table caption, the group names and even for arguments in the `symbol' column and occurrences of zeros in the `uses' column (all replacements can refer to the first argument):

	\begin{Verbatim}[frame=single,fontsize=\footnotesize,tabsize=4,commandchars=+()]
+decorate(\notationSetLayoutTable){\textsc{#1}\dotfill}
+decorate(\notationSetLayoutGroup){\textit{#1}}
+decorate(\notationSetLayoutColumnHeader){\underline{#1}}
+decorate(\notationSetLayoutArgument){\textcolor{Green}{#1}}
+decorate(\notationSetLayoutZeroUses){\textcolor{Magenta}{#1}}
	\end{Verbatim}

	Using this code, the ouptut by \verb#\tableofnotation# is:


	{\color{teal}
	\notationSetLayoutTable{\textsc{#1}\dotfill}
	\notationSetLayoutGroup{\textit{#1}}
	\notationSetLayoutColumnHeader{\underline{#1}}
	\notationSetLayoutArgument{\textcolor{Green}{#1}}
	\notationSetLayoutZeroUses{\textcolor{Magenta}{#1}}

	\tableofnotation
	}
\end{document}