RoboHelp Word Project Conversion

To convert a RoboHelp Word (WinHelp) project to Doc-To-Help use Convert RoboHelp Word Project in the File | Convert menu.

Files:

All files in the original project folder and its subfolders are copied to the Doc-To-Help project folder except those that are used by RoboHelp for its internal purposes. This is done to ensure that external files that may be referenced in the project source files are present in the converted folder and do not cause broken links. If you see files that you know are not needed, you can delete them manually.

Source documents (Word .RTF files included in the project) are converted to Doc-To-Help format. For example, WinHelp hotspots are converted to D2HML hotspots, and so on; please see the following conversion information. Other files are copied to the destination directory unchanged.

Source documents located outside the original project directory are not copied and not converted, with a warning issued in the conversion log.

Graphic files (help images, included in statements such as {bmc}) located outside the project directory remain in their places and their paths in the documents are changed to an absolute path with a warning in the conversion log.

Files included in the BAGGAGE section of the project are not copied to the destination directory unless they are located inside the source project directory. If you need those files, copy them manually to an appropriate location in the project directory.

A special directory _defbmp is created in the converted project directory containing standard WinHelp bitmaps (bitmaps supplied by Help Workshop) such as bullet.bmp, shortcut.bmp, etc.

Styles and templates:

Styles and style appearance in the source documents are preserved in conversion. Converted documents have a Doc-To-Help template, C1H_NOMARGIN.DOT, attached to them, so the author can use Doc-To-Help styles. However, the template does not change the appearance of the styles already used in the source document, because the check box Automatically update document styles in the converted Word document’s Tools|Options menu is unchecked. If you check that check box, the styles appearance can change, because it will be defined by the C1H_NOMARGIN.DOT template.

The target template, which is set through the HelpTarget.Template, property in the converted Doc-To-Help project is set to (None) to preserve the appearance of the source documents in the help target. You can change it to one of the standard Doc-To-Help templates or to your own customized template if you want to control target appearance by a template.

The style of the heading of each topic in Doc-To-Help must be one of the active paragraph styles, those styles that define a topic when Doc-To-Help compiles the document. For a topic with the first paragraph formatted with a style without an outline level (non-active style), its first paragraph is reformatted with a new style with the postfix (Topic) added in the end of the style name, the new style is inherited from the original style. For styles with outline levels (active styles) that are used in the original documents in a mixed way, both for formatting topic headings and for formatting paragraphs that are not topic headings, the paragraphs that are not topic headings are reformatted with a new style with (Nontopic) added in the end of the style name, the new style is inherited from the original style.

Topics:

A Doc-To-Help topic is created in the converted project for each WinHelp topic. A WinHelp topic ID becomes a topic link tag and the value of the topic’s AsciiName property. If a topic has an alias in the project file, that alias is also added to the collection of the topic’s link tags.

Topic properties and TopicType:

Some topic properties are implemented in Doc-To-Help via topic types. For example, you can’t assign windows to individual topics directly, but you can set Topic.TopicType to a topic type that has a specific window in the TopicType.Window property. To enable this mechanism, topic types are created in the converted project as necessary, having the necessary property values, and these topic types are assigned to the Topic.TopicType property as needed, to specify various topic properties.

Topic properties:

Topic title ($ footnote) is converted to the Topic.DisplayTitle property specified by a D2HML hot spot (style C1HTopicProperties) in topic text.

Topic title specified in the table of contents (TOC) is converted to the Topic.ContentsTitle property specified by a D2HML hot spot (style C1HContentsTitle) in topic text.

Topic window (> footnote) is converted to the Topic.TopicType.Window property.

Topic macro (! footnote) is converted to the Topic.WinHelpMacro property.

Topic.TopicType.Nonscrolling is set to True when a topic heading paragraph in the source document has its Word paragraph format setting Keep with next = True.

Topic.TopicType.Midtopic is set to True for topics that are mid-topics, that is, bookmarks in their parent topic rather than separate topics. According to WinHelp rules, such topics are characterized by the absence of a page break before their first paragraph.

TOC:

Table of Contents is converted to Doc-To-Help TOC.

Index keywords:

Index keywords are converted to Doc-To-Help index keywords. They appear on the Index tab in Doc-To-Help. Keywords are defined by D2HML hot spots in topic text (style C1HIndexInvisible), so they can be modified in Doc-To-Help either on the Index tab of the Project Editor or in the topic text using D2HML.

See Also (A-keywords):

A-keywords are converted to Doc-To-Help groups. They appear on the Index tab in Doc-To-Help. Groups are defined by D2HML hot spots in topic text (style C1HGroupInvisible), so they can be modified in Doc-To-Help either on the Index tab of the Project Editor or in the topic text using D2HML.

Links:

Jump and pop-up links (including those defined by macros JI, PI) are converted to D2HML hot spots (styles C1HJump, C1HPopup) in topic text.

Keyword links:

Keyword links (macros KL, JK) are converted to D2HML hot spots (style C1HKeywordLink) in topic text.

A-links (See Also links):

A-links (macro AL) are converted to D2HML hot spots (style C1HGroupLink) in topic text.

Windows:

Windows specified in the project are converted to Doc-To-Help windows with the same names. Doc-To-Help window properties are set for a WinHelp target based on the values of corresponding properties in the source project.

Map IDs:

Map IDs are converted to topic context IDs in the Doc-To-Help project. Context IDs are defined by D2HML hot spots in topic text (style C1HContextID), so they can be modified in Doc-To-Help either in the topic property browser of the Project Editor or in the topic text using D2HML.

Browse sequence:

Topics included in a browse sequence (having + footnotes) are included in the Doc-To-Help navigation sequence by setting Topic.TopicType.AutoNavigate = True. However, custom browse sequence (+ footnotes with browse code) is not converted, because Doc-To-Help browse sequence is always determined by the topic hierarchy, that is, by positioning of topics inside documents.

RoboHelp document default browse sequence:

RoboHelp document default browse sequence is not converted, because Doc-To-Help browse sequence is always determined by the topic hierarchy, that is, by positioning of topics inside documents.

Conditional build tags:

Conditional build tags (* footnotes) are converted to Doc-To-Help attributes. You can see the attributes in the Attributes node of the Doc-To-Help Project Editor tree view.

Conditional build tags in RoboHelp layouts:

Conditional Build Expressions in RoboHelp layouts are converted to Doc-To-Help property HelpTarget.AttributeExpression.

Topic-level conditional build tags:

Conditional build tags specified in the properties of a WinHelp topic (* footnotes) are converted to a D2HML topic properties hot spot (style C1HTopicProperties) in the Doc-To-Help topic text.

Conditional build tags in topic text:

RoboHelp conditional text (specified as special comments in the source document) is converted to Doc-To-Help conditional text comments in topic text.

Macros:

Macros defined in the project file for the entire help (CONFIG section) are converted to the WinHelpMacro property in Project Settings.

Macros defined in the project file for a window (CONFIG:window section) are converted to the Window.WinHelpMacro property.

Macros defined for a topic (! Footnote) are converted to the Topic.WinHelpMacro property.

Macros defined in macro hotspots in topic text are converted to Doc-To-Help WinHelp macro comments in topic text unless they are jump, pop-up or K-/A-links. In the latter case they are converted to D2HML hotspots.

RoboHelp proprietary macros are omitted, not converted. This is done to keep the converted project vendor-independent.

Notes: WinHelp macros have effect only in the WinHelp target; they are ignored in all other targets.

Doc-To-Help has a limitation of 255 characters for macro string length. Macro strings that exceed that limit are truncated, with a warning in the conversion log.

Help images:

Help images (bitmap statements {bmc}, {bml}, {bmr}) are converted to linked pictures (Word {INCLUDEPICTURE} field).

Hotspot images:

Hotspot images (SHED images, segmented hypergraphics) are converted to Doc-To-Help image maps, images with hot spots. Image maps can then be explored and edited using the Doc-To-Help Image Map Editor.

Buttons:

Help buttons ({button} statements) are converted to D2HML hot spots (styles C1HJump, C1HPopup, C1HkeywordLink, C1HGroupLink) with property DisplayAsButton = True.

RoboHelp graphical buttons:

RoboHelp graphical buttons are converted to images formatted with D2HML hot spot styles C1HJump, C1HPopup, C1HKeywordLink, C1HGroupLink.

Help multimedia and embedded windows:

Help multimedia ({mci} statement) is not converted because it is not supported in Doc-To-Help.

Embedded windows ({ew*} statements) are not supported with the exception of those generated by RoboHelp graphical buttons, which are converted to images formatted as Doc-To-Help hotspots.

RoboHelp glossary:

The RoboHelp glossary is converted to a Doc-To-Help glossary, a Word document Glossary.doc. Glossary topics (glossary term definitions) are assigned special link tags of the form RhGlossDef_... necessary to preserve pop-up links to glossary terms created by the RoboHelp Glossary Hotspot Wizard. You can add new glossary terms to the glossary after conversion; they will be used in Doc-To-Help according to the Doc-To-Help glossary rules. You do not need to assign link tags to glossary terms that you add after conversion.

Note that in addition to glossary hotspots converted from those existing in the original project, you may find new glossary pop-ups in the help built by Doc-To-Help. This is because the Doc-To-Help glossary is automatic in the sense that every occurrence of a glossary term automatically generates a pop-up. You can disable this automatic pop-up generation by formatting a glossary term with the D2HNoGloss style.

RoboHelp single source layouts:

RoboHelp single source layouts are converted to Doc-To-Help help targets. A property specified in a RoboHelp layout is converted to a Doc-To-Help target property only if Doc-To-Help supports that property. The following properties are converted:

Help Target

RoboHelp Property

Doc-To-Help Property

HTMLHelp:

Conditional Build Expression

HelpTarget.AttributeExpression

 

Default Topic

Default Topic

Background Watermark

HelpTarget.BackgroundImage

 

 

WebHelp (converted to the Doc-To-Help NetHelp target):

 

Conditional Build Expression

HelpTarget.AttributeExpression

Default Topic

Default Topic

Background Watermark

HelpTarget.BackgroundImage

 

JavaHelp:

 

Conditional Build Expression

HelpTarget.AttributeExpression

Default Topic

Default Topic

Navigation Pane TOC

HelpTarget.ContentsTab

Navigation Pane Index

HelpTarget.IndexTab

Navigation Pane Full-text Search

HelpTarget.SearchTab

 

Printed Documentation (converted to the Doc-To-Help Manual target):

 

Conditional Build Expression

HelpTarget.AttributeExpression

Name of the printed documentation

HelpTarget.Title

Chapter layout

TOC for the Manual target

 

Project Settings|Language|Advanced|LNG File:

 

[Common]

 

 

Contents

StringContents

 

Index

StringIndex

 

Search

StringSearch

 

SyncToc

StringSyncToc

 

 

[BrowseSequence]

 

 

PreCaption

StringPrevious

 

NextCaption

StringNext

 

 

[WebHelp]

 

 

IndexInputPromt

StringIndexCaption

 

FtsInputPromt

StringSearchCaption

 

TopicNotFound

StringFoundZero

 

FtsBtnText

StringSearchGo

 

 

[PrintedDoc]

 

 

TableOfContents

HTMLTarget(Manual).StringContents

RoboHelp printed documentation chapter layout:

In RoboHelp, you can customize the contents of your printed documentation, the order and hierarchy of topics, in essence, customize the TOC for the Printed Documentation target. Customized chapter layout is converted to the Manual target TOC in Doc-To-Help. You can see the Manual TOC on the Contents tab of the Doc-To-Help Project Editor. If it differs from the main TOC of the project, the converted TOC is customized separately from the main TOC, that is, the Manual target has its OwnTOC property set to True. If there are more than one Print Documentation layouts in the RoboHelp project that have a customized chapter layout different from the main project TOC, additional Manual targets are created in the converted Doc-To-Help project, each with its own customized TOC.

RoboHelp printed documentation section layout:

RoboHelp section layout for printed documentation is not converted to Doc-To-Help, because Doc-To-Help does not support custom section breaks in the Manual target. Doc-To-Help creates default sections, separate sections for the title, contents and index and for each top-level chapter.

RoboHelp printed documentation style mapping:

In RoboHelp, you can map styles in your source documents to styles in your template for printed documentation. This mapping is not converted to Doc-To-Help, because Doc-To-Help provides a different, in fact, more versatile, mechanism of determining the target appearance of styles. If you have a custom style mapping for printed documentation in your RoboHelp project, use the HelpTarget(Manual).Template property to achieve the same effect in the converted Doc-To-Help project. Note that you only need to do this if you want style appearance in printed documentation to be different from that in the online targets.

Unsupported RoboHelp topic properties:

Background and nonscrolling watermark and alignment are not converted, because they are not supported by Doc-To-Help

Custom topic browse sequence is not converted because browse sequence in Doc-To-Help is always determined by the positioning of topics inside documents. However, topics included in a RoboHelp browse sequence are included in Doc-To-Help navigation sequence by setting Topic.TopicType.AutoNavigate = True.

To Convert a RoboHelp Word project:

1.   Open Doc-To-Help 2007 and click Convert RoboHelp(R) Word Project.

2.   Browse, select an .hpj project file and click Open.

3.   Review the location and click Next.

4.   Enter the name of the Doc-To-Help project to be created in the Name text box and browse for a location for the new project.

5.   Click the Convert button to begin the conversion. A window appears showing the conversion process.

6.   Once the conversion is complete, click OK.

7.   Click the Close button to close the Convert dialog box. Your new Doc-To-Help project opens in the Doc-To-Help project editor. You can begin customizing and building your help files.