Conditional Compilation /

Conditional Compilation: Overview

HelpSmith allows you to compile different variants of the same help system by using the possibilities of conditional compilation. This help topic describes the key aspects that you need to know to use conditional compilation in your own help project.

How Conditional Compilation Works

Conditional compilation is based on build tags which you can define for your help project and also on conditions which you can define for individual entities such as a topic, conditional text block, etc.

A build tag is a simple object with a name and description. Conditions, in turn, are based on build tags, but conditions use a combination of build tags and logical operators (OR, AND, OR NOT, AND NOT) to implement the desired logic that determines whether a specific entity should be included or excluded to/from the compiled help system.

Finally, when you compile your help project, you can select build tags that you want to apply to the given compilation and, as a result, generate a specific version of the help system.

About Build Tags

Any help project includes a number of reserved build tags that correspond to the supported help formats (HTML Help, Web Help, Printed Manual, Adobe PDF, MS Word, ePub, Markdown). These reserved build tags cannot be deleted or renamed.

However, you can also add custom build tags for which you can set any name and description. For your convenience, a new help project already includes custom build tags (Custom1, Custom2), but you can delete or rename them like any other custom build tags.

You can visit this topic for more details on editing build tags of your help project.

Build Options (Conditions)

An entity (e.g. a topic, or conditional text block) that can be included or excluded to/from the output help system allows you to define build options for it.

Build options are a set of conditions that can use build tags and logical operators, such as AND, OR, AND NOT, OR NOT. Thus, build options defined for an entity can be evaluated either with a positive (True) or negative (False) result, which determines whether to include or exclude this entity to/from the compilation.

The Build Options dialog allows you to define simple conditions (IF, IF NOT) which implement only OR logic, but also it allows you to add extra conditions that can implement any other logic.

When to Use Conditional Compilation

There are different situations when you may need to use conditional compilation in your help project.

Below are some examples:

•You develop a help system for different editions of the same product (e.g. free, standard, and professional edition) and would like to include or exclude some content to/from the help file written for a certain product version.

•You need to create custom builds of the help system for a number of your marketing partners and would like to replace company names or URLs according with their requirements.

•You may be working on new content that should not be released until the features it describes are available in the product.

•You may want to include or exclude some blocks of text to/from a specific output help format or to/from a specific output help format in a custom build, etc.

Thus, the possibilities of conditional compilation allow you to have a single source help project and easily get different versions of the help system, which eliminates the need to maintain separate copies of the same help project.