Next: Boxes Up: Commands Previous: Document structure

## Definitions

In LATEX, commands can have both mandatory and optional arguments, for example in:

       \documentclass[11pt]{article}

the `11pt` argument is optional, whereas the `article` class name is mandatory.

In LATEX 2.09 users could define commands with arguments, but these had to be mandatory arguments. With LATEX2e, users can now define commands and environments which also have one optional argument.

`\newcommand` `{`<cmd>`}` `[`<num>`]` `[`<default>`]` `{`<definition>`}`
`\newcommand*` `{`<cmd>`}` `[`<num>`]` `[`<default>`]` `{`<definition>`}`
`\renewcommand` `{`<cmd>`}` `[`<num>`]` `[`<default>`]` `{`<definition>`}`
`\renewcommand*` `{`<cmd>`}` `[`<num>`]` `[`<default>`]` `{`<definition>`}`

These commands have a new, second, optional argument; this is used for defining commands which themselves take one optional argument. This new argument is best introduced by means of a simple (and hence not very practical) example:

       \newcommand{\example}[2][YYY]{Mandatory arg: #2;
                                     Optional arg: #1.}

This defines `\example` to be a command with two arguments, referred to as `#1` and `#2` in the `{`<definition>`}`--nothing new so far. But by adding a second optional argument to this `\newcommand` (the `[YYY]`) the first argument (`#1`) of the newly defined command `\example` is made optional with its default value being `YYY`.

Thus the usage of `\example` is either:

       \example{BBB}

which prints:

> Mandatory arg: BBB; Optional arg: YYY.

or:

       \example[XXX]{AAA}

which prints:

> Mandatory arg: AAA; Optional arg: XXX.

The default value of the optional argument is `YYY`. This value is specified as the `[`<default>`]` argument of the `\newcommand` that created `\example`.

As another more useful example, the definition:

       \newcommand{\seq}[2][n]{\lbrace #2_{0},\ldots,\,#2_{#1} \rbrace}

means that the input `$\seq{a}$` produces the formula , whereas the input `$\seq[k]{x}$` produces the formula .

In summary, the command:

> `\newcommand` `{`<cmd>`}` `[`<num>`]` `[`<default>`]` `{`<definition>`}`

defines <cmd> to be a command with <num> arguments, the first of which is optional and has default value <default>.

Note that there can only be one optional argument but, as before, there can be up to nine arguments in total.

`\newenvironment` `{`<cmd>`}` `[`<num>`]` `[`<default>`]` `{`<beg-def>`}` `{`<end-def>`}`
`\newenvironment*` `{`<cmd>`}` `[`<num>`]` `[`<default>`]` `{`<beg-def>`}` `{`<end-def>`}`
`\renewenvironment` `{`<cmd>`}` `[`<num>`]` `[`<default>`]` `{`<beg-def>`}` `{`<end-def>`}`
`\renewenvironment*` `{`<cmd>`}` `[`<num>`]` `[`<default>`]` `{`<beg-def>`}` `{`<end-def>`}`

LATEX2e also supports the creation of environments that have one optional argument. Thus the syntax of these two commands has been extended in the same way as that of `\newcommand`.

`\providecommand` `{`<cmd>`}` `[`<num>`]` `[`<default>`]` `{`<definition>`}`
`\providecommand*` `{`<cmd>`}` `[`<num>`]` `[`<default>`]` `{`<definition>`}`

This takes the same arguments as `\newcommand`. If <cmd> is already defined then the existing definition is kept; but if it is currently undefined then the effect of `\providecommand` is to define <cmd> just as if `\newcommand` had been used.

All the above five `defining commands' now have `*`-forms that are usually the better form to use when defining commands with arguments, unless any of these arguments is intended to contain whole paragraphs of text. Moreover, if you ever do find yourself needing to use the non-star form then you should ask whether that argument would not better be treated as the contents of a suitably defined environment.

The commands produced by the above five `defining commands' are now robust.

Next: Boxes Up: Commands Previous: Document structure