Wiki (Rev #4)

Preface

A Wiki is a way of allowing visitors to a web site to edit the content of that site. ROOL use this for general documentation. You’re using a Wiki right now if you’re reading this page.

Creating pages

New pages are created by adding Wiki words to any existing page. Such “magic words” are presented as links in the page, that take you to other pages, just like on pretty much any other web site. When a Wiki is first made, it has one initial (usually empty) home page defined automatically; after that, Wiki words in that home page link to other pages and so-on. The whole structure of pages – what links to what – is entirely defined in this way. More on how to create Wiki words later.

If you’re browsing around the RISC OS Open documentation section and you see some text with a dark grey background followed by a question mark, which is itself a hyperlink (the exact appearance will depend on your web browser), then you’re looking at a Wiki word for a page which hasn’t been created yet. Following the question mark link will take you to an editing page when you can create the very first version of that page. After this, if you go back to your original “parent” page, you’ll see that the link now appears in a more normal way without the question mark and links straight to the new page you just wrote.

Editing pages

All pages have “Edit” links at the bottom for logged in users – to find out more about logging in, please read the “Log in system” page. You can also get to the editing screen by defining a new page through a Wiki word, as described above. From the editor, you can make any changes you like and save the results, or cancel them using the links underneath the text editing area. A special text format is used for things like:

• lists

…or bold, italic, underlined text and so-on. For more details, see the help text shown next to the text editing box whenever you are editing a page.

To include Wiki words in pages, again please see the help text shown next to the editor for the page. This text describes how to add Wiki words. If you want to link to an existing page, the best way is to find a page that already has such a link, edit it, copy the bit where it makes the link, cancel the edit, go back to the page you were originally modifying and paste in the link text. It sounds cumbersome but by using a couple of Web browser windows (or tabs, if your browser supports them) it’s a really simple process and is very quick once you’ve done it a couple of times.

It’s quite safe to edit any page as you can always cancel your changes. It’s also possible to look back at previous versions of pages and even “roll back” to some earlier version so that’s what everyone sees as the current live page – perhaps you didn’t like the changes someone, including yourself, made in a recent revision and want to revert to an older version. A “Back in time” link appears next to “Edit” at the bottom of any page which has more than one revision (a new revision being created every time someone saves changes they have made to a page).

Hyperlinks

Hyperlinks to other pages in the Wiki should be done as described above. Hyperlinks to external resources are dealt with by the text formatting language that the Wiki uses (Textile), described by the help text shown next to the text editing area when you are modifying a page.

When in doubt, find a page that seems to do something similar to what you have in mind and edit it to examine how it did something. Don’t forget to cancel editing if you decide not to make any changes!

Automatic section numbering

The Wiki pulls in some JavaScript code to provide automatic section numbering for sufficiently able Web clients. Older browsers should degrade gracefully and simply show no section numbers. To use, follow these rules:

• Use header levels 2 (“h2.”) to 6 (“h6.”) only; header 1 is used already for the page title that’s placed automatically above your content.
• Don’t skip header levels; if you jump from (say) level 2 to 4, you will end up with a section number including a zero for the missing header level 3.
• Finally, to enable numbering, add the following to the very start of your page:

<div id="toc_heading"></div><div id="toc"></div>

It is strongly recommended that you add a level 2 heading after the table of contents line, e.g.:

<div id="toc_heading"></div><div id="toc"></div>

h2. Preface

Start of content here...

Pages never die

Since Wiki words automatically define links to pages, if you delete a particular Wiki word from all pages in the whole Wiki, nothing will link to that page anymore. The page doesn’t die; if you were to put the Wiki word back, you’d find it still linked to the most recent revision of the page in question. The “All pages” link at the top of each page would also show that page.

Occasionally scanning for any pages “orphaned” in this way is an administrative task and day to day users don’t need to worry about it, though it does help if you think carefully about the structure of the documentation you’re about to create before starting. That helps to avoid creating orphan pages due to structural changes in the first place.

It is suggested that pages that are no longer required, should have their contents removed, and replaced with:

No longer used. Can be safely deleted.

This will ensure that any person accessing the page, directly or indirectly, will know that it is no longer valid. It may also help in the process of identifying which pages can be safely deleted (Administrative task).