Upgrading the OIC Wiki: What Broke?

["Dennis E. Hamilton" <dennis.hamilton@acm.org>]

There were two significant changes to the wikiText format as we and others were using it and the 1.6 version that was mechanically upgraded to in early August.

I describe those changes below as a little case study in what happens when up- and down-level interoperability is broken.  That some of the automatic upgrading from one format to the new one failed is also instructive.  Might make a nice case-study paper for a computer class, or at least a blog post or two.

 - Dennis

1. CHANGING MACRO BRACKETS

   1.1 The syntax for macros was previously of the form "[[macro-form]]".

   1.2 For wiki 1.6, the format is now "<<macro-form>>".  This change enabled the major change to link syntax (below).

   1.3 This applies to the Specification Analysis wiki in the (new-format) macros like

       <<Anchor(Chapter1)>> for placing text anchors on page fragments

       <<Date(2009-08-27T21:27:05Z)>> inserted for timestamps, as when using @SIG@.

   1.4 The upgrade is a rather straightforward replacement of "[[" and matching "]]" outside of comment lines with "<<" and ">>", at least for these two cases of macros.

2. CHANGING LINK SYNTAX

   2.1 The syntax for making links on a wiki page was by using wikiText of the form

           [wikiURI]

or         [wikiURI text]

and the result is an HTML link in the web rendering of the wikiText.  When the text is present, it appears as the underlined text that has the clickable link behind it.  If there is no text, the wikiURI is used as the text.  There will be more to say about wikiURI syntax in (3, below).

   2.2 The corresponding syntax in version 1.6 is

            [[wikiURI]]

or          [[wikiURI|text]]

   2.3 Again, upgrading is a rather mechanical change and it would have gone unnoticed (unless you are editing a page and surprised to see the new syntax) except that wikiURI format has also experienced some breaking changes.

   2.4 (You can now see why the changes in (1) needed to be made, and effectively be made first, in order to provide for the link syntax change.)


3. CHANGING WIKIURI SYNTAX

   3.1 A wikiURI is my term for the special forms that are allowed and used as the first text in a [[wikiURI...]] entry.  The wikiURI ends immediately before "]]" or "|", whichever occur first.  A wikiURI could not contain spaces in previous versions.  I do not know if that has changed.

   3.2 An absolute HTTP URI can be used as a wikiURI.  The resulting HTML <a> element link will have that as the href attribute value.

   3.3 A wikiName, possibly with subfolder names and fragment references, can be used as
a wikiURI.  It is always relative to the top of the wiki.  For example, on the OIC TC wiki

   [[SpecAnalysis/Construction/templates#aTemplates|Specification Analysis Construction Templates]]

will produce a link with text "Specification Analysis Construction Templates" and an href value linking to

    http://wiki.oasis-open.org/oic/SpecAnalysis/Construction/templates#aTemplates

This technique, along with sub-foldering in the wiki names, is used heavily in the Specification Analysis portion of the OIC Wiki.

   3.4 SPECIAL WIKI SCHEMES.  There were also special wikiURI schemes that have no URI counterparts.  These schemes used ":"-terminated scheme names in the wikiURI.

It appears that special scheme names have been removed in wiki 1.6.  For example, links that were originally in the form [wiki:mumble text] have been upgraded to the form [[mumble|text]].

   3.5 BROKEN SCHEME UPGRADE.  The problem in the upgrader is the replacement of links in the old format of form [wiki:self:mumble2 text2] with the form [[self:mumble2|text2]].  In 1.6, the wikiURI self:mumble2 is translated as a URL-escaped wiki name in the web-page link.  That is not the correct upgrading of those links.  

   3.6 It is not difficult to repair the broken wiki:self: upgrades.  It is only necessary to do a search and replace on [self: in the upgraded wikiText and substitute a correct leading part to result in a correct wikiName reference.  This correction will be context-specific, but it will be easy to make as part of a manual review in any reasonably-capable text editor.

4. WHAT DO "DOCUMENTED" AND "UNDOCUMENTED" MEAN FOR AN OPEN-SOURCE WIKI?

I am not sure where I learned about the scheme [wiki:self:... ] but I found it necessary to have subpages work properly.  I probably acquired my techniques from a combination of copy and paste, help-page review, and experimentation.  I'm not clear how I would have known the wiki:self: scheme was an "undocumented feature," and the old documentation is now gone so I can't check.

It is valuable, in fact, that the help pages that are supplied as part of 1.6 wikis have been upgraded to reflect the current syntax.  

However, http://moinmo.in/Documentation is typical.  Trying to find the syntax changes (rather than the installation instructions for upgrading) requires system administrator skills and knowledge of how to find the /docs subdirectory of the moin-moin download site.

Ah well ...

Dennis E. Hamilton
------------------
NuovoDoc: Design for Document System Interoperability 
mailto:Dennis.Hamilton@acm.org | gsm:+1-206.779.9430 
http://NuovoDoc.com http://ODMA.info/dev/ http://nfoWorks.org