# Multiple TOCs
> [HTML Version](hm_working_toc_multi.html)
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](hm_working_compile_tocs.md) 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.
[] How to create an additional TOC
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.** **
_(./images/newtoc.png)_
2. This opens the New TOC dialog:
_(./images/dlg_newtoc.png)_
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.
_(./images/mnu_newtocnode.png)_
4. Then create new entries in the new TOC in any of these ways:
- Drag 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.
- Copy and paste from another TOC.
- Create 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.
[] IMPORTANT: The "main" TOC always includes all 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](hm_advanced_conditions_builds.md)), 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.
[] Popups in secondary TOCs
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](hm_advanced_conditions_deadlinks.md) to exclude them automatically.
_(./images/include_dead_topics.png)_
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.
_(./images/includeinbuilds.png)_
[] Managing links to excluded topics in additional TOCs
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**
In HTML-based output formats this exports the topic file without a TOC entry so that the link displays the topic. In PDF and DOCX this has no effect, because only topics that are in the TOC can be in the document.
- **Remove link**
This turns the link into plain text. The referenced topic is not exported.
- **Allow links to be dead**
This leaves the links unchanged in the topics but does not export the linked topic files. So either nothing happens or an error message (404) is displayed when the user clicks on the link. This can be good "protection" if you are managing the links with conditional output, to make sure that the excluded topics are never seen.
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](hm_advanced_conditions_deadlinks.md) 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:
_(./images/ed_toc_conditions.png)_
This inserts the first link if you are not exporting the **CLIENT\_B** version and the second link if you are.
[] Setting the default topic with multiple TOCs
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](hm_working_projects_hometopic.md) 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**
Default topics for secondary TOCs must be set directly in the TOC. The setting in Configuration > Common Properties > Language Options is only for the main 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.
_(./images/setdefaulttopicmulti.png)_
[] More granular control of output with include options on topic files
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:
_(./images/newtoc_topicopts.png)_
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.
[] Topics without TOC entries in additional TOCs
When you use [topics without TOC entries](hm_working_topics_createnotoc.md) 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](hm_advanced_conditions_definingincludes.md) with a descriptive name like **NONTOC** or something like that and [apply it to the topic file](hm_advanced_conditions_builds.md#topicfiles) in the Topic Files section. Then you just need to [activate that option](hm_advanced_conditions_using.md#activateinclude) in the Publish screen when you publish. Then all topics tagged with that option will be included in your output.
[] Creating TOC entries for "invisible" topics in PDFs
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 _(./images/btn_browse.png)_ 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.
[] How to "filter" the TOC display by build/include options
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](hm_advanced_conditions.md) 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.
**Important Notes:**
- 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](hm_ribbon_view_options_general.md) for details on these settings.
See also:
[Preventing dead links](hm_advanced_conditions_deadlinks.md) (Conditional Output)
[Publishing projects with multiple TOCs](hm_working_compile_tocs.md) (Publishing)