12.8 \newenvironment & \renewenvironment ¶

Synopses, one of:

\newenvironment{env}{begdef}{enddef}
\newenvironment{env}[nargs]{begdef}{enddef}
\newenvironment{env}[nargs][optargdefault]{begdef}{enddef}
\newenvironment*{env}{begdef}{enddef}
\newenvironment*{env}[nargs]{begdef}{enddef}
\newenvironment*{env}[nargs][optargdefault]{begdef}{enddef}

or one of these.

\renewenvironment{env}{begdef}{enddef}
\renewenvironment{env}[nargs]{begdef}{enddef}
\renewenvironment{env}[nargs][optargdefault]{begdef}{enddef}
\renewenvironment*{env}{begdef}{enddef}
\renewenvironment*{env}[nargs]{begdef}{enddef}
\renewenvironment*{env}[nargs][optargdefault]{begdef}{enddef}

Define or redefine the environment env, that is, create the construct \begin{env} ... body ... \end{env}.

The starred form of these commands requires that the arguments not contain multiple paragraphs of text. However, the body of these environments can contain multiple paragraphs.

env

Required; the environment name. It consists only of letters or the * character, and thus does not begin with backslash, \. It must not begin with the string end. For \newenvironment, the name env must not be the name of an already existing environment, and also the command \env must be undefined. For \renewenvironment, env must be the name of an existing environment.

nargs

Optional; an integer from 0 to 9 denoting the number of arguments of that the environment takes. When you use the environment these arguments appear after the \begin, as in \begin{env}{arg1} ... {argn}. Omitting this is equivalent to setting it to 0; the environment will have no arguments. When redefining an environment, the new version can have a different number of arguments than the old version.

optargdefault

Optional; if this is present then the first argument of the defined environment is optional, with default value optargdefault (which may be the empty string). If this is not in the definition then the environment does not take an optional argument.

That is, when optargdefault is present in the definition of the environment then you can start the environment with square brackets, as in \begin{env}[optval]{...} ... \end{env}. In this case, within begdefn the parameter #1 is set to the value of optval. If you call \begin{env} without square brackets, then within begdefn the parameter #1 is set to the value of the default optargdefault. In either case, any required arguments start with #2.

Omitting [myval] in the call is different than having the square brackets with no contents, as in []. The former results in #1 expanding to optargdefault; the latter results in #1 expanding to the empty string.

begdef

Required; the text expanded at every occurrence of \begin{env}. Within begdef, the parameters #1, #2, ... #nargs, are replaced by the values that you supply when you call the environment; see the examples below.

enddef

Required; the text expanded at every occurrence of \end{env}. This may not contain any parameters, that is, you cannot use #1, #2, etc., here (but see the final example below).

All environments, that is to say the begdef code, the environment body, and the enddef code, are processed within a group. Thus, in the first example below, the effect of the \small is limited to the quote and does not extend to material following the environment.

If you try to define an environment and the name has already been used then you get something like ‘LaTeX Error: Command \fred already defined. Or name \end... illegal, see p.192 of the manual’. If you try to redefine an environment and the name has not yet been used then you get something like ‘LaTeX Error: Environment hank undefined.’.

This example gives an environment like LaTeX’s quotation except that it will be set in smaller type.

\newenvironment{smallquote}{%
  \small\begin{quotation}
}{%
  \end{quotation}
}

This has an argument, which is set in boldface at the start of a paragraph.

\newenvironment{point}[1]{%
  \noindent\textbf{#1}
}{%
}

This one shows the use of a optional argument; it gives a quotation environment that cites the author.

\newenvironment{citequote}[1][Shakespeare]{%
  \begin{quotation}
  \noindent\textit{#1}: 
}{%
  \end{quotation}
}

The author’s name is optional, and defaults to ‘Shakespeare’. In the document, use the environment like this.

\begin{citequote}[Lincoln]
  ...
\end{citequote}

The final example shows how to save the value of an argument to use in enddef, in this case in a box (see \sbox & \savebox).

\newsavebox{\quoteauthor}
\newenvironment{citequote}[1][Shakespeare]{%
  \sbox\quoteauthor{#1}%
  \begin{quotation} 
}{%
  \hspace{1em plus 1fill}---\usebox{\quoteauthor}
  \end{quotation}
}