18.11.5 Understanding alias-file entries

By default DITA2Go generates alias-file entries of the following form:

symbolic_ID=helptopicfile.htm

For example:

IDH_CnvDsgnr=02x998989.htm
IDH_Export=02x999005.htm

Mid-topic destinations

To make a CSH link take the user directly to a mid-topic destination, the alias-file entry for the symbolic ID must include a hash value after the file name:

symbolic_ID=helptopicfile.htm#symbolic_ID

For example:

IDH_110100=ac960367.htm#IDH_110100
IDH_110200=ac960367.htm#IDH_110200

To direct DITA2Go to generate alias-file entries of this form, specify the following option:

[MSHtmlHelpOptions]
UseAliasAName=Yes

See §18.11.1 Inserting CSH destinations in your document.

First entry cannot have a mid-topic destination

There is a catch: because of a defect in HTML Help alias-file processing, the very first entry in the alias file must not have a hash value. Even when you specify UseAliasAName=Yes, DITA2Go omits the hash value for the first entry; therefore, the CSH link for the first symbolic ID listed in the alias file always takes you to the beginning of the topic that contains the relevant destination. If this is not acceptable, you can provide a dummy first entry by inserting a TopicAlias PI marker containing a dummy symbolic ID at the start of the first file in the book. This symbolic ID must also appear in a valid entry in the map file, so you might have to get the developers to add a corresponding dummy entry to the map file.

Even with this workaround, HTML Help Workshop will report an error on every alias with a hash value; but the CSH links work anyway.

Previous Topic:  18.11.4 Creating an alias file for CSH links

Next Topic:  18.11.6 Producing a list of aliases and associated topic titles

Parent Topic:  18.11 Setting up CSH for HTML Help

Sibling Topics:

18.11.1 Inserting CSH destinations in your document

18.11.2 Determining whether you need map and alias files

18.11.3 Specifying and generating a map file for CSH links

18.11.4 Creating an alias file for CSH links

18.11.6 Producing a list of aliases and associated topic titles