setoptions

The setoptions extension implements a non-standard \setOptions macro that allows you to change the options for a TeX package, or for the TeX input jax itself, from within a TeX expression.

\setOptions[package]{options}

Sets the options for package to the ones given in options. Here, options is a collection of space-separated option names (to be set to true) or option=value declarations, where the given option will get the specified value. If the value contains spaces, it can be enclosed in braces, which will not become part of the value.

For example:

\[
  \setOptions{tagSide=left}
  E = mc^2 \tag{1}
\]

\[
  \setOptions{tagSide=right}
  e^{\pi 1} + 1 = 0 \tag{2}
\]

would typeset the first expression with its tag on the left, and the second (and subsequent) expressions with tags on the right.

To change a package setting, use the package name as an optional bracket argument:

\[
  \setOptions[physics]{arrowdel=true}
  \grad
  \setOptions[physics]{arrowdel=false}
\]

Here the gradient symbol with have an arrow, but subsequent ones will not.

Note that any changes made by \setOptions are global, so will affect all the following expressions. If you want a local change, you will need to set the value back to its original one explicitly.

Because changing the option settings can cause adverse consequences, and so could be misused in a setting where users are provided the TeX content for your site, the setoptions package is not autoloaded, it does not appear in the list of all packages, and it can not be loaded with \require{}. You must include it in the package list explicitly if you want to allow its use.

To load the setoptions extension, add '[tex]/setoptions' to the load array of the loader block of your MathJax configuration, and add 'setoptions' to the packages array of the tex block.

window.MathJax = {
  loader: {load: ['[tex]/centernot']},
  tex: {packages: {'[+]': ['centernot']}}
};

---

The require command with setoptions

If the require package is enabled, setoptions modifies \require to allow passing of options for the required package (and makes the original \require macro available as \Require). So the new syntax is:

\require[options]{package}

where options is a list of options in the same format as used by \setOptions, and package is the name of the extension to load. This command is equivalent to:

\Require{package}\setOptions[package]{options}

meaning that the package is loaded and then its options are set.

For example:

\require[harrowsize=3em]{amscd}

would load the amscd extension and then set its harrowsize option to 3em.

Note that the same rules apply to which options can be set for which package as those that govern \setOptions itself.

---

setoptions Options

Adding the setoptions extension to the packages array defines a setoptions sub-block of the tex configuration block with the following values:

MathJax = {
  tex: {
    setoptions: {
      filterPackage: SetOptionsUtil.filterPackage,  // filter for whether a package can be configured
      filterOption: SetOptionsUtil.filterOption,    // filter for whether an option can be set
      filterValue: SetOptionsUtil.filterValue,      // filter for the value to assign to an option
      allowPackageDefault: true,       // default for allowing packages when not explicitly set in allowOptions
      allowOptionsDefault: true,       // default for allowing option that isn't explicitly set in allowOptions
      allowOptions: {                  // list of packages to allow/disallow, and their options to allow/disallow
        //
        //  top-level tex items can be set, but not these ones
        //    (that leaves digits and the tagging options that can be set)
        //
        tex: {
          FindTeX: false,
          formatError: false,
          package: false,
          baseURL: false,
          tags: false,          // would require a new TeX input jax instance
          maxBuffer: false,
          maxMaxros: false,
          macros: false,
          environments: false
        },
        //
        // These packages can't be configured at all
        //
        setoptions: false,
        autoload: false,
        require: false,
        configmacros: false,
        tagformat: false
      }
    }
  }
};

filterPackage: SetOptionsUtil.filterPackage

This is a function that is called to determine if a package can have its options set or not. It is passed the TeX parser and the name of the extension as its arguments, and returns true if the package allows its options to be configured and false otherwise. The default is to first check that the named package exists, then check if the package is explicitly allowed by its entry in the allowOptions property being either true or a list of the allowOptions property. The entry can either be true, allowing all options of the package to be set, or a list of the options that are allowed to be set. If the entry is explicitly false or the allowPackageDefault option is false, an error is issued. You can supply your own function to process the package names in another way if you wish.

filterOption: SetOptionsUtil.filterOption

This is a function that is called to determine whether an option can be set for a given package. It is passed the TeX parser, the package name, and the option name as its arguments, and returns true if that option can be set for that package, and false otherwise. The default is to check if the option is listed explicitly in the list of options for the given package in the allowOptions. If the value is explicitly false, or if it is not listed and the allowOptionDefault is false, then produce an error. Otherwise check that the option actually exists for the package, and report an error if not, otherwise allow the option to be set. You can supply your own function to process the option names in another way if you wish.

filterValue: SetOptionsUtil.filterValue

This is a function that is called to check the value provided for a given option is allowed. It is passed the TeX parser, the package name, the option name, and the new option value as its arguments, and it returns the value to be used for the option. The default is simply to return the value it is given, but you can use this to alter the value, or to produce an error if the value is not valid.

allowPackageDefault: true

This indicates how to handle packages that are not listed explicitly in the allowOptions list. If true, packages that are not listed are allowed to have their options set. If the value is false, only the packages that are listed as true or have explicit option lists can have their options set.

allowOptionsDefault: true

This indicates how to handle options that are not listed explicitly in the allowOptions list for a given package. If true, options that are not listed are allowed to be set, and if false, only the options that are listed explicitly as true for the given package can have their options set.

allowOptions: {...}

This is a list of the packages that indicates whether their options can be set or not, and which options can be set. If a package name appears and is explicitly set to false, that package’s options can’t be set. If it is true and allowOptionsDefault is true, then any of its options can be set. If it is an explicit list of options, then if the option is listed as true, it can be set, and if false it can not. If an option is not listed, then the value of allowOptionsDefault is used to determine whether it can be set or not. If a package does not appear explicitly in the list, then the value of allowPackageDefault is used to determine if the package’s options can be set or not.

You can include additional package names and their options in this list. The defaults are set to allow reasonable security without having to list every single option that can be set.

---

setoptions Commands

The setoptions extension implements the following macros: \setOptions

---