Source

xmlwiko / index.wiki

@author: Dirk Baechle
@title: xmlwiko

Fundamentally lazy, I always try to minimize my efforts to get work done...even when
editing homepages. So when I planned to rewrite this site, I did not want
to fiddle with ApacheForrest XML the whole day. Instead, inspired by [[http://wiko.sf.net
WiKo (the Wiki Compiler)]] I hacked together this little script.

It is not pretty, nor complete...but it does a good job in keeping me
concentrated on creating simple pages for this website (or for Docbook XML).

== Current version == version

~[[xmlwiko.zip xmlwiko]]||Archive with the Python script and the $$*.wiki$$
source for this page.

== Usage ==

Simply start the script as

Code:
python xmlwiko.py

and it will traverse the current directory. Whenever it finds a $$*.wiki$$ file
it converts it into an XML file, conforming to the ApacheForrest DTD.

You can also start $$xmlwiko$$ with an additional argument (the exact text
does not matter):

Code:
python xmlwiko.py db

and you get Docbook XML files instead. Easy!

== Basics == basic

An xmlwiko file ($$*.wiki$$) is an UTF8 encoded file that consists of text blocks. These blocks
are separated by one or more blank lines (2+ newlines). A text block itself
can not contain blank lines.

At the start of each file you should place a header with the %%title%%
and %%author%% variables as follows:

Code:
\blank@title: Title of the document
\blank@author: Whowrote This

The markups for the text can be divided into the categories:
sections, simple paragraphs, lists and environments.

== Sections == sections

Sections outline the structure of your text. You can indent or dedent sections
to any level you like, so we need ways of adding a subsection or closing
several opened sections at once (dedent).

A simple section is started by the code:

Code:
== title == [id]

As the square brackets imply, the id is optional for you...but required for
the Forrest DTD. You can leave it out, then the given title will be joined
by underscores %%_%% and the result converted to lowercase as the id of this
section.

Starting a section like this, will keep the current indentation level. So if
another section has been opened before, it will be closed first.
If you want to open a subsection (indent) you type:

Code:
==+ title == [id]

Note the %%+%% that signals: ''I want to increment the level of indentation''.

While you can only increment by steps of one, you can dedent arbitrarily
using:

Code:
==-- title == [id]

Here we dedent by two, which effectively results in closing the last three
sections...and then opening the new one.

Larger levels of dedent can be directly entered with a single minus, followed
by an integer number:

Code:
==-7 title == [id]

At the end of the text, all sections that are still open get closed
automatically.

Finally, you can jump to a lower level of indentation by directly giving the
section indent behind the starting tag:

Code:
==0 title == [id]

for starting a new section at the top level $$0$$ (all opened sections are closed first).

== Simple paragraphs == para

The following markups are local to a text block (=paragraph). They have to appear matched,
because they don't get closed automatically
at the end of the block:

Emphasis (em)

Code:
This is an \\emphasis\\.

Bold (strong)

Code:
A !!bold!! word.

Double quotes

Code:
Enter ''quit'' to get out of here.

Code words (like variables or verbatim inline text)

Code:
This $$optionList$$ is never referenced.

Code words, enclosed in double quotes

Code:
The %%vlink%% attribute can be used for images.

Anchor (<anchor id=""/>)

Code:
@@label_id@@

== Links, Images, Figures == links

These three elements confront us with a new problem: attributes. Sometimes it is simply not enough
to say

Code:
<a href="test.html">test</a>
or
<img src="test.png"/>

because we want to add special attributes like %%vlink%% or %%width%%.
First, let's have a look at the basic forms:

~$$[\blank[href text]\blank]$$||Creates a link to the URL %%href%% with %%text%% as the link text.
~$$<<href>>$$||Places an %%img%% tag (or $$inlinemediaobject$$) for the image %%href%% at the current position.
~$$Figure:$$||A \\figure\\ is an image that stands on its own line, it can have a title and is specified
like an environment.</p>
<source xml:space="preserve">
Figure: href
Title/description of the figure.
</source>
<p>While the $$href$$ is mandatory, you can leave out the title. This results in a simple image without any description
(a.k.a $$mediaobject$$ in Docbook).

Now when you want to give some special attributes to these three tags, you can split the $$text$$ for the link and the
$$href$$ for the images into two parts by a %%||%%. The first part is recognized as list of attributes then, while the
rest is used as text or link to the actual image.

Some examples:

Code:
[[index.html vlink="#C0C0C0"||Visit this page!]]
&lt;&lt;test.png||alt="test" width="80%">>
Figure: er2.png||alt="er2" width="100%"
The parallel computer ER2.


== Lists ==

Within a list block you can indent/dedent the item level and also
change between ordered ($$#$$), unordered ($$*$$) and description lists ($$~$$).
The opening and closing of the single environments is handled by xmlwiko.
Just like for normal environments, only one paragraph per list item is allowed.

Note:
The description lists ($$~$$) can not be nested further, so the single %%~%%
is always the rightmost element of a list specification!

Code:
#first
more text for first item
#second
#parent 1
##child 1
more text for child 1 item
##*non numerated child
##*non numerated child
##child 2
###subchild 1
#child 3
##~dt||dd (description list)
#parent 2

results in:

#first
more text for first item
#second
#parent 1
##child 1
more text for child 1 item
##*non numerated child
##*non numerated child
##child 2
###subchild 1
#child 3
##~dt||dd (description list)
#parent 2

== Environments ==

You can open special text blocks as an ''environment'' by prepending
a line with the block type as follows:

Code:
Abstract:
Here we write text for our
abstract...

At the moment, environments support only one paragraph!
Available environments are: 

Code, Figure, Abstract, Remark, Note, Important,
Warning, Caution, Keywords, TODO, Definition,
Lemma, Proof, Theorem and Corollary.

Note:
When using the $$Code$$ environment, you still have to escape the %%&lt;%%
as %%&amp;lt;%%!

== Special stuff ==

You may wonder why all the markers for environments are doubled up. The reason behind
this is, that we might want to print a ''%\blank%'' in the middle of our text
(uh, oh...there it happened already). And if there is a real %%quoted%% environment in the same text block, the script gets confused easily.

For this case, the %%\bl\blankank%% marker was introduced as a special ''escape sequence''.
It gets replaced with a string of zero length for the final output (after
all other processing work was done).

So if you want a  ''%\blank%'' in your text you can type:

Code:
''%\bl\blankank%''

Final question: ''What do you have to type in order to get %%\bl\blankank%% in
the output?'' $$:)$$