File indexing completed on 2024-11-24 04:34:43
0001 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 0002 <html> 0003 <!-- This document is an unofficial reference manual for LaTeX, a 0004 document preparation system, version of November 2018. 0005 0006 This manual was originally translated from LATEX.HLP v1.0a in the 0007 VMS Help Library. The pre-translation version was written by 0008 George D. Greenwade of Sam Houston State University. The 0009 LaTeX 2.09 version was written by Stephen Gilmore. The 0010 LaTeX2e version was adapted from this by Torsten Martinsen. Karl 0011 Berry made further updates and additions, and gratefully acknowledges 0012 using Hypertext Help with LaTeX, by Sheldon Green, and 0013 LaTeX Command Summary (for LaTeX 2.09) by 0014 L. Botway and C. Biemesderfer (published by the TeX Users 0015 Group as TeXniques number 10), as reference material. We also 0016 gratefully acknowledge additional material appearing in 0017 latex2e-reference by Martin Herbert Dietze. (From these references no 0018 text was directly copied.) 0019 0020 Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013, 0021 2014, 2015, 2016, 2017, 2018 Karl Berry. 0022 0023 Copyright 1988, 1994, 2007 Stephen Gilmore. 0024 0025 Copyright 1994, 1995, 1996 Torsten Martinsen. 0026 0027 Permission is granted to make and distribute verbatim copies of 0028 this manual provided the copyright notice and this permission notice 0029 are preserved on all copies. 0030 0031 0032 Permission is granted to copy and distribute modified versions of this 0033 manual under the conditions for verbatim copying, provided that the entire 0034 resulting derived work is distributed under the terms of a permission 0035 notice identical to this one. 0036 0037 Permission is granted to copy and distribute translations of this manual 0038 into another language, under the above conditions for modified versions. --> 0039 <!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ --> 0040 <head> 0041 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 0042 <title>\newcommand & \renewcommand (LaTeX2e unofficial reference manual (November 2018))</title> 0043 0044 <meta name="description" content="\newcommand & \renewcommand (LaTeX2e unofficial reference manual (November 2018))"> 0045 <meta name="keywords" content="\newcommand & \renewcommand (LaTeX2e unofficial reference manual (November 2018))"> 0046 <meta name="resource-type" content="document"> 0047 <meta name="distribution" content="global"> 0048 <meta name="Generator" content="makeinfo"> 0049 <link href="index.html#Top" rel="start" title="Top"> 0050 <link href="IndexDocument.html#Index" rel="index" title="Index"> 0051 <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 0052 <link href="Definitions.html#Definitions" rel="up" title="Definitions"> 0053 <link href="_005cprovidecommand.html#g_t_005cprovidecommand" rel="next" title="\providecommand"> 0054 <link href="Definitions.html#Definitions" rel="prev" title="Definitions"> 0055 <style type="text/css"> 0056 <!-- 0057 /* $Id: latex2e.css 690 2018-09-15 15:20:19Z jimhefferon $ 0058 Minor css for latexrefman. Public domain. 0059 Originally written by Jim Hefferon and Karl Berry, 2018. */ 0060 0061 /* So you can style for yourself */ 0062 @import url("/css/latexreflocal.css"); 0063 0064 0065 0066 a.summary-letter {text-decoration: none} 0067 blockquote.indentedblock {margin-right: 0em} 0068 blockquote.smallindentedblock {margin-right: 0em; font-size: smaller} 0069 blockquote.smallquotation {font-size: smaller} 0070 div.display {margin-left: 3.2em} 0071 div.example {margin-left: 3.2em} 0072 div.lisp {margin-left: 3.2em} 0073 div.smalldisplay {margin-left: 3.2em} 0074 div.smallexample {margin-left: 3.2em} 0075 div.smalllisp {margin-left: 3.2em} 0076 kbd {font-style: oblique} 0077 pre.display {font-family: inherit} 0078 pre.format {font-family: inherit} 0079 pre.menu-comment {font-family: serif} 0080 pre.menu-preformatted {font-family: serif} 0081 pre.smalldisplay {font-family: inherit; font-size: smaller} 0082 pre.smallexample {font-size: smaller} 0083 pre.smallformat {font-family: inherit; font-size: smaller} 0084 pre.smalllisp {font-size: smaller} 0085 span.nolinebreak {white-space: nowrap} 0086 span.roman {font-family: initial; font-weight: normal} 0087 span.sansserif {font-family: sans-serif; font-weight: normal} 0088 ul.no-bullet {list-style: none} 0089 BODY { 0090 margin-top: 1em; 0091 margin-left: 1em; /* auto results in two-digit <ol> lost off left */ 0092 margin-right: 1em; 0093 margin-bottom: 1em; 0094 /* the idea is to use the whole window, unless it is ridiculously 0095 wide, probably with too-small fonts, too. */ 0096 max-width: 64em; 0097 } 0098 0099 /* Because we want @math{... @code ...} to be upright, not slanted, 0100 and Texinfo won't fix it. */ 0101 code {font-style:normal; font-family:monospace; } 0102 0103 /* We put a link to our own home page at the bottom. */ 0104 div.referenceinfo {font-size:small;} 0105 0106 --> 0107 </style> 0108 0109 0110 </head> 0111 0112 <body lang="en"> 0113 <a name="g_t_005cnewcommand-_0026-_005crenewcommand"></a> 0114 <div class="header"> 0115 <p> 0116 Next: <a href="_005cprovidecommand.html#g_t_005cprovidecommand" accesskey="n" rel="next">\providecommand</a>, Up: <a href="Definitions.html#Definitions" accesskey="u" rel="up">Definitions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="IndexDocument.html#Index" title="Index" rel="index">Index</a>]</p> 0117 </div> 0118 <hr> 0119 <a name="g_t_005cnewcommand-_0026-_005crenewcommand-1"></a> 0120 <h3 class="section">12.1 <code>\newcommand</code> & <code>\renewcommand</code></h3> 0121 0122 <a name="index-_005cnewcommand"></a> 0123 <a name="index-commands_002c-defining-new-ones"></a> 0124 <a name="index-commands_002c-redefining"></a> 0125 <a name="index-defining-a-new-command"></a> 0126 <a name="index-new-commands_002c-defining"></a> 0127 0128 <p>Synopses, one of: 0129 </p> 0130 <div class="example"> 0131 <pre class="example">\newcommand{\<var>cmd</var>}{<var>defn</var>} 0132 \newcommand{\<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>} 0133 \newcommand{\<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>} 0134 \newcommand*{\<var>cmd</var>}{<var>defn</var>} 0135 \newcommand*{\<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>} 0136 \newcommand*{\<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>} 0137 </pre></div> 0138 0139 <p>or one of these. 0140 </p> 0141 <div class="example"> 0142 <pre class="example">\renewcommand{\<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>} 0143 \renewcommand{\<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>} 0144 \renewcommand{\<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>} 0145 \renewcommand*{\<var>cmd</var>}{<var>defn</var>} 0146 \renewcommand*{\<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>} 0147 \renewcommand*{\<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>} 0148 </pre></div> 0149 0150 <p>Define or redefine a command. See also the discussion of 0151 <code>\DeclareRobustCommand</code> in <a href="Class-and-package-commands.html#Class-and-package-commands">Class and package commands</a>. 0152 <a name="index-starred-form_002c-defining-new-commands"></a> 0153 <a name="index-_002a_002dform_002c-defining-new-commands"></a> 0154 The starred form of these two requires that the arguments not contain 0155 multiple paragraphs of text (in plain TeX terms that it not be 0156 <code>\long</code>). 0157 </p> 0158 <p>These are the parameters: 0159 </p> 0160 <dl compact="compact"> 0161 <dt><var>cmd</var></dt> 0162 <dd> 0163 <p>Required; the command name. It must begin with a backslash, <code>\</code>, 0164 and must not begin with the four letter string <code>\end</code>. For 0165 <code>\newcommand</code>, it must not be already defined. For 0166 <code>\renewcommand</code>, this name must already be defined. 0167 </p> 0168 </dd> 0169 <dt><var>nargs</var></dt> 0170 <dd><p>Optional; an integer from 0 to 9, specifying the number of arguments 0171 that the command takes, including any optional argument. Omitting this 0172 argument is the same as specifying 0, meaning that the command has no 0173 arguments. If you redefine a command, the new version can have a 0174 different number of arguments than the old version. 0175 </p> 0176 </dd> 0177 <dt><var>optargdefault</var></dt> 0178 <dd><p>Optional; if this argument is present then the first argument of 0179 <code>\<var>cmd</var></code> is optional, with default value <var>optargdefault</var> 0180 (which may be the empty string). If <var>optargsdefault</var> is not present 0181 then <code>\<var>cmd</var></code> does not take an optional argument. 0182 </p> 0183 <a name="index-positional-parameter"></a> 0184 <p>That is, if <code>\<var>cmd</var></code> is used with square brackets, as in 0185 <code>\<var>cmd</var>[<var>optval</var>]{...}...</code>, then within <var>defn</var> the 0186 parameter <code>#1</code> is set to the value of <var>optval</var>. On the 0187 other hand, if <code>\<var>cmd</var></code> is called without the square brackets 0188 then within <var>defn</var> the parameter <code>#1</code> is set to the value of 0189 <var>optargdefault</var>. In either case, the required arguments start with 0190 <code>#2</code>. 0191 </p> 0192 <p>Omitting <code>[<var>optargdefault</var>]</code> is different from having the 0193 square brackets with no contents, as in <code>[]</code>. The former sets 0194 <code>#1</code> to the value of <var>optargdefault</var>; the latter sets <code>#1</code> 0195 to the empty string. 0196 </p> 0197 </dd> 0198 <dt><var>defn</var></dt> 0199 <dd><p>Required; the text to be substituted for every occurrence of 0200 <code>\<var>cmd</var></code>. The parameters <code>#1</code>, <code>#2</code>, 0201 ... <code>#<var>nargs</var></code> are replaced by the values that you supply when 0202 you call the command (or by the default value if there is an optional 0203 argument and you don’t exercise the option). 0204 </p> 0205 </dd> 0206 </dl> 0207 0208 <p>TeX ignores spaces in the source following an alphabetic control 0209 sequence, as in ‘<samp>\cmd </samp>’. If you actually want a space there, one 0210 solution is to type <code>{}</code> after the command (‘<samp>\cmd{} </samp>’, and 0211 another solution is to use an explicit control space (‘<samp>\cmd\ </samp>’). 0212 </p> 0213 <p>A simple example of defining a new command: 0214 <code>\newcommand{\RS}{Robin Smith}</code> results in <code>\RS</code> being 0215 replaced by the longer text. Redefining an existing command is similar: 0216 <code>\renewcommand{\qedsymbol}{{\small QED}}</code>. 0217 </p> 0218 <p>If you try to define a command and the name has already been used then 0219 you get something like ‘<samp>LaTeX Error: Command \fred already 0220 defined. Or name \end... illegal, see p.192 of the manual</samp>’. If you try 0221 to redefine a command and the name has not yet been used then you get 0222 something like ‘<samp>LaTeX Error: \hank undefined</samp>’. 0223 </p> 0224 <p>Here the first command definition has no arguments, and the second has 0225 one required argument. 0226 </p> 0227 <div class="example"> 0228 <pre class="example">\newcommand{\student}{Ms~O'Leary} 0229 \newcommand{\defref}[1]{Definition~\ref{#1}} 0230 </pre></div> 0231 0232 <p>Use the first as in <code>I highly recommend \student{} to you</code>. The 0233 second has a variable, so that <code>\defref{def:basis}</code> expands to 0234 <code>Definition~\ref{def:basis}</code>, which ultimately expands to 0235 something like ‘<samp>Definition~3.14</samp>’. 0236 </p> 0237 <p>Similarly, but with two required arguments: 0238 <code>\newcommand{\nbym}[2]{$#1 \times #2$}</code> is invoked as 0239 <code>\nbym{2}{k}</code>. 0240 </p> 0241 <p>This example has an optional argument. 0242 </p> 0243 <div class="example"> 0244 <pre class="example">\newcommand{\salutation}[1][Sir or Madam]{Dear #1:} 0245 </pre></div> 0246 0247 <p>Then <code>\salutation</code> gives ‘<samp>Dear Sir or Madam:</samp>’ while 0248 <code>\salutation[John]</code> gives ‘<samp>Dear John:</samp>’. And 0249 <code>\salutation[]</code> gives ‘<samp>Dear :</samp>’. 0250 </p> 0251 <p>This example has an optional argument and two required arguments. 0252 </p> 0253 <div class="example"> 0254 <pre class="example">\newcommand{\lawyers}[3][company]{#2, #3, and~#1} 0255 I employ \lawyers[Howe]{Dewey}{Cheatem}. 0256 </pre></div> 0257 0258 <p>The output is ‘<samp>I employ Dewey, Cheatem, and Howe</samp>’. The optional 0259 argument, the <code>Howe</code>, is associated with <code>#1</code>, while 0260 <code>Dewey</code> and <code>Cheatem</code> are associated with <code>#2</code> 0261 and <code>#3</code>. Because of the optional argument, 0262 <code>\lawyers{Dewey}{Cheatem}</code> will give the output ‘<samp>I employ 0263 Dewey, Cheatem, and company</samp>’. 0264 </p> 0265 <p>The braces around <var>defn</var> do not define a group, that is, they do not 0266 delimit the scope of the result of expanding <var>defn</var>. For example, 0267 with <code>\newcommand{\shipname}[1]{\it #1}</code>, in this sentence, 0268 </p> 0269 <div class="example"> 0270 <pre class="example">The \shipname{Monitor} met the \shipname{Merrimac}. 0271 </pre></div> 0272 0273 <p>the words ‘<samp>met the</samp>’ would incorrectly be in italics. The solution 0274 is to put another pair of braces inside the definition: 0275 <code>\newcommand{\shipname}[1]{{\it #1}}</code>. 0276 </p> 0277 0278 0279 0280 <hr/><div class='referenceinfo'> <a href='https://latexref.xyz/'> <i>Unofficial LaTeX2e reference manual</i></a></div> 0281 </body> 0282 </html>