Manual for the open-sTeam WiKi

The sTeam-Wiki syntax is similar in many aspects to that used in popular wiki engines. To write a wiki1, you just write down your text, using some special notations to structure your text or set it in a certain way. Wikis use a syntax that aims at being more simple than complex markup languages like HTML, so that it probably won't take you long to learn the few special notations that you need in your wikis.

Note: This documentation is also available as smaller, interlinked documents, which might be easier to browse.

Anchors

Anchors are positions in the text that can be linked to. To create an anchor, you enclose a hashmark ('#') and a pipe symbol (vertical line: '|'), followed by an index text, in double brackets. This can be thought of as an anchor hyperlink without a target, and with the anchor index as link text.

The index text may only contain letters a-z / A-Z, digits 0-9, dashes ('-') and underscores ('_').

Headings automatically have anchors with an index like the heading text, but with spaces replaced by underscores and any invalid characters omitted.

Footnotes also have anchors, which are the same as the footnote index text.

Anchors can be linked to by using a special hyperlink notation.

[[#|hello]]This line has an anchor called 'hello'.

[[#hello|Link]] to the 'hello' anchor above.

Annotations

Text can be annotated by opening brackets, writing the text, followed by the annotation in brackets, and then closing the first brackets again.

this is [an annotated[this is an annotation]] text

Embedding Wikis

To embed other wikis directly into your wiki, enclose the name of the desired wiki document in curly braces.

{Paragraphs.wiki}

First\Second

Footnotes

Footnotes are enclosed in brackets. You write a hashmark ('#'), followed by an (optional) index (some identifier you use for referencing this footnote) and then followed by the footnote text, again in brackets.

This can be thought of as writing an annotation, with a hashmark and index as the annotated text and with the footnote text as annotation. The index can be omitted, but if you specify an index, you can reuse the footnoe in the wiki by using an anchor with the footnote index. Anchors to footnotes are automatically made visible in the text by outputting the footnote number.

The footnote texts are usually output at the end of the page, but if you would like to output them at a different position, you can explicitly output them with the '@@FOOTNOTES@@' notation.

simple[#[a simple footnote]]

anchored[#myref[an anchored footnote]]

here is another reference[[#myref]] to that anchored footnote

Headings

Text enclosed in equation signs is considered a heading. You can define up to four levels of headings by using one to four equation signs.

Horizontal Line

To separate two paragraphs with a horizontal line, type five or more consecutive hyphens ('-').

-----

Hyperlinks

To make a hyperlink to another wiki document, enclose the name of a wiki document in the same room within double brackets. If the document's name ends with '.wiki', then you can omit the '.wiki' suffix. If you link to a wiki document that doesn't exist, then a wiki document with that name will be created when a user follows the link. You can also link to wikis in other rooms by prepending the name of the room, or the name of an exit in the current room to the name of the wiki, separated by a colon.

To link to an anchor defined in the wiki (e.g. a heading), prepend the name of the anchor with a hashmark ('#').

Hyperlinks to external URLs are enclosed in single brackets.

If you would like to specify a different link text than the link target, you can append the link text to the link target, separated by a pipe symbol (vertical line: '|').

link to a wiki: [[Wiki-Documentation]]

link to a wiki (with link text): [[Wiki-Documentation|Index]]

link to a wiki in another room: [[SomeRoom:My-Wiki]]

link to an anchor: [[#Hyperlinks]]

link to a website: [http://www.open-steam.org]

link to an email-address: [mailto:info@www.open-steam.org]

Images

Images can be embedded into the wiki by enclosing the text 'image:' followed by the name of an image object in the same room as the wiki in double brackets. This can be thought of as making a hyperlink to an 'image'.

Example:

[[image:why_wiki_wiki.jpg]]

---

Indentation

To indent text, type a colon at the beginning of the line.

:a line beginning with a colon ':'

Italics and Boldface

Text enclosed in double apostrophes is displayed in italics, while text enclosed in triple apostrophes is displayed in boldface. To combine the two, just enclose your text in five apostrophes.

''italics''
italics

'''boldface'''
boldface

'''''italics and boldface'''''
italics and boldface

List of all Wikis in a Room

The special notation '@@LIST@@' outputs a list of all wikis in the room. The entries in the list are hyperlinks to the corresponding wiki documents. You can omit wikis from the list by specifying them with a minus sign ('-') in front, either separated by spaces after the '@@LIST' text, or by putting them on separate lines before the closing '@@'.

You can also create a list of just a few selected wikis by specifying them with a plus sign ('+') in front instead of a minus sign. This will only use these specified wikis and not all wikis from the room.

@@LIST@@

@@LIST -First.wiki -Second.wiki@@

@@LIST
-First.wiki
-Second.wiki@@

@@LIST
+First.wiki
+Second.wiki@@

Lists

There are two types of lists: bullet lists and numbered lists. Lines that start with asterisks ('*') will be put in a bullet list, with the depth of the entry being defined by the number of asterisks. Numbered lists are defined in a similar way, but by using hashmarks ('#') instead of asterisks.

* this is a bullet list
** this is a sub-item
*** deeper...
* ...and on the first level again

# this is a numbered list
## this is a sub-item
### deeper...
# ...and on the first level again

Mathematical Formulas

The syntax for mathematical formulas is rather complicated. Formulas are enclosed between '<math>' and '</math>' tags, and the formula itself is written in LaTeX syntax. The description of that syntax is beyond the scope of this documentation, but you will find a lot of information about it on the internet when searching for 'short introduction to latex'.

<math>c = sqrt{ a^+b^ }</math>

Overview of all Wikis in a Room

The special notation '@@OVERVIEW@@' outputs an overview of all wikis in the room. This overview is just a concatenation of all wikis in the room pasted together. You can omit wikis from the overview by specifying them with a minus sign ('-') in front, either separated by spaces after the '@@OVERVIEW' text, or by putting them on separate lines before the closing '@@'.

You can also create an overview of just a few selected wikis by specifying them with a plus sign ('+') in front instead of a minus sign. This will only use these specified wikis and not all wikis from the room.

@@OVERVIEW@@

@@OVERVIEW -First.wiki -Second.wiki@@

@@OVERVIEW
-First.wiki
-Second.wiki@@

@@OVERVIEW
+First.wiki
+Second.wiki@@

Pike Code

The most complex and complicated notation that can be used in sTeam-wikis is the pike code notation. This notation is written as '@@PIKE@@', where everything between '@@PIKE' and the closing '@@' is considered to be pike code and will be executed. The code should return a string, which is output directly into the resulting HTML code. The pike code is usually enclosed in curly braces.

@@PIKE{
return "The current date is: "+ctime(time());
}@@

Table of Contents

The special notation '@@TOC@@' inserts a table of contents at that position, containing links to all headings in the wiki. The levels of headings included in the table of contents can be specified by appending them to the 'TOC' after a colon.

The table of contents will automatically have an anchor called 'TOC'.

@@TOC@@

@@TOC:23@@

[[#TOC]]

Tables

Wikis can also contain simple tables, which are enclosed in '{|' and '|}' (curly brackets and pipe symbol / vertical bar). If the line after the opening notation begins with a pipe and a plus sign ('|+'), then the text on that line will be used as the table caption.

New rows are defined by writing a pipe and a hyphen ('|-') on a single line. New cells in a row are defined by starting a line with a pipe ('|') and then the text that should be in that cell.

({
|+A sample table
|cell 1.1
|cell 1.2
|cell 1.3
|-
|cell 2.1
|cell 2.2
|}