Defining macros

When you find yourself typing the same thing over and over — or you know you will want to change it everywhere later — you define your own command (a macro). The foundation is \newcommand. This page walks through the whole basis for defining commands: taking arguments, redefining existing commands, the modern \NewDocumentCommand, and the craft of avoiding “fragile” commands.

Defining commands with \newcommand

The most basic tool is **\newcommand{\name}{definition}**. The first argument is the name of the command you want, the second is what it stands for. If you write your research group’s name over and over, define it once in the preamble and thereafter typing \name expands to definition.

% プリアンブルで定義 / define in the preamble
\newcommand{\grp}{Knuth Typesetting Lab}

% 本文で使う / use it in the body
Welcome to the \grp. The \grp{} was founded in 1978.

Note the **{}** after the second \grp. A command made of letters, like \grp, swallows the space right after it as the marker that ends its name — so \grp was loses the space and prints “Labwas” rather than “Lab was”. The standard fix is an empty pair of braces {} to mark where the name ends (see “Syntax rules” for the full story).

A key rule: \newcommand succeeds only if that name is not already defined. Use it on a name that already exists (including kernel or package commands) and it stops with Command \name already defined. This is a deliberate safety net against silently clobbering an existing command. To rework an existing command on purpose, use \renewcommand, covered below.

Macros that take arguments

To vary the contents at each call, give the command arguments. Write the number of arguments in square brackets after the name — **\newcommand{\name}[⟨nargs⟩]{... #1 #2 ...} — and refer to them inside the definition as #1, #2, and so on. The parameters run #1 through #9: nine at most.**

\newcommand{\unit}[2]{#1\,\mathrm{#2}}

% \unit{9.8}{m/s^2} → 9.8 m/s^2（数と単位の間に細い空き）
$a = \unit{9.8}{m/s^2}$

You can also make the first argument optional, with a default value. Doubling the brackets — **\newcommand{\name}[⟨nargs⟩][⟨default⟩]{...}** — makes #1 an optional argument whose default is ⟨default⟩. You then call it as \name (which uses the default) or \name[x] (which sets #1 to x); any remaining mandatory arguments start at #2.

% 全 2 引数、うち #1 は省略可能で既定値 2
\newcommand{\plusbinomial}[2][2]{(x + y)^{#1}_{#2}}

$\plusbinomial{n}$      % → (x + y)^2_n   （#1 は既定の 2）
$\plusbinomial[3]{n}$   % → (x + y)^3_n   （#1 を 3 に）

Mind how the brackets are counted: the ⟨nargs⟩ in [⟨nargs⟩] is the total number of arguments, including the optional one. So the example above means “two arguments, the first of which is optional.” Also, *omitting* [⟨default⟩] is different from writing empty brackets []: the latter gives an optional argument whose default is the empty string.

Redefining, providing, and making robust

\newcommand has three siblings for different purposes. All take arguments the same way ([⟨nargs⟩][⟨default⟩]); what differs is how each behaves toward a name that is already defined.

\renewcommand** redefines an existing command. The mirror image of \newcommand, it errors if the target is not already defined. You reach for it to replace the contents of a command LaTeX already provides — for instance, to change the bullet used in a list.

% itemize の第 1 階層の記号をダッシュに
\renewcommand{\labelitemi}{--}

% 既存マクロを新しい中身で作り直す
\renewcommand{\grp}{Lamport Typesetting Lab}

\providecommand defines a command only if it does not yet exist.** If the name is undefined it behaves exactly like \newcommand; if the name already exists it does nothing and keeps the existing definition (no error). It suits style files that might be loaded more than once, where you want to “provide a command just in case.”

\DeclareRobustCommand builds a robust command** even when some of its inner code is fragile (the terms come in the next section). Unlike \newcommand it does not error on an existing name; when it redefines one it merely writes a note to the log file. Commands made this way are slightly less efficient, though, so use it only when the contents are fragile *and* the command appears in a moving argument — otherwise prefer \newcommand.

Fragile commands and \protect

LaTeX has a special context called a moving argument. The title in \section{...} is not just typeset in the body — it is also **written out to the table of contents, the running head, and the .aux auxiliary file**, “moving” to several places. The contents of \caption{...} (figure and table captions), \thanks{...}, and the @{...} expressions in tabular/array are moving arguments too.

A command that breaks into invalid TeX code when expanded in such a context is called a fragile command; one that survives is a robust command. The classic remedy is to put **\protect** right before a fragile command, telling LaTeX “do not expand this here — write it out as-is.” Protection is per-command: each \protect shields only the single command that follows it.

% 可動引数の中で壊れやすい \verb を保護する
\section{The \protect\verb|\par| primitive}

There is good news, though: since the October 2019 LaTeX, most formerly-fragile commands were made robust. Commands with optional arguments such as \raisebox, and inline math \(...\), can now go into a heading without \protect. The most common holdout is **\verb**, which \protect often cannot save anyway — in a heading or caption it is quickest to rewrite it with \texttt{...}. When you define your own macro, defining it robustly with \DeclareRobustCommand from the start removes the worry about \protect altogether.

The modern \NewDocumentCommand

Modern LaTeX offers one more, more powerful way to define commands: **\NewDocumentCommand{\name}{⟨arg-spec⟩}{...}**. Originally a feature of the xparse package, it is **now part of the LaTeX kernel (ltcmd)** and available without \usepackage. Instead of writing a number of arguments, you declare an argument specification (arg-spec): a string of letters naming the kind of each argument.

It is more powerful than \newcommand in two ways: it can take several optional arguments, and it handles true starred variants properly. The example below branches on the star with \IfBooleanTF (here #1 is the star, #2 the mandatory argument). For new code, this modern interface is the recommended choice; the “xparse” page covers it in depth.

\NewDocumentCommand{\diff}{s m}{%
  \IfBooleanTF{#1}%
    {\frac{\mathrm{d}}{\mathrm{d}#2}}%   星つき: d/dx 形
    {\mathrm{d}#2}%                      星なし: dx 形
}

$\diff{x}$    % → dx
$\diff*{x}$   % → d/dx

Good macro practice

Macros shine brightest as semantic macros. Naming things by what they are — the reals as \newcommand{\R}{\mathbb{R}}, the differential d as \newcommand{\dd}{\mathrm{d}} — keeps notation consistent across the whole document, and if you later want to change the look, editing one line of the definition updates every occurrence.

\newcommand{\R}{\mathbb{R}}
\newcommand{\dd}{\mathrm{d}}

% 統一された表記で書ける / write with consistent notation
$\int_{\R} f(x)\,\dd x$

That said, too many macros hurt readability. An extreme abbreviation like \newcommand{\x}{\xi} can become a cipher to your future self or a co-author months later. Reserve macros for what is repeated often, likely to change in bulk, or worth naming by meaning — for the rest, writing it out plainly is often more readable in the end.

Finally, avoid name clashes. **Do not lightly overwrite kernel or package commands with \renewcommand — the side effects can surprise you. For your own commands, avoid names that are too short, and prefer a project-specific prefix** (\myR, \bookTitle); that keeps them clear of existing commands and other packages. When in doubt, define with \newcommand first — an already defined error tells you the name is taken.