12

I've been under, apparently, the misapprehension that if you have defined an environment called <env_name> then \begin<env_name> and \<env_name> accomplish the same thing. But considering @egreg 's admonishment and my attempts to implement his suggestion, I see that I'm quite wrong.

Occasionally I want to define a new environment, or a command that invokes an environment, in a manner where too early expansion of \begin{<env_name>} will result in errors. Here's a MWE of what I'm thinking of:

\documentclass{article}
\usepackage{pgfkeys}
\usepackage{fancyvrb}
\makeatletter
\pgfkeys
  {
    /ae/mwe/.is family,
    /ae/mwe,
   usegobble/.initial=,
   gobble/.style = { usegobble={gobble=#1,} },
  }
\newenvironment{aetestingmwe}[1][]
  {%%'
    \pgfqkeys{/ae/mwe}{#1}%%'
    \edef\ae@begin@verbatim
      {%%'
        \noexpand\Verbatim[\pgfkeysvalueof{/ae/mwe/usegobble}]}%%'
    \ae@begin@verbatim
  }
  {
    \endVerbatim
  }
\makeatother
\pagestyle{empty}
\begin{document}

\begin{aetestingmwe}
  [
    gobble=2,
  ]
  \textbf{Random stuff}
This line will get decapitated!
\end{aetestingmwe}

\end{document}

If I try to define the environment as

\newenvironment{aetestingmwe}[1][]
  {%%'
    \pgfqkeys{/ae/mwe}{#1}%%'
    \begin{Verbatim}[\pgfkeysvalueof{/ae/mwe/usegobble}]
  }
  {
    \end{Verbatim}
  }

I'll get an error:

! Package keyval Error: gobble=2, undefined.

See the keyval package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              

l.27   ]

?              

So it seems that it is sometimes necessary to use \<env_name> in place of \begin{<env_name>}.

How do I know when it's safe to assume these two are the same? When are they different? Does it matter whether the environment was defined using low level commands or LaTeX's \newenvironment? What about environments created using xparse?

  • 1
    The only environments that are unsafe in this respect are document and lrbox that, for different reasons, issue \endgroup in the starting part and \begingroup in the finishing part. Verbatim environment definitions should never use \begin and \end in their arguments. – egreg Jul 29 '13 at 21:58
8

\begin{<env_name>} and \<env_name> almost never do the same thing.

In the usual case

\begin{<env_name>}

is (apart from error checking) the same as

\begingroup\<env_name>

The extra grouping may or may not matter depending on the code in question.

So what are the unusual cases ...

  • document

    For efficiency reasons the document environment doesn't form a group. The definition of \document starts with \endgroup so if you use \document on its own you would get an error, but as noted above the thing you should be comparing to is \begingroup\document which would in fact work. (But you shouldn't be nesting document environments anyway.)

  • lrbox

    As with document, lrbox requires the outer group so you need to use \begingroup\lrbox... \endlrbox\endgroup if you want to avoid the environment form. Here the issue is that lrbox locally saves its contents in a box register so uses some \aftergroup trickery so the box register has that value after the environment. If you use \lrbox not surrounded by a group then this \aftergroup token will appear somewhere but probably not where you intended.

  • Environments with \ignorespacesafterend in their end-code.

    This command just sets a boolean flag which is picked up in the definition of \end which causes it to issue \ignorespaces. So if you use \end<env_name> instead of \end{env_name} the \ignorespaces will be issued by the \end that does end the current group, will not be issued at all if the group ends with } or \endgroup explicitly. This may be the behaviour you want but it is in any case a difference.

  • verbatim-like environments

    Inside verbatim and similar macros \end does not trigger the command \end as \ is not special, \end is just the four tokens \ e n d . So that it works like an environment the definition uses a delimited argument macro defined as if by

    \def\@@@something#1\end{verbatim}{...}
    

    This means that the expected environment name such as \end{verbatim} has to appear literally in the document. \endverbatim (even with a suitable catcode setup) will not form the end delimiter for such a macro.

    In the original verbatim definition in LaTeX, verbatim is explicit in the code so the environment can not be nested in macros at all. The verbatim (and most late packages) make this a bit more flexible in that if you use \verbatim rather than \begin{verbatim} the \verbatim code will pick up the name of the current environment and use that to define the delimited macro (or other tests) that terminate the environment. Thus Verbatim and listings etc can be nested in another environment definition if they are called as macros but not if the \begin \end form is used internally.

  • environments that grab their body as a macro argument.

    Some environments (notably and possibly originally amsmath environments such as align), tabularx, and any environment defined via the environ package definitions. use a mechanism similar to that described above for verbatim to grab their body via a macro argument (and defined as the macro \BODY in the case of environ.

  • Very thorough write up. I appreciate the details. – A.Ellett Sep 8 '13 at 15:26

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.