|Scroll Prev Top Next More|
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.
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.
•Assigning include options to a chapter does not automatically assign the selected options to the sub-topics and other chapters it contains. You must use multi select (Shift+Click and Ctrl+Click) to apply include options to multiple topics and chapters. If you exclude a chapter without excluding its subtopics the TOC entries for the sub-topics will not be included (they have nowhere to go) but the topic files will, and it will be possible for users to find them with Search and in the Index.
•You can't include a topic that has a parent without including its parent as well. If you have inconsistent build options like this an option is displayed in the right-click menu with which you can correct it, by applying the missing options to the parent chapter.
•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 publish.
Including/excluding a chapter does not include/exclude its sub-topics
Include options you apply to a chapter are not automatically applied to sub-topics. You must use multi select (Shift+Click and Ctrl+Click) to apply include options to multiple topics and chapters. If you exclude a chapter without excluding its subtopics the TOC entries for the sub-topics will not be included (they have nowhere to go) but the topic files will, and it will be possible for users to find them with Search and in the Index.
Excluding all a chapter's sub-topics
If you exclude all of a chapter's sub-topics this will not exclude the chapter. If a 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.
Excluding parent chapters and including their children:
This creates a conflict situation – since the parent is excluded the children cannot be included. To correct it right-click on the one of the child topics and select the option for adding the missing build options to the parent. This tool is also available in Project > Change > Include in Builds and is only displayed when there is such a conflict.
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.
When you use topics without TOC entries in combination with additional TOCs you may need to take additional action to ensure that the topic file is included in your output. An additional TOC acts like an include option for every topic it includes, and by default all other topics can be excluded. Because of this, topic files that are only accessed by hyperlinks and not by TOC entries may get excluded if you are not careful.
Method 1: Use the compiler option to force inclusion
This is the simplest solution. It tells Help+Manual to automatically include any topic file that is referenced with a link in your project. Just go to View > Program Options > Compilers and set the Handling of dead links option to Silently include linked topic. This will include all topic files referenced with hyperlinks, even if they don't have TOC entries. The included topic files will be listed in the compiler report.
Side-effect: This will also include topics that were excluded from the TOC with build options, if there are links to those topics that you have overlooked. Check the compiler report!
Method 2: Use a user-defined include option
Alternatively, you can define an include option with a descriptive name like NONTOC or something like that and apply it to the topic file in the Topic Files section. Then you just need to activate that option in the Publish screen when you publish. Then all topics tagged with that option will be included in your output.
1.Select Publish in the Project tab or the File menu.
2.Select your output format, then check the options in the Include Options: setting in the Publish settings.
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.