input/tex/extensions/begingroup.rst
.. _tex-begingroup:
########## begingroup ##########
The begingroup extension implements commands that provide a
mechanism for localizing macro definitions so that they are not
permanent. This is useful if you have a blog site, for example, and
want to isolate changes that your readers make in their comments so
that they don't affect later comments.
It defines two new non-standard macros, \begingroup and
\endgroup, that are used to start and stop a local namespace for
macros. Any macros that are defined between the \begingroup and
\endgroup will be removed after the \endgroup is executed.
For example, if you put \(\begingroup\) at the top of each
reader's comments and \(\endgroup\) at the end, then any macros
they define within their response will be removed after it is
processed. Note that \begingroup and \endgroup do not have to
appear within the same expression.
In addition to these two macros, the begingroup extension defines
the standard \global and \gdef control sequences from TeX.
(The \let, \def, \newcommand, and \newenvironment
control sequences are already defined in the :ref:tex-newcommand
package.)
The begingroup package also defines two non-standard macros:
\begingroupReset and \begingroupSandbox. The first
effectively applies \endgroup to any open \begingroup macros,
returning the definitions to the ones that were in effect before the
first \begingroup, plus any new \global definitions.
The \begingroupSandbox macro can be used to isolate the
definitions in one section of the page from those in another, so that
sites, such as question-and-anser sites, can use this between user
posts to make sure that one user's definitions won't affect any other
user's expressions. The \begingroupSandbox macro can't be
redefined, and its action is to remove all the open \begingroup
calls and then start a new local greoup (effectively doing
\begingroupReset\begingroup). This removes any previous user
definitions and makes a new group for the next user's definition.
Furthermore, \global definitions are put into the new
\begingroup so that even if the math includes \global
definitions, they will be removed when the next \begingroupSandbox
command is performed, and will not pollute the next user's macro
namespace.
Any definitions made before the first \begingroupSandbox
invocation is made will be available within all the sandboxes, but
once \begingroupSandbox is performed, there is no going back; the
original macro namespace is no longer accessible to new definitions.
The begingroup package is not autoloaded, so you must request it
explicitly if you want to use it. To load the begingroup extension
explicitly, add '[tex]/begingroup' to the :data:load array of
the :data:loader block of your MathJax configuration, and add
'begingroup' to the :data:packages array of the :data:tex
block.
.. code-block:: javascript
window.MathJax = { loader: {load: ['[tex]/begingroup']}, tex: {packages: {'[+]': ['begingroup']}} };
Alternatively, use \require{begingroup} in a TeX expression to load it
dynamically from within the math on the page, if the :ref:tex-require
extension is loaded.
.. _tex-begingroup-options:
Adding the begingroup extension to the :data:packages array defines an
:data:begingroup sub-block of the :data:tex configuration block with the
following values:
.. code-block:: javascript
MathJax = { tex: { begingroup: { allowGlobal: ["let", "def", "newcommand", "DeclareMathOperator", "Newextarrow"] } } };
.. _tex-begingroup-allowGlobal: .. describe:: allowGlobal: ["let", "def", "newcommand", "DeclareMathOperator", "Newextarrow"]
This lists the commands that can follow the \global command.
Extensions may add to this if they include new macros that can
define global values. Alternatively, you can remove commands from
the list to prevent users from making global definitions.
.. _tex-begingroup-commands:
The begingroup extension implements the following macros:
\begingroup, \begingroupReset, \begingroupSandbox, \endgroup, \gdef, \global
|-----|