16.10.2 Specifying
CSH mappings
To provide CSH when DITA2Go generates
Help files for your project:
- Give
each target topic a <data />
element that contains a symbolic ID. In your DITA document, insert
a <data />
element in each topic that will be the target of a call from the application
program. The name is topicalias
and the value is the symbolic ID for the topic. Insert a separate <data />
element with a unique symbolic ID for each call from the application.
Put the <data />
element in the topic, after the root and before the title. For example:
<topic id="framistans">
<data name="topicalias" value="IDH_framistan" />
<title>Framistan maintenance</title>
...
</topic>
DITA2Go also supports Omni Systems
TopicAlias
PI markers of the form:
<?dthtm TopicAlias="IDH_about"
?>
and native FrameMaker DITA CSH PI markers
of the form:
<?FM MARKER [TopicAlias] IDH_about?>
as well as DITA-FMx <data />
elements of the form:
<data datatype="fm:marker" name="TopicAlias"
value="IDH_about" />
- 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
Table of Contents • Index