Tag Archives: TocEntry

Flare Topic Titles, Topic Headings, and TOC Labels

If you create Flare topics and TOCs outside of the Flare application, it is a good idea to learn the differences between topic titles, topic headings, and TOC entry labels.

In the Flare UI, when you drag a topic from a Content folder to a TOC in the TOC Editor, the topic is added to the TOC. That topic already had a title and at least one heading. In many cases, a topic’s heading matches its title. The TOC label created when you drag the topic to the TOC will match the topic title and possibly the heading text. But sometimes those items do not match.

Why? Because a topic title, topic heading, and TOC entry label are distinct values.

Within the XML for a topic in a Flare project, there are elements which closely follow the patterns for XHTML. There is an html element which contains a head and a body element. If you view the markup for the topic file, you can see both. If you view the topic file in Flare’s XML editor, you can only see the html, body, and children of the body element. The head element is not accessible. But if you view the properties for the topic such as through the right-click menu, you can see items maintained in the head element. One of these is the value of the title element, a child of the head element. It appears on the Topic Properties section of the Properties dialog for the topic file as Topic Title.

The topic title also appears in many browsers as the title on the browser tab for the page rendered in the browser tab. When you use a breadcrumbs proxy, the topic title is the text you see in breadcrumbs.

MadCap Flare 8 Documentation: Changing Topic Titles

Flare TOCs do not contain topics. Flare TOCs have references to topics. These references are primarily established through links. In the markup for a TOC, a reference to a topic is a Link attribute in a TocEntry element. The text that appears in the TOC Editor for the topic reference is the value of the Title attribute for the TocEntry element. When you view the Properties for an entry on a TOC from the Flare UI, there is a Label field on the Appearance section. The value in the Label field is the value of the Title attribute for the TocEntry element. The TOC label appears in help outputs as the text in the TOC navigation. But in print outputs, the topic heading is used.

MadCap Flare 8 Documentation: Changing the Label for TOC Entries

The heading in the topic influences the behavior of cross-references. If you update the heading and then a cross-reference to the heading, the cross reference will reflect the heading text. But updating the heading will not affect the label on the TOC. However, the choice for first heading will affect the topic title if you add the topic through the TOC Editor and indicate for the title to match the first heading.

Here is a useful exercise: Create a Flare topic from the TOC Editor. Then compare the Properties for the topic with the topic markup, topic heading, the label for the node in the TOC, and the TocEntry element in the TOC markup. Do the same comparison for an existing topic dragged to a TOC. Finally, make some changes and compare the markup.