TOC entry and topic file include options

<< Click to Display Table of Contents >>

Navigation:  Reference > Modules, Conditional Output & Variables > Variables and Conditional Output >

TOC entry and topic file include options

Your TOC entries and topic files are actually two separate items: The TOC entries are only links pointing to the topic files. The TOC entry and the topic files also have separate include options. If you work in the TOC you will normally not need to think about this because the matching include options for the associated topic files will be set automatically.

However, the situation is different if you have multiple TOC entries for the same topic in the TOC. Then you need to think about what happens when you set different include options for TOC entries linked to the same topic file.

How build options are applied to TOC entries and topic files

Working in the TOC:

When you work in the Table of Contents section of the Project Explorer setting or changing an include option for the TOC item automatically sets the same option for the topic file to which the TOC entry is linked. Normally this is a 1:1 association and you don' t need to think about it at all. It is set and cleared for both items automatically. However, the situation is different for topic files with multiple TOC entries. See below for details.

Working in the Topic Files section:

Setting or changing an include option for a topic in the Topic Files section of the Project Explorer does not automatically change the include options for any associated TOC entries. For technical reasons, the topic files cannot be permitted to control the TOC entries. Among other things, this would create a mess when the TOC contains multiple references to the topic file, each with different build options.

Topic files with no TOC entry

If a topic file has no TOC entry (for example for popup topics or topics displayed in external windows) you must set include options directly for the topic file, in Topic Files in the Project Files section of the Project Explorer.

This is generally the only time when you should set include options for topic files directly. In all other cases you should set the options in the TOC unless you have a specific reason for wanting different options for the TOC entry and the associated topic file.

Topic files with multiple TOC entries

If you have multiple TOC entries for the same topic in the TOC setting include options for the individual TOC entries is a little more complicated. Basically, the following principles are applied:

The include options are saved separately for each TOC entry.

The include options of the linked topic file are set as the sum of all the options set for the linked TOC entries.

Note that these settings are handled automatically if you set the options in the TOC. However, if you set the include options for the topic files directly you are responsible for getting the associations right yourself.

Examples:

In the following example the include options of the topic file are set to ALL because only this setting will cover all the settings required for both the associated TOC entries.

Item Type

Name

Include Options

TOC entry 1

Introduction

CHM

TOC entry 2

Introduction(2)

ALL

Topic file

Introduction.xml

ALL

In the following example the include options of the topic file are set to the combination of the options for both associated TOC entries.

Item Type

Name

Include Options

TOC entry 1

Introduction

CHM, HTML

TOC entry 2

Introduction(2)

PDF

Topic file

Introduction.xml

CHM, HTML, PDF