Tag Archives: MadCap Flare

Sorting TOCs in a Project

TOC sorting is probably only useful for reference documentation. But please post comments with any use-cases for TOC sorting you can think of. My desire to sort a TOC is threefold. I want to be able to:

  • Flatten a TOC with levels down to one level
  • Sort a flattened TOC in ascending order by the Title attribute of a TocEntry
  • Sort a TOC with a multi-level hierarchy in ascending order by the Title attribute of a TocEntry and respect the level structure

The UI is left to you.

Create a Visual Basic Windows Forms project and build a form with items which correspond to the procedures in the sample. An open file dialog is necessary to select the TOC. With the dialogs, limit the file type to *.fltoc. The TOC structure is rendered in a tree view. I placed it prominently in the center of the form. I used buttons for the options. But radio buttons would make more sense.

A preview of the options display in the tree view when a button is clicked. But nothing is saved until the save dialog is shown. You can use that to overwrite or to create a new TOC. If I see any use-cases, I’ll post a full sample project in a later post.

Flare to MediaWiki to Flare (part 6, of wiki template articles and snippets)

A mapping effort chronicled in a blog is less than exciting to read. So let’s switch gears and lay some groundwork for the parser. We will use a Wikipedia article as the first test and as a guide for what parts of the markup to tackle firstly. Since wikis are moving targets, we will work with the markup at a specific point in time.

This discussion is going to become complicated very fast. It may seem overly complicated. But rest assured that the parser will be doing the work both ways and the complex structures created in Flare to solve the issues we encounter aren’t much more complex than the wiki markup itself.

The article is http://en.wikipedia.org/wiki/Data_mapping. We can see the source for the article by switching to the Edit tab at http://en.wikipedia.org/w/index.php?title=Data_mapping&action=edit. For my use, I copied the markup to a text file. But remember, we have already established that the markup can be retrieved with an API.

The markup begins with this line followed by an empty line:

{{Data transformation}}

The double curly braces indicate a template. Templates are described in http://en.wikipedia.org/wiki/Help:Template. The term, template, surprises me because templates are pages which can be used in other pages. Snippet or boilerplate would have made more sense to me. But with MediaWiki, templates are for content reuse.

How do we track down that template? Templates can be maintained in the Template namespace. Let’s see if that works. Look here: http://en.wikipedia.org/wiki/Template:Data_transformation.

The template is there. As of writing, it establishes a box in the upper right-hand corner of the article which provides links to data transformation topics. So we will need to pull that article over during import. At the moment, I’m leaning toward storing template articles as snippets and using a naming convention for the snippet files which indicates the file’s status as a Flare version of a wiki template.

Snippets help: http://webhelp.madcapsoftware.com/flare8/Content/Snippets/About_Snippets.htm

This popped up in a Google search: http://www.contentinsomnia.net/reusing-content-on-wikis-and-blogs/. I thought I would share the link since it confirms someone else equates Flare snippets with MediaWiki templates.

For the Flare markup, we can use this:

<MadCap:snippetBlock src=”../Snippets/Template_Data_transformation.flsnp” />

We could use a regular expression for this since the object is replace {{ with:

<MadCap:snippetBlock src=”../Snippets/Template_

And }} with:

.flsnp” />

We should also retain the line ending. This replacement is our rule A for now. Rule B is to record the template name for future export and import. By the way, there is an export option to include templates with http://www.mediawiki.org/wiki/Special:Export.

The third line in the markup is:

{{inline|date=June 2010}}

There are more curly braces. But the contents of the braces seem more complex. The first part indicates another template: http://en.wikipedia.org/wiki/Template:Inline. But the second part indicates to display a date. The template article includes instructions about how to use the Inline template. The template is an appeal to improve the article because the citations are insufficient. The date portion is a parameter: http://www.mediawiki.org/wiki/Help:Templates#Parameters. This must be why it is called a template and not a snippet. How are we going to handle parameters in a snippet? Conditions, variables, something else?

A condition applied to the markup for the snippet block is an attribute for the snippet block element. This makes a condition attractive. But imagine how many conditions we would introduce as we imported more templates with more parameters. Besides, the condition doesn’t influence the appearance of the content until a target is generated. What to include or exclude is set on targets. Similarly, variable values are set on targets. Conditions and variables don’t give us what we want.

What about styles?

That feels closer. But unfortunately, which style to use is established in the markup with a class attribute. An element only gets one of those. If class is used, every parameter value would have to be conveyed through that one attribute. We want class for styles and we don’t want hundreds of MediaWiki template parameter mapped styles.

We could also consider grouping the snippet block in a div element with other elements to represent the parameters. But unfortunately some parameters influence the text of the MediaWiki template article. With the Inline template, you can replace the word article with another word indicated in a parameter. How can we achieve parity with the wiki if this is the case? This is an important decision point. We should convey the parameters to Flare so we can make the round trip. But how concerned are we about the way the parameters are manifested in Flare? In this case, we are probably not very concerned. But the meaning of the template can be changed drastically with a parameter. We must address it.

We can address it with a new attribute. But if we do that, we will run into problems conveying the parameters if the snippet is used elsewhere with different parameters. We will convey the parameters within the name of the snippet itself.

<MadCap:snippetBlock src=”../Snippets/Template_Inline|date=June 2010.flsnp”  />

I’m not sure about the pipe character in the markup, I’ll have to check. Secondly, we can place the parameter information in the snippet so as to display in Flare as intended. We can use another snippet within the template snippet for the parameter.

Snippet propagation.

It can be named according to the template and the parameter and contain the appropriate value. When the round trip is completed, the snippet block for the parameter will be translated to the markup in the template which declares the parameter. But the parameter snippet content will not be conveyed. That content is just for Flare. We can see the markup for the Inline template here: http://en.wikipedia.org/w/index.php?title=Template:No_footnotes&action=edit.

Only one version of the snippet contents will be parsed back into wiki markup when the round trip is completed. But the parameter values will still be parsed from the template snippet names. But what if we want to edit a snippet for the template and have the changes propagate to other versions of the template? You guessed it.

More snippet propagation!

All of the content in between snippets for parameters can also be snippets. This way someone can drill down and make changes in Flare which will be reflected in each parameter set version for the snippet for the wiki template article.

The ground rules and guidelines are:

  1. Don’t rename these snippets. Renaming will change the parameter values returned to the wiki on completion of the round trip.
  2. Only create new snippets as needed. Name the template snippets and parameter snippets according to the template article name and parameter values. Follow the convention strictly. The new parameters will convey to the wiki.
  3. Consider that template changes in wikis are a big deal. Don’t take them lightly.

Wikis use bots and people to maintain things like parameters in transclusions. We are attempting to maintain a similar structure in Flare without the advantage of bots. It may be a good idea to create a validation algorithm to check these projects periodically or even constantly just to ensure the Flare side is maintained such that the wiki is respected.

And on to line 4 of the wiki markup…




Flare to MediaWiki to Flare (part 5, Still Mapping)

Initially I wanted to distinguish between parsing and mapping. But as I study MediaWiki markup, I am increasingly convinced the best approach is to map the markups and create a parsing algorithm based on that. I took a break from this series for some other posts. This is a late evening endeavor. So the pace is slow. But I put some time into the map. In the course of mapping, I’ve realized the structure of the MediaWiki markup is varied. My feeling is that the markup is a product of what works to promote wiki contribution and that it is an evolving structure.

I’m working through this Wikipedia Help article: Help:Wiki markup and making notes in a spreadsheet as I go. Developing the map will take at least a couple of iterations. At the moment, I’m through about one third of the help article. Some of the Flare tags in the table do not show the unique class which will be used. This is a pasting issue.

MediaWiki Markup Flare Topic XML / XHTML
Start End Start Tag Nested Start or End Tag Nested Start or End Tag Nested Start or End Tag Nested Start or End Tag End
== == <h2> </h2>
=== === <h3> </h3>
==== ==== <h4> </h4>
===== ===== <h5> </h5>
====== ====== <h6> </h6>
; : <div > <div> </div> <div > </div> </div>
—- <hr />
__TOC__ Mini TOC Proxy
__NOTOC__ <div />
<br /> <br />
<br> <br />
single newline <div />
empty line </p> <p>
: <div />
<blockquote> </blockquote>
<div style=”width:auto; margin-left:auto; margin-right:auto;”> </div> <div style=”width:auto; margin-left:auto; margin-right:auto;”> </div>
* <ul> <li> <p> </p> </li>
*: <p> </p> </li>
# <ol> <li> <p> </p> </li>
#: <p> </p> </li>
newline </ol>
<poem> </poem> <pre> </pre>
<i> </i>
”’ ”’ <b> </b>
”” ”” <b> <i> </i> </b>
{{Smallcaps|small caps}}
<code> </code> <code> </code>
<syntaxhighlight> </syntaxhighlight> <syntaxhighlight> </syntaxhighlight>
<small> </small> <small> </small>
<big> </big> <big> </big>
&nbsp; &nbsp;
{{pad|4em}} <div> </div>
<tt> </tt>
&Aacute; &Acirc; &Atilde; &Auml; &Aring; &AElig;
&Ccedil; &Egrave; &Eacute; &Ecirc; &Euml;
&Igrave; &Iacute; &Icirc; &Iuml; &Ntilde;
&Ograve; &Oacute; &Ocirc; &Otilde; &Ouml; &Oslash;
&Ugrave; &Uacute; &Ucirc; &Uuml; &szlig;
&agrave; &aacute; &acirc; &atilde; &auml; &aring; &aelig; &ccedil;
&egrave; &eacute; &ecirc; &euml;
&igrave; &iacute; &icirc; &iuml; &ntilde;
&ograve; &oacute; &ocirc; &otilde; &ouml; &oslash; &oelig;
&ugrave; &uacute; &ucirc; &uuml; &yuml;
&iquest; &iexcl; &sect; &para;
&dagger; &Dagger; &bull; &ndash; &mdash;
&lsaquo; &rsaquo; &laquo; &raquo;
&lsquo; &rsquo; &ldquo; &rdquo;
&apos; &quot;
<pre> </pre> <pre> </pre>
<nowiki> <nowiki>
&trade; &copy; &reg; &cent; &euro; &yen;
&pound; &curren;

MadCap Flare + Python + Google Calendar = Topic-based Training Session Scheduler?

There is no code at the end of this post. I’m just brainstorming. What triggered this is a blog post at Google: Python Client Library for Google APIs is out of Beta. Here are some other links for the library: Google APIs Client Library for Python & Write your First App: Prerequisites (Google Calendar API v3).

The idea is to create a Flare project with topics which contain training material for short, perhaps one hour, training sessions. These topics would be organized in sequential order in a TOC or browse sequence. A script would parse the output and create Google Calendar events based on some schedule parameters and the output TOC or browse sequence. The events would have links to the topics. So a student or instructor could access training content through a calendar interface.

Scheduler parameters would be maintained in an accessible place. Maybe a table in a topic or separate data file would work. Parameters would be choices such as:

  • Include weekends
  • Start date
  • Session length
  • Exclude these days
  • Exclude these hours
  • And so forth…

Python comes into play with TOC parsing and making calls to Google calendar with the client library. The Python script would parse the TOC with something like minidom. While looping through each TocEntry, the script would use the client library from Google to create events on a Google Calendar.

Since this post speculates on using Python, it may be helpful to point out that there is a post at MadCap’s MadBlog about a Python script to retrieve MindTouch content: Extracting MindTouch Wiki Content.

Other related links:

A Simple Flare HTML5 Output ‘Re-skin’ with PHP

Although I am not a huge fan of PHP, there are some things it does well. One of those is content reuse on web pages. Having previously built a (no longer extant) website which used little more of PHP than the include function, I admit the choice saved a lot of time and code for little cost. A little PHP enabled content reuse without a CMS.

This post describes a simple “re-skin” of an existing HTML5 output. The idea is to use the topic files and the Toc.xml file to recreate a navigation and topic display. This will be a simple example without many bells and whistles and no CSS. But you can build on it if you find it useful. This example does not goes as far as using the Title attribute for the text of the links or indenting the links based on topic level. This is just a proof-of-concept.

To create the PHP “skin,” you can install PHP on the web server hosting the skin, place the Flare HTML5 output on the web server, and place the code sample in a file called Index.php at the root of the Flare HTML output folder. You can read more about how PHP works at:


In the PHP file, HTML5 syntax will be used for the HTML portions and the scripting will be PHP tags. The “skin” will have a list of linked topics based on Toc.xml in the Data folder of the HTML5 output and a view of the selected topic which appears at the top when you click a link.

A previous post described how to return all of the Link attributes in the TocEntry elements in the Toc.xml file in an HTML5 output with XPATH. That was a building block post. Now we are going to use that block to build the list of linked topics.

In Flare HTML5 output, the URLs for topic navigation appear as a pound sign and topic file name after the URL for the main help file: http://localhost/flareoutput/default.htm#topicname.htm

With this PHP “skin,” the URL will look like this: http://localhost/flareoutput/Index.php?topic=topicname.htm

The first PHP script checks if there is a topic qualifier in the URL.  If there is a topic qualifier, the script removes the / from the beginning. This is because Toc.xml stores the paths that way and PHP expects no / at the beginning of relative URLs in this case. It loads the topic into an iframe at the top of the page. There is also a check to see if the qualifier is there: isset.

The second script uses the XPATH expression to get all of the Link values for TocEntry elements in Toc.xml. It displays each as a hyperlink with a format which uses Index.php and the qualifier with the topic name.

You can install PHP on your web server, copy a Flare HTML5 output to it, place an Index.php file containing the sample below at the root of the output, an open the URL to Index.php to see this work.


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 to MediaWiki to Flare (part 4, Starting to Map MediaWiki Markup to Flare Topic XML)

Parsing the wiki markup for MediaWiki wikis is a challenge. There is not a markup spec to which to build a parser. But parsers exist. There would be no Wikipedia without one.

The original plan for this blog series was to use an existing libary to parse wikitext. That may still be the solution. But to convert one markup to another, a good map comes in handy. Here is the simplest version of the map: MediaWiki wikitext > Flare topic XML. But the nuts and bolts are much more complicated.

There is a wiki page on the MediaWiki.org website which discusses the possibility of a spec: Markup spec. The conclusion I draw from reading that page is that the rules for wikitext on a MediaWiki wiki is defined by the parser for a MediaWiki site. In other words, if you want your wiki markup to work, determine the parser behavior.

Writing markup to suit the needs of a parser isn’t especially shocking. Web developers constantly tweak their HTML to accommodate the whims of web browser makers. At least with this markup, there is really only one parser about which to be concerned, the MediaWiki parser. How does that parser behave?

The Markup spec page describes the parser’s actions. Notably, the outline describes a preprocessor, a parser, and a save parser with different behaviors. This is a potential model for different parsing behaviors in the round trip. A section of the page describes parts of the markup language. For example, content within equals signs (=…=) is a first level heading. That will probably be mapped to <h1>…</h1>, possibly with an attribute to indicate the heading is derived from wikitext: <h1 class=”MediaWikiFirstLevelHeading”>…</h1>. Then again, one could just treat all h1 tags the same. We’ll see as we get deeper into the mapping.

To avoid rework, decisions about how to convey metadata in the wikitext to metadata in the Flare topic XML should be made at this point. If conveying metadata is to rely on markup, conveying metadata is a part of the mapping process. An alternative is to store that information in a separate repository, like a database. But maintaining the information in the Flare topic seems like a more convenient option at this point.

For the next post, I’ll build a table with three columns: one for the wikitext tokens, one for the Flare topic XML tags, and one to explain the mapping behavior. That process will go on for a few posts until the mapping is satisfactory.


Frameborder around Topic Frame in WebHelp

You can’t remove or change the frameborder around the topic frame in WebHelp with the skin editor. At least I haven’t figured out how. Moving to the HTML5 target type eliminates the issue. But in case you aren’t ready for that yet, here is how you can change it post-build with a Visual Basic command line application.

  1. Create a Visual Basic command line application project in Visual Studio.
  2. Add the module below.
  3. Build the application. You may need to add some references to your project.
  4. Copy the executable to a known location.
  5. Use the application from the command line or a batch file. The argument is the name of the file to update.
The originating frameborder setting is on line 35 of Default.htm in this folder or a similar location in your installation:

You could change it there. But that would change the setting for any WebHelp generated on your Flare instance. Or you can change the setting post-build in the corresponding file in WebHelp output. The program reads the the text of the file into a string, changes the frameborder setting text in the string, and replaces the text of of the file with the string. Double double quotes are escape sequences for double quotes in Visual Basic.

Flare to MediaWiki to Flare (part 3, Placeholder Flare Topics)

In the previous post about this effort, I discussed the MediaWiki API and how to create a Flare TOC from the response from an API call. The same approach is possible for the Flare topics. But since the wiki page content is not maintained as XML, the conversion is more complicated from wiki page to Flare topic. That is why this post is called Placeholder Flare Topics. Converting the wiki markup will be tackled in a subsequent post.

It may also be a good idea at this point to note some technical debt in the work so far. Although an API call was made and a TOC was created, there are a few other considerations depending on the MediaWiki instance. Firstly, some calls may require authentication. The example so far did not because I did not require a password for myself as the administrator on my local instance. But down the road, the issue of authentication will come up. But the issue has been encountered by many others and handled before, so I feel it is okay to leave that one for later. Secondly, some calls to the MediaWiki API may have limitations on the number of items returned. This is this case for the list of pages call from the previous post. If the wiki becomes large enough, that will have to be addressed.

Creating a Flare topic can be accomplished in the same way as the creating the TOC. Determining what topics to create can be accomplished by cycling through the TocEntry elements in the TOC and using Linq to XML to create one. Populating the topic with content can be accomplished through a MediaWiki API call to retrieve the content and then parsing the wiki markup to create XML. This post’s sample will only show how to create the topics and touch on the API call. For now, I haven’t broken anything out into separate procedures so that you can see the similarities between the TOC creation and the topic creation. Here is the updated (and only partially checked) code:

Notes about Word and MadCap Flare

This isn’t a code-oriented post. Here are a few thoughts about how to use Word as a part of your Flare infrastructure.

When it comes to technical authoring, inevitably, someone will ask if they can use Microsoft Word. And as author’s skills with Word grow, so does their attachment. A desire to structure content, create a single source, and produce multi-channel output lead the author to ask, how can I do those things with Word? It’s a fair question and it isn’t impossible to accomplish those things with Word. But if you are reading this, you have probably passed through that learning curve.

Word is everywhere and there are many solid use-cases for Word. It turns out that Word can be leveraged to improve one’s Flare workflow as well. In particular, two features of Word combined with Flare’s Word imports can be very powerful.

Flare’s Word import functionality is strong. If a Word document has been thoughtfully constructed with Styles, Flare can do a lot with it. Styles in Word map nicely to CSS styles in Flare. Word emphasizes headings in the default style galleries, which eases delineating Word headings into Flare topics.

Microsoft Office supports a technology called Object Linking and Embedding (OLE). OLE enables embedding of other objects, such as Visio diagrams, into Office documents. A Visio diagram embedded in Word can be seen by the reader of a Word document as a diagram. But to someone editing the document, it can be edited as a Visio file. When a Word document with an embedded Visio diagram is imported into Flare, the resulting item in Flare is an image file and a reference to it in the corresponding Flare topic.

This is great if you want to manage content by subject matter experts. It is almost certain the SME is familiar with Word. If the SME is technically minded, there is a good chance she is familiar with Visio. An SME can create content in Word, including embedded objects, and that content can be imported into Word.

One can place the Word file in a known place, such as on a network drive. If you agree to only edit the Word document and not the resultant Flare topics, the SME can come back and make changes time and time again. Add to that, the SME can update embedded objects and those will come over on the import also.

But Word can be used to as a starting point for a Flare project too. The natural use for Word import is to import existing content. When a Word shop switches to Flare, Word imports are central to the conversion process. But Word can also help create new content. Here is why.

Think about the experience of creating a Flare TOC with blank topics from scratch. It is pretty easy. But it takes longer than creating a new Word document and adding headings to create an outline. So why not just create the Word outline and import it into Flare? If you are only going to do it once, it may not be worth it. There is a time cost to setting up a Word template and a Word import file in Flare to map to the Styles in the template. But, if you like to outline your documentation before you fill in the content, it is definitely worth the time.