source: project/wiki/edit-help @ 36496

== Editing help

[[toc:]]

=== Introduction

This wiki uses a simplified version of the wiki syntax used by
[[http://wiki.freaks-unidos.net/svnwiki|svnwiki]].  Below you will
find an explanation of the subset that's supported by this wiki:

=== 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.
The levels correspond to HTML's {{<h2>}} up to {{<h6>}} tags. The first
level is reserved for use by the wiki itself.

The very first title will be used as the page title of the entire wiki page.
This usually appears in your browser's window title and in the search
results of a search engine so it's important to choose a good title!

This wiki does ''not'' support HTML {{<h1>}}..{{<h6>}} syntax for headings.

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

Bold and italics can be nested, but type-written text is treated as-is. This means <nowiki>''{{foo}}''</nowiki> works but <nowiki>{{''foo''}}</nowiki> does not. This is mainly for convenience, because often type-written text is used for identifiers and other programming-like material which can often contain strange sigils that might otherwise affect the wiki.

See also the section below about [[#marking-up-code|marking up code]] for
how to mark up entire ''blocks'' of program code or technical output.

== 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:

 [[toc:]]

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 numbered 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 numbered sub sub item
* The last item

As you can see, you can mix bullets and numbered 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
HTML {{<table>}} tag.

Example:

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

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>

This syntax is rather restricted and clumsy; it is hoped that in a
future version there will be better syntax for tables.

=== Horizontal dividing line

You can include an horizontal dividing line with the following 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; a relative URL
will link to a page at the same level.  ''dst'' is used unchanged as the descriptive
text, but the link target will be lowercased, stripped of special characters,
and have spaces changed to hyphens.

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]].  When descriptive text is provided, the link target
is used without change.

To link to an egg, use 

* <nowiki>[[name]] from within another egg page</nowiki> 
* <nowiki>[[/egg/name|name]] from outside an egg page</nowiki> 
* <nowiki>[[/eggref/3/name|name]] for an egg for a specific CHICKEN version (here, 3)</nowiki> 

To link to a manual page, use 

* <nowiki>[[/manual/Page name|Page name]] from outside a manual page</nowiki> 
* <nowiki>[[/man/3/name|name]] for a man page for a specific CHICKEN version (here, 3)</nowiki>

''Note'': You can't use the plain <nowiki>[[Page name]]</nowiki> syntax for manual pages, as the page URL will be lowercased and hyphenated.

Here are some examples.  Since this page is neither an egg nor a man page, we must use the full /egg or /manual syntax for those:

* <nowiki>[[http://www.call-cc.org/]]</nowiki>: [[http://www.call-cc.org/]]
* <nowiki>[[http://www.call-cc.org/|The CHICKEN wiki]]</nowiki>: [[http://www.call-cc.org/|The CHICKEN wiki]]
* <nowiki>[[/users/felix-winkelmann|Felix]]</nowiki>: [[/users/felix-winkelmann|Felix]]
* <nowiki>[[/manual/Unit posix|Unit posix]]</nowiki>: [[/manual/Unit posix|Unit posix]]
* <nowiki>[[/egg/awful|the awful egg]]</nowiki> : [[/egg/awful|the awful egg]]
* <nowiki>[[Internals]]</nowiki> : [[Internals]]
* <nowiki>[[/tips and tricks|Tips and tricks]]</nowiki> : [[/tips and tricks|Tips and tricks]]

== 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 and ''ALT'' with a simple description of the image.

Example:
''<nowiki>[[image:http://www.call-with-current-continuation.org/chicken-small.png|CHICKEN logo]]</nowiki>''

Renders this:

[[image:http://www.call-with-current-continuation.org/chicken-small.png|CHICKEN logo]]

If you keep your images in the wiki repository, the base for the absolute URL is: {{http://code.call-cc.org/svn/chicken-eggs/wiki/}}.  For example, an image {{egg-image-1.png}} uploaded into {{wiki/eggref/4}} has URL {{http://code.call-cc.org/svn/chicken-eggs/wiki/eggref/4/egg-image-1.png}}

== Marking up code

=== Syntax coloring

You can embbed code or information in many file formats or programming languages; the wiki will use the [[/egg/colorize|colorize]] egg to add syntax highlighting to it. You can use any language supported by colorize. This is a growing list.

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

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>

=== Literal blocks of preformatted text

Sometimes you don't want any fancy formatting or interpretation at
all, you just want to dump a block of preformatted text as-is onto a
wiki page.

Examples include license statements, transcripts of shell sessions,
code in alien languages not supported by colorize or when you're
frustrated by the wiki because it keeps interpreting what you're
trying to put on a page.

This is easily done by simply prefixing each line of the text you are
pasting by at least one space.

 Like this!

=== Escaping wiki interpretation

To include something in a page literally (preventing the wiki from converting it
to HTML), place it inside a {{<nowiki> ... </nowiki>}} pair.  This currently
only has an effect on HTML output (not the other outputs supported by [[/egg/multidoc|multidoc]], so please don't rely on it too much.


== Extensions for CHICKEN documentation

=== Tags for procedure-like definitions

The following tags are supported:

* {{procedure}}
* {{macro}}

Each of these should be used as follows:

  <procedure>(string-append a b ...)</procedure>

This will be roughly rendered as follows (with some divs and spans for easy CSSing):

[procedure] {{(}}'''{{string-append}}'''{{ a b ...)}}

=== Tags for other definitions

The following tags are also supported:

* {{read}}
* {{parameter}}
* {{record}}
* {{string}}
* {{class}}
* {{method}}
* {{constant}}
* {{setter}}
* {{syntax}}
* {{type}}

They should be used as follows:

  <string>doctype:xhtml-1.0-strict</string>

This will be rendered roughly as follows:

[string] '''{{doctype:xhtml-1.0-strict}}'''

== Tools

=== Emacs

At [[https://github.com/mario-goulart/el-chicken-wiki|https://github.com/mario-goulart/el-chicken-wiki]] you can find some Emacs commands to help editing this wiki.

[[https://github.com/wasamasa/svnwiki-mode]] provides a major mode for highlighting buffers using this wiki syntax.