|Scroll Prev Top Next More|
Help+Manual's conditional output features can create a wide range of variants of your project for different purposes. However, it is difficult to create versions with TOCs that have very different structures using only conditional output. The multiple TOC feature solves this problem. It allows you to create completely different TOCs with a different structure and different entries for different purposes.
The entries in your additional TOCs can point to the same topic files as in your main TOC. Or they can have their own topic files that only exist in that TOC. When you publish you choose which TOC you want to use, and only the topics referenced by that TOC are exported – in some cases along with topic files linked to in those topics, to prevent dead links.
See Publishing projects with multiple TOCs for details on selecting specific TOCs when you are publishing your projects. Also see the Multiple TOCs tutorial project that you can access directly in the Welcome page at the top of the Project Explorer on the left.
1.Right-click on the Table of Contents entry at the top of the Project Explorer on the left and select Create new Table of Contents in the context menu.
2.This opens the New TOC dialog:
3.Enter a descriptive title for the new TOC and choose whether you want it to be empty or a copy of the current TOC. If this is your first additional TOC you probably want it to be empty rather than a full copy of the entire TOC. Later you may want to make copies of existing additional TOCs that you then edit.
4.Then create new entries in the new TOC in any of these ways:
oDrag items from another TOC into the new one (onto the empty node if it doesn't yet have any entries). This does not create new topics. It only creates new references to existing topics.
oCopy and paste from another TOC.
oCreate new entries with the Add Topic tool in the Project tab. If you use the TOC Link option it creates new entries for existing topics. If you use the New Topic option you will create completely new topics.
To maintain compatibility with existing projects, the "original" or "main" TOC in your project will always include all topics when you publish with it. If you remove TOC entries from it without explicitly excluding the topic files that no longer have TOC entries (by using build options), those files will still all be included in the background in HTML output when you publish with the main TOC. They can then be found by search and the keyword index.
This only applies to CHM, WebHelp, eWriter and Visual Studio Help output. It doesn't apply to PDF, DOCX and eBooks, because there only topics that have TOC entries can ever be included.
Only secondary TOCs automatically exclude the topics for which they do not have TOC entries!
If you want to create an alternative TOC with a reduced or different set of topics, always do this with a secondary TOC, not with your "main" or "original" TOC (the top one). Again: The main TOC is always complete. If there are topic files without TOC entries in the project they will be included in the background when you choose the main TOC unless they have explicit build options that exclude them.
Use build options to to include hidden topics with secondary TOCs
By the same token, topic files without TOC entries will not be included automatically in the background with secondary TOCs. Then, a topic file without an entry in the current TOC will still be excluded even if it is set to "all builds". It will only be included if you explicitly set a specific build option on it and activate that in the include options for the publishing operation.
When you use popup topics in secondary TOCs the popup topic files your links refer to will not be included automatically as they are when you use the primary TOC. The All Builds include option assigned to all topics by default only works automatically in the primary TOC.
When you are using multiple TOCs in your project and publishing a secondary TOC, any popup topics you link to must be included explicitly. You can do this in two different ways:
Option 1: Dead links handling options
Go to View > Program Options > Compilers and set the dead links handling option to Silently include linked topic. This is the simplest solution but it will also automatically include any excluded topic files that you may have referenced with regular topic links. So you should always check your compiler report for topics like these that you may have not wanted to include. You can then handle the links with conditional text to exclude them automatically.
Option 2: Set the build options of your popup topic files
Alternatively you can set the build options of your popup topic files to the output formats that support popups, which are WebHelp, CHM, eWriter, and Visual Studio Help (if you are using that). The eWriter format will be included automatically if you set WebHelp, so generally you will only need to set CHM and WebHelp.
1.Right-click on the popup topic file in Project Files > Topic Files and select Include in Builds in the context menu.
2.Set the include options to WebHelp, CHM and (if necessary) also VSHelp.
3.Repeat for all your poup topic files.
When you create a TOC that is a subset of the main TOC, your topics will often contain links to topics that are not in the new TOC. You need to take steps to deal with these links to ensure that they are not dead and so that they do not accidentally provide access to content you don't want to include in the version with this TOC.
Failsafe: Global options for links to excluded topics
You can set a global option for how links to excluded topics are handled in View > Program Options > Compilers. There are three choices:
•Silently include linked topic
•Allow links to be dead
Use conditional output to replace the links with alternative text
This is basically the same approach you would use for handling the same problem in normal conditional output scenarios where topics are excluded. See this topic for full instructions.
Create conditional output build options for your additional TOCs and apply them to the links to the external topics so with the Conditional Text tool. You can use this method to either remove the references entirely, or replace them with alternative text or alternative links in the version with the additional TOC.
For example, suppose you have a TOC for a specific client. You could create a conditional build option called CLIENT_B and then tag the link with it like this:
This inserts the first link if you are not exporting the CLIENT_B version and the second link if you are.
If you are using multiple TOCs in your project you can set a separate default topic for each TOC. Then you will automatically get the correct default topic for that TOC when you use it.
See Setting the default topic for full details on setting and managing the default topic for your project.
Important: The default for secondary TOCs must be set in the TOC
Each TOC you define can have its own default topic. Just right-click on the topic you want to use as the default in the TOC and select "Set as Default Topic" in the context menu.
In addition to the conditional output tagging inside topics described above, it is also possible to apply include options to the topic files referenced by the links but not to the TOC entries in the main TOC pointing to them. This is possible because TOC entries and topic files are separate items and each can have their own build options.
Consider this example:
This would allow you to include the Overview topic file with your additional TOC by activating the build option CLIENT_B in your publishing settings, even if it does not have a TOC entry.
You can do this if you activate the global option "Allow links to be dead" to handle the majority of links, but have a few links for which you do want to include the linked topics, for example.
What happens to topics like this in Word and PDF output?
When you then publish the normal TOC that includes the Overview entry to PDF or Word you have a logical discrepancy: The TOC entry says to include it, but the topic file include option says to exclude it. That is OK, because in those formats only topics with TOC entries are included and the TOC entry setting then has priority. The topic will thus be included normally.
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.
PDF is a special case because only topics with TOC entries can be included in PDF documents. If your project contains "invisible" topics that are normally only displayed with hyperlinks from other topics you must add TOC entries for them to be able to include them in the PDF version of your output. This is very simple to do with the knowledge you now have:
1.Create TOC entries for the "invisible" topics: Either drag the topic file into the TOC or create a "new" topic and select the topic ID of the invisible topic with the browse button in the Topic ID: field of the new topic dialog. You might want to organize these TOC entries as one or more special chapters in your TOC.
2.Apply build options to the new TOC entries so that they are only included in the PDF version of your output. See See Including and excluding TOC entries above for instructions.
You can use include options to "filter" the display of your topics in the TOC and Topic Files section of the Project Explorer. This makes it possible for you to see only the topics that will be included in a specific build, so that you can preview the results of specific build options without publishing your project.
1.Apply build options to one or more topics. If you don't do this filtering will not have any effect! See Conditions and Customized Output for details.
2.Select Explore > Filter in Project > Manage Topics and set the filter options you want to apply. The filter settings are also available from the right-click menu in the Project Explorer (Explore > Filter).
This works both in the TOC and in Topic Files. This only filters entire topics, it does not filter conditional text tagged within your topics.
•The current build settings of topics are shown in the Project Explorer, next to the topic caption in the TOC. Topics and chapters set to All Builds (the default) will always be included, of course – you cannot hide them.
•Filtered topics will be either shown in a different color or hidden completely. This depends on your settings for When filtering the table of contents... in View > Program Options > General. See Program Options - General for details on these settings.
Preventing dead links (Conditional Output)
Publishing projects with multiple TOCs (Publishing)