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…