Tag Archives: mediawiki

Expanding wiki templates inside <pre>

I tend to do a fair amount of wiki work these days. Whether it’s scripting against the mediawiki api, or just manually editing pages … you tend pick up little tips here and there. One such gem I’ve been using for a while is to get mediawiki templates to expand when used inside preformatted <pre> tags.

Why bother? Well, when writing test cases, or related pages, I frequently provide command-line samples or output. I like to ensure that the output remains relevant over time. Even more, I dislike having to frequently update a page release after release to ensure the commands or output are still relevant. For some common QA-related <pre> tag examples, checkout the following links …

Okay, you get the idea. The fun part is hidden in the first example. What if you want to take advantage of some awesome wiki templates, such as {{FedoraVersion}}? If you try that … the <pre> tags will show you just that … pre-formatted text as shown below.

mock -r fedora-{{FedoraVersion||previous}}-x86_64 --init 

If you like puzzles, and are hell-bent on having templates expansion inside <pre> tags, let me save you a tremendous waste of time searching for the correct solution. … To expand mediawiki templates inside <pre> tags … you can use a miscellaneous parser function. The function is a bit strange, but works as follows …

{{#tag:pre| 
mock -r fedora-{{FedoraVersion||previous}}-x86_64 --init 
}}

The above syntax will produce the following wiki output …

mock -r fedora-14-x86_64 --init 

All that to emit two characters! I know, but I’m lazy and this solution helps me to never update that particular wiki page ever again. It will always point to the proper release thanks to Template:FedoraVersion. Also, thanks to a post from Das Gurke on the Customizing-MediaWiki mwusers forum for pointing out the right answer.

If you have other creative uses for the #tag:tagname parser function, please share!

Advertisements

{{Key_press}}

If you haven’t heard me say it before … “I really like media wiki.”  It’s tremendously flexible, clearly very well-used and maintained, and as there is an abundance of useful content on mediawiki.org. If you are trying to do something on the wiki, chances are someone has already done it.

For example, displaying test results on the wiki (refer to {{Result}}).  While this was started by Will Woods, it later adapted based on experiences with templating on OLPC’s wiki.  Also adapted from OLPC’s wiki is our use of {{QA/Test_Case}}.  Finally, as Athmane recently pointed out, I borrowed {{!}} and {{=}} from mediawiki so you can make use of those characters when using a template.  Who cares?  Well, if you’ve ever attempted to write an admonition (e.g. {{admon/warning}}), you may have noticed it doesn’t format properly when you include certain characters (notably = and | which have special meaning in mediawiki template syntax).

Without “escaping” the special characters, your template will render improperly as seen below …

{{admon/warning|Warning!|Sometimes a=b and b=c. 
In that case, a=c. :-| }}
{{admon/warning|Warning!|Sometimes a=b and b=c.  In that case, a=c. :-| }}

This doesn't look correct.

This can be corrected by using the {{!}} and {{=}} templates, as shown below.

{{admon/warning|Warning!|Sometimes a{{=}}b and b{{=}}c. 
In that case, a{{=}}c. :-{{!}} }}
{{admon/warning|Warning!|Sometimes a{{=}}b and b{{=}}c. In that case, a{{=}}c. :-{{!}} }}

Much better!

Today I found another really helpful series of templates for something I’ve wanted for a long time.  In Fedora QA, we write and maintain a lot of test cases on the wiki.  Often in a test case, one describes a series of steps, or procedure, to perform a particular function in a specific manner.  We extensively use <pre>, lists (both forms # and <ol>) and helper templates such as {{filename}}, {{package}} and {{command}}.

It’s always bugged me that we didn’t have a consistent, and visually striking manner for representing keyboard events.  For example, telling a tester to … “Hit <code>Ctrl-Alt-Backspace to stop Xorg” ([1]) just doesn’t stand-out to me enough.  What can I say … I’m a visual person.  I stumbled upon an awesome series of templates from mediawiki.org for displaying key combinations.  Enter … {{Key_press}}.  With the help of many smaller templates, I’ve added this support, along with the rock solid “upstream” documentation, to the fedoraproject.org Wiki.  I’m not sure who to thank for the template, as there are a significant number of editors.

So instead of something like  …

# Activate the overview by pressing the Windows key,
 pressing <code>Alt-F1</code>, or by moving the mouse
 to the top-left corner of the screen.

One can write …

# Activate the overview by pressing the 
 {{key press|Win}} key, pressing {{key press|Alt|F1}},
 or by moving the mouse to the top-left corner of the
 screen

Which results in something my brain responds to much better…

Much better!

From my docbook XML days, I appreciate structured ways to write content and separation between content and the look’n’feel.  However, I dislike editing content in XML.  Templates like {{command}}, {{filename}} and now {{Key_press}} offer a ways to accomplish the same thing with mediawiki.  I plan to use this more when documenting keyboard events in future test cases.  Hopefully, someone else finds this useful as well.

Embedding mediawiki templates inside <pre>

I’ve experimented with this a few times, but never found something that works.  My intent was to use some mediawiki templates inside code/file samples on the wiki. On the wiki, we typically use <pre> tags to properly format code/file samples. By definition, the html <pre> tag allows for pre-formatted text to be displayed as-is.  Meaning, most html tags inside <pre> will be displayed and not processed. There are exceptions for some font mark-up tags, but I’m not fully aware of which html tags are explicitly allowed inside <pre>.  Let’s try an example using the following html markup …

<pre>
This is <strong>bold <span style="color: red;">red</span></strong> text
<a href="#link">This is a link</a>
<span style="color:green;
                font-size:xx-large;
                font-family:'Times New Roman', Times, serif;
                font-weight:bolder;">big and green times</span>
</pre>

This will display in a browser as …

This is bold red text
This is a link
big and green times

Introducing mediawiki into the mix complicates things slightly. By design (as security precaution I’d guess), mediawiki does not honor all HTML tags on a wiki page. However, it does recognize and permit some tags, <pre> being one of them. As noted previously, we use the <pre> quite a bit to call out command execution or file contents.

Where the wrinkle comes is trying to use mediawiki templates inside a <pre> block. Well why would you want to do that? Often, our command samples or file contents include Fedora release version specific information. Since Fedora releases come out about every 6 months, for every wiki page that doesn’t need to reference an explicit Fedora release, someone would need to modify every wiki page that references a Fedora version. At a quick glance, that comes to about ~179 wiki pages. As I mentioned, not all of those pages would need an update when a new release comes out, but it at least gives a rough estimate.

After some searching, I came across a forum post which recommends a solution that works. To demonstrate using a mediawiki template inside a <pre> block, I’ll use the wiki page Creating_a_Test_Day_Live_Image. On that page, we recommend checking out a git branch of spin-kickstarts whose name matches the upcoming Fedora release. I’d like to use the FedoraVersion template so we don’t need to constantly update this page each time a new version of Fedora is released.

To make use of the FedoraVersion mediawiki template inside a <pre> block, you would enter the following …

<pre&lt;noinclude&gt;&lt;/noinclude&gt;>
git clone 'git://git.fedorahosted.org/spin-kickstarts.git' -b F-{{FedoraVersion|number|next}}
</pre&lt;noinclude&gt;&lt;/noinclude&gt;>

This instructs mediawiki to format the page as follows:

git clone 'git://git.fedorahosted.org/spin-kickstarts.git' -b F-14

I have no idea why the magic combination of noinclude mediawiki tags works. Bonus points to anyone who can answer: why does this work?