Help+Manual supports multiple levels of conditional output that give you very precise control over what is included in your published projects on the basis of output format and user-defined output conditions. These features make it possible to generate different versions of your project for different purposes and formats. You can control the inclusion or exclusion of everything from individual words (or even single letters) to entire topics and branches of the Table of Contents (TOC).
For example, if you output your project to both HTML Help and PDF you will generally need to make some small changes to the text for the PDF version because some things that are relevant in electronic help don't make sense in PDF or a printed manual. With conditional output you can include both versions in the same project and only the relevant components will be included when you publish.
How conditional output works:
Instead of creating and maintaining multiple versions of your project for different versions you only have one project, or one set of modular projects, containing all the content and topics for the alternate versions you need to generate. The chapters, topics and topic content (text, graphics, tables etc.) for the alternate versions are "tagged" with conditions called "include options" (also known as build conditions) that control whether they are included in the output or not.
Note that in HTML Help you can also create different versions of your documentation with runtime modular projects. See Runtime and publish time merging for details on this.
Format-based include options:
These options allow you to include or exclude topics and content on the basis of the selected output format.
For example, suppose you have two different versions of a sentence, one for the HTML Help version and one for the PDF version. You would enclose the first version in an IF_CHM conditional text tag and the second in an IF_PDF tag. And that is all you have to do, everything else is automatic. When you publish to HTML Help only the IF_CHM version is included, and when you publish to PDF only the IF_PDF version is included.
User-defined include options:
These options allow you to include or exclude topics and content on the basis of conditions that you define. This makes it possible to create different versions of your published output irrespective of the output format. For example you may have different documentation for different versions of a product.
For example, suppose you defined an include option called BETABUILD and tag specific text passages and topics in your project with an IF_BETABUILD condition. To include those passages in your output you just select the BETABUILD include option in the Publish dialog when you publish, along with any other relevant options.
Multiple TOCs
You can combine alternative TOCs with conditional output when you need to create versions of your project with a completely different TOC structure.
Conditional output and links
It is important to plan your links when you are working with conditional output. When you exclude a topic from your output any hyperlinks to that topic in other topic will be dead unless you also exclude the links.
Before excluding a topic always right-click on its TOC entry and select Check Referrers to locate any links to the topic. You can then use the same conditions to exclude the links from your output. In addition to this you may want to add additional conditional text options to include alternative text to replace the links.
You can configure Help+Manual to include the topic anyway to prevent dead links, but it is better to exclude the links using the same output conditions.
Levels of conditional output supported by Help+Manual:
Conditional text: |
On the text level you can use conditional text tags to mark sections in your topics – paragraphs, graphics, sentences and even individual words and letters – that should only be included when a specific condition is fulfilled (output format or user defined). |
Text variables: |
Text variables (see Using Variables) allow you to use variables for text items. Then if the item changes you only need to redefine the variable once to implement the change throughout your entire project. Variables are not really conditional output in the strictest sense of the term, but you can use them for conditional output by redefining them globally with a project skin or a variables file that replaces the variable definitions in your project at publish time. |
Topic conditions: |
These conditions allow you to include or exclude entire topics and chapters on the basis of output format or user-defined conditions. |
Multiple TOCs: |
You can combine alternative TOCs with conditional output when you need to create versions of your project with a completely different TOC structure. |
Modular projects: |
Help+Manual's modular projects features enable you to include or exclude entire projects in your help at publish time. This makes it possible to quickly add or remove entire blocks with multiple chapters |
HTML conditions: |
You can also use some special conditional switches in HTML templates to control when code in the template should be included or excluded. |
See also:
Conditions and Customized Output
