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

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

characterType 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 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 eq-1.png 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

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.

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

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


Last update: 2005-09-02 15:10:16 +0000
Copyright 2004, 2005, Jaime E. Villate <villate AT gnu.org>
Verbatim copying and distribution of this entire page is permitted in any medium, provided this notice is preserved.