Pagination, topic naming, and context-sensitive Help

When you link or import a FrameMaker document, you define how FrameMaker content is presented as topics in RoboHelp. With Technical Communication Suite, you can set how the content is paginated, topics named, and map context-sensitive Help topics for integration with a product.

Considerations for pagination and topic titles

Determine the pagination option suited to your environment based on the following factors:

Completeness of content in the topic
Ensure that the topic generated contains relevant and complete information for the reader. For example, if you set pagination for Heading 3 level paragraph, it is possible that the topic contains only the task information, without the required contextual information that is covered in another Heading 3 level topic. To avoid such disconnected topics, set the pagination at a higher level so that complete information is available in a single Help topic.

Drop-down text
Ensure that the paragraph format for the drop-down text body is not set for pagination. The paragraphs applied with this format must accompany the drop-down text caption paragraph format.

Even though it is easy to define pagination and topic title generation based on FrameMaker paragraph formats, this approach has the following limitations:

Lack of topic-level controls
Because the pagination settings are set at the project level, you cannot exercise discrete control over topics that are not in the defined heading levels. For example, suppose you want to make an H3 level topic a separate Help topic. If you set pagination at H2 for your project, you can’t do so. The H3 topic is included under the topic immediately above it.

Uniform topic naming convention
Help topics use the same file-naming conventions that you define in the conversion settings, especially if your authoring environment is Structured FrameMaker. You can’t deviate from these conventions.

Lack of flexibility in topic titles
You cannot selectively alter the titles or filenames of the topics without changing the source content. When you search for content in RoboHelp, topic titles are displayed in search. An intuitively titled topic helps the reader quickly identify the most relevant information from search results.

Possibility of inconsistency in documents from multiple books
Linked and imported FrameMaker documents from multiple books can lead to inconsistent heading styles for generated topics.

For example, suppose you link to or import FrameMaker documents from a user guide and reference guide. In this case, topic titles can reflect differences in style for instructional content and reference content. If topic titles are derived from the paragraph text at which pagination is set, the Help topics generated can have inconsistent titles.

Advantages of setting pagination from within FrameMaker

Using custom markers in FrameMaker, you can overcome these drawbacks for smaller projects and do the following:
Create workflow-based content
With the intelligent use of custom markers in FrameMaker, you can create RoboHelp topics that present users information about the workflow. You can create Help topics irrespective of the heading styles applied in the FrameMaker document.

Optionally, define the titles of the topic
This option becomes useful when you want to combine many topics and assign a relevant title to the combined topic, rather than derive the topic title text from one of the heading styles.

Optimize topic length
Because you define from FrameMaker how Help topics are created in RoboHelp, you can precisely control the topic length suited for topic-based authoring. However, if you use the mini-TOC feature for your Help topics, limit the number of headings included in a topic. A long mini-TOC can make the topic contents accessible only through scrolling.

After you define these markers in your FrameMaker documents, you can set the conversion settings in RoboHelp to create and name topics according to your preferences.

Pagination options

You can define how FrameMaker content is segregated as different Help topics in RoboHelp.

Create separate HTML topics based on FrameMaker paragraph formats
You specify the heading styles in FrameMaker that should be used as the page break. For example, if the FrameMaker file contains ten topics, each with subtopics, tasks, and tables, you can have each topic convert into a separate HTML file. If each of these topic headings is at Heading 1 format, you can set each Heading 1 topic to be created as a separate HTML topic. On the other hand, if you set the pagination at Heading 2, separate HTML files are created for each Heading 2 topic,

Define Page Break markers in FrameMaker content
You can insert Page Break markers at the beginning of the paragraph in FrameMaker documents. Typically, you create page breaks at the heading levels that you choose. If you use this option, avoid defining pagination setting based on paragraph formats.

Use custom markers defined in FrameMaker
If you are converting legacy content in FrameMaker that used custom markers to define pagination using other tools, you can use this option. Avoid using the Page Break markers in such documents.

Topic name options

You can define how topics that are generated from FrameMaker content will be named within RoboHelp. By default, you can define the text of the paragraph set for pagination as the topic name. In addition, you can define other naming conventions. If the filenames use sequential numbering, such as helptopic001.html and helptopic002.html, you can define the pattern for such conventions.

Based on paragraph text
When you set heading styles for pagination, the heading text becomes the default filename for the topic file created in RoboHelp. For example, suppose you define Heading 2 for pagination, and the FrameMaker document has two Heading 2 topics, “Introduction” and “Beyond basics.” In this case, RoboHelp creates the topics introduction.htm and beyond_basics.htm. Thus, you get intuitively named HTML files that indicate the topic title.

Topic Name Pattern
Topics are named according to the selected pattern. You can select one of the following or create a topic name pattern using the Topic Name Pattern building blocks provided by RoboHelp. In addition, you can add standard static text, such as “HelpTopic,” followed by sequential number as the topic name pattern.

Building block

Converted topic name pattern

default

HTML topic generated has the filename consisting of the paragraph text.

<$filename_no_ext>-<$paratext>

HTML topic generated has the filename consisting of the filename of the FrameMaker document without the .fm extension and the topic title, separated by a hyphen. For example, the FrameMaker document named “Chapter.fm” with "1-Introduction" as paragraph text is converted to an HTML topic with the filename "Chapter-1-Introduction.htm”

<$filename_no_ext>-<n>

HTML topic generated has the filename consisting of the filename of the FrameMaker document without the .fm extension and the paragraph number separated by a hyphen. For example, the FrameMaker document "Chapter.fm" is converted to an HTML topic with the filename "Chapter-1.htm"

<$paratext_no_num>

HTML topic generated has the filename consisting of the paragraph text of the paragraph format at which pagination is set, without the paragraph number. For example, a heading 1 paragraph "1. Introduction" is converted to an HTML topic with the filename "Introduction.htm"

<$paratext>

HTML topic generated has the filename consisting of the paragraph text of the paragraph format on which pagination is set. For example, a heading 1 paragraph "Introduction" is converted to an HTML topic with the filename "Introduction.htm"

Topic Name Marker
You can use topic name markers in the FrameMaker document to create topic titles and filenames from the marker text. If you select this option, the pagination settings applied on the Paragraph Styles pane are ignored. Use this option to precisely control the creation of separate Help topics from the FrameMaker documents.

Page Break Marker
If you are creating new content in FrameMaker, and do not want to use custom markers to define pagination, you can use the Page Break marker. When you define the topic title, FrameMaker automatically creates the topic name based on the topic title.

Avoid using this option when your FrameMaker document already contains custom markers for pagination, or when you want to define pagination based on FrameMaker paragraph formats.

Define topic name settings

  1. Select File > Project Settings.

  2. In the Import tab of the Project Settings dialog box, click Edit under FrameMaker document.

  3. In the Other Settings tab, select the required option:

Context-sensitive Help markers in FrameMaker documents

If you are using Technical Communications Suite, you can define the context-sensitive Help map IDs within FrameMaker itself, in addition to using other markers.

You can convert the context-sensitive Help markers that you insert in your FrameMaker documents and reuse them as map IDs. You specify the context-sensitive Help marker in the Project Settings dialog box before linking FrameMaker documents. You can also specify this setting when you import FrameMaker documents. You can work with context-sensitive Help markers in FrameMaker documents in two ways:

Automatic conversion of map IDs from FrameMaker documents
You apply context-sensitive Help markers in your FrameMaker documents, and specify the marker type in the conversion settings. RoboHelp imports the markers from FrameMaker documents and adds the map IDs from the strings contained in the context-sensitive Help markers.

Manually adding map IDs
You can use the map IDs you received from your development team in two ways:

  • From within FrameMaker, use the CSH marker option to enter the map IDs for the topics that you want generated. This option is available only if you are using the Technical Communications Suite.

  • From within FrameMaker, use the map ID as the text for the marker that you want to use the context-sensitive Help marker. When you link or import the FrameMaker documents, you specify the context-sensitive Help marker in the conversion settings.

If you are using the first option, avoid specifying the context-sensitive Help marker in the conversion settings.

Specify the context-sensitive Help marker

  1. Select File > Project Settings.

  2. In the Import tab of the Project Settings dialog box, click Edit under FrameMaker Document.

  3. In the Other Settings group of the Conversion Settings dialog box, select Context-Sensitive Help Marker.

// Ethnio survey code removed