# \$Id: refmanual,v 1.1 2005/09/01 03:37:25 villate Exp $
##html-title: Wikiup Reference Manual
##author: J. E. Villate
##date: September 2005

= Wikiup Reference Manual =

== Special characters ==

There are several characters that might be parsed in a special way,
depending on their context. If you notice that a character from your
source document is not appearing in the HTML page, it means it is
being interpreted as a special formatting character, you can always
prevent that from happening by escaping it with a backslash (\\).
Inside verbatim blocks, all special characters loose their meaning and
they always appear as typed.

The list of special characters is as follows:

	*:	When it appears as the first character in a line, preceded
	by tabs and followed by a space, it takes a special meaning (starts
	an item in a list). It also takes on a special meaning when it
	appears with a matching * in the same line (bold face).

	_:	It is a special character when accompanied by a matching
	_ in the same line (italic face).

	`:	When matched by a similar character in the same page, the
	text in between is typed in mono-spaced font.

	$:	It is a special character when matched by another dollar
	sign in the same line (mathematical equation).

	[ and ]:	When the two square brackets appear in the same
	line, in that order, the text in between becomes a hyper-link.

	%:	As the first character inside a hyper-link, it is used
	to insert labels that can be cross referenced from the same page
	or from external pages.

	|:	If it appears in the first column of a line, the rest of
	the line is interpreted as a row in a table. Other | characters
	in that line are used to delimit the columns in that row.

	-:	If 3 of them appear in the first 3 columns of a line,
	without any other non-blank characters in the line, it is
	interpreted as the delimiter for a verbatim block.

	=:	When typed in the first column of a line, whose last
	non-blank character is also a = sign, the line is interpreted as
	a section header. The level of the header is equal to the
	number of = signs at the beginning of the line.

	::	Before a tab, in a line that starts with one or more tabs,
	it becomes the delimiter between a keyword and its description, in
	a descriptive list.

	#:	If it appears in the first column of a line, the line is
	ignored as a comment in the source file. If there are two of
	those characters in the beginning of a line, the contents of the
	line might be a keyword providing meta-information for the
	document. This character is also used for cross-references.

	\\:	This is the escape character. The character to its right
	will loose any formatting meaning that it might have. To obtain one
	backslash in the output file, two of them should be type in the
	source file. If the last non-blank character in a line is a single
	backslash it means that the next line is a continuation of this one.
	If the last two non-blank characters in a line are a couple of
	backslashes, they are replaced by a line break in the current
	paragraph.

	digits:	If a line stars with one or several tabs, followed by one
	or several digits, a period or a dash, and a space, that sequence marks the
	beginning of an item in an enumerated list.


== Paragraphs and blocks ==

Paragraphs are separated by one or more empty lines. To force a line
[%br break] inside a paragraph, \\\\ should be type in the end of a line,
where the line break should go.

If the lines in a paragraph are all indented with the same number of tabs,
the paragraph will become part of a list or will be indented, depending on
the first non-tab characters in that paragraph:

	* If the paragraph starts with a *, followed by a space, it will
	be replaced by a bullet an the paragraph becomes an item in a
	list.

	* If the paragraph starts with one or more digits, then a period
	or a dash, and finally one or more spaces. The paragraph will be
	part of a numbered list and will be given a number accordingly.

	* If the paragraph starts with one non-blank character, which might
	be by other characters, a semicolon and a space, the paragraph will
	be an item in a glossary (descriptive list). The characters before
	the semicolon will be the term in the glossary entry, and the rest
	of the paragraph, after the semicolon, will be the term's
	description.

	* In any other cases, the paragraph will be typeset with wider
	margins.

In all the above cases, the level of indentation of the paragraph will
depend on the number of tabs on the left.

A paragraph that contains only a mathematical equation will become a
displayed equation (typeset centered inside a blank block). An if the
paragraph's only content is an image, the [%figures image] will be
centered. In both cases the displayed block will be put inside <div>
tags in the HTML output file, with a class that can be either
*equation* or *figure*. You can see below how to represent equations
and images and how to change the display style of those <div> blocks.

Other type of blocks are verbatim blocks, which will be discussed later on.

== Section headers ==

A section header is set by typing one or more equal sign in the
beginning of a line, whose last non-blank character is also a =
sign. The text inside the equal signs will be used for the header. The
level of the header will be equal to the number of = signs at the
beginning of the line.

== Font types ===

To display a piece of text in a different font, it should be delimited by
two identical special characters, according to the following table:

| *character* |     *Type of Font*  |
|     *       |       Bold          |
|     _       |      Italic         |
|     `       |     Monospaced      |

The two delimited characters must appear in the same line. If the text to
enclose is too large, and you do not want to used long lines, you can end
each line with a backslash, and they will be interpreted as part of one
single line.

You can combine two or three of the font types, as long as they are
correctly nested. Namely, the first special character to appear in the line,
should be the last one to be matched with another identical character.

== Links and cross-references ==

Hyperlinks  are written inside square brackets, or by giving a complete,
correct URL. If the name of the link is a single word, without periods or
slashes, it will be interpreted as a link to another document generated
with wikiup. The HTML page will point to a page with the name inside the
brackets, followed by the suffix `.html`

If the text inside the brackets includes white spaces, the first set of
non-blank character will be taken as the name of the link, and the remaining
will be a longer name for the link.

If the link name starts with %, it will be interpreted as a symbolic label
that should be inserted at that point. It the name starts with #, it will
represent a cross reference to the place where a label with the same
name was inserted, in the same document.

The name of the link can also be a complete URL; if it is not followed by
space and a descriptive name, the square brackets around it are not
mandatory. It the a URL (complete or relative to the current server) ends
with # followed by a name, it points to the place in the external page
where there should be set a label with that name.

== Images ==

Images are inserted by writing the name of the file inside square brackets.
The file name should end with one of the supported suffixes, which are
currently: `.gif`, `.jpg`, `.jpeg` and `.png` (in either upper or lower
case).

== [%equations Equations] ==

Equations are typeset using Latex syntax, inside two matching $ signs.
The wikiup parser will generate a PNG image for each equation, and will
put pointers to those images in the HTML page. If an equation appears
several times in the document, the corresponding graphic file will only
be generated once. For instance, if you want two insert a Greek character
$\pi$ several times in the document, you can use its Latex notation several
times, without imposing a serious slowdown to either the parser or
the browser (the file has to be downloaded only once).

In order to parse mathematical equations, you must have *Latex* installed
and the program *dvipng*, which makes part of most software
distributions, or can be downloaded from http://www.sf.net/projects/dvipng

By default, the names used for the graphic files of the equations will
be "eq-1.png", "eq-2.png", "eq-3.png", ... , but the prefix "eq-" can be
modified with a command-line option for parsewikiup.

== [%tables Tables] ==

A table is formed by several lines all starting by |. If the first
line also ends with |, the completed table will have lines separating
its cells. If the first row does not end with |, there will be no lines
in between cells. Cells are separated by other | characters. Those
characters do not have to be visually aligned, although that might make
the source file easier to read.

If the text in an cell is separated with spaces from the two delimiting |,
that text will be centered in the cell. If the text touches the left-side
bar, it will be left-justified, and if it only touches the bar on the
right, it will be justified to the right.

If the text inside a cell is all set in bold font, it will be interpreted
as a header. By default, tables will be centered in the page. You can
change that by altering the default style, as explained below.

== Verbatim blocks ==

A verbatim block is anything that goes in between two lines that have only
three dashes --- and nothing else (notice that the 3 characters are dashes
and not underscores). The only modification that will be made
to a verbatim block is to replace the restricted HTML characters &, < and
>, by their HTML representation. In that way, the text inside the block
will be correctly displayed by the HTML browser.

== [%css Cascading Style Sheets] ==

By default, the HTML pages generated will include a very simple stylesheet
that centers, tables, displayed figures and equations, and defines the
size of the page fonts. You can override that style or introduce more
styling rules by including your own custom style sheet. You can specify
the name of the CSS file to be included by using a command line option
for `parsewikiup`, or by writing a _keyword line_ in the source file,
such as:

---
## stylesheet: filename.css
---

Notice that keywords are inserted in a line that starts with ## and
has the name of the keyword followed by a semicolon, and the keyword's
content. The options of `parsewikiup` are shown in a later section.

You can also modify the style by passing attributes for the HTML page that
will be generated. To pass attributes for an HTML tag, the keyword *html*
should be used. For instance, to add the attribute `cellpadding="10"` to
tables, one would insert the following line:

---
## html: table: cellpadding="10"
---

That will only affect the tables appearing after it.

== Templates ==

Wikiup uses a template to produce the HTML pages. A template is a simple
HTML file with the string %(text)s in the place where the parsed content
of the source file should go.

The default template used by Wikiup is:

---
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<meta name="generator" content="wikiup 0.2, http://villate.org/wikiup/">
<title>%(title)s</title>
<style type="text/css">
div.figure {margin: 0; padding: 1.5em; text-align: center;}
div.equation {margin: 0; padding: 0.5em; text-align: center;}
table {margin-left: auto; margin-right: auto;}
body {font-size: 12px;}
</style>
</head>
<body>
%(text)s
</body>
</html>
---

In addition to the page *text*, the *title* will also be inserted into
the template. You can include any known keyword in the template. For
instance, since we have used above a keyword *stylesheet*, you could
add the following text to the template: "this page uses an external
CSS stylesheet %(stylesheet)s" and the name of the file would be substituted
in due place. However, caution must be taken, because if a single one
of the keywords used in the template is not defined, none of the keywords
will be substituted and you will end up with just the original template.

The keywords that are always defined by parsewikiup are: text, title
(by default, the source file name), date, today and rightnow (current
date and local time). You can define your own keywords in the source files
and used them in your own template.

If you want to use a custom template, you can create it in a file named
`template.html`, in the same directory where `parsewikiup` is run. You
can even put anywhere in your filesystem, with any name you would like,
and indicate that name with a keyword *template* in the source file, or
with a command-line option for parsewikiup.

== [%parsewikiup Parsewikiup] ==

The program used to parse the source files is a python script named
`parsewikiup`. It's usage is as follows:

---
parsewikiup [options] filename
---
with the following options:

---
   -t FILE or --template=FILE    Use FILE as HTML template
   -s FILE or --stylesheet=FILE  Link HTML page to CSS stylesheet FILE
   -h or --help                  Print this summary to the screen
   -o FILE or --output=FILE      Save output into FILE
   -e PREF or --eqprefix PREF    Use PREF as prefix for equation files
   -z NUM  or --zoom=NUM         Magnify the HTML page to NUM zoom factor
   --nopng                       Does not create PNG files for the equations
---

  
