Tag Archives: Topics

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.

Flare Topics (part 1)

Topics in a Flare project are XML files. Here is the markup for a basic topic file in a Flare project:

The first line is called the XML declaration.

If you edit a Flare topic with the XML Editor in Flare, you can not change that declaration. But you can alter the declaration outside of the XML Editor. For example, you can open the topic file with the Text Editor in Flare, delete the declaration, and save it. If you open the file with the XML Editor again, Flare will recognize the file is no longer an XML document and offer to convert the document to XML with a wizard.

Following the declaration are XML elements.

The root element in this document is named html. It contains two other elements (head and body) and a namespace (xmlns:MadCap=”http://www.madcapsoftware.com/Schemas/MadCap.xsd”). These XML elements correspond to elements used in HTML and XHTML. But a Flare topic file in a project is an XML document. Therefore, the html, head, and body elements in the XML document are XML elements. The correspondence is purposeful. Topics in a Flare project are not HTML. But is possible to generate HTML output based on the topics in a Flare project.

If you look at the structure information in the XML Editor, you will notice head element is not included. There is a block for html which contains body. You can right-click the html block for a menu of actions you can take on the html element. These actions focus on adjusting the attributes for the html element. For example, you can add a class attribute. Flare determines which values are allowed for the class attribute through a stylesheet, CSS file. This is the case for all of the elements in the Flare topic. The class attribute of an element in a Flare topic should correspond to a style in a CSS. But if you change the value of the class attribute outside of the XML Editor to a value not defined in the CSS and open the file again in the XML Editor, Flare will respect the change. But you will not be able to set that particular value for another element in the file using the XML Editor unless you add a style to the CSS.

The namespace in the html element refers to a MadCap Software schema document. The html element in a Flare topic file in a project should conform to that schema. The schema is an XSD file.

If you want to make changes to the head element in a Flare topic from the Flare user interface, you can right-click a topic file in the Content Explorer and select Properties. Some of the actions you can take on this Properties screen involve the head element attributes and others involve the html element attributes. For example, you can also change the class for the html element from the Properties screen (Topic Properties > Topic Style Class). For the head element, you can add a title element from the Properties screen (Topic Properties > Topic Title).

Flare provides an XML Editor, a Text Editor, and right-click behavior to open files with other programs. So you can easily find out what the effect of an action in Flare is by observing the changes in the XML Editor and comparing those changes to the markup in the Text Editor. Sometimes the interface gives hints. For example, you can insert a text box into a topic with the Insert > Text Box… menu item in the Classic view or the Insert > Text > Text Box button on the Ribbon view. The screen that appears makes it clear that text boxes in Flare are div elements. You can also see this in the structure blocks in the XML Editor. On the Text Box screen, you can set items such as width. From the XML Editor, you can also adjust the width through a floating drop-down or the right-click menu for the div block. But it may not be apparent that the width is stored in a style attribute for the div element until you view the markup in the Text Editor. Not every div is a text box.

With a better understanding of topics in a Flare project, we can recognize how topics change when they are generated into an output. But firstly, let’s review the workflow to generate output such as a PDF or a help file. This is a broad overview.

Source files are maintained in Flare projects. Source topics are XML files. TOCs are XML files which organize topics. Targets define how to build a output such as a PDF. There is a TOC associated with every target. When you build a target, Flare creates an output structured according to the target’s associated TOC. Sometimes an output includes a file structure and files which correspond to the source project structure. HTML5 output is an example of this. HTML5 output can have a Content folder and a Project folder just like a Flare project. But the files inside those folders are different. For example, topic files in Flare projects are XML files but topic files in HTML5 output are HTML5 files.

If you produce HTML5 output which includes this topic,the generated HTML5 topic may look like this:

The declaration at the top of a generated topic in HTML5 output is the declaration defined by the HTML5 standards in progress. For WebHelp output, the declarations at the top of the generated topics are one of the three options in the XHTML standard. If you produce WebHelp output which includes this topic, the generated XHTML 1.0 topic may look like this:

If you produce WebHelp Mobile output which includes this topic, the generated XHTML Mobile Profile 1.2 topic may look like this:

In each of these outputs, the declarations at the top of the document are different from the XML source document. The attributes for the html element also vary. For each output, there are different children in the head and body elements. In the head element, the meta, link, and script elements are tailored to the needs of the output.

Before we look closer, let’s review some other Flare artifacts which influence the output. In addition to an association with TOCs, targets for online outputs have an association with a skin and a topic stylesheet. Skins establish the appearance and user interaction wrapping a generated topic displayed in a web browser. Skins support interactions such as TOC navigation and search. Stylesheets have already been mentioned in context of topics. But there are also stylesheets associated with skins. With topic stylesheets, you can edit the styles through Flare’s topic stylesheet editor or you can go outside of Flare to edit the stylesheet. Most of your outside edits will be still supported by the Flare editor. You can adjust some of the styles for skins from the skin editor in Flare.It is also possible to adjust the stylesheets used by the skins. But these stylesheets are not maintained in your project. Rather, skin stylesheets live in the installation folder for Flare. If you make changes to these stylesheets, the changes are global to any output created on the machine. For outputs such as HTML5 where both the topic and skin stylesheets are exposed in the file structure of the output, you can potentially perform post-build processing to change the behavior of the output.

There are links to different stylesheets and each output may use different JavaScript to control the skin behavior. A quick inspection of the values of the href attributes of the stylesheet links indicates how the stylesheet is used. Skin stylesheets have a path such as:

Topic stylesheets have a path such as:

From the perspective of the generated topic, the TextEffects.css is located a folder back and three folders down another path. For example, if the generated topic is in this folder:

Then the TextEffects.css file is in this folder:

The ../ part of the file path means parent directory. For the topic stylesheet above, the CSS file is in a subdirectory of the topic file. So there is no notation for parent directory at the beginning of the file path. But both path in the link element href attributes are relative paths. This way you can copy the output files anywhere and the output still works.

In summary, topics in Flare projects are XML files. You can edit the text of a topic file directly in the XML Editor and you can change attributes and elements through features in the Flare user interface. Topics in a Flare project are source files which are transformed when Flare builds a target to generate an output such as a PDF or HTML5 help. The generated topics may appear as another document type sucha s HTML5 or XHTML in the file structure for the output.