# wiKib

wiKib is a markup langage developped for my own use, because other tools (even if they are certainly better) like reSt or Markdown where either to heavy or too limited for writing my blog.

You can translate any wiKib doc to HTML (or LaTeX document, even if this is highly experimental at the time).

The only thing you'll have to do is writting some css or sty file to customize it to your needs.

wiKib is extensible : you can write your own rules for the markup, even if I choose to make a default one.

## What's new ?

Since v0.8, wiKib evolved a lot to suit my needs in a new version 1.0. The editor I've made with PyQt4 has been abandonned, I think it's easier for you to configure your personnal editor for the task.

• Quicker than before ! This document is rendered in XHTML in exactly 0.0713214884814s on my computer : that's not so bad !
• Better paragraphs handling;
• Synonyms are a powerful way to optimize typing the same things again and again;

If you're interested in looking at the sources of this page in .kib format, please take a look at it here.

The rendering of this page through LaTeX gave the following : wikib.pdf

## Requierements

To use wiKib, you only need two things :

## Using it

The main script is wikib.py, inside it there is a main() function showing you how to deal with a basic document (this one).

Basically, you have to :

1. choose your Handler from Html_handler or Tex_handler ;
2. build an instance of a Parser with arguments your kib text and your handler;
3. the parse method of the parser is used to retrieve the genrated code. If you give it a, optionnal filename argument, your final doc will be then saved.

Headers from level 1 to 6 are supported and included in the wiKib table of contents. If you don't want a header to be included inside the Table, just add a * behind it.

```= h1

== h2

=== this one will not be included in the TOC*
```

I did not include the sample here because it will then be included in the Table.

## Paragraphs

A paragraph is composed of lines of text delimited by a double line ending character.

```My first paragraph is like this
whatever I write inside.

This is another paragraph, and
you can force a linebreak with this char /
so that this line is a new one
```

My first paragraph is like this whatever I write inside.

This is another paragraph, and you can force a linebreak with this char
so that this line is a new one

It's just a convenient list that you can put anywhere you want. Just write ~~TOC~~ on the start of a single line and you're done ! The result is shown here at the top of this page.

## Formating

```//italics//

**bold**

__underline__

--strikethrough--

upper^^text^^

lower..text..

hrule
```

Results in :

italics

bold

underline

strikethrough

uppertext

lowertext

Of course, you can combine them and all can be extended on a paragraph!

```upper^^//**__text__**//^^
```

gives you this : uppertext

```some //text here in /
italics//
```

some text here in
italics

## Maths

Sometimes it is convenient to write a formula inside your page. wikib uses MimeTeX for rendering HTML and of course LaTeX's power for the rest.

```\$2x^2+5x-3\$
```

The formula will be rendered in HTML like this (yes, it's a rather ugly image, but publishing maths on the Web is a real pain for the moment): $2x^2+5x-3$

Just type something like this :

```[http://kib2.alwaysdata.net/tempo/test.html|wikib page]
```

Here you can go to wikib page.

## Images

You can embed images with a target inside wikib, like the following :

A centered image :

```[[im http://groups.google.com/group/enclojure/icon?v=1&hl=fr|http://groups.google.com/group/enclojure/icon?v=1&hl=fr|center|my alternative text]]
```

A left image :

```[[im http://groups.google.com/group/enclojure/icon?v=1&hl=fr|http://groups.google.com/group/enclojure/icon?v=1&hl=fr|left|my alternative text]]
```

A right image :

```[[im http://groups.google.com/group/enclojure/icon?v=1&hl=fr|http://groups.google.com/group/enclojure/icon?v=1&hl=fr|right|my alternative text]]
```

## Lists

You can build a simple list like this :

### Normal lists

The default behaviour is bulleted lists :

```[list]
- first
- second, you can put whatever you want here, even /
line breaks :-)
- etc
[/list]
```

Results in :

• first
• second, you can put whatever you want here, even
line breaks :-)
• etc

### Enumerated lists

enumerated lists :

```[list=1]
- first
- second
- etc
[/list]
```

Results in :

1. first
2. second
3. etc

### Alphabetical lists

alphabetical lists :

```[list=a]
- first
- second
- etc
[/list]
```

Results in :

1. first
2. second
3. etc

## Inserting inline HTML

Maybe sometimes you'll need to add some particular media in your pages. Use this :

[[nowiki]] whatever here [[/nowiki]]

## Quotes

You can quote something like this :

```[''someone told me : never piss on your pants'']
```

Wich gives :

someone told me : never piss on your pants

## Monospace

```{{for i in xrange(10)}}
```

So easy ! for i in xrange(10)

Note : don't put any wikib markup inside, it will be interpreted.

## Source code

wikib has been made to handle sourcecode by using the fabulous Pygments library for Python. You just have to look at pyg_'s documentation to understand how to use it.

Here's a sample of a Python code :

```{{{python

for i in xrange(10):
print "i=%s"%i
}}}
```

results in :

```for i in xrange(10):
print "i=%s"%i
```

## Synonyms

That's a convenient way to avoid typing multiple times the same markup, ie if you're typing an HTML adress.

For example, in this document I've just set these ones at the bottom of my 'kib' doc:

```[synon]
_wikib --> [http://kib2.alwaysdata.net/tempo/test.html|wiKib]
_toc --> Table
_pyg --> [http://pygments.org/|Pygments]
[/synon]
```

## What's up next ?

Some ideas in the future :

• rewrite wikib : it has been simply designed and now that it has grown, the code is not particularly nice;
• fix the LaTeX backend;
• handle author, title, pagebreaks, etc.;
• better maths support in HTML;
• validate all of XHTML (errors are inside images);
• smileys ?

I'll be glad if some Python developper would like to contribute to wiKib in whatever way. Working alone on a project like this is really hard.

## Bugs ?

Yes, there are certainly some inside, so please mail-me at kibleur dot christophe at gmail dot com.

## Thanks

• to all the people how are using wiKib. Gilles : I greatly appreciated your help;
• to the Sphinx team : I've litteraly copied their html and css style : sorry for this, I'm really hate working with those file types.
• to Pygments team for their awesome job;