[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Upgrading the OIC Wiki: What Broke Awfully?
Here is the interesting problem with the dramatic unannounced changes made to the OASIS TC Wikis.
First, any use of the wiki to document the creation of wiki text in support of the Specification Analysis was left incorrect after the upgrade. That is, the explanation of how to maintain the Specification Analysis will be incorrect since the discussion and explanation of the wikiText format will be unchanged. It is as if the old help pages were kept with the upgraded wiki (even though put through the upgrader).
I have no idea whether this case would have come to mind if there had been prior notice of the upgrade and the dramatic changes made to the wikiText format. I didn't catch it after the fact until I was cleaning up a page that did have construction information and examples.
I do know that without advance notice and discussion, there is no way I could have prepared for this. I wonder if any notices prepared at the time the version 1.6 format was introduced identified this case as something users would have to investigate and remedy manually.
This really is an interesting case study in change management and broken up-down-level interoperability of a format.
- Dennis
ACTUAL ILLUSTRATION OF THE PROBLEM AND WHAT IT TOOK TO CURE IT
This page is what was left by the upgrader for a discussion of Appendix B (References) and how it is created and maintained with live links to the references from other parts of the specification on the wiki:
<http://wiki.oasis-open.org/oic/SpecAnalysis/1.1/B/Discussion?action=recall&rev=5>
The grayed links are the ones that were not properly upgraded, being left in [[self:... ]] link formats. That's easy to fix with a search and replace function (though the replace varies depending on the specific case).
The interesting problem is revealed when you scroll down and look at the documentation that is included on how to edit the wiki in a way that honors the conventions I am using.
There's an amusing cast at section c1 under the construction notes. (I can't use a permalink because those always go to the latest version, an edge case I overlooked until this moment.)
Of course, the discussion and the examples are incorrect, even though the actual wikiLinks have been updated. There is no way for the wiki upgrader to know the text talks *about* the use of anchors and links and uses literal exemplary text that the upgrader is not supposed to touch because the wiki doesn't touch it.
Here is the manually re-edited page update after repair and review on the corrective-maintenance plan I am following:
<http://wiki.oasis-open.org/oic/SpecAnalysis/1.1/B/Discussion?action=recall&rev=6>
You can see that the [[self: ...]] links have been repaired in the Context section at the top. You can also see that the section on Creating Citation Permalinks is now different in some critical respects:
<http://wiki.oasis-open.org/oic/SpecAnalysis/1.1/B/Discussion#dB-c1> (Don't be confused. This link always goes to the latest, corrected version.)
You can also do a compare of the two wikiTexts on the info tab and you'll see that there is a lot more than just removal of "self:" in various places, although there are also a fair number of those:
<http://wiki.oasis-open.org/oic/SpecAnalysis/1.1/B/Discussion?action=diff&rev1=5&rev2=6>.
-----Original Message-----
From: Dennis E. Hamilton [mailto:dennis.hamilton@acm.org]
Sent: Monday, August 31, 2009 18:04
To: 'OIC TC List'
Cc: 'Mary McRae'
Subject: RE: [oic] Upgrading the OIC Wiki: What Broke? - UPDATE
I found a different change being made for the macros that introduce images.
1.5 In the Specification Analysis, there were image-link macros of the old-style form
[[ImageLink(imageURL, wikiURL, alt=alt-text)]]
(if I remember correctly). The 1.6 upgrader correctly rewrote these as links in the new format:
[[wikiURL|{{imageURL|alt-text}}]]
where wikiURL is the click-through target
imageURL is the URL of the image itself
alt-text is the hover text on image
and also accessibility help
-----Original Message-----
From: Dennis E. Hamilton [mailto:dennis.hamilton@acm.org]
http://lists.oasis-open.org/archives/oic/200908/msg00031.html
Sent: Thursday, August 27, 2009 15:20
To: OIC TC List
Cc: Mary McRae
Subject: [oic] Upgrading the OIC Wiki: What Broke?
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
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]