Pagination for Help

When you link or import a FrameMaker document, you define how the contents of the FrameMaker file are presented as topics in RoboHelp. For example, if the FrameMaker file contains ten topics, with each topic containing subtopics, tasks, and tables, you can set each topic to appear as 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.

Even though you can set pagination for any FrameMaker paragraph format, follow these guidelines:

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.

Topic name pattern

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. In addition to this default scheme, 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.

  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 one of the following:

    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
    Topics are named after the marker applied in the FrameMaker document. Ideally, you specify the topic name as the marker text, so that topic names reflect their content. 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.

Limitations of style-based pagination and topic titles

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 pagination based on FrameMaker custom markers

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.

Convert context-sensitive Help markers from FrameMaker documents

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 a map ID file
If you received map IDs from your development team, you use these map IDs as the context-sensitive Help marker text strings for the marker to be used as context-sensitive Help marker in your FrameMaker documents. Later, you create a map ID file by associating the map IDs from the development team and the context-sensitive Help marker text you inserted in the FrameMaker documents. You then add this file to the project. When you link or import the FrameMaker documents, you specify the context-sensitive Help marker in the conversion 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 group of the Conversion Settings dialog box, select Context-Sensitive Help Marker.

Apply FrameMaker conditional text build expressions

You can apply the Show/Hide settings of the conditional text build expressions to the content in your FrameMaker documents imported into RoboHelp projects. RoboHelp imports the content after applying the Show/Hide settings to the FrameMaker content. Any text that is hidden is not brought into RoboHelp project.
  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 Apply FrameMaker Conditional Text Build Expression.