Forest

Gallery

5.2 forest-index¶

The indexing system used to document the Forest package uses the package itself quite heavily. While this might be a bit surprising at first sight, as indexing draws no trees, the indexing package illustrates the usage of some of the more exotic features and usage-cases of the Forest package, which is why its source is included in this documentation.¹

This package has three main functions:

• It is possible to index subentries using a short form of their index key, i.e. without referring to their ancestor entries. For example, instead of writing \index{option>content} one can simply write \index{content}. (Obviously, the subentry must “content” be defined as belonging to entry “option” first. This is done using \indexdef{option>content}.) This works for all keys which are a subentry of a single entry.

• All subentries are automatically entered as main entries as well, with a qualificator of which entry they belong to. So, \index{option>content} produces two index entries: entry “option” with subentry “content” and entry “content option”. This works for an arbitrary number of subentry levels.

• Entries can be given options that format the appearance of the entry and/or its descendants in both text and index. (Entries that format the appearance of their descendants are called categories below.)

• If hyperref package is loaded, the following hyperlinks are created besides the standard ones linking the page numbers in index to text:

  

The Forest package mainly enters the picture with respect to the entry formatting. A simple (narrow) tree is built containing an entry and all its ancestors. Formatting instructions are then processed using Forest’s option processing mechanisms.

Finally, note that this package might change without retaining backwards compatibility, and that changes of this package will not be entered into the changelog.

Identification.

Remember the original LaTeX’s \index command.

5.2.1 The user interface macros¶

\index is the general purpose macro. \indexdef and \indexex are shorthands for indexing definitions and examples. \indexitem is a combination of \indexdef and the \item of the lstdoc package. It automatically indexes the command being documented. \indexset neither typesets or indexes the entry, but only configures it; it is usually used to configure categories. All these macros parse their arguments using xparse. The arguments, listed in the reverse order:

• The final argument, which is the only mandatory argument, is a comma-separated list of index keys.

• The boolean switch > just before the mandatory argument signals that the keys are given in the full form. Otherwise, keys without a level separator are considered short.

• Indexing options are given by the [optional ] argument.

• The first (optional) argument of:

  • \indexitem: specifies the default value of the command.

  • \index: is used to provide “early” options.

Among the options of these commands, three keylists are of special importance: index_key_format, index_form_format and print_format. These hold instructions on how to format the index key, the form of the entry in the index and the form of the entry in the main text. They work by modifying the contents of an ⟨autowrapped toks⟩ register result.

An example: how macros are indexed in this documentation. Style macro defined below does everything needed to format a macro name: it detokenizes the given name (in case the name contains some funny characters), prefixes the backslash, wraps in in the typewriter font, adds color and hyperlink (the final two styles are defined in below this package). Note the usage of \protect: it is needed because we want to use these styles to format entries not just in the main next, but also in the index.

Then, we configure the main level entry “macro”: the child of this entry will be formatted (both in index and in the main text) using the previously defined style.

Usage is then simple: we write \indexex{macro>forestoption} (or simply \indexex{forestoption} to get \ forestoption.

All UI macros call this macro.

1. early option keylist

2. late option keylist

3. a comma-sep list of forest index key (full or short form). A key can be given an argument using key=argument syntax. How the argument is used is up to the user. For example, the “environment” entry of the Forest documentation uses it to typeset the contents of the environment:

   copy\indexitem{environment>forest={[\texttt{(}\meta{config}\texttt{)}]\meta{tree}}}


Partition the index keylist into single keys. And put it all in a group: the persistent stuff is saved globally.

Short-key resolution. The result is stored into \forestindex@fullkey.

Manipulate arguments a bit, so that we can use our quick-and-dirty one-arg memoization.

Call the central processing command, style @index. See how .process is used to expand (once) the last argument.

5.2.2 Declarations¶

Should we print and/or index the entry? For example, \index[not_print]{...} will index silently (as LaTeX’s \index command does).

Options name, content, key and argument hold info about the current entry. We need to declare only the latter two, the former two we steal from Forest.

These options will hold first the initial, and then the calculated values of the index key, index form and the form in text. When (late) options are executed, these options are initialized to the value of option key; it is safe to modify them at this point. Afterwards, they will be further processed by keylists index_key_format, index_form_format and print_format, respectively.

The customization of entries’ appearance is done by specifying the following three keylists. The keylists work by modifying register result.

Some shorthands.

Entry types are normal (default), definition, example. Only definitions are special, as their options are automatically saved.

This option is used internally to store the hyper ids.

Some formatting tools need to know whether we’re typesetting text or index: this info is stored in the stage register.

5.2.3 The central processing command¶

1. early option keylist (these are only used to define category “@unknown” at the end of this package)

2. late option keylist

3. index key (full form)

Set the defaults.

Create the tree structure: [entry[subentry[subsubentry...]]]. Three options of every node created:

• key contains the key of the (sub)entry

• name contains the full path to the (sub)entry

• arguments contains the arguments given to the (sub)entry’s key

• content contains the full key, with arguments for all but the most deeply embedded subentry

for nodewalk is used because create@subentry@node walks down the created tree. At if n=0 below, we’re thus positioned at the lowest node.

The components of the full key are separated using split, with different keys being executed for the first component and the rest.

Remove the argument from the most deeply embedded subentry.

Don’t memoize if the key is of an unknown category.

Option print_form is what will be typeset in the text. Option index_key is the key that will be used for sorting the index. Option index_form is what will be typeset in the index. All these are initialized to the key. See how .option is used to assign an option value to another option.

Below, on invalid is set to fake at four points. This is so we won’t get in trouble when \indexsetting the categories: when the category formatting code will try to step into the child, it will fail as the child does not exist when \indexset is called for the category; but we ignore the failure.

Go to the the most deeply embedded subentry.

Execute every index options and the given early options.

Ancestors are walked in the reverse order (top down). At every node, the saved configuration is executed (if it exists).

We don’t execute the saved configuration for definitions, as definitions are where the configuration is set.

Execute late (well, normal) options. See the discussion about early options above.

Remember the given config for the rest of the document.

If we’re at a definition, save the config into the auxiliary file.

Create hyperlink targets of the form .entry.subentry.subsubentry....

Forest points:

Index.

For each (sub)entry, format the index_key using the instructions in index_key_format.

For each (sub)entry, format the index_form using the instructions in index_form_format.

Create an index entry for all nodes where index_form is non-empty.

All the ancestor nodes with an non-empty index_form will be appended (in script size, as a hyperlink) to the index_form of the current node.

Create the hypertarget that the definitions in text and other index entries will point to.

Add the (inner) current node to the index entry of the (outer) current node.

Do the actual indexing.

For each (sub)entry, format the print_form using the instructions in print_form_format.

Typeset the entry in the text.

Create the main entry node and set to be the root.

Create a subentry node and move into it.

Parse #1 into key and argument, and assign name and content.

5.2.4 Saving and loading the options¶

This register holds whatever we need to remember.

Besides storing the keylist in the register, also immediately execute it..

Remember things by saving them in a global style.

Save thinks to the auxiliary file.

Don’t save entries of unknown category.

Don’t save if nothing is set.

Save the full form of the key in the auxiliary file. Obviously, do it only for subentries. The full form contains whatever arguments were given to the non-last component.

Load settings from the auxiliary file into the global style. Warn if anything was configured more than once (e.g. by \indexdefing the same key twice).

Load the full form of a short key from the auxiliary file. Out of kindness for the end user, remember all the full keys corresponding to a short key: this will make a more informative warning below.

5.2.5 Short key resolution¶

Nothing to do for a long key.

Decide whether a key is short or long based on the absence or presence of the level separator >.

Before resolving the short key, we need to split the user input into the key and the argument. The latter is then appended to the full key (which can, in principle, contain arguments for other components as well).

5.2.6 Formatting styles¶

Define default colors for index entry types and provide a style that typesets the entry in text (but not index) in the desired color.

Use this style in ..._format keylists if you want the index entries to be hyperlinks to the definition, and the definition to be a hyperlink to the index.

Color page numbers in the index, with or without hyperref package.

Provide dummy \hyper... commands if hyperref is not loaded.

This is used by entry qualifiers: we want them to be hyperlinks, but black.

Use style item to have the index entry (in text) function as the \item of a lstdoc’s syntax environment.

5.2.7 Utilities¶

We will need a global version of several pgfkeys commands.

Begin and end group, Forest-style:

5.2.8 Memoize¶

Quick and dirty memoization. Single argument macros only. Does not support nesting.

The following two \defs remove one level of hash-doubling from the arguments, introduced by \write.

Commenting the following line turns off memoization.

5.2.9 Initialize¶

Declare category “@unknown”.

Load the auxiliary file made in the previous compilation, and open it for writing to save data from this compilation.