Customizing the Content of a TOC
This topic contains tips on customizing the content of your table of contents (TOC), by basing the TOC on elements other than the standard title contexts, using conditions to define the titles that should be included, and specifying the format of the entries.
|
|
Special formatting properties that specify that a title should look different in a TOC to how it looks in the body of the document are ignored in chunked HTML outputs (EPUB, HTML Help, and Web). These online TOCs are generated by the chunker, which only makes reference to those settings that determine which titles should be included
|
Example: Including Generated Titles in a Table of Contents
This procedure describes how to build your table of contents from titles that are not defined in specific title elements, but rather are generated automatically for the semantic divisions in your document. For example, your DTD may define the elements introduction, subject, description, and summary as fixed divisions that must occur in a certain order in the document. These elements do not contain a child title element and as such must each generate their own title to appear at the beginning of the division.
1. In
Arbortext Styler, create an individual generated text setting for each of the semantic division elements so that they will generate their own title in the absence of a specific title element. Refer to
Generating Titles for Divisions Without Title Elements in
Labeling and Numbering Divisions for further information.
If the divisions are already set up in this way, proceed to step 2.
By generating titles using this method, you are creating a substitute title element for each of the divisions by managing a context of a single UFE in each division. It is this pseudo element that will be extracted and included in the final TOC.
2. For the element that is set to generate your table of contents for the whole document, refer to its entry in the
Elements list
. Proceed to its
Generated text category, and note which TOC object it will use the to format the TOC. If this has not been done, make this setting now using the guidelines contained in
Styling an Element to Generate a Table of Contents.
3. Proceed to the
Tables of Contents list
and select the relevant TOC format object. In its properties area, click the
Customize button to open the
Customize Table of Contents dialog box.
4. In the contexts list in the dialog box, check the Include option for each context of the UFE that wraps the title in your divisions. Here you have requested that the pseudo title elements for your divisions should be extracted and included in the TOC.
5. Click OK to exit the Customize Table of Contents dialog box.
6. Choose > to test your TOC settings. You should see that the titles of the divisions are included in the TOC, with their page numbers, as usual.
Example: Controlling TOC Entries Based on Conditions
This procedure describes how to specify the conditions that must be matched for a division's title to be included in a table contents (TOC). When creating conditions for TOCs, you have access to the same types of test as when creating conditions for elements or contexts:
• Attribute test
• Content test
• XPath test
• Start of HTML chunk test
This example is based on the sample document transport.xml, located in your Arbortext Editor environment at Arbortext-path/samples/styler, and its associated stylesheet.
1. In the document, note that the
toc element appears before the first chapter to generate the table of contents for the whole document. Refer to the
toc everywhere else context in the
Elements list
in
Arbortext Styler, and go to its
Generated text category. You will see that it is set to use the
Book Table of Contents TOC object to format the TOC.
2. Go to the
Tables of Contents list
and select the
Book Table of Contents object.
Click the Customize button in the properties area of the list to open the Customize Table of Contents dialog box.
3. Click the Add button next to the Condition each title must match field. The Table of Contents Condition dialog box opens.
4. Use the functionality of the dialog box to create conditions based on the test type you require. The next four steps of the procedure each give an example of the available tests. For each one, click the button that relates to the type of test then use the dialog box that opens to create the test.
5. Attribute test - this example will create a test based on the toc=”yes” attribute being set for a division
a. Click the New Attribute Test button to open the Attribute Test dialog box.
b. Configure the following settings in the dialog box:
▪ Test attribute of : parent
▪ Attribute name: toc
▪ Comparison: = yes
Click OK to save the setting and exit the dialog box.
c. The TOC Condition dialog box displays the test attribute “toc”=”yes”
6. Content test - this example will create a test based on the presence of text in a division title, i.e. excluding those titles that have no content from the TOC
a. Click the New Content Test button to open the Content Test dialog box
b. Configure the following settings in the dialog box:
▪ Element whose content to test : current element
▪ Test type: includes
▪ Test depth: top level
▪ Content to test for: text content
Click OK to save the setting and exit the dialog box.
c. The TOC Condition dialog box displays the test element includes text content at top level.
7. XPath test - this example will extract titles both of chapters that have the toc=”yes” attribute set and of sections that include the contents=”1” attribute
a. Click the New XPath Test button to open the XPath Test dialog box.
b. Enter the XPath expression in the Enter an XPath expression field:
parent::chapter/@toc='yes' or parent::section/@contents='1'
Click OK to save the setting and exit the dialog box.
c. The TOC Condition dialog box displays the test XPath expression (parent::chapter/@toc='yes' or parent::section/@contents='1') is true
8. Start of HTML chunk test - this example will extract titles whose parent division appears at the top of an HTML chunk
| Only use HTML chunk tests in TOC conditions if the TOC is used for chunked HTML outputs and is not used in any other outputs. HTML chunk tests are always false in other outputs. |
a. Click the New Chunk Test button to open the Start of HTML Chunk Test dialog box.
b. Configure the following settings in the dialog box:
▪ At start of HTML chunk
▪ Element to test: Parent element
Click OK to save the setting and exit the dialog box.
9. Note that you can define as many tests of any of these types in the TOC Condition dialog box. Select All tests are true or Any test is true to define which of the listed tests should be matched.
10. Click OK to exit the dialog box. The condition any title must match field in the Custom Content dialog box shows a summary of the condition(s) that must be matched in order for the title contexts given the Include setting to be included in the TOC.
11. Click OK to exit the dialog box.
12. Choose > . In the print preview window, note that the titles that match the condition(s) you described in the Custom Content dialog box are included in the TOC.
Example: Changing a Title's Punctuation in its TOC Entry
This procedure describes how to amend the punctuation of a second level division title when it appears in a table of contents (TOC), by specifying that a period should come after the final section number in its compound numbering. The title itself, when appears in the body of the document, will not include the period, neither will those titles in the TOC that are based on first level divisions.
This example is based on the sample document transport.xml, located in your Arbortext Editor environment at Arbortext-path/samples/styler, and its associated stylesheet.
1. In the document, note that the
toc element appears before the first chapter to generate the table of contents for the whole document. Refer to the
toc everywhere else context in the
Elements list
in
Arbortext Styler, and go to its
Generated text category. You will see that it is set to use the
Book Table of Contents TOC object to format the TOC.
2. Navigate to the
Tables of Contents list
and select the
Book Table of Contents object.
3. Click the Customize button in the properties area of the list to open the Customize Table of Contents dialog box.
4. Navigate to the title in sect1 context in the contexts list in the dialog box, and click its Add button to open the Custom Content dialog box. Click the Edit button next to the Number field to open the Custom Number generated text editor. You will see that the field contains an ElementLabelAndNumber element, which defines the title's numbering in the TOC.
5. Place your cursor after the ElementLabelAndNumber element and enter a period. Choose > to save the changes to the number and exit the editor.
6. Note that the additional period is displayed in the Number field in the Custom Content dialog box. Click OK to exit the Custom Content dialog box.
7. Note that the Add button for the title in sect1 context in the Customize Table of Contents dialog box has now changed to Edit as you have added some custom content. Click OK to exit the Customize Table of Contents dialog box.
8. Choose PreviewPrint. In the print preview window, note that the TOC entry for the title of the only sect1 element in the document contains the additional period, making it 2.1. Employee information - for internal use only. The titles in the TOC that are based on chapter elements in the document do not display the additional period. If you refer back to the title of the sect1 element in the body of the document you will see that it does not contain the additional period either.
Example: Changing a Title's Numbering Scheme in its TOC Entry
This procedure describes how to amend the numbering of division titles when they appear in a table of contents (TOC), by specifying that they should be bulleted or hyphenated rather than numbered. The titles themselves, when they appear in the body of the document, will be numbered based on a compound numbering scheme.
This example is based on the sample document transport.xml, located in your Arbortext Editor environment at Arbortext-path/samples/styler, and its associated stylesheet.
1. In the document, note that the
toc element appears before the first chapter to generate the table of contents for the whole document. Refer to the
toc everywhere else context in the
Elements list
in
Arbortext Styler, and go to its
Generated text category. You will see that it is set to use the
Book Table of Contents TOC object to format the TOC.
2. Navigate to the
Tables of Contents list
and select the
Book Table of Contents object.
3. Click the Format button in the properties area of the list to open the Table of Contents Format dialog box. Note in the preview window that the TOC is currently set to generate compound numbers based on its divisions, i.e. 1, 1.1, 1.1.1, etc. Close the dialog box.
4. Click the Customize button in the properties area of the list to open the Customize Table of Contents dialog box.
5. Navigate to the title in chapter context in the contexts list in the dialog box, and click its Add button to open the Custom Content dialog box. Click the Edit button next to the Number field to open the Custom Number generated text editor. You will see that the field contains an ElementLabelAnd Number element, which defines the title's numbering in the TOC.
6. Delete the ElementLabelAnd Number tag. Choose the > menu option to insert a symbol, select the Bullet character and click Insert. Close the Insert Symbol dialog box. The Custom Number editor now contains a bullet character.
7. Click > to save the numbering setting and exit the editor. Note that the bulleted numbering setting is displayed in the Number field in the Custom Content dialog box.
8. Click OK to exit the Custom Content dialog box. Note that the Add button for the title in chapter context in the Customize Table of Contents dialog box has now changed to Edit as you have added some custom content.
9. Repeat steps 5–8 for the title in sect1 context, adding a hyphen character (-) as the symbol for its number symbol.
10. Choose > . In the print preview window, note that the TOC contains bulleted chapter titles, and section titles numbered with a hyphen. If you refer to the same titles in the body of the document, however, you will see that they are numbered according the original compound numbering scheme.
11. If you want to format the positioning of the bullet and hyphen characters, navigate to the Book Table of Contents object and click the Format button to open the Table of Contents Format dialog box. You can make the required settings for indentation and alignment for each level of the TOC here.
Example: Including Additional Generated Text in a TOC Entry
This procedure describes how to supplement an entry in a TOC with additional generated text extracted from another element. In this case, we will add the title of the chapter to the title of sections in that chapter, when the section titles appear in the TOC. When the section appears in the body of the document its title will not include the chapter information.
This example is based on the sample document transport.xml, located in your Arbortext Editor environment at Arbortext-path/samples/styler, and its associated stylesheet.
1. In the document, note that the
toc element appears before the first chapter to generate the table of contents for the whole document. Refer to the
toc everywhere else context in the
Elements list
in
Arbortext Styler, and go to its
Generated text category. You will see that it is set to use the
Book Table of Contents TOC object to format the TOC.
2. Navigate to the
Tables of Contents list
and select the
Book Table of Contents object.
3. Click the Customize button in the properties area of the list to open the Customize Table of Contents dialog box.
4. Navigate to the title in sect1 context in the contexts list in the dialog box, and click its Add button to open the Custom Content dialog box. Click the Edit button next to the Text field to open the Custom Text generated text editor. You will see that the field contains an ElementContent element, which defines the title's text label in the TOC.
5. Place your cursor before the ElementContent element, and choose the > menu option to add content from a second element. The Insert Element Content dialog box opens.
6. Configure the following settings in the dialog box:
◦ Select the by name and occurrence-within-ancestor option
◦ Name: title
◦ Occurrence: 1st
◦ Within: chapter
◦ Insert: Only content
Click OK to save the setting and exit the dialog box.
7. Add a separator between the two ElementContent elements if required, for example a colon. Click > to save the generated text and exit the editor. The Text field in the Custom Content dialog box now displays the updated generated text setting for the title's TOC label.
8. Click OK to exit the dialog box.
9. Click OK to exit the Customize Table of Contents dialog box.
10. Choose > . In the print preview window, note that the only second level entry in the TOC is shown as 2 Water - the Cruise Ship: Employee information - for internal use only. Here the title is made up of the title of the chapter to which the sect1 element belongs, followed by the sect1's own title, separated by a colon.
11. Refer to the sect1 element in the body of the document - you will see that it still displays just its own title.
Create Lists of Tables and Graphics
This procedure describes how to create a list of tables and a list of graphics n your document. You will also set tables and graphics from the document to be numbered according to two separate numbering schemes, so that their numbers in the lists in which they appear are consecutive. The lists will be generated from two separate table of contents format objects, one that includes titles in table elements as its entries, and one that includes titles in graphic elements. The lists will have different titles, produced in the document via generated text.
This example is based on the sample document transport.xml, located in your Arbortext Editor environment at Arbortext-path/samples/styler, and its associated stylesheet. Some of the steps may have already been completed for you - if so, skip to the next step.
1. In the Elements list, set the title element to be of Title style via the > menu option.
2. Set the figure element to be of Formal Block style. Arbortext Styler creates a context for the title in a figure, i.e. title in figure, and sets it to generate a number.
3. Select the title in figure context and copy and paste it.
4. In the New Context dialog box that opens, select the figure node in the hierarchy and select XPath Predicate in the Position list.
5. Enter the predicate ./informaltable in the field in the XPath Predicate dialog box. Here you have specified that this context will only match titles in figures that contain an informaltable element. Once you have saved the change and exited the dialog boxes, the context title in figure[./informaltable] will appear in the Elements list.
6. Navigate to the Generated text category for the context. Set the context to be numbered by selecting the Number option in the Numbers and bullets field.
7. Click the Details button in the Numbers and Bullets field to open the relevant title numbering dialog box and configure the numbering for the title.
8. Select (new) in the Custom counter field, and enter a name for the counter that will count occurrences of a table figure, e.g. figure-table. Click OK to exit the New custom counter dialog box.
9. Make any other changes to the formatting of the number you desire, for example add the text Table followed by a space in the Label field. Click OK to exit the title numbering dialog box.
10. Repeat steps 3–9 to create a context of the title element that will only match titles in figures that contain graphics. Use the XPath predicate ./graphic, create the custom counter figure-graphic, and set the label Graphic in the title numbering dialog box.
11. You have now configured Arbortext Styler to number tables and graphics according to two separate numbering schemes. The next step is to create two tables of contents in your document, one to include all titles of informal tables and the other to include all titles of graphics.
12. Create a new table of contents format object called “List of Tables”, and set it to include formal block titles only. In the Formal block element field, select figure from the drop down list.
13. Click the Customize button to open the Customize Table of Contents dialog box. The dialog box contains a list of all element contexts configured in the stylesheet but only figure-related contexts are selected for inclusion in the table of contents. Deselect all other figure contexts except title in figure [./informaltable]. Here you have specified that the table of contents “List of Tables” should only include titles of figures that contain informaltable elements. Click OK to exit the dialog box.
14. In the Elements list, create a new context of the toc element. Set the context to match the second occurrence of the toc element in the book element, using the XPath predicate 2 for the toc node in the New Context dialog box. When finished, the context toc[2] in book will appear in the Elements list.
15. Navigate to the Generated text category for the context. Click the Edit button next to the After-text field to open the Generated Text Editor. Select > and select the List of Tables TOC object from the list in the Insert Table of Contents dialog box. Click > to exit the Generated Text Editor.
16. Create the context title in toc[2] in book for the title element. In the Generated text category for the context, set the title text List of Tables to appear before element content.
You have now configured a table of contents that will generate a list of tables in your document.
17. Repeats steps 12–13 to create a table of contents format object called List of Graphics, which includes only the figure context title in figure[./graphic].
18. Repeat steps 14–15 to create the context for the third occurrence of the toc element in the book, i.e. toc[3] in book, and assign the List of Graphics TOC object to that context.
19. Repeat step 16 to create the title in toc[3] in book context, and set it to generate the title List of Graphics.
20. In the transport.xml document, add two more toc elements after the existing one at the beginning of the document. Add a title child element for each toc element.
21. Back in Arbortext Styler click > to generate a preview of the printed document. You will note that the document now contains three tables of contents -Contents, List of Tables, and List of Graphics.
If you want to generate lists that contain entries, add figure elements with titles in your document, and give them graphic or informaltable children. You will note two things when you regenerate the print preview:
a. The titles of the graphic and informaltable elements will be numbered, and counted according to their separate counting schemes.
b. The List of Tables and List of Graphics lists will include links to titles of these figures.
Including a Title that Contains Footnotes
If you elect to include a title that contains footnotes in your table of contents, you may encounter error messages of the form shown below when composing your document:
[A12531] ERROR: Styldesc counter variable "cnt__footnote_default_footnotes.cnt"
is modified in the pagedesc.
You will also see the footnote reference in the title, and a footnote will appear on the page.
To avoid this situation, create the context footnote anywhere in _sfe:xxxx for the relevant generated text element, and set the value of the Hidden field in the Text category to Yes for that context. For example, if you create the context footnote anywhere in _sfe:Table of Contents, it will be matched for footnotes in tables of contents and neither the footnote reference nor footnote will appear when the title appears in the table of contents. As another example, you could create the context footnote anywhere in _sfe:Gentext. In this case you will ensure that footnote references will be hidden when the title appears in headers, footers, tables of contents, and cross references.
