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>\newenvironment & \renewenvironment (LaTeX2e unofficial reference manual (November 2018))</title> 0043 0044 <meta name="description" content="\newenvironment & \renewenvironment (LaTeX2e unofficial reference manual (November 2018))"> 0045 <meta name="keywords" content="\newenvironment & \renewenvironment (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="_005cnewtheorem.html#g_t_005cnewtheorem" rel="next" title="\newtheorem"> 0054 <link href="_005cnewsavebox.html#g_t_005cnewsavebox" rel="prev" title="\newsavebox"> 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_005cnewenvironment-_0026-_005crenewenvironment"></a> 0114 <div class="header"> 0115 <p> 0116 Next: <a href="_005cnewtheorem.html#g_t_005cnewtheorem" accesskey="n" rel="next">\newtheorem</a>, Previous: <a href="_005cnewsavebox.html#g_t_005cnewsavebox" accesskey="p" rel="prev">\newsavebox</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_005cnewenvironment-_0026-_005crenewenvironment-1"></a> 0120 <h3 class="section">12.8 <code>\newenvironment</code> & <code>\renewenvironment</code></h3> 0121 0122 <a name="index-_005cnewenvironment"></a> 0123 <a name="index-_005crenewenvironment"></a> 0124 <a name="index-environments_002c-defining"></a> 0125 <a name="index-defining-new-environments"></a> 0126 <a name="index-redefining-environments"></a> 0127 0128 <p>Synopses, one of: 0129 </p> 0130 <div class="example"> 0131 <pre class="example">\newenvironment{<var>env</var>}{<var>begdef</var>}{<var>enddef</var>} 0132 \newenvironment{<var>env</var>}[<var>nargs</var>]{<var>begdef</var>}{<var>enddef</var>} 0133 \newenvironment{<var>env</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>begdef</var>}{<var>enddef</var>} 0134 \newenvironment*{<var>env</var>}{<var>begdef</var>}{<var>enddef</var>} 0135 \newenvironment*{<var>env</var>}[<var>nargs</var>]{<var>begdef</var>}{<var>enddef</var>} 0136 \newenvironment*{<var>env</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>begdef</var>}{<var>enddef</var>} 0137 </pre></div> 0138 0139 <p>or one of these. 0140 </p> 0141 <div class="example"> 0142 <pre class="example">\renewenvironment{<var>env</var>}{<var>begdef</var>}{<var>enddef</var>} 0143 \renewenvironment{<var>env</var>}[<var>nargs</var>]{<var>begdef</var>}{<var>enddef</var>} 0144 \renewenvironment{<var>env</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>begdef</var>}{<var>enddef</var>} 0145 \renewenvironment*{<var>env</var>}{<var>begdef</var>}{<var>enddef</var>} 0146 \renewenvironment*{<var>env</var>}[<var>nargs</var>]{<var>begdef</var>}{<var>enddef</var>} 0147 \renewenvironment*{<var>env</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>begdef</var>}{<var>enddef</var>} 0148 </pre></div> 0149 0150 <p>Define or redefine the environment <var>env</var>, that is, create the 0151 construct <code>\begin{<var>env</var>} ... <var>body</var> ... \end{<var>env</var>}</code>. 0152 </p> 0153 <a name="index-_002a_002dform-of-environment-commands"></a> 0154 <p>The starred form of these commands requires that the arguments not 0155 contain multiple paragraphs of text. However, the body of these 0156 environments can contain multiple paragraphs. 0157 </p> 0158 <dl compact="compact"> 0159 <dt><var>env</var></dt> 0160 <dd><p>Required; the environment name. It consists only of letters or the 0161 <code>*</code> character, and thus does not begin with backslash, <code>\</code>. 0162 It must not begin with the string <code>end</code>. For 0163 <code>\newenvironment</code>, the name <var>env</var> must not be the name of an 0164 already existing environment, and also the command <code>\<var>env</var></code> 0165 must be undefined. For <code>\renewenvironment</code>, <var>env</var> must be the 0166 name of an existing environment. 0167 </p> 0168 </dd> 0169 <dt><var>nargs</var></dt> 0170 <dd><p>Optional; an integer from 0 to 9 denoting the number of arguments of 0171 that the environment takes. When you use the environment these 0172 arguments appear after the <code>\begin</code>, as in 0173 <code>\begin{<var>env</var>}{<var>arg1</var>} ... {<var>argn</var>}</code>. Omitting 0174 this is equivalent to setting it to 0; the environment will have no 0175 arguments. When redefining an environment, the new version can have a 0176 different number of arguments than the old version. 0177 </p> 0178 </dd> 0179 <dt><var>optargdefault</var></dt> 0180 <dd><p>Optional; if this is present then the first argument of the defined 0181 environment is optional, with default value <var>optargdefault</var> (which 0182 may be the empty string). If this is not in the definition then the 0183 environment does not take an optional argument. 0184 </p> 0185 <p>That is, when <var>optargdefault</var> is present in the definition of the 0186 environment then you can start the environment with square brackets, as 0187 in <code>\begin{<var>env</var>}[<var>optval</var>]{...} ... \end{<var>env</var>}</code>. 0188 In this case, within <var>begdefn</var> the parameter <code>#1</code> is set to the 0189 value of <var>optval</var>. If you call <code>\begin{<var>env</var>}</code> without 0190 square brackets, then within <var>begdefn</var> the parameter <code>#1</code> is 0191 set to the value of the default <var>optargdefault</var>. In either case, 0192 any required arguments start with <code>#2</code>. 0193 </p> 0194 <p>Omitting <code>[<var>myval</var>]</code> in the call is different than having the 0195 square brackets with no contents, as in <code>[]</code>. The former results 0196 in <code>#1</code> expanding to <var>optargdefault</var>; the latter results in 0197 <code>#1</code> expanding to the empty string. 0198 </p> 0199 </dd> 0200 <dt><var>begdef</var></dt> 0201 <dd><p>Required; the text expanded at every occurrence of 0202 <code>\begin{<var>env</var>}</code>. Within <var>begdef</var>, the parameters 0203 <code>#1</code>, <code>#2</code>, ... <code>#<var>nargs</var></code>, are replaced by the 0204 values that you supply when you call the environment; see the examples 0205 below. 0206 </p> 0207 </dd> 0208 <dt><var>enddef</var></dt> 0209 <dd><p>Required; the text expanded at every occurrence of 0210 <code>\end{<var>env</var>}</code>. This may not contain any parameters, that is, 0211 you cannot use <code>#1</code>, <code>#2</code>, etc., here (but see the final 0212 example below). 0213 </p> 0214 </dd> 0215 </dl> 0216 0217 <p>All environments, that is to say the <var>begdef</var> code, the environment 0218 body, and the <var>enddef</var> code, are processed within a group. Thus, in 0219 the first example below, the effect of the <code>\small</code> is limited to 0220 the quote and does not extend to material following the environment. 0221 </p> 0222 <p>If you try to define an environment and the name has already been used 0223 then you get something like ‘<samp>LaTeX Error: Command \fred already 0224 defined. Or name \end... illegal, see p.192 of the manual</samp>’. If you try 0225 to redefine an environment and the name has not yet been used then you 0226 get something like ‘<samp>LaTeX Error: Environment hank undefined.</samp>’. 0227 </p> 0228 <p>This example gives an environment like LaTeX’s <code>quotation</code> 0229 except that it will be set in smaller type. 0230 </p> 0231 <div class="example"> 0232 <pre class="example">\newenvironment{smallquote}{% 0233 \small\begin{quotation} 0234 }{% 0235 \end{quotation} 0236 } 0237 </pre></div> 0238 0239 <p>This has an argument, which is set in boldface at the start of a 0240 paragraph. 0241 </p> 0242 <div class="example"> 0243 <pre class="example">\newenvironment{point}[1]{% 0244 \noindent\textbf{#1} 0245 }{% 0246 } 0247 </pre></div> 0248 0249 <p>This one shows the use of a optional argument; it gives a quotation 0250 environment that cites the author. 0251 </p> 0252 <div class="example"> 0253 <pre class="example">\newenvironment{citequote}[1][Shakespeare]{% 0254 \begin{quotation} 0255 \noindent\textit{#1}: 0256 }{% 0257 \end{quotation} 0258 } 0259 </pre></div> 0260 0261 <p>The author’s name is optional, and defaults to ‘<samp>Shakespeare</samp>’. In 0262 the document, use the environment like this. 0263 </p> 0264 <div class="example"> 0265 <pre class="example">\begin{citequote}[Lincoln] 0266 ... 0267 \end{citequote} 0268 </pre></div> 0269 0270 <p>The final example shows how to save the value of an argument to use in 0271 <var>enddef</var>, in this case in a box (see <a href="_005csbox-_0026-_005csavebox.html#g_t_005csbox-_0026-_005csavebox">\sbox & \savebox</a>). 0272 </p> 0273 <div class="example"> 0274 <pre class="example">\newsavebox{\quoteauthor} 0275 \newenvironment{citequote}[1][Shakespeare]{% 0276 \sbox\quoteauthor{#1}% 0277 \begin{quotation} 0278 }{% 0279 \hspace{1em plus 1fill}---\usebox{\quoteauthor} 0280 \end{quotation} 0281 } 0282 </pre></div> 0283 0284 0285 0286 0287 <hr/><div class='referenceinfo'> <a href='https://latexref.xyz/'> <i>Unofficial LaTeX2e reference manual</i></a></div> 0288 </body> 0289 </html>