Wiki (Rev #7, changes)

Showing changes from revision #6 to #7: Added | Removed | Changed

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 page 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.
For security though, 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.

Pages 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.

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]]

[[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 itself is as 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.