An example SPS file to demonstrate the basic use of TOCs, called ChaptersSimple.sps, is in the (My) Documents folder, C:\Documents and Settings\<username>\My Documents\Altova\StyleVision2019\StyleVisionExamples\Tutorial\TOC. This SPS is based on a schema that defines the content model of a large chapter-based document. The schema structure is shown in the screenshot below and can be viewed in the Schema Tree window of StyleVision when you open ChaptersSimple.sps. (A more complex TOC example based on the same schema is described in the next section of this documentation, Example: Hierarchical and Sequential TOCs.)
The document element is helpproject, which contains a child topics element. The topics element can contain an unlimited number of topic elements, each of which can in turn contain descendant topic elements. The first level of topic elements can be considered to be the chapters of the document, while descendant topic elements are sections, sub-sections, and so on.
This SPS creates a TOC, located at the top of the document, which lists the names of each chapter (the first-level topics). Creating the TOC involves three steps:
|1.||Structuring the design in TOC levels: One or more levels are inserted in the design document to structure the (output) document hierarchically. This hierarchic structure will be the one that the TOC reflects. In our current example, to keep things simple, only one TOC level has been created—on the Topic template. Because there is only one level in the design, the TOC template—when it is created subsequently—can have only one level in its structure (i.e. one level reference).|
|2.||Creating TOC bookmarks: A TOC bookmark is created within the TOC level that was created in Step 1 (in the design document). This enables TOC references in the TOC template (which will be created in the next step) to point back to this TOC bookmark. The TOC bookmark also specifies the text that will appear in the TOC item that points to it.|
|3.||Creating the TOC template: This is the template that creates the TOC in the document. It is structured into level references (levelrefs), which must correspond to the structure of TOC levels in the design document. For example if there are three nested levelrefs in the TOC template, then the design document must have at least three nested levels. In this example we have a single levelref to correspond to the single TOC level in the design document. It is within the levelref that the TOC reference (TOCref) is placed. It is this TOCref that generates the TOC items for this level in the TOC.|
SPS structure and levels
Look at the structure of the design in the SPS. Notice that the main template (with the green $XML tags) contains the TOC. The rest of the main template specifies, through the rest-of-contents instruction, that global and default templates are to be applied. The rest of the SPS design—outside the main template and after it—consists of global templates.
The TOC definitions (TOC levels and TOC bookmarks in the design) are in the global template for topic (screenshot below). In this global template a condition has been inserted to separate topic elements according to how many ancestor topic elements each has, thus providing separate processing (within different conditional branches) for chapters, sections, and sub-sections.
The screenshot above shows the contents of the first conditional branch, for first-level, chapter-type topic elements. Note that a TOC level has been created on the template start-tag of this topic element. In the other two conditional branches no TOC level has been created on the topic template. As a result, the document has been assigned only one TOC level, and this is at the level of the first-level (chapter-type) topic element.
Creating the TOC bookmark
A TOC bookmark (yellow tags in screenshot below) has been created within the header descendant element of topic (but outside the para element). This TOC bookmark serves as an anchor for every top-level, chapter-type topic element..
The properties of the TOC bookmark can be edited in the Properties sidebar (screenshot below).
The Group property sets the TOC bookmark group (and is the name of the TOC bookmark). In our example, we have specified the value MyTOC for this property. The bookmark group will be referenced in the TOC when it is created, and it enables different TOC groups to be specified within the same level. The ID property enables unique IDs to be specified for the bookmark instances created. The Remove if not referenced property is an option to remove the bookmark if it is not referenced. The Text From property specifies the text entry that will be used as the text of the TOC item in the TOC. The text could come from the bookmark's content (the content between the start and end tags of the bookmark in the design) or from an XPath expression. In our example, an XPath expression is used which returns the header text, respectively, of each first-level topic element.
Inside the TOC template (screenshot below), a single Level Reference (levelref) has been inserted. This levelref corresponds to the TOC Level assigned on the first-level, chapter-type topic element in the design (see 'SPS Structure and Levels' above).
Within this levelref, a TOC reference (TOCref) has been inserted. This TOCref has been set to select bookmarks (i) that are in the bookmark group named MyTOC (see 'Creating the TOC bookmark' above), and (ii) that are within the scope of the current level only. These settings can be made in the Properties sidebar when the TOCref is selected, or by right-clicking the TOCref in the design and selecting the relevant editing command from the context menu..
The appearance of the TOC item is specified within the TOCref tags of the TOC. The numbering format, the text, the leader, and the page reference can be inserted by right-clicking within the TOCref tags and selecting the component to insert from the context menu. Each of these components can be edited by selecting it in the design and modifying its properties in the Properties sidebar.
© 2019 Altova GmbH