Wiki (Rev #5, changes)
Showing changes from revision #4 to #5:
Added | Removed | Changed
Preface 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.
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 Everyone can edit pages have “Edit” links at the bottom for logged in users – to find out more about logging in, please read the “ Wiki. To do so, you Log must be logged 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
Basics
…or 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.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 try to and link to an existing page, the best way is to find a page that already has such a link, edit it, copy the bit same where it makes the link, cancel the edit, go back to the page you as were someone originally else, modifying you’ll be warned that they’re doing so. You should wait and paste try in again the later. 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.Never edit a page being edited by someone else.
It’s Wiki 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 use even something “roll called 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).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.
Hyperlinks
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.
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.
Creating new pages, or links to existing pages
When New in pages doubt, are find created a by page adding that /Wiki seems words/ to do an something /existing/ similar page. to Such what “magic words” are presented as links that take you have in mind and edit it to examine other how pages, it just did like something. on Don’t pretty forget much to cancel editing if you decide not to make any changes! other web site.
Automatic section numbering
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:
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:[[Some New Page]]
- 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:
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.
<div id="toc_heading"></div><div id="toc"></div>
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).
It To is link strongly to recommended existing that pages, you just add write a two level opening 2 and heading closing after square brackets surrounding the table title of contents the line, page e.g.: of interest.
<div id="toc_heading"></div><div id="toc"></div> h2. Preface Start of content here...
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:
Pages never die
You can find more information on [[Some Page Title|this page]].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.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.
Occasionally Links 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 outside to structural changes in the first Wiki, place. whether elsewhere on theROOL site or on a different web site altogether, can safely use normal Textile markup.
It is suggested that pages that are no longer required, should have their contents removed, and replaced with:
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.
This …or will words ensure to that any effect. 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).
Images, documents, audio and video
Adding links
- Edit a page and add a link of the form:
or[[mypic.jpg:pic]]
or[[mymovie.ogg:video]]
or[[mysound.wav:audio]]
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.[[myfile.pdf:file]] - Save the page, and click on the resulting link.
- 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.
- 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.
Social
and
ROOL Store
Buy RISC OS Open merchandise here, including SD cards for Raspberry Pi and more.