\documenttype{article}
\newcommand{gellmu}{\abbr{GELLMU}}
\newcommand{\gst}{\gellmu syntactic translator}
\newcommand{sgml}{\abbr{SGML}}
\newcommand{\Q}{\regch{\bold{Q}}}
\newcommand{\gl}[2][2]{\mbox{GL}_{#1}(#2)}
\newcommand{q}{\regch{\slnt{Q}}}
\surtitle{The \gellmu Archive}
\title{The Use of \emph{newcommand} in \gellmu}
\nobanner
\begin{document}

\section{Introduction}

In \gellmu the command \emph{newcommand} is a meta-command that is
handled by macro-like pre-processing in the \gst.  This pre-processing
takes place very early after the processing of the required meta-command
\emph{documenttype} and after the insertion of any (relatively rare)
internal \sgml declaration subset.

\section{First Examples}

The markup for the field $\Q$ of rational numbers is a \emph{newcommand}
invocation \qquostr{\bsl;Q} without arguments that expands to
\qquostr{\bsl;regch\{\bsl;bold\{Q\}\}}.\footnote{The command \emph{regch}
is an alternative form of \emph{mbox} in the didactic \gellmu document
type definition that differs from the latter in that it is permitted as
the content of an \quophrase{accent} tag as in the example $\ovbar{\Q}$\aoc
which is written in the \gellmu source here with
\quostr{\bsl;ovbar\{\bsl;Q\}}\eos;}
Newcommand names are case-sensitive.  Here the newcommand invocation
\qquostr{\bsl;q} expands to \qquostr{\bsl;regch\{\bsl;slnt\{Q\}\}},
which yields the ad-hoc math symbol $\q$\aos

Markup to represent the general linear group may be a \emph{newcommand}
with definition
\display{
\verb{\bsl;newcommand\{\bsl;gl\}[2][2]\{\bsl;mbox\{GL\}\_\{\#1\}(\#2)\}} .
}
When invoked with \qquostr{\bsl;gl\{3\}\{F\}}, it yields
$\gl{3}{F}$\aos

Mention of the group $\gl{F}$ is obtained alternatively here with the
minimized markup invocation \qquostr{\bsl;gl\{F\}} relying on the
default value of the first argument given in the definition of
\qquostr{\bsl;gl}.

\section{Some Details}

With the \emph{newcommand} definition
\display{
\verb{\bsl;newcommand\{\bsl;Q\}\{\bsl;regch\{\bsl;bold\{Q\}\}\}}
}
the markup \verb{\bsl;Q;} may always be used instead of \verb{\bsl;Q}
and must be used if the $\Q;$ is followed immediately by characters
that could have the effect of making the \quochar{Q} in the markup
look simply like the first character in a larger string.  However, the
markup \verb{\bsl;Q;\{\}} is incorrect unless \emph{regch} is a
command that takes two arguments.  For it expands to
\display{
\verb{\bsl;regch\{\bsl;bold\{Q\}\}\{\}} \eos
}

\subsection{What Markup Can Follow a \emph{newcommand}\eoq}

What characters can safely follow the name of a \emph{newcommand}?
Of course, a following \quochar{\{} can only mean the beginning of
an argument to the command.  On the other hand the \quochar{\{} can
be escaped.

Some examples:
\begin{tablec}{ll}
\tr\td{\bold{Markup}~~~~}\td{\bold{Yield}}
\tr\td{\verb{\$\bsl;Q\$}}\td{$\Q$}
\tr\td{\verb{\$\bsl;Q;xy\$}}\td{$\Q;xy$}
\tr\td{\verb{\$\bsl;Q;\$xy}}\td{$\Q;$xy}
\tr\td{\verb{\$\bsl;Q;;\$}}\td{$\Q;;$}
\tr\td{\verb{\$\bsl;Q;\$;}}\td{$\Q;$;}
\tr\td{\verb{\$\bsl;Q\bsl;bsl;\$}}\td{$\Q\bsl;$}
\tr\td{\verb{\$\bsl;Q\bsl;\{\$}}\td{$\Q\{$}
\tr\td{\verb{\$\bsl;Q\bsl;\}\$}}\td{$\Q\}$}
\tr\td{\verb{\$\bsl;Q\bsl;lsb;\$}}\td{$\Q\lsb;$}
\tr\td{\verb{\$\bsl;Q\bsl;rsb;\$}}\td{$\Q\rsb;$}
\tr\td{\verb{\$\bsl;Q!\$}}\td{$\Q!$}
\tr\td{\verb{\$\bsl;Q@\$}}\td{$\Q@$}
\tr\td{\verb{\$\bsl;Q\bsl;\#\$}}\td{$\Q\#$}
\tr\td{\verb{\$\bsl;Q\bsl;\%\$}}\td{$\Q\%$}
\tr\td{\verb{\$\bsl;Q\crt;5\$}}\td{$\Q^5$}
\tr\td{\verb{\$\bsl;Q\und;p\$}}\td{$\Q_p$}
\tr\td{\verb{\$\bsl;Q\bsl;und;\$}}\td{$\Q\und;$}
\tr\td{\verb{\$\bsl;Q\bsl;crt;\$}}\td{$\Q\crt;$}
\tr\td{\verb{\$\bsl;Q*\$}}\td{$\Q*$}
\tr\td{\verb{\$\bsl;Q-\$}}\td{$\Q-$}
\tr\td{\verb{\$\bsl;Q(t)\$}}\td{$\Q(t)$}
\tr\td{\verb{\$\bsl;Q+\$}}\td{$\Q+$}
\tr\td{\verb{\$\bsl;Q=\$}}\td{$\Q=$}
\tr\td{\verb{\$\bsl;Q\$}=}\td{$\Q$=}
\tr\td{\verb{\$\bsl;Q,\$}}\td{$\Q,$}
\tr\td{\verb{\$\bsl;Q.\$}}\td{$\Q.$}
\tr\td{\verb{\$\bsl;Q?\$}}\td{$\Q?$}
\end{tablec}

\subsection{Comments in newcommand definitions}

It is useful here to comment on \gellmu, which is a bridge from
\latex; to \sgml;, as it compares to \latex;.
\latex; usage of \emph{newcommand} sometimes takes the form
\newcommand{\foo}[2]{%
This is an instance of the \emph{newcommand} \lsq;\lsq;foo\rsq;\rsq; %
with first argument `#1' and%  Space following a newline is swallowed
 second argument `#2'.}
\begin{tablec}{l}
\tr\td\verb{\bsl;newcommand\{\bsl;foo\}[2]\{\%}
\tr\td\verb{This is an instance of the \bsl;emph\{newcommand\} \lsq;\lsq;foo\rsq;\rsq; \%}
\tr\td\verb{with first argument `\hsh;1' and\%  Space following a newline is swallowed}
\tr\td\verb{\spc;second argument `\hsh;2'.\}}
\end{tablec}

This usage is useful in that it gives the author a way, especially with
empty comments, to make the source document more readable.

With \gellmu as a general matter such use of comments in regular
command arguments may have side effects if the author is not careful.
Because \emph{newcommand} is a meta-command handled by the \gst, this
use of comments will not have side effects.

Since \emph{newcommand} in \gellmu is a meta-command, it is \bold{not}
necessary to restrict an instance of \emph{newcommand} to a document
preamble.  However, any invocation of a command defined with
\emph{newcommand} must be preceded by the definition.

The definition of \quostr{\bsl;foo} appears in this
document just before the display of its definition, and the next
sentence is the invocation \qquostr{\bsl;foo\{cat\}\{dog\}}.
\foo{cat}{dog}

Note that the comment \quophrase{Space following \ldots} on the second
line of the value string absorbs the space at the beginning of the
third line with the result that the words \emph{and} and \emph{second}
are run together.  This phenomenon mimics \latex;; however, such
comment \quophrase{overrun} is the behavior of the \gst
only inside a \emph{newcommand} value string.  In all other contexts
there is no comment overrun in \gellmu, and space at the beginning of
a line following a comment is significant.

\subsection{Newlines in newcommand definitions}

It is important to note, however, that \emph{anything} inside the
value argument of a \emph{newcommand} definition is propogated by the
\gst; to every invocation.  With basic \gellmu newlines inside a
newcommand value string are removed since \sgml does not acknowledge a
newline as a special form of white space and since newlines in a value
string, when propogated to all invocations cause extra lines in the
\gst output, thereby blocking the goal of line number alignment
between \gellmu source and the \sgml output, which is important for
the interpretation of \sgml parser error messages.

In regular \gellmu, newlines can be significant.  For this reason
newlines in newcommand definitions are not removed.  However, the use
of newlines inside value strings is deprecated since they break line
number alignment between the \gellmu source and the output of the
\gst.  There are other ways to achieve the effect of a newline inside
a newcommand value string.

\end{document}