Wiki (Rev #12)

About the Wiki

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.

Editing pages

Everyone can edit pages in the Wiki. To do so, you must be logged in.

Basics

All pages have “Edit” links at the bottom. Using this you can make any changes you like and save the results, or cancel your edit using the links underneath the text editing area. A history of changes to pages is built up so people can see what has been changed and, if necessary, roll back to an earlier version of a page.

If you try and edit the same page as someone else, you’ll be warned that they’re doing so. You should wait and try again later. Never edit a page being edited by someone else.

Wiki pages use something called Textile which lets you define headings, tables, text styles and so forth. See the Textile Reference for more information about this main page syntax used for the Wiki, as well as many other places on the RISC OS Open web site.

An extra layer of markup is added to support the page linking and creation features of the Wiki. This is colloquially known as “Wiki Syntax” and more about this is described below.

Creating new pages, or links to existing pages

New pages are created by adding Wiki words to an existing page. Such “magic words” are presented as links that take you to other pages, just like on pretty much any other web site.

To create such a link, enclose the text that will become both the new page’s title and the visible text for the link in two opening and closing square brackets:

[[Some New Page]]

You can change page titles after creation, but you may need to update the links to that page elsewhere. In general this isn’t recommended, so think carefully about page titles before creating new pages and make sure you type them in properly.

So, to create new pages you edit an existing page, include one or more new WikiWords linking to your new pages and save your edits. The edited page will be displayed and you’ll see clearly the highlighted links, with a question mark after each, for the new pages. Follow that link to start filling in the contents of the new page(s).

To link to existing pages, just write two opening and closing square brackets surrounding the title of the page of interest.

If you want the page title and visible link text to be different, include a vertical bar in your link, following it by the text that will be seen:

You can find more information on [[Some Page Title|this page]].

You must always use Wiki syntax for links between pages – not Textile! The Wiki tries to keep a database of cross-references between pages, so it knows when pages are “orphaned” – not linked to anywhere else at all. It can also tell you which pages are “wanted” – where Wiki words refer to a page that has not yet been written. This only works if you use Wiki syntax for links. If you use Textile to link to a Wiki page, the Wiki will try to spot it and correct the mistake. It can’t always do that; your links will work, but the Wiki won’t know about them.

Links to pages outside the Wiki, whether elsewhere on the ROOL site or on a different web site altogether, can safely use normal Textile markup.

HTML and non-Wiki markup

You can wrap code in “notextile” and “nowiki” HTML-like tags if you want to tell Textile to ignore the content in between, or the Wiki to ignore the content in between.

<nowiki>I'll be ignored by the Wiki</nowiki>
<notextile>and I'll be ignored by Textile</notextile>

This means you can write HTML within ‘notextile’ tags, if you prefer that markup language. Use XHTML 1.0 transitional markup – don’t forget closing </li> tags in lists, for example, or self-closing tags for things like <br />.

For security, certain sensitive HTML tags are always removed – it is not possible to insert inline JavaScript for example. This used to be possible in an earlier version of the RISC OS Open web site Wiki but is not allowed anymore.

The Wiki engine considers preformatted or code text as literal and does not interpret its markup. The above examples don’t need <nowiki> or <notextile> escaping as a result; just plain Textile pre. or the @code@ markup syntax is sufficient. View this page’s source to find out more.

Pages should never die

If a page no longer has any links to it within the Wiki, it is technically inaccessible. However, there may be links outside the Wiki that still refer to it – forum posts, other web sites and so-on. So, pages are not deleted automatically, though a page without any links to it within the Wiki is marked as an “orphan” and shown as such in the “All Pages” list which you can reach from the sidebar to the right.

Occasionally administrators may scan for pages thus “orphaned” and delete those that look like they aren’t needed. 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.

If you intentionally want to have a page deleted because it is no longer relevant or was created by accident, remove its contents and replace it with:

No longer used. Can be safely deleted.

…or words to that effect.

Pages may die

Despite the above, pages have been known to vanish unexpectedly.

It’s therefore advisable to always create a reference to the page elsewhere in the Wiki, so it’s a complete single tree of self-contained, fully navigable documents. The simplest way to ensure this is done is by inserting a link within an existing page, then creating the new page by following the newly-generated link.

Categories

Wiki pages can be placed into categories. At the top of a page add a category declaration. This starts with “category:” (all lower case) and is followed by the category name. For example, to make sure a category called “Help” exists and to put the edited page into that category, you would add:

category: Help

Category names should be human-readable, so correctly spelled and categorised. Spaces within category names are allowed but you should avoid unusual punctuation – it is best to stick to alphanumeric characters and spaces. To assign a page to several categories, use a comma-separated list.

category: Help, Web Site, Wiki

When categories are in use, the “All pages” and “Recently revised” lists show filtering options based on those categories and the page itself gains a link to its categories at the top.

Automatic contents and section numbering

The Wiki uses 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, first make sure your page content follows these rules:

1. Use header levels 2 (“h2.") to 6 (“h6.”) only. Header 1 is used already for the “Documentation” main section title that’s placed automatically above your content.
2. 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.

Then at the top of the page, underneath a category: declaration if you have one (see above), include this HTML fragment on its own line:

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

Finally, you should make sure there is a level 2 (“h2.”) heading after the table of contents line, so that the contents table is clearly separated from the text that follows. This will become the first numbered section. For example:

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

h2. Introduction

Start of content here...

Automatic section numbering is in use on the help page you’re reading right now, to serve as a worked example.

Images, documents, audio and video

Adding links

1. Edit a page and add a link of the form:

   [[mypic.jpg:pic]]

   or
   

   [[mymovie.ogg:video]]

   or
   

   [[mysound.wav:audio]]

   or
   

   [[myfile.pdf:file]]

   The filename entered here will be the filename of the uploaded file on the Wiki. It need not be the same as the name of the file on your computer.
2. Save the page, and click on the resulting link.
3. This will bring up a file upload dialogue. Choose the file to upload, and enter a brief description.
   • For images, this description will be used as the default alt-text of the image.
   • For files, it will be used as a tooltip. It also serves as the default link text, if you don’t specify alternative link text (see below).
   • For video and audio, this will be the fallback text seen by browsers that don’t support the HTML5 <video> or <audio> elements.
4. Once the file is uploaded, the image, video or file link should magically appear on your page. If it doesn’t, go back and re-edit the page.

If you want to specify alternative alt-text (or link text), you can use:

[[mypic.jpg|alt text:pic]]

or

[[myfile.pdf|link text:file]]

Limitations

Images and videos are always shown at their full size, so make sure you shrink them down to dimensions appropriate for the page in which you intend to include them.

Media files cannot also be links. If you try and nest Wiki syntax to create an in-Wiki link that’s also an image, say, or if you try to combine a Wiki media link with a Textile link, the results won’t work and the page may not even render at all. Don’t try this!

Deleting files

Only administrators can do this – please contact us if you want help deleting an unwanted file.

Example

This page is itself an example of image links and Textile working together. The cog below uses the Wiki syntax for images, with Textile markup asking for it to be shown within a centred paragraph. Use the “Source” link near the bottom of the page to see how it works.