source: project/wiki/wiki-syntax @ 8447

[[tags:wiki syntax]]
[[toc:]]

== Introduction

This document describes the syntax used by [[http://wiki.freaks-unidos.net/svnwiki|svnwiki]] to represent
contents in a wiki.

If you have suggestions to improve svnwiki, please [[http://wiki.freaks-unidos.net/svnwiki-suggestions|let us know]].

== Text Formatting

=== Creating a paragraph

To create a paragraph simply enter the text. You can place a single
newline anywhere in your paragraph and it will have no effect.

To split a paragraph use two consecutive newlines (an empty line).

The above two paragraphs could have been written as:

 To create a paragraph simply enter the text.
 You can place a single newline anywhere in
 your paragraph and it will have no effect.

 To split a paragraph use two consecutive newlines (an empty line).

=== Creating titles

To create a title, use a line starting with two, three, four or five equal signs:

 == Title Name
 === Sub-title Name
 ==== Sub-sub-title Name
 ===== Sub-sub-sub-title Name

If you use two equal signs, you will create a top-level title.  The more
equal signs you use, the less important your title will be.

An alternative option for creating titles is using ''<nowiki>&lt;h1&gt;</nowiki>''
''<nowiki>&lt;h2&gt;</nowiki>'', ''<nowiki>&lt;h3&gt;</nowiki>'',
''<nowiki>&lt;h4&gt;</nowiki>'', ''<nowiki>&lt;h5&gt;</nowiki>'' and
''<nowiki>&lt;h6&gt;</nowiki>'' tags.
There is one important difference with the
previous syntax: tags created in this manner will not be included in the
articles' Table of Contents.  For this reason, you are encouraged not
to use this syntax unless you have specific reasons.

=== Font styles (bold, italics, technical)

To create '''bold''' text, use three apostrophes ('), as in: ''<nowiki>'''bold'''</nowiki>''.  Use two for ''italics'': ''<nowiki>''italics''</nowiki>''.  For {{type-written
text}}, which is useful for technical documentation, use
this syntax: ''<nowiki>{{text}}</nowiki>''.

Related with type-written text, you can mark entire paragraphs
to be shown in type-written text.  This is used for lines that
correspond to program's output or commands that a user should
enter.  To active this all you need to do is start each line in
your paragraph with a space.  Paragraphs written in this manner
are shown as follows:

 > uptime
  23:04:03 up 14:18,  1 user,  load average: 0.02, 0.06, 0.18
 > uname -a
 Linux azul 2.6.10 #1 Mon Feb 7 00:20:16 COT 2005 i686 GNU/Linux
 >

=== Font size (big, small)

To increase or decrease the size of the text you can wrap it around
a pair of ''<nowiki>&lt;big&gt;...&lt;/big&gt;</nowiki>'' and
''<nowiki>&lt;small&gt;...&lt;/small&gt;</nowiki>'' tags respectively.

Example:

 <nowiki>&lt;big&gt;This text is big...&lt;/big&gt;</nowiki>

 <nowiki>&lt;small&gt;... and this is small.&lt;/small&gt;</nowiki>

This is shown as:

<big>This text is big...</big>

<small>... and this is small.</small>

 
=== Centering text

To center text you can wrap multiple paragraphs (and lists, titles, etc.) with a pair of ''<nowiki>&lt;center&gt;...&lt;/center&gt;</nowiki>'' tags, as in:

 <center>
 some text
 * item
 * another
 </center>

This will be shown as:

<center>
some text
* item
* another
</center>

=== Special characters

svnwiki automatically replaces certain sequences of characters with HTML
entities that browsers display better.  The following is the list of sequences:

 <nowiki>(R) (C) <- <-> -> <= <=> => -- --- << 1/4 1/2 3/4 >></nowiki>

These sequences are replaced with these characters respectively:
(R) (C) <- <-> -> <= <=> => -- --- << 1/4 1/2 3/4 >>

 
=== Quotes

If you want to make quotes, you can start your lines with ''>'' (the
standard character for email quotation).  Alternatively, you can
surround it with <nowiki>&lt;blockquote&gt; ... &lt;/blockquote&gt;</nowiki>

This text will be show as:

> I am enough of an artist to draw freely upon my imagination.
> Imagination is more important than knowledge.
> Knowledge is limited.
> Imagination encircles the world.


 
== Organizing your article (Table of contents, lists, tables, horizontal lines)

=== Table of Contents

If you want to show the table of contents of an article, use the following
code:

 <nowiki>[[toc:]]</nowiki>

This will be replaced with the table of contents.  You can see an example at
the beginning of this page.

=== Lists of items

You can create lists of bullets or numbers by starting your lines with
asterisks or number signs:

 * Some item
 * Another item
 ** A sub item
 ** Another sub item
 **# A numbered sub sub item
 **# Another numberd sub sub item
 * The last item

The above list will be rendered as:

* Some item
* Another item
** A sub item
** Another sub item
**# A numbered sub sub item
**# Another numberd sub sub item
* The last item

As you can see, you can mix bullets and numbers lists any way you want.

=== Lists of Definitions

You can create a list of definitions by using multiple lines with the
following syntax:

 ; ''TERM'' : ''DEFINITION''

This is useful to give a list of terms along with their respective
definitions.

Example:

 ; Lassie : A very intelligent dog.
 ; Garfield : A pessimistic cat.
 ; Tux : A fearsome pinguin.

This list is shown as:

; Lassie : A very intelligent dog.
; Garfield : A pessimistic cat.
; Tux : A fearsome pinguin.

=== Using tables

You can create a table using the standard HTML syntax, based on the
<tt><nowiki>&lt;table&gt;</nowiki></tt>,
<tt><nowiki>&lt;tr&gt;</nowiki></tt> and
<tt><nowiki>&lt;td&gt;</nowiki></tt> tags.

Example:

 <nowiki>&lt;table&gt;</nowiki>
 <nowiki>&lt;tr&gt;&lt;th&gt;Country&lt;/th&gt;&lt;th&gt;Number of cities&lt;/th&gt;&lt;/tr&gt;</nowiki>
 <nowiki>&lt;tr&gt;&lt;td&gt;Colombia&lt;/td&gt;&lt;td&gt;16&lt;/td&gt;&lt;/tr&gt;</nowiki>
 <nowiki>&lt;tr&gt;&lt;td&gt;Argentina&lt;/td&gt;&lt;td&gt;16&lt;/td&gt;&lt;/tr&gt;</nowiki>
 <nowiki>&lt;tr&gt;&lt;td&gt;Brasil&lt;/td&gt;&lt;td&gt;31&lt;/td&gt;&lt;/tr&gt;</nowiki>
 <nowiki>&lt;/table&gt;</nowiki>

This is shown as:

<table>
<tr><th>Country</th><th>Number of cities</th></tr>
<tr><td>Colombia</td><td>17</td></tr>
<tr><td>Argentina</td><td>12</td></tr>
<tr><td>Brasil</td><td>31</td></tr>
</table>

Currently it is not possible to include parameters in any of the above tags;
this will probably be fixed in a future release.

=== Horizontal dividing line

You can include an horizontal dividing line with the followking markup:

 ----

This is shown as:

----

== Creating Links

To create links use ''<nowiki>[[dst]]</nowiki>'', where ''dst'' is the
link target.  You can use relative or absolute URLs.

If you want your link to display a text other than its target, use
''<nowiki>[[dst|Some text]]</nowiki>''.  This will be shown as:
[[dst|Some text]].

Here are some examples:

* <tt><nowiki>[[http://wiki.freaks-unidos.net/]]</nowiki></tt>
* <tt><nowiki>[[default|Home Page]]</nowiki></tt>

== Including Images

To include images in your articles use the following text:

 ''<nowiki>[[image:URL|ALT]]</nowiki>''

Here you'll need to replace ''URL'' with the URL of your image (which can
be absolute or relative) and ''ALT'' with a simple description of the image.

Example:
 ''<nowiki>[[image:http://azul.freaks-unidos.net/files/svnwiki-small.png|Image]]</nowiki>''

Renders this:

[[image:http://azul.freaks-unidos.net/files/svnwiki-small.png|Image]]

== Svnwiki and programming languages

=== Syntax coloring

You can embbed code or information in many file formats or programming languages;
Svnwiki will use [[http://www.codento.com/people/mtr/genscript/|GNU Enscript]] to highlight it.
Use the <nowiki>&lt;enscript&gt;</nowiki> tag and pass the programming language or file format as the highlight parameter.

For example,

 <nowiki>&lt;enscript highlight=c&gt;</nowiki>
 static void
 pinst_check ()
 {
   pid_t pinst = pinst_find();
   if (pinst != -1 && kill(pinst, 0) != -1)
     printf("%s: server alive (%d)\n", program_name, pinst);
   else
     printf("%s: server is not running\n", program_name);
   exit(EXIT_SUCCESS);
 }
 <nowiki>&lt;/enscript&gt;</nowiki>

is shown as:

<enscript highlight=c>
static void
pinst_check ()
{
  pid_t pinst = pinst_find();
  if (pinst != -1 && kill(pinst, 0) != -1)
    printf("%s: server alive (%d)\n", program_name, pinst);
  else
    printf("%s: server is not running\n", program_name);
  exit(EXIT_SUCCESS);
}
</enscript>

Note that in order for this to work you'll need to have GNU Enscript installed.
If you don't, the information will be shown with no coloring.

The following languages are supported: ada asm awk bash c changelog cpp csh delphi diff diffs diffu dylan eiffel elisp erlang forth fortran fortran_pp haskell html icon idl inf java javascript ksh lua m4 mail makefile matlab nroff oberon2 objc outline oz pascal perl postscript pyrex python rfc scheme sh skill smalltalk sml sql states synopsys tcl tcsh tex vba verilog vhdl vrml wmlscript zsh.

=== Embedding Scheme code

It is possible to embbed entire programs in
the Scheme programming language inside the wiki pages.
svnwiki will execute it securely (in a safe environment)
and replace it with whatever output it produces.

For example, you could include code that prints some numbers:

 <nowiki>&lt;scheme&gt;</nowiki>
<enscript highlight=scheme>
(let loop ((a 0) (b 1) (i 0))
  (cond
    ((< i 10) (format #t "<p>~A: ~A~%" i a) (loop b (+ a b) (+ i 1)))))
</enscript>
 <nowiki>&lt;/scheme&gt;</nowiki>

This code would get replaced with the following:

<scheme>
(let loop ((a 0) (b 1) (i 0))
  (cond
    ((< i 10)
     (format #t "<p>~A: ~A~%" i a)
     (loop b (+ a b) (+ i 1)))))
</scheme>

Note that the output of the Scheme code will be included literally
in the page (so you can output HTML tags directly).

=== Literal code

To include something in a page literally (preventing svnwiki to convert it
from wiki to HTML), place it inside a <nowiki>&lt;nowiki&gt; ... &lt;/nowiki&gt;</nowiki> pair.

----

If you have suggestions to improve Svnwiki, please [[http://wiki.freaks-unidos.net/svnwiki-suggestions|let us know]].