#
#	quickie - a small fast C++ Wiki Wiki
#	Copyright (C) 2005 Peter Miller
#
#	This program is free software; you can redistribute it and/or modify
#	it under the terms of the GNU General Public License as published by
#	the Free Software Foundation; either version 2 of the License, or
#	(at your option) any later version.
#
#	This program is distributed in the hope that it will be useful,
#	but WITHOUT ANY WARRANTY; without even the implied warranty of
#	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#	GNU General Public License for more details.
#
#	You should have received a copy of the GNU General Public License
#	along with this program; if not, write to the Free Software
#	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
#
# MANIFEST: var/manual/markup.wiki
#
! Text Layout and Formatting Guide
The input text for wiki pages is meant to be very simple.  In most
cases, will you need to do is paste in the text you want in the page,
with a blank line between paragraphs, and you are done.

This page came with the default Quickie installation.  Like all
wiki pages, this page can be edited.  If you find something
which needed more explaining please email your improvements to
[mailto:millerp@canb.auug.org.au|Peter Miller] so that they can be
included in the next release.

There is also a [manual/markup_hints|brief summary] of this page
made available on all edit pages.

!! No HTML Markup
Please don't try to use HTML markup in your wiki pages, it simply will not work.
This is intentional; trying to mix wiki markup and HTML markup on the
same page is unreasonably difficult, considering what a wiki is supposed
to be.

If you know enough HTML to be tempted to use it, maybe you should
consider dumping the wiki concept and simply write HTML pages instead.

!! Comments
You can put comments in your wiki files that will not show in the final
page displayed to readers.
{{{# This is an example comment.}}}
Lines with a hash ({{#}}) character at the start of the line are treated
as comments.

!! Headings
To get headings in your text, you need a line which starts with an
exclamation mark.  It will look something like this:
{{{! My Heading}}}
The number of exclamation marks controls the style of the heading.
Top level headings get one exclamation mark, the next level get two,
''etc''.

If your wiki page has a level one heading as its first line, that
heading will be used for the page heading, rather than a "pretty
version" of the page's name.

!! Emphasis
Your can add emphasis to your text with __bold__ and ''italic'' markup.

You get italics by surrounding your text
with pairs of single quote ({{'}}) characters.
For example
{{{''hello''}}}
becomes ''hello''.

You get bold by surrounding your text
with pairs of underscore ({{_}}) characters.
For example
{{{__hello__}}}
becomes __hello__.

!! Mono-spaced Text
There are two ways to get {{mono-spaced text}}, sometimes called fixed-width.

Inline text as you see in this paragraph is produced by having two
opening braces in a row {{ { { }} to start the mono-spaced text, and
then two closing braces in a row {{ } } }} to finish.  Text like this
is still subject to the usual {{__bold__ markup}} and {{''italic''
markup}} sequences.

The second way is to have sets of triple braces.
Text of the form { { { blah blah } } }
appears like this:
{{{blah blah}}}
within this text, there is no additional markup interpretation.
This is useful for inserting software code examples.

!! Links
You can put links to other wiki pages using {{[}} square brackets {{]}}
around the name of the wiki page to be linked.  For example,
{{{[index]}}}
is the markup needed to produce this link: [index].
This link will take you back to the default front page of this wiki.

If you create a link to a wiki page which does not exist (perhaps
because you are about to create it) a following question mark will be
highlighted.  If you click on it, you will be taken to the edit page for
the new wiki page.

If you want to have different text than the wiki page title as the text
highlighted by the link, you specify the text after the page name,
separated by a vertical bar ({{|}}) symbol.  For example,
{{{[index|the front page]}}}
is the markup needed to produce this link: [index|the front page].

All of the usual markup, such as __bold__ and ''italic'' text, may be
used in the right-hand half of this kind of link markup.
However, you can't nest links.

!!! Categories
You can divide your wiki pages into categories
by using slash {{/}} characters between the wiki words.
For example, the Quickie manual is a category called "manual",
so a link to this manual page would look like
{{{[manual/markup]}}}
and other manual pages can be linked in a similar way.  When you do not
provide a default heading, the slash turns into a space when the default
page heading is calculated.

!!! External Links
You can link to ordinary web pages by using a very similar notation
to internal links.  For example,
{{{[http://quickie.sourceforge.net/]}}}
is the markup needed to produce this link:
[http://quickie.sourceforge.net/].  The text which is highlighted by
link is the same as the link itself.
You will notice that external links have a little arrow next to them,
to tell you that the link is to an web page outside this wiki.

If you would like to change the highlighted text, use the same style of
link as for internal links.  For example,
{{{[http://quickie.sourceforge.net/|Quickie Home Page]}}}
is the markup needed to produce this link:
[http://quickie.sourceforge.net/|Quickie Home Page].

Just as for internal links, you can have additional markup in the
right-hand half of this kind of link.

! Style Sheets
You can use CSS (Cascading Style Sheets) to customise the appearance of
your wiki pages.
Best of all, CSS changes take effect immediately, there
is no need to regenerate the HTML from the wiki text.

The default style sheet may be found in the [admin/default.css] file of
your wiki tree.  Even though you can view it here, you will have to edit
it with a text editor from outside Quickie.

The name of the style sheet file may be altered using the
''style-sheet-name'' field of the [manual/configuration|configuration]
settings.

More information about CSS, including tutorials, can be found on the
[http://www.w3.org/Style/CSS/learning|learning CSS page].
