Monthly Archives: September 2012

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>
</ul>
# <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>
&Agrave;
&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:

http://www.php.net/

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.

Index.php:

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.