Monthly Archives: August 2012

Use Linq to XML with Flare Files (part 1)

Linq to XML is a library for XML manipulation for use with Microsoft’s Visual Basic and Visual C#. Linq to XML offers extensive functionality at the cost of limiting development to a .NET context. Microsoft posts information about Linq to XML here:

http://msdn.microsoft.com/en-us/library/bb387098

The Visual Basic manifestation of the System.XML.Linq interface is particularly interesting because it allows you to work with XML markup in-line with the Visual Basic code as an XML literal. For example, to create a new Flare topic from an application which uses Linq to XML, the code could look like this:

That document could also have been created with Linq to XML with C#:

Flare and Schemas (part 1)

XSD is a schema language for XML. The World Wide Web Consortium (W3C) published XML Schema Part 1: Structures Second Edition and XML Schema Part 2: Datatypes Second Edition as recommendations in 2004. W3C XML Schema Definition Language (XSD) 1.1 Part 1: Structures and W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes were published as recommendations in 2012. The W3C recommendations are posted at:

http://www.w3.org/TR/xmlschema-1/

http://www.w3.org/TR/xmlschema-2/

http://www.w3.org/TR/xmlschema11-1/

http://www.w3.org/TR/xmlschema11-2/

An XML Schema Document declares what is an acceptable structure for an XML document which references the schema. Take a look at this fragment of the XML from the XML source for the topic you are reading:


At the time of writing, when the URI value in the string for the xmlns:MadCap namespace attribute is placed in a web browser as the URL, the website for MadCap Software shows a Page Not Found message. The URI looks like a web page URL and it could be. Sometimes the authors of schemas post copies of their schemas at the URL which matches the URI. But that is not the primary function of the URI. Rather, the idea is to ensure uniqueness. MadCap Software knows that http://www.madcapsoftware.com/Schemas/MadCap.xsd can only belong to MadCap Software. This minimizes the chance that some other schema author will use the same URI.

But MadCap Flare does use a copy of the schema identified by http://www.madcapsoftware.com/Schemas/MadCap.xsd to validate the XML files which reference it. Look in the Schemas folder for your Flare installation:

In the Schemas folder there is a file called MadCap.xsd which begins this way:


As you browse through the schema, you will see Flare-centric items. For example:

When you insert a cross-reference in a Flare document, the element may look like this in the Text Editor:

The element name, xref, is qualified with the schema name, MadCap. In the opening fragment of MadCap.xsd you can see the attribute for the xs: schema element which declares the schema to require qualified elements. Were you to remove the MadCap qualifier from the name, the Flare topic would not validate against MadCap.xsd.

Knowing where the schema is comes in handy if you want to validate a Flare topic against the schema outside of the Flare interface.

Use XQuery with Flare Files

XQuery is another XML query language. XQuery uses XPath expressions, so XPath 2.0 is included with XQuery 1.0. The World Wide Web Consortium (W3C) published XQuery 1.0: An XML Query Language as recommendation in 2007 and edited to XQuery 1.0: An XML Query Language (Second Edition) in 2010. The W3C recommendation is posted at:

http://www.w3.org/TR/xquery/

To use XQuery, you need an XQuery implementation. W3C lists implementations known to W3C at:

http://www.w3.org/XML/Query/#implementations

To demonstrate XQuery, we will use a freely available technology. As of writing this, Microsoft SQL Server 2012 Express has an implementation of XQuery. You can download the database, tools, or both. But don’t feel limited to using the SQL Server implementation to learn about XQuery.

In the XPath post, we queried a Flare TOC for the Link attribute nodes for every TocEntry element. But we retrieved the attribute node. We could not filter for just the attribute value. With XQuery, we can accomplish that. Here is an XQuery code executed with Transact-SQL to create hyperlinks for every TOC entry in a generated Flare TOC in the Data folder of an HTML5 output.

The output is:

But there is a pitfall here. Not every TocEntry element has a link attribute. So be careful. If you are working with a FLTOC file in a project, there is another pitfall. Not every link is to a topic file. So be even more careful there.

Use XPath with Flare Files

XPath is a node query language for XML. The World Wide Web Consortium (W3C) published XML Path Language (XPath) Version 1.0 as recommendation in 1999. XML Path Language (XPath) 2.0 was recommended in 2007 and edited to XML Path Language (XPath) 2.0 (Second Edition) in 2010. The W3C recommendations are posted at:

http://www.w3.org/TR/xpath/

http://www.w3.org/TR/xpath20/

To use XPath, you need a supporting technology. Many scripting and programming languages support XPath expressions to varying degrees. XPath is embedded in XQuery and XSLT. And when we get to the posts for XQuery and XSLT, we will use XPath expressions. But for our first XPath example, we will query a Flare TOC from the JavaScript console in the Google Chrome web browser.

Flare TOCs are XML documents which create a hierarchical table of contents with titles and links. A Flare TOC establishes the order of topics in a target output, the level or indentation of the topic, and in some cases the heading level of a generated topic. A Flare TOC is an excellent candidate for a query of XML. In this example we look at a generated TOC in HTML5 output. This version of the Flare TOC lives in the Data folder of a target’s output. The TOC is called Toc.xml. Notice the file extension is not FLTOC as in the Flare project.

In a Flare project TOC (FLTOC), a node may link to another TOC. But in the generated output for WebHelp, WebHelp Mobile, and HTML5, these links are replaced with the nested TOC’s hierarchy and links. This content in a FLTOC file:

May end up as this in HTML5 output:

There are two versions of XPath. But rather than get mixed up in the differences, let’s create an expression to return the titles and links for a Flare TOC. XPath “sees” XML as comprised of nodes. For our XPath expression, we are concerned with the document, element, and attribute nodes.

This XPath expression returns every Link attribute in a TocEntry element in a Flare TOC (FLTOC) file or a Toc.xml file in a target output’s Data folder:

Let’s use a supporting technology to evaluate the expression. Here is how to evaluate it with Google Chrome’s JavaScipt console:

Open the Toc.xml file in the browser. If you want to try this with a project TOC file, you’ll need to save it with an XML extension. Copy the file path for the file into the URL field and click the right-arrow to go to it. The XML appears in the browser tab. Click the wrench icon and select Tools > JavaScript console. In the JavaScript console, type the following and press ENTER:

We had to use a technology other than  XPath to evaluate the XPath expression and at this point we need some other mechanism to extract the values of each attribute. XPath does not support extracting attribute values. The natural choice is to use whatever technology evaluated the expression. So we will stop here until we discuss technologies which support evaluating XPath expressions.

Flare TOCs (part 1)

Like topics in a Flare project, Flare TOCs are also XML files. But Flare TOCs are not designed to reflect the structure of HTML. Instead, Flare TOCs establish a hierarchy for topics. This hierarchy may also include other TOCs or the generated output from another system. A Flare TOC which only contains references to topic files may look like this:

This simple TOC creates a structure of four topics. Each TocEntry element corresponds to a topic file. The relative file location is indicated by the Link attribute and the Title in the TOC is indicated in the Title attribute. One of the entries contains another entry.This child entry, TestTopicA.htm, fould be considered a subtopic of TestTopic2.htm from the perspective of the TOC.

Let’s take note of some qualities of a Flare topic in relation to a TOC. A Flare topic has a filename with an htm extension. It is an XML file, but it has an HTML extension. The HTML-like markup in the Flare topic file may include a title element within the head element. The text of the title element in a Flare topic does not necessarily correspond the value of the Title attribute in a TocEntry element in a TOC. When you add a topic to a TOC, it is possible that the Title attribute takes the value of the title element in the topic. But that depends on the topic and how you go about adding the topic. When you view the Properties screen for a node in a TOC, the Title attribute in TocEntry does correspond to field called Label on the General tab. If you change the value in Label and save, the Title attribute in the TocEntry element changes. But the title element in the topic does not change.

The TOC Editor in Flare enables quick manipulation of this XML. You can drag and drop elements in the TOC within the TOC itself. You can also drag files into the TOC. You can change attributes for each element through a Properties screen. If you delete a topic in a project, Flare can check all of the TOCs to see if there is a reference to that topic. Flare does this with many of file types to ensure links are not broken throughout the project when a file is added or deleted.

If you perform actions on topic files outside of the Flare user interface, that last point is a very important consideration. Flare backs you up by checking for links. If you delete or move a topic or any other Flare artifact outside of the Flare user interface, you are on your own. But since the project structure is so open, you can perform your own checks as you see fit. For example, if you want to programmatically delete a file from a Flare project outside of the user interface, there is nothing stopping you from programmatically checking each TOC in the project for links to the topic.

Flare TOCs are not limited to TocEntry elements with references to topics.Here is a TOC with other kinds of links:

The TocEntry with Title=”Links to Topic” has a relative path to a topic file as the value of its Link attribute. We have seen this kind of link already. The next TocEntry links to another TOC file (Test.fltoc). When the outer TOC is generated, the references in the nested TOC will be included in the output.

The TocEntry with Title=”Links to Browse Sequence” has a relative path to a browse sequence. A browse sequence is similar to a TOC. The Browse Sequence Editor looks much like the TOC Editor. The file extension is different (FLBRS) and Flare outputs handle browse sequences differently than TOCs.

The next two entries include an attribute for the absolute path as well as the relative path. The entry which links to a Flare target indicates paths to the project file with bookmark notation for the target file name minus the file extension for targets. The entry which links to a Flare HTML5 output has paths to the main XML file for the help system. In this case, the file extension is MCWEBHELP.

Finally, there is a TocEntry with no link. This represents just a label in the TOC with no linking behavior. In HTML5 output, this would appear as a node in the TOC navigation with text equal to the value of the Title attribute. If there were child TocEntry elements, the node could be expanded or collapsed. But there would not be a link directly from the node.

On that note, if a TocEntry links to another TOC, there is a setting which merges the node when output is generated. The property (When merging, replace node with merged TOC) appears on the Advanced tab of the Properties screen. There are several options for this property. A Flare TOC stores this as an attribute of the TocEntry element. Here is how the element looks when the property is selected with option to Replace.

Flare TOCs manifest in different ways depending on the output type. The hierarchy of a TOC appears in a PDF as bookmarks and as the document order of topic content. In HTML5 output, the TOC navigation reflects the TOC and the links in the navigation correspond to the paths in each TocEntry. In HTML5 output, a file called TOC.xml is clearly based on the TOC associated with the target from which the output was generated.

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.