Include in Builds option does not update topics on TOC

[julio]

Hi, I have just discovered a behavior in Help & Manual 7.0.6.3732 that appears to be a bug. If you select any build to a topic using the Include in Builds option on Table of Contents section of a project, this topic's build is updated accordingly on Project Files - Topic Files - Topics (*.xml) section.
However, if you use that same option for a topic on Project Files - Topic Files - Topics (*.xml) section, that topic's build is not updated on Table of Contents section.
Well, I say that this behavior appears to be a bug because it does not influence the table of contents of a CHM for example, but the file is added to the CHM. How do I know that? Because this file, which does not appear on the table of contents, does appear on searches (CHM's Search tab) and if users double click it, this file is displayed but it is not selected on CHM's Contents tab.
I thought these two sections were only two ways of viewing the same files and options, but apparently the Project Files section is used to add files and the Table of Contents section is used to create the table of contents. As options are different on these sections, the table of contents does not reflect the files available on the CHM file, and vice-versa.

[Tim Green]

Hi Julio,

However, if you use that same option for a topic on Project Files - Topic Files - Topics (*.xml) section, that topic's build is not updated on Table of Contents section.

This is NOT a bug! On the contrary, this behavior is an essential to the proper functionality of Help & Manual's conditional output system. Understanding how and why this works is also essential to getting the most out of this system.

To understand this, you need to know what the TOC and Topic Files sections really are: The TOC is a list of links pointing to topic files, nothing more. When you select a TOC link in the Project Explorer it displays the topic file the link points to for editing. However, ALL the topic files only actually exist in the Topic Files section -- both those with TOC entries and those without.

So the TOC entry and the topic file are two separate items: A link pointing to the topic file, and the topic file itself. Both of these items have their own separate build options. When you apply a build option to the TOC entry it automatically also applies the same option to the topic file. However, it is quite possible, and often desirable, to apply a separate build option to the topic file: You can exclude the TOC item, but include the topic file. This works in WebHelp, CHM and EWriter eBooks, where you can then still display the topic file with links in topics, and with searches in the keyword index and full-text search.

This is why setting the build options in the Topic Files section does not change the build options in the TOC. That is intended and necessary. The only thing you can't do with this system is include the TOC item and exclude the topic -- because that would create an invalid TOC entry, which you don't want.

Similarly, when you delete an item in the TOC you can also choose to NOT delete the associated topic file. Then it also becomes a file that is only accessible via hyperlinks, search and the keyword index.

All this has a different effect in print-style output formats like PDF, DOCX and standard eBooks (ePUB and Amazon Kindle). There, topics that do not have TOC entries don't exist, because they have nowhere to go: These formats are really just representations of printed documents on paper, so everything in them must be "visible" by definition. If a topic doesn't have a TOC entry it doesn't have anywhere to go, because the TOC is the only thing that defines its position in the document.

[julio]

Thank you for the explanation, that behavior never crossed my mind. I thought it was a bug because users may be surprised by having a 'ghost' topic that never shows up on the table of contents.