More Advanced Procedures > Conditions and Customized Output

Topic include options are used to include or exclude entire topics or chapters from your output on the basis of one or more conditions. When you apply topic includes to a chapter you can include or exclude all the chapter's sub-topics with a single setting.

Separate TOC entry and topic file include options

Your TOC entries and topic files are actually two separate items: The TOC entries are connected to the topic files by a kind of hyperlink. 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.

Please see Topic entry and topic file include options for more information, also on setting include options for topic files directly.

1.	Select the topic or chapter you want to include or exclude by clicking on its entry in the Table of Contents (TOC). You can select multiple topics and chapters with Ctrl+Click and Shift+Click.

2.	Select the topic in the TOC, then select Change > Include in Builds in Project > Manage Topics and select the conditions you want to apply. You can select multiple options.

You can also access these options by right-clicking on a topic in the Project Explorer.

3.	Select Find > Referrers in Project > Manage Topics to make sure that there are no links to the topic that will be dead in the output if the topic is excluded.

If you wish, you can include such topics in your output automatically to prevent dead links.

•	ALL BUILDS is the default. Selecting it deselects all other options.

•

Including or excluding a chapter automatically includes or excludes all the sub-topics and other chapters it contains without displaying any changes in the include options of th sub-topics and sub-chapters. You only need to apply settings to individual sub-topics and sub-chapters if you want them to be different from those of their "parent" chapter – for example to exclude individual topics.

•	Including a sub-topic automatically includes its parent chapter topic; you can't include a topic that has a parent without including its parent as well.

•	If you exclude all the sub-topics of a chapter and include the chapter topic the chapter will be converted to a normal topic when you compile.

Including/excluding a chapter automatically includes/excludes its sub-topics

Include options you apply to a chapter are not automatically applied to sub-topics. However, they don't need to be – if you include a chapter its sub-topics are included automatically, if you exclude a chapter its sub-topics are excluded automatically.

Excluding all a chapter's sub-topics

It works a little differently the other way round: If you exclude all of a chapter's sub-topics this will not exclude the chapter. However, if the chapter no longer has any sub-topics it is no longer a chapter – it will be automatically converted to a normal topic when you publish your project.

You should generally set and change include options for topics in the TOC, then the options for the associated topic files will be set automatically. However, for topics without TOC entries you must set the include options directly in Topic Files, in the Project Files section of the Project Explorer. Just select the topic file and then set the include options in exactly the same way as for a TOC entry

Important: Setting topic file include options does not automatically set the corresponding include options for any linked TOC entries. You should always work directly in the TOC for topics that have TOC entries unless you have a specific reason for wanting to set the options for the topic files only.

See Topic entry and topic file include options for more background information.

When you exclude topics from your output it is important to make sure that there are no links to the excluded topic from other topics in your project. If there are, the links will be dead in your output – when the user clicks on them either nothing will happen or an error will be displayed (this depends on the output format).

See Preventing dead links for a more detailed discussion of this subject and strategies for dealing with the problem efficiently.

Checking for dead links

1.	Right-click on the TOC entry of the topic you want to exclude and select Find Referrers in the context menu.

2.	If any links to the current topic are listed click on the links to jump to the topics containing the links so that you can correct them.

Correcting dead links with conditional text

You can use the same condition that you are using to exclude the topic to simultaneously exclude the links to the topic. You just need to enclose the links in conditional text tags using the same condition that you used to exclude the topic.

For example, if you want the topic to only be included in HTML Help output you would tag all the links to the topic with an IF CHM conditional text condition to match the HTML Help setting in Builds which include this topic. The procedure is similar for user-defined conditions.

Inserting alternative text to replace the excluded links

In addition to excluding the links you can also use conditional text tags to include alternative text to replace the links that are being excluded. For example, if the topic is only to be included in HTML Help you might use an ELSE or an IFNOT CHM condition to include the alternative text in all other formats, or an IF PDF condition to show the alternative text in the PDF version. Here too, the procedure is similar for user-defined conditions.

1.	Select Publish in the Project tab or the Application Menu.

2.	Select your output format, then check the options in the Include Options: setting in the Publish dialog.

3.	Select the options you want to apply from the list by checking the boxes next to the names in the Include Options section on the right.

All topics whose include options match the options selected here will be included in your output. Topics whose options don't match will be excluded.

4.	Check the other settings in the dialog and click OK to publish.

The include option for the current output format is always selected automatically but it is only relevant for topics not tagged with ALL BUILDS. Any other include options must be selected manually.