Bookmarking Items for TOC Inclusion
Bookmarking an item in the design for inclusion in a TOC consists of two steps, which can be done in any order:
1.Structuring the design document in a hierarchy of nested TOC levels. A TOC level can be created in the design either on a template or around a design component. In the screenshot below, a TOC level has been created on the topic template .
When a level is created on a template, this is indicated by the level icon inside the start tag of the template, for example, . When a level is created around a component it is indicated by TOC level tags . In the screenshot above, the topics template component is enclosed by a level. The difference between the two ways of marking levels is explained in the section Structuring the Design in Levels. When the TOC template is created, it must be structured in a hierarchy of levels, with the levels in the TOC template corresponding to the levels you have created in the design. Even for TOCs with a flat structure (one level), the design must have a corresponding level.
2.Creating a TOC bookmark in the design with a name and TOC-item text. The TOC bookmark can either enclose or not enclose a design component; in the latter case it is empty. In the screenshot below, the TOC bookmark does not enclose a design component.
The TOC bookmark serves as an anchor in the document. In the screenshot above, the TOC bookmark (and anchor) is located at the start of para element instances. The TOC bookmark has two attributes: (i) a name that will be used to reference the TOC bookmark when creating the TOC item in the TOC template, and (ii) a text string that will be used as the text of the corresponding TOC item. How these two attributes are assigned is described in the section, Creating TOC Bookmarks.
How bookmarked items are referenced in the TOC template
The TOC template is structured in nested levels (called level references (levelrefs) to differentiate them from the levels created in the main body of the design template). Within each levelref , a TOC reference (TOCref) is inserted (see screenshot below). The TOCref within a levelref references TOC bookmarks using the TOC bookmark's name. Each TOC bookmark with that name and in the corresponding level in the XML document will be created as a TOC item at this level in the TOC. For example, the TOCref indicated with the tag references all TOC bookmarks named chapters in the corresponding level in the XML document (when the scope of the TOCref has been set to current). The text attribute of the respective instantiated TOC bookmarks will be output as the text of the TOC item.
In the screenshot above of a TOC template, there are three nested levelrefs, within each of which is a TOCref that contains the template for the TOC item of that level. For example, in the first levelref, there is a TOCref that references TOC bookmarks that have a name of MyTOC . As a result, all TOC bookmarks in the first level (as structured in the design) and named MyTOC will be accessed for output at this level in the TOC. The TOCref within the second levelref also references TOC bookmarks having a name of MyTOC. As a result, all TOC bookmarks in the second level of the document and that are named MyTOC will be used for second-level items in the TOC. The third levelref works in the same way: TOC bookmarks named MyTOC that occur within the document's third level are referenced for third-level items in the TOC.
In the sub-sections of this section, we describe: (i) how the design is structured into levels, and (ii) how bookmarks are created. How the TOC template is created is described in the section, Creating the TOC Template.