xmlwiko /

@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 
[[ 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]]||Archive with the Python script (v1.4) and the $$*.wiki$$
source for this page.

== Usage ==

Simply start the script as


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

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

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

The markups for the text can be divided into the categories:
((sections)), ((para simple paragraphs)), ((links)), ((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:

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

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:

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

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

==-7 title == [id]

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

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

==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 single text line. They have to appear matched,
because they don't get closed automatically
at the end of the block:

Emphasis (em)

This is an \\emphasis\\.

Bold (strong)

A !!bold!! word.

Double quotes

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

Code words (like variables or verbatim inline text)

This $$optionList$$ is never referenced.

Code words, enclosed in double quotes

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

Anchor (<anchor id=""/>)


== Links, Images, Figures == links

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

<a href="test.html">test</a>
<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 external URL %%href%% with %%text%% as the link text.
~$$(\blank(id text)\blank)$$||Creates a link within the document to the %%id%% with %%text%% as the link text.
The %%id%% can point to a section or a defined anchor (see ((para Paragraphs))).
~$$&&id text&&$$||Creates an xref entry to the %%id%% within the document. Although Docbook
does not require a link %%text%% for this element, you have to provide a fallback for the
Forrest output.
~$$<<href>>$$||Places an %%img%% tag (or $$inlinemediaobject$$) for the image %%href%% at the current position.
~$$Image: href$$||A graphic %%href%% that stands on its own line. It has no title and is specified
like an environment.
~$$Figure: href$$||A \\figure\\ is an image %%href%% that stands on its own line. In contrast to
the \\Image\\ environment above it has a title.

Figure: href
Title/description of the figure.

Now when you want to give some special attributes to these six tags, you can split the $$text$$ for the link/xref and the
$$href$$ for the images into two parts by a %%||%%. Like this, the first token is always recognized as 
the link target (or image source). Then, the list of optional attributes follow
and the link text is found at the end of the expression.

Some examples:

[[index.html vlink="#C0C0C0"||Visit this page!]]
<<test.png||alt="test" width="80%">>
((examples xrefstyle="template: the examples in ch. %n"||the examples))
Figure: er2.png||alt="er2" width="100%"
The parallel computer ER2.

== Filters == filters

Sometimes you may want to pass text or input in general, to one
output type only. A typical example would be a parameter like %%scale%% for
a Docbook %%imagedata%%, which does have no effect in Forrest and leads to an error.

Here, you can use a filter (enclosed in %%*\blank*%%) as follows:

<<test.png||alt="test" **docbook scale="80"**>>

The parameter %%scale%% only gets included in the ouput if %%docbook%% is selected.

Currently available filters are: %%forrest%% and %%docbook%%.

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

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

more text for first item
#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:

more text for first item
#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:

Here we write text for our

Available environments are: 

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

When using the $$Code$$ environment, you still have to escape the %%<%%
as %%<%% and the %%&%% as %%&%%!

== Environments extended == extenvs

When defining environments or lists, you would normally be restricted to a
single paragraph. Xmlwiko works line-oriented for its parsing and a blank line
usually ends an environment/listitem.

If you'd rather like the script to understand the empty line as ''start a new paragraph''
, you can enclose the environment in a braces block, like this:

This is the first paragraph.

And here is another...

This gives:

This is the first paragraph.

And here is another...

The same is possible for single list items, e.g.:

*First item
{\blank{**Second indented item.

The second paragraph in this item.

which yields:

*First item
{{**Second indented item.

The second paragraph in this item.

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


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