Tag Archives: MadCap Flare

Flare to MediaWiki to Flare (part 2, make an API call and a Flare TOC)

To get the wiki pages, something has to make the API calls. A program is needed. I decided to build it rather than look for one that fits. But the plan was to use preexisting libraries to access the MediaWiki API if possible. I also decided to go with a Visual Basic project for this next part of the experiment. That decision could have gone many ways. MediaWiki is built on PHP, so that would be a good choice. Java is nice (and I’m familiar with it) and there are plenty of scripting languages which would fit the bill. But, this program is going to run on the same machine as a Flare installation. Flare is a .NET application and so too will be this program to move content to and from Flare projects.

But the real motivation to use Visual Basic was Linq to XML. Once wiki markup was converted to XML, there would probably be more XML manipulation to perform. Linq to XML is good for that. The general idea to get conversion framework started was this:

  • Make an API call to get the list of pages on the wiki
  • Create a one level Flare TOC based on the list of pages
  • Make API calls to get the wiki page markup
  • Convert the wiki markup to some kind of XML
  • Create Flare topics with the XML

Accomplishing that will not finish the MediaWiki to Flare conversion part of the story. But it will give it a good start and something to work with. Once the basic framework for moving the content is in place, other decisions can be made such as how to handle persisting metadata from the wiki page.

In a previous post, how to create a Flare topic with Linq to XML was demonstrated. So one piece of the puzzle is out of the way. I decided to tackle the easier part of the problem firstly: getting the list of pages and creating the Flare TOC. This was started at the end of the previous post with this API call:

Which returns this:

When I looked at that, TRANSFORMATION screamed in my head. But I wasn’t sold yet. A previous post demonstrated how to perform a transformation to create a Flare topic from XML with XSLT and the approach is roughly the same to create a Flare TOC from XML data. But before that, I figured I should create a Visual Basic project. I created a Console Application project called MediaWikiToFlare. At this point, I planned to run the conversion from a command line or PowerShell.

I know I said I planned to use a preexisting library for the API calls. But just to start, I decided to hard code the REST call. Here is a good example for Yahoo API REST calls: Make Yahoo! Web Service REST Calls With VB.NET. I followed that basic pattern for my initial test. I used Linq to XML to store the returned XML and to make the conversion to a new document.

I created the folder structure for the save:

And ran the application. A file called WikiPages.fltoc was created in the folder. Here is how the file contents look:

Flare to MediaWiki to Flare (part 1, getting started)

I asked for suggestions for posts on the Users of MadCap Flare on Linkedin. The first one was to see content flow freely between Flare and a wiki. I’m not promising anything. But the suggestion is very good and it is worth a try. I saw some posts on MadCap Software Forums about this. It sounds like Flare to wiki to Flare has been done with varying degrees of success.

I’m going to try this with MediaWiki. Click a few links from a Google search and you’ll see that MediaWiki is not necessarily the preferred wiki platform for wiki customization. But Wikipedia is powered by powered by MediaWiki and that is a strong enough argument for me. The idea is to blog this as it happens. If I misstep, I’m going to blog it.

If you are reading this, you probably already have Flare installed. I have never implemented a MediaWiki wiki, so I am not going to assume everyone else has. The download is appropriately posted on the MediaWiki wiki. I downloaded 1.19.1. It is a .tar.gz file and WikiMedia notes that you can use 7-Zip to extract the files. Use the file manager application that comes with 7-ZIP. You will have to drill into the file to get to the actual folder.

I’m testing this on my computer which is a Windows 7 laptop. I copied the mediawiki-1.19.1 folder from the downloaded archive to C:\inetpub\wwwroot. Then in a web browser, I entered this URL: http://localhost/mediawiki-1.19.1/index.php, which brought up an webpage with a link to install:

I clicked that and followed the wizard. For my setup, I re-installed MySQL separately. Remember to run these items as an administrator. I had previously installed MySQL for another stack and I couldn’t remember the password. I had to reset it. Instructions to do that for Windows are here: How to Reset the Root Password. After that I mostly selected the defaults on the wizard. The point is just to get a test wiki up and running.

A freshly installed MediaWiki wiki already has a page. I didn’t add anything else right away. The big question is how to retrieve the wiki content. The solution should be programmatic and repeatable. MediaWiki has an API. There is also a bulk export. Without committing to either one, I firstly explored the API.

One requirement for this round trip is to get wiki pages from the wiki and convert the pages to Flare topics. The API is a web service and if you browse to the endpoint for the web service on your installation of MediaWiki, you can see the generated documentation page. Again, I installed the wiki locally. My installation’s API endpoint is http://localhost/mediawiki-1.19.1/api.php.

The MediaWiki wiki has an introductory example that describes a get of the content for the main page on the English version of Wikipedia. The call for my installation is:

When I viewed the call in a web browser, the browser displayed the returned XML from the call. I could have specified another format such as JSON or PHP. But I thought XML would be a safe place to start. Unfortunately, the returned XML wraps another kind of markup which is the actual content. Parsing XML would great since that is what Flare wants. But instead, it is necessary to parse Wikitext. It has been done before and MediaWiki provides a repository of links at Alternative parsers.

A few side notes: It may be worth looking into direct queries of the database which houses the wiki content. It is tempting to look into grabbing HTML. But I have a feeling that would greatly complicate the round trip back into the wiki.

The upside of the API is that other information is nicely organized in the XML. The content would be difficult without a parser. Although it would be interesting to build one, I won’t. But the rest of the metadata and probably the navigation seem easier. Here is a call to get all pages:

To recap this initial exploration, installing MediaWiki isn’t perfectly strait forward but it isn’t terrible. MediaWiki has an API which among other things can be used to retrieve content. Content is not in XML but in Wikitext. There are many Wikitext parsers out there already and there is no reason to reinvent the wheel.

Regular Expressions and Flare Markup (Danger)

Danger ahead…

This post does is not a recommendation to use regular expressions for automation which involves XML and XHTML parsing. Unless you are watching the action or verifying the results later, there are dangers to using regular expressions to parse XML and XHTML. This is discussed extensively on developer forum websites. Computer science curricula which describe language theory may even include formal proofs which demonstrate why parsing XML and XHTML with traditional regular expressions is impossible.

There is a particularly colorful post about the subject by Jeff Atwood called “Parsing Html The Cthulhu Way.”

Flare has a find and replace feature which supports wildcards and regular expressions. The feature includes an option to search source code. In other words, you can search the text of a topic or the underlying markup. Flare’s find and replace works well for project-specific needs. Analyzer includes more advanced features to find items. This is a better option if your goal is to change markup. But the functionality is also project-specific. Since Flare artifacts are text files, non-Flare text editors can be used to edit Flare artifacts. And many editors support regular expressions.

If you maintain content in a small number of projects, find and replace in Flare may be sufficient. But if you use many projects to maintain your content, an external find and replace may come in handy. When you step outside of Flare, find and replace are limited to the XML and XHMTL of the Flare artifacts. When working within Flare, find and replace works within the context of the XML (semi-WYSIWYG) editor as well as in the context of the text editor (true XML).

Many programs which support text find and replace also support scripting. Visual Studio includes find replace functionality which can be scripted through Visual Studio macros. The .NET framework has its own flavor distinct from Visual Studio. Many scripting languages and IDEs support find and replace. Most have their own variation of syntax and functionality.

XML and XHTML are text. Regular expressions parse text. It is tempting to use regular expressions to parse XML and XHTML. But when it comes to XHTML and XML, regular expressions have limitations. In computer science terms, traditional regular expressions describe a regular language. XHTML and XML are not regular languages. A regular language can not fully parse a non-regular language. In particular, regular expressions have difficulties with nested tags.

Many languages called regular expressions exceed the scope of traditional regular expressions. For example, some languages called regular expressions support recursion and backtracking. This can be exploited to overcome issues with nested tags.

Since Flare projects are openly maintained in XML, XHTML, and CSS text files, there are patterns in Flare artifacts which can be exploited through regular expressions. For XML and XHTML artifacts, the formatting for markup is similar. There is an opening and closing tag which wraps content.

The obstacle to changing elements with markup such as XML is to change both the opening tag and the corresponding closing tag. The natural desire is to identify the content of the tag in such a way that the closing point of the content is also identified. Another obstacle is implementations of regular expressions may differentiate line ends from other characters. There is potentially more than one line end in any given element. So that must also be considered.

The issue with line ends can be handled. Some issues with nested tags can be handled. But as an overall solution for XML and XHTML parsing, regular expressions are not appropriate. Here is a demonstration as to why.

Let’s begin with a simple regular expression to find the opening tag for a p element. Assume we have a document which contains this element in the source: <p>Example</p>. In the Find field of a find and replace feature, enter <p>. With Visual Studio, if you attempt to find with this value, with no options selected, the opening p tag will be found and highlighted. If Use: Regular expressions is selected, p will not be found. The greater than and less than symbols must be escaped if Regular expressions are used. To escape a character in Visual Studio regular expressions, precede it with \. So adjust the find field to:

With Use: Regular expressions selected, <p> will be found and highlighted. But if Use: Regular expressions is not selected, a message will appear which says:

The following specified text was not found: \<p\>

So far, we have no problems. We sought to find the opening tag for a p element with no attributes and no whitespace in the tag. In order to find the rest of the content in the opening tag’s first line, we can adjust the regular expression to:

This expression uses . to represent any character other than line breaks and * to represent unlimited repetitions of the preceding item. The effect is to return everything until there is a line break. With Use: Regular expressions selected, the entire line is found:

If the goal is just to find content starting with a particular tag which spans one line, that technique is sufficient. But there are two more considerations. Firstly, line breaks are still an issue. Let’s look at an element with a line break:

The same find with Use: Regular expressions would find:

The line break excluded everything after the first line from the find. In Visual Studio regular expressions, a line break is represented by: \n

and “or” is represented with: |

Changing the find to:

Will return everything after and including the opening p tag. But the expression does not stop until the end of the file. The expression will find everything including <p> and after. To terminate the find text at another point, we can specify not to include a character. Visual Studio regular expressions indicate any one character not in a set with:

[^…], where the ellipses is the set of characters

We can use this to specify a stopping point for the find this way:

Now the find will return every thing from the opening p tag up to the first closing tag in the markup, any closing tag. And herein lies the problem. Elements can be nested in elements. For example, the p element may contain a span element or an a element. You could continue down this road for a while. But the more you adapt (complicate) a regular expression to handle situations, the less elegant the solution becomes.

In short, regular expressions work well for some plain text problems. With markup, regular expressions work well for innermost elements, which are elements which contain no other elements. Regular expressions also work well for changing attributes for every kind of element. For example, name=” for p, pre, b, and every other element. But for true XML and XHTML parsing, regular expressions are not reliable.

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.