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 (v1.3) 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)), ((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:

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 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.
~$$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 five 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:

Code:
[[index.html vlink="#C0C0C0"||Visit this page!]]
&lt;&lt;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.


== 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;%% and the %%&amp;%% as %%&amp;amp;%%!

== 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?'' $$:)$$
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.