If you need to generate a help file for different editions of the same product, or printed manual for different audiences of users from the same source help project, you can use the capabilities of conditional compilation that enables you to include or exclude help topics to or from a particular compilation, and also to include or exclude specific parts of content such as text blocks, images, tables, and so on.
In this post, you will find the basic examples showing how you can use conditional compilation in your own help projects. For full information on this powerful feature, you can refer to this topic, or see the sample help project named “Conditional Compilation” that is available on the Start Page in HelpSmith.
About Build Tags
When you compile your help project into a specific output format such as HTML Help (CHM), Web Help, or PDF document, you can select one or more Build Tags to say the compiler which topics and conditional text blocks you want to appear in this compilation.
It should be pointed out that a help project contains a set of system build tags that correspond to the output help formats, but you can also add any number of custom build tags for use in Build Options of a help topic or conditional text block.
Selecting Build Tags Before Compiling a Help File
Add or Edit Build Tags of Your Help Project:
- On the Project tab, in the Project group, click Project Options.
- In the dialog, in the left sidebar, under General, click Build Tags.
- Add, edit or remove Build Tags according to your needs.
- Click OK.
Include or Exclude a Help Topic from the Compilation
By default, any help topic uses the “All Builds” condition in its Build Options which means that the topic should be included into the compiled help file with any Build Tags selected during the compilation.
If you want to exclude a help topic from a compilation, you should modify its Build Options:
- In the Project Manager pane, select the topic for which you want to modify the Build Options.
- On the Project tab, in the “Topics & Templates” group, click Properties.
- In the Topic Properties dialog, click Build Options to edit the topic’s inclusion conditions.
- Click OK.
Editing Build Options of a Help Topic
Thus, by editing the Build Options of a help topic, you can set one or more Build Tags for which this topic should be included to the compiled help file or document.
Include or Exclude a Content Block
The Conditional Text functionality enables you to define Build Options for a specific content block within a help topic. This means that you can define when a specific part of content should be included to or excluded from the compiled help file, or even to replace a content block with alternative content.
To define a new conditional text block:
- In the word processor, select the content for which you want to define Build Options.
- On the Insert tab, in the Conditions group, click Condition.
- In the drop-down menu, select the block elements to insert (for example, IF-ELSE-END).
- In the Build Options dialog, define the inclusion conditions, which is similar to the conditions for a help topic.
- Click OK.
Defining a Conditional Text Block
Related Topics
HelpSmith includes one of the most powerful implementation of Conditional Compilation functionality making it possible to define Build Options of any complexity, to automatically include/exclude TOC items, Index keywords, and also to process “dead hyperlinks” which appear as the result of excluding the corresponding help topics.
While this article demonstrates only the basic tasks, you can get full information on conditional compilation capabilities by visiting the topics below: