16.10.2 Specifying CSH mappings
To provide CSH when DITA2Go generates Help
files for your project:
- Give each target topic a
TopicAlias
PI marker that contains a symbolic ID. In your DITA document, insert
a TopicAlias PI marker in
each topic that will be the target of a call from the application program.
The content of the marker is the symbolic ID for the topic. Insert a
separate TopicAlias PI marker with
a unique symbolic ID for each call from the application. Put the PI marker
in the topic, after the root and before the title:
<topic id="framistans">
<?dthtm TopicAlias="IDH_framistan" ?>
<title>Framistan Maintenance</title>
...
- </topic>
- Create or obtain a map file
(possibly except JavaHelp and Oracle Help for Java; see §20.12 Setting
up CSH for JavaHelp or Oracle Help).
- Specify prefixes that identify
CSH links (HTML Help or OmniHelp). List topic-name prefixes in the
configuration file, to identify TopicAlias PI markers intended
for CSH use. If you do not specify any prefixes, all TopicAlias PI markers are
included.
- Map the appropriate application-provided
number to each symbolic ID. For C/C++ applications, usually the
developer provides a map file. If not, for WinHelp or HTML Help you can
use a simple syntax described in the Help provided for those Help systems.
Otherwise, for each Help call in the program, add a line of the following
form to the map file:
#define symbolic_ID numeric_ID
You cannot map multiple numeric IDs to the same symbolic
ID; each entry in the map file must specify a different symbolic ID.
If you need CSH links to the same Help topic from more than one point
in the application, include in the topic a separate TopicAlias PI marker with
a unique symbolic ID for each such Help call.
- Add a map-file entry to the
Help project file (WinHelp or HTML Help). In the [MAP] section of the Help
project file (MyDoc.hpj or MyDoc.hhp), add a line of the
following form to identify the map file:
#include MapFileName.h
DITA2Go creates a CSH link destination from
each TopicAlias PI marker whose
name starts with one of the prefixes you specified in Step 3, or all the TopicAlias PI markers if
you did not specify any prefixes. Make sure the symbolic IDs in the TopicAlias PI markers are
spelled the same way as in the map file.
By default, DITA2Go removes punctuation and
spaces from the TopicAlias PI marker content.
If your HTML-based Help system requires CSH IDs that use characters such
as periods, set the following option:
[HTMLOptions]
; UseRawNewlinks = No (default, remove punctuation, spaces)
; or Yes (as is)
UseRawNewlinks=Yes
Previous Topic: 16.10.1 Understanding
how CSH works
Next Topic: 16.11 Setting up
a dynamic modular Help system
Parent Topic: 16.10 Setting up
Context Sensitive Help (CSH)
Sibling Topics:
16.10.1 Understanding
how CSH works