You are here: Defining and Organizing Topics

Defining and Organizing Topics

The Topics Icon displays a grid view of the Help topics derived from the source documents during compilation. It also provides an interface for setting properties of individual topics, such as index keywords and context-sensitive Help IDs. The left hand pane of the project editor contains a tree list allowing the author to view specific types of topics. You can view all topics, deleted topics or topics with and without Attributes, Context IDs, Groups and Keywords. Additionally, you can sort the topics in the right project editor pane by using the convenient outlook style grouping and filtering features provided with ComponentOne Doc-To-Help 2007.

Doc-To-Help derives topics from your source documents. In multiple topic documents, there is not an explicit way for you to create a new topic from scratch. Instead, you create topics indirectly by applying a paragraph style to one or more source document paragraphs in Microsoft Word or your HTML editor, defining a like-named active paragraph style in your Doc-To-Help project, if one does not already exist, then compiling the affected documents either individually or by building the Help target. After compilation, you can view the newly created topics and edit their properties in the Topics window. With single topic documents, a new topic is created in your Doc-To-Help project when you create a new document. You can view the new topic and its properties immediately once it is created; you do not need to recompile the document.

The term active paragraph style denotes a style that Doc-To-Help uses to define topics. Any style with a numeric outline level is active. For example, the predefined Doc-To-Help styles Heading 1, Heading 2, and Heading 3 are active, while, for example, the built-in Word styles Normal, Body Text, and List Bullet are not. If you have your own document templates or cascading style sheets that use other styles to format topic titles, you can import them into a Doc-To-Help project so that they are recognized during compilation.

A topic from single topic document is automatically available when it is added to the project. Topics from a multiple topic document do not formally exist in a Doc-To-Help project file until you build a Help system. During a build, each Word source document is compiled as follows:

1.   Doc-To-Help saves a copy of the document, which is placed in a folder created by Doc-To-Help. Your original document is never modified. Once created, the copy is not modified, although Doc-To-Help may delete it during subsequent builds. This applies to all source documents, single and multiple topic.

2.   For each paragraph in the document, Doc-To-Help compares the name of the associated style against the names of the active paragraph styles defined in the Doc-To-Help project. This applies to multiple topic Word or HTML source documents.

3.   For each paragraph that matches an active style, Doc-To-Help adds a topic record to the project file using the text of the entire paragraph as the topic title. (If the topic was already encountered during a prior build, Doc-To-Help does not add a new record.) This applies to multiple topic Word or HTML source documents.

4.   Doc-To-Help generates one or more additional intermediate files in a format that is appropriate for the current Help target. These files include suitable mark-up symbols derived from the topic records and other elements of the project file. This applies to all source documents, single and multiple topic.

Once all source documents have been compiled, Doc-To-Help combines all marked-up intermediate files into a single entity. For WinHelp and HTML Help, this step involves running a Microsoft compiler. For other Help targets, Doc-To-Help generates ancillary files (such as HTML framesets) as needed.

Notes:  Only the topic title should be formatted with the active paragraph style. In the topic you are now reading, the paragraph above containing the words Defining and Organizing Topics is formatted with the Heading 1 style, but the remaining paragraphs are formatted with the Normal style.

Topic titles must be no more than 255 characters long, or else a compile-time error occurs.

Topic titles defined by a paragraph style with a Level 1 type must be unique within a document. That is, a single document can contain multiple topics named Example if each is formatted with a different level 1 paragraph style, but it cannot contain multiple topics named Example that are formatted with the same style. The only way to have multiple like-named topics that are formatted with the same style is to place each in a separate source document. These restrictions are enforced at compile time.


Topic Properties

Making a Paragraph Style Active

Specifying the Help Contents

Specifying the Navigation Sequence

Providing Links to Subtopics

Providing Links to Specific Topics

Customizing the Related Topic Jumps

Labeling Subtopic Links

Providing Links to the Next Topic

Editing Topic Properties

Adding a Link Tag to a Topic

Modifying the Help Contents

Context Sensitive Help

Sorting Topics For Easy Viewing With Outlook Style Grouping

Filtering Topics in Doc-To-Help