Updating wiki pages - help reqd

Hi there I was trying to update some wiki pages so they no longer use the global namespace. ie all files are currently reside in the same low level folder.

I wanted to create a sub folder so I could then create wiki pages that belonged to its parent page, but I cannot seem to get this to work. Does anyone know why this does not seem to work?

An example below

Any help would be appreciated. Cheers.

I’m not a wiki expert, but most of those I’ve seen have a flat namespace. Instiki supports multiple named wikis (not what we want here) but there’s no mention of hierarchical naming. The only wiki I know which supports hierarchies is MoinMoin, but that’s only really some server munging… it’s still a flat namespace.

You can make a horrid kludge using backslashes or colons – see Tests\Hierarchy and Tests:Hierarchy – but it’s nasty and still flat. Apart from picking a more friendly character, I don’t think there’s any other way :(

Hi Theo Many thanks for your help on this matter. I see you have carried out some preliminary testing of this in the wiki pages themselves. It helped me understand what I was doing wrong with my links.

ROOL, what are your views on how we should proceed with the wiki documentation? Should we just use the ’\’ characetr to denote hierarchy? Or are there plans to move to a non-flat namespace as Theo mentioned above?

Thanks

I think there is some misunderstanding on how a traditional Wiki works.

You don’t get to see where files are located, unless you ask for a list of all pages on the Wiki (which is indeed delivered flat). Instead, you just write pages. Any page links to any other by adding in a Wiki word, as you’ll know by now having played with it. And there is your hierarchy – you simply design links between pages so that they form the structure you want.

There’s already a link to the PRMs from the top-level “home” page for the Wiki, but this just plunges into a long list of components. Personally, I’d structure these pages like the PRMs themselves; the PRMs were strong because they were both a reference work and something you could read front-to-back, thanks to all the extra introductory text and structuring of the four volumes. The contents of the fifth volumes (sic.) would ideally be merged back into this wider structure.

So I’d build links named after the subjects for each of the four volumes; within each volume, links corresponding to contents pages entries; and so-on.

As far as naming your WIki Words goes, you should:

• Design namespacing if you wish to avoid Wiki Word clashes
• That would require a convention discussed on this site or explained within the Wiki itself no matter what the technical underpinnings
• This said, if the page structure dictates a hierarchy then you shouldn’t need to expose that in a link – instead of “Desktop / Pinboard” or whatever, you’d have a page for “Desktop” and this would contain the link to “Pinboard”
• Keep words simple – note a broken link from using strange characters exists on the wiki test stuff at the moment. Spaces are OK on this Wiki so we Don’tNeedToWriteLikeThis – as seen on some others – but try to avoid punctuation.

I think that covers it…

...I’ve made some edits to the Wiki pages so you can see the sort of thing I had in mind.

http://preview.tinyurl.com/chr29m

This does bring up a couple of other things:

• Keeping Wiki Words as “obvious” and simple as possible helps cross-linking. I started off with “Part 1 – Introduction (etc.)” all as part of the link, but as soon as I wrote the introduction text, which lists the purpose of the various parts, I realised that just having “Part 1”, “Part 2” etc. as the link word was a far better choice, making it easy to cross-link directly into a part from the introduction text too.
• It may be desirable for us to come up with a common style for a breadcrumb trail hand-written within individual PRM pages; since it’s internally flat the Wiki can’t easily do this itself (it might be possible to infer it from the user’s navigation actions and generate a sort of visual history as a breadcrumb trail though). At the very least, a link at the top of each sub-page back to the contents page would be useful I think, to avoid having to go back to “Documentation Home” each time.
• The biggest issue on the Wiki IMHO is still that you cannot embed / attach images directly, so you’re forced to upload them independently and add links to remote files. This isn’t a particularly good solution but it’s (still) all we have at the moment.

Finally, I’m not sure that namespacing is immediately obviously necessary. I think you should just write the most logical Wiki Word to fit within the text at hand and link to a new page. If you save your edits and discover that such a page already exists then you could perhaps alter your wording a bit to avoid the clash, or just hack it and add in some kind of numerical index – e.g. “for more information see the section [[Introduction (2)]]”.

Even more finally, I note that Instiki development has livened up in the last year or two and the project doesn’t look anywhere near as dead as it once was. The ROOL site used Instiki very early on but it was buggy and too problematic to fix in the timescales available, so I shifted to I2, which was a branch from the same source. I2 was a lot more stable but had a lot less features.

If we move to Instiki’s head revision – assuming no howler bugs exist – then it provides a few nice extra features such as Zip file export of the Wiki and page categorisation. We could thus tag PRM pages with a “prm” category (say) and I could add features to the ROOL site template for the Wiki which give access to lists of pages, updates etc. filtered by categories.

It might take a while to do this because of the modifications needed to integrate any recently-imported component with the single sign-on mechanism, the reliance of Instiki on a newer Rails version than present on Arachsys currently (which isn’t the problem since you can freeze local copies of Rails with an application – but Rails 2.3 in turn requires a newer version of the ‘gem’ package manager underneath and this is a problem), the need to re-skin Instiki for the ROOL site and, of course, the need to do some testing. It may prove difficult to migrate data from the old Wiki too, if Instiki’s internal data model has changed much.

Point for Alan…

The ‘subdirectories’ links don’t work in the version control system. So:

https://www.riscosopen.org/wiki/documentation/pages/The+Window+Manager+Technical+Details

works, but:

https://www.riscosopen.org/wiki/documentation/pages/The+Window+Manager+Technical+Details/versions/26

has broken links like:

https://www.riscosopen.org/wiki/documentation/pages/The+Window+Manager+Technical+Details/versions/The+Window+Manager+Polling

It’s unfortunate because the ‘Recently revised’ RSS links to the version stamped pages. This is my main point of entry into the documentation system rather than the menu links. So you get this not only by clicking ‘Back in time’ (where it’s less likely to be annoying if you’re just editing the page)

hmmm. Thanks for letting me know about this.

Sounds to me like we will need someone within ROOL to have a look at the rail code to see if this can be amended somehow.

Thanks for the report. This is a Wiki bug rather than a user error.

https://www.riscosopen.org/tracker/tickets/205