Most typesetting software lets the user operate within its functionality and thorough programming knowledge is required to write any form of extension to the system, typically in the form of a module written in C. With LaTeX this form of extensibility is built into the language, allowing you to program your own solutions, and to easily use other peoples' solutions to problems. One of the key places to find these other solutions is at places like CTAN (the Comprehensive TeX Archive Network).

While many premade solutions exist, there will invariably be times where you need something custom made. Today we will look at the basics of creating new commands in LaTeX. Previous familiarity with programming will be a benefit, but, I hope, not an absolute requirement.

A command in LaTeX can accomplish pretty much anything (for the really interested, LaTeX is Turing complete), but for our purposes it is mostly used to abstract away formatting or change the values of counters or lengths. As such, familiar things in LaTeX such as \section, \usepackage and the like are all commands that abstract some behaviour. To familiarise ourselves with how to introduce commands, we will look at a fictional problem: We are writing a larger document containing a lot of acronyms, and we'd like to be able to standardise on the typography for printing acronyms, and ensure that the first time an acronym is used its full definition is written out.

Introducting a command in LaTeX is done using the \newcommand command. Its full definition is on the following form:

\newcommand{command-name}[number-of-arguments]{body}

Inside the body, the arguments can be referenced by typing #n where n is the n'th argument to the command. With this in mind, let us create an \ac command for typesetting acronyms.

\newcommand{\ac}[1]{\textbf{#1}}

What this does it create a command, \ac that takes one argument, and it expands to boldfacing the argument in the text. If you find using bold type for typesetting acronyms bad style, there is, fortunately, a single place to correct the formatting with this command, rather than having to go through the entire document and correct every single acronym.

While this lays the foundation for the command, what we would really like is to be able to define a number of acronyms, i.e. both their short forms and their expanded forms, and have LaTeX make sure that we have always presented the long form of an acronym the first time we use it. This is a good deal tricker, as we will have to introduce commands that are constructed dynamically. Basically we would like to be able to define an acronym like: \acronym{ETA}{Expected Time of Arrival}, and when we use it the first time have it print something like: ETA (Expected Time of Arrival) and just ETA at subsequent occurrances in the text.

So at the core we have something like:

\newcommand{\acronym}[2]{ }

And we need to fill something into the body. If we just do something like this:

\newcommand{\acronym}[2]{ \newcommand{\acronym#1}{#2} }

Then we're told that the command \acronym already exists. So we need some way of splicing acronym and our command together to form a whole command. This can be done with the \csname and \endcsname constructs, like this:

\newcommand{\acronym}[2]{ \newcommand{\csname acronym#1\endcsname}{#2} }

However, now this tells us that the \csname command is already defined. So we need some way to indicate to LaTeX that it should resolve and concatenate acronym#1 first, then invoke \csname and finally call \newcommand. We can accomplish this using the fairly low-level command \expandafter. This command does, when placed in front of a command indicate that what comes after it should be expanded before we call the command. So we have to jump over \newcommand and \csname, so we will need two uses of \expandafter, like this:

\newcommand{\acronym}[2]{ \expandafter\newcommand\expandafter{\csname acronym#1\endcsname}{#2} }

Using this with our call to \acronym{ETA}{Expected Time of Arrival} creates a new command, \acronymETA, which we can call normally, and this command will print ‘Expected Time of Arrival’.

The next thing we need to accomplish is to only print this expanded text the first time we use the acronym. To aid us slightly, we use the ifthen package's commands \newboolean and \setboolean as follows:

\newcommand{\acronym}[2]{ \newboolean{acronym#1} \setboolean{acronym#1}{true} \expandafter\newcommand\expandafter{\csname acronym#1\endcsname}{#2} }

Here the \newboolean figures out that the name of the boolean should be expanded before the creation of a new boolean on its own, so we don't have to place manual \expandafter commands throughout the code.

This means that we have everything in place to create a new command that prints the actual acronym:

\newcommand{\ac}[1]{ \ifthenelse{\boolean{acronym#1}} {#1 (\csname acronym#1\endcsname) \setboolean{acronym#1}{false}} {#1} }

Using this as follows:

The \ac{ETA} is now 5 minutes. The \ac{ETA} is now 4 minutes.

Would result in the following: ‘The ETA (Expected Time of Arrival) is now 5 minutes. The ETA is now 4 minutes.’ This is, of course, all great and well, but recreating all of \ac can be a bit taxing, if we want to change the formatting of parts of the word. So let us create two more commands to typeset the acronym with and without the expanded text:

\newcommand{\printlongacronym}[2]{#1 (#2)} \newcommand{\printshortacronym}[1]{#1}

And we change the definition of \ac to use these as follows:

\newcommand{\ac}[1]{ \ifthenelse{\boolean{acronym#1}} {\printlongacronym{#1}{\csname acronym#1\endcsname} \setboolean{acronym#1}{false}} {\printshortacronym{#1}} }

This now lets us change the formatting of acronyms merely by changing the definition of \printlongacronym and \printshortacronym, thus abstracting away all the technical issues of changing boolean values and whatnot from the end user. The user just needs to focus on how to adapt these two commands for his formatting needs. And, if these things are wrapped away in a package, the user can use \renewcommand to change the meaning of the commands.

This is basically all there is to commands: give it a name, some arguments and do something in the body. Even a simple command such as typesetting some code inline in the text might be a boon if you have to go over the document at a later time to fix up the layout.

Advanced commands and TeXing

Now that we have our fancy \ac function, it is time to consider what happens if we write something like: ‘Some of the \ac{CIA}'s archives have recently been opened up.’ The outcome could be one of two things, depending on whether this is the first use of the CIA acronym or not, namely:

Some of the CIA's archives have recently been opened up.

or

Some of the CIA (Central Intelligence Agency)'s archives have recently been opened up.

In the latter case, the possessive should still have been attached to CIA rather than the parenthesis. One way to cope with this is to use TeX's mechanism for defining functions and in particular functions with optional parameters. This is done using the TeX function \def. If we were to code a command with optional parameters (keeping in mind that optional parameters are typically given in []'s as the first part of a command, in TeX), it would look something like this:

\def\acopt[#1]#2{ \ifthenelse{\boolean{acronym#1}} {\printlongacronym{#2#1}{\csname acronym#2\endcsname} \setboolean{acronym#2}{false}} {\printshortacronym{#2#1}} }

This basically means we can call it like this: \acopt['s]{CIA} and we'd get:

CIA's (Central Intelligence Agency)

if this was the first use of the acronym. Now, we could just call \acopt whenever we need to add some fancy possessive or what have you to an acronym. However, we'd like to be able to extend \ac so that we only have to type one command, and that'll figure out whether to call \acopt sensibly. In order to do this, we must use a built-in command \@ifnextchar. This command is primarily meant to be used from inside a package, but we can use it in normal document code by surrounding it by the two commands \makeatletter and \makeatother. These two commands are necessary, as @ isn't treated as a normal letter in LaTeX commands and thus we're required to change @'s code group (if you're getting confused now, don't worry, you can just use the two commands around the location where you need to use a command with an @ in it and worry about the details at some later time). With this we can define \ac like this:

\makeatletter \def\ac{\@ifnextchar[\acopt\acnoopt} \makeatother

What this does it it queries the token stream (the next bunch of characters in the document, for a very loosely hand-waved definition) and if the next character is a left-bracket we call \acopt, or otherwise we call \acnoopt, the latter of which we can define very easily:

\def\acnoopt#1{\acopt[]{#1}}

With this we can now both write \ac['s]{CIA} and \ac{CIA} and everything will sort itself out nicely.

On the horison

Apart from these few commands we've seen, it is also possible to define commands globally using \gdef (commands are otherwise local to the environment they're declared in), redefine LaTeX commands using \renewcommand, create commands that cannot include paragraph changes using \newcommand* and many, many others. However, the command construction you've seen above goes for pretty much all the other commands as well, so presuming you've gleaned some meaning from my ramblings, you should be able to get somewhere fast no matter the situation.