Basic Working Procedures > Compiling Your Project

In this topic:

Once you have made all your preparations and set your configuration options for the output format you are using compiling is basically just a question of selecting the output format and clicking on OK. Everything else is handled by Help & Manual.

Compiling to XML:

Note that generating XML output us a special case with a number of special settings unique to this output format. It is also not possible to include or exclude individual topics or chapters in XML, the output always contains your entire project. In this sense, it is really more a save format than an output format. For detailed instructions see Compiling to XML.

How to compile your project:

1.	Save your project, then select File > Compile Help File or in the Toolbar. This displays the Compile Help File and Run dialog:

2.	Select the output format in the Output Format: field. Some of the options displayed in the dialog will change depending on the format you choose.

•	For details on the options in the compile dialog see Compile Help File in Reference > Menus and Dialogs > The File Menu.

3.	Check the Output File: field. In most cases the program will automatically compile to the project folder, using the project name as the file name. You can change both the output folder and the file name if you want and Help & Manual will remember this change next time you compile.

4.	Select the output options and click on to compile. This can take a couple of minutes with very large projects.

A report on the compile process including any errors and a list of the files and/or folders you need to include when you distribute your help to your users is displayed in an external viewer window. This window contains controls with which you can save the report to an external HTML file if you want.

Compiling Visual Studio Help:

Please note that Visual Studio Help (MS Help 2.0) is a special case. Please see the special Visual Studio Help section in the More Advanced Procedures section for details.

Visual Studio Help is a special help format that is only used for documenting third-party programming components designed for integration in Visual Studio .NET. It cannot be used for normal application programs and if you are not a VS.NET system programmer you don't need to know anything about it!

Compiling Browser-based Help:

Compiling Browser-based Help is almost the same as compiling any other format. However, since you are actually creating a website consisting of a large number of individual files there are a couple of additional points you need to bear in mind:

Always compile Browser-based Help to its own folder, which should preferably be empty. A large project can consist of several hundred files in this format! (The program will suggest creating a folder called \HTML inside your project directory, which is a good choice.)

When you compile to Browser-based Help you can the use the option to clear the output folder before compiling. You don't need to use this during normal working but it is a good idea to select it before creating a build that you are going to publish.

Clearing the output folder makes sure that no files for topics that you have deleted are included in your output unnecessarily. In addition to taking up space these files will also be indexed and will appear in the full-text search (see below).

Clearing the output folder is also essential when you change the name of the project, as this changes the names of a number of important files that are components of your Browser-based Help. If you don't clear the folder the old files will remain in place and will be included in the index.

You don't need to worry about the timestamps of your output HTML files when you clear the output folder. The the HTML file timestamps are always set to the last time the topic was edited, not the time when the project was compiled.

Microsoft Internet Explorer now displays a yellow warning bar when you open any HTML files containing scripting on your local machine. You can disable this warning by activating the option Enable local testing for MS Internet Explorer in the Compile Help File dialog.

Your Browser-based Help files will then open normally in Internet Explorer, without the yellow warning bar. If you plan to deploy your Browser-based Help for installation on local computers you can leave this setting activated for your production output if you want.

Important: Note that file links do not work when this option is activated.

When you are compiling the new Browser-based Help with full-text search it's important to understand that the search index is not generated from your .HMX project file or from the files on your server. It is generated from the HTML files on your local computer, after the HTML files have been generated.

•	If the output directory contains any other HTML files these will be included in the index. To prevent this do not place any other files in the output directory. Since the index is generated locally you can upload other files to your server separately, then they will not be included in the index.

•

Outdated HTML files will be included in the index if you don't delete them.
To ensure that the HTML files of outdated topics are not included in the index use the

option in the Compile dialog to delete the contents of the output directory before compiling. This will not cause problems with the timestamps of topic files that have not been changed – the HTML file timestamps are always set to the last time the topic was edited, not the time when the project was compiled.

Compiling selected topics only:

For test purposes you can compile only the topics that are currently selected in the Table of Contents pane (TOC). Note that this will result in dead links in topics that contain links to topics which are not included in your output!

1.	Select the topics you want to compile in the TOC pane. You can use Ctrl+Click and Shift+Click to select multiple topics out of order and sequences of topics. Selecting chapters automatically selects all the chapters' sub-topics.

2.	Select File > Compile Help File or in the Toolbar to display the Compile Help File and Run dialog.

3.	Select the output format, then select Selected Topics in the Include Options: box. The box will be highlighted in yellow to remind you that only selected topics will be included in your output.

4.	Select your other compile options, then click on to compile.

Using the "Include Options":

With the exception of the Selected Topics option (see above) the Include Options settings in the Compile Help File dialog are only relevant if you are using Help & Manual's conditional output functions to control which topics and content are included in your compiled output.

When you select include options only topics and content tagged with matching include options in your project will be included in your compiled output. You can tag topics in the Topic Options tab and individual content with the Insert > Conditional Text function.

By default the include options are set to the selected output format. Do not change this unless you are explicitly using conditional output.

•	For more information see Conditions and Customized Output in the More Advanced Procedures section and Compile Help File in Reference > Menus and Dialogs > The File Menu.

Quick-launching your project:

The Quick Launch function compiles your output and displays it without displaying the Compile Help File dialog.

This function automatically uses the last compile settings you used with when you compiled with the compile dialog. It is thus advisable to compile to the selected format with the File > Compile Help File option at least once before using Quick Launch.

1.	Click on the arrow symbol next to the tool in the Toolbar to display the Quick Launch output options:

2.	Then just select the output format you want to output to. Your project will be compiled and displayed automatically as soon as the compile process is finished.

Test-compiling Asian languages on non-Asian Windows:

Normally, you cannot compile help projects written Asian languages on non-Asian versions of Windows because the necessary language settings don't match. However, if you just want to do a quick test compile and don't have a Windows version in the matching Asian language there is a configuration setting that will allow you to do this.

•	Go to Tools > Customize > Compilers and activate the option .

The resulting help file will contain errors if the languages of your Windows version and the help file don't match but you will be able to complete the compilation, which is sufficient for testing.