Once you have written this very simple document you may want to add some content, for example paragraphs and lists. Both paragraph and lists (and also sections) are structural elements, which means that they help you to structure the content of the document.

Writing !paragraphs! is pretty simple, you basically just have to type your text, taking care that all lines have the same indentation, and insert a blank line between your paragraphs.

You may want to insert !line breaks! within your paragraphs. In this case instead of separating the two parts of your paragraph by a blank line, which would lead Kiwi to consider that your paragraph is in fact two paragraphs, you insert a pipe character on the blank line.

Here is an example of a paragraph with a line break in it:

Blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah
blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah
|
Here we are still in the same paragraph. Blah blah blah blah blah blah blah
blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah

The other important structural elements are !lists!. Kiwi provides two types of lists: the classic lists and the definition lists. The classic list only lists items, whereas the defintion list offers a way to list terms and give a definition to them.

These two types are not very different, I will explain the differences later. Basically a list is composed of an optional list heading which is a sentence that ends with a colon, like this:

Here is simple list heading:

This optional heading can span over many lines, provided there is no paragraph break between those lines.

The other component of a list are of course list items which begin with a dash or a single letter or digit with a closing paren, which is followed by an optional list item heading, which is also followed by a list item body.

Here is the example of a least that illustrate the differents aspects of the lists:

 Here is simple list heading: 
   -  Here is the optional list heading:
      Here is the list body
   b) Here is another list item. Note that the indentation of the text
      must be the same as the preceding list item, otherwise it may be
      interpreted as a nested list.

   1) We can also jump lines between list items.
      - And make nested list items
      - Heading: That also have a list item heading.

You may sometimes want to do group paragraphs or whole subsets of your document under a particular term (or qualifier). For instance, if you are defining concepts, or describing different elements, you may want to tell that a set of paragraphs belong to that particular element.

This is the purpose of the definition lists: they provide a mean to express a term (or a sentence), and the following elements with a higher indentation will be considered as being part of the term definition.

Term::

    Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Cras accumsan. 
    
    Nullam ac purus quis magna consectetuer luctus. Duis sit amet sem. 

Other term::

    Donec a magna mattis dolor semper pulvinar. Donec viverra libero sit amet dolor.
    Duis ut ante at lacus pharetra iaculis.

Will be rendered as

Term

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Cras accumsan.

Nullam ac purus quis magna consectetuer luctus. Duis sit amet sem.

Other term

Donec a magna mattis dolor semper pulvinar. Donec viverra libero sit amet dolor. Duis ut ante at lacus pharetra iaculis.

Note ______________________________________________________________
Lorem ipsum dolor si amet

will be displayed a

You can also write a note than contains multiple paragraphs:

Note ______________________________________________________________

Lorem ipsum....

Dolor si amet...

_____________________________________________________________________

Notes are actually annotated blocks, which are blocks surrounded by an annotation (here, the annotation is Note). You can use many other annotations (such as Example, Use case, etc..), as with annotations will be translated to a lower-case class attribute in your resulting HTML document. So you simply have to add the styles you want in your CSS stylesheet to support more annotations blocks.

As with lists, indentation is primordial. Your note block should be more indented than the parent paragraph. All paragraphs with the same indentation level as the note will be considered part of the note.

Once you have written your text you may want to add structure, for example you may want to create sections, sub sections, etc. If you want to create !sections! and also nested sections, you just have to insert a section heading in your text.

A section heading consists in a single line of text that is prefixed by an optional section number, which is constituted of digits separated by dots. Then follows an optional underline, like the following example shows:

Section level 1
===============

Section level 2
---------------

1. Section level 3
------------------

1.2 Section level 4

The leading number is not required when the section is underlined (using === or ---), but it does indicate the depth of the section (1 means depth 1, 1.1 means depth 2, 1.1.a means depth 3, etc).

Section depths are computed using the following rules:

• Sections underlined with === are have a lower depth than sections with ---, which in turn have a lower depth sections without underlining.

• Sections with no number will have a lower depth than sections with 1 number (1. Section), which have a lower depth than sections with 2 numbers (1.1 Section), etc.

• Sections which are explicitly indented will have a depth which is at least equal to their parent section.

Alternatively, you can also write sections by prefixing the title by a number of = like that:

== Section level 1
=== Section level 2
==== Section level 3

this notation is designed for people who don't indent their text and sections (if you are using Kiwi as markup language for a Web wiki, for instance). The depth of the section is identified by counting the number of '=' characters, where the first does not count.

Kiwi section markup is very flexible, and allows you to use indentation, numbers or different underlines to denote the depth of your sections. Numbering is not important as the section numbering will be recalculated anyway, so you can use X.X instead of 1.2. This will make your life easier when typing large documents.

Tables are written using the following markup:

Optionally, table borders can use single pipes |.

The previous feature table has been written using the following markup:

    == Tables
    ===================================================================
    Table header    || ``== Header``
    -------------------------------------------------------------------
    Row separator   || Use a line of dashes, equal signs or plus signs
    -------------------------------------------------------------------
    Cell separator  || ``||``
    =============================================

There are two ways of doing preformatted text. The first one is by prefixing each line of your text by > plus one tab or at least 3 spaces.

>   def hello():
>     print "Hello, world !"

will be rendered as

def hello():
  print "Hello, world !"

Using this > markup helps explicitly delimiting a block and visually denoting where the indentation starts. However, this markup makes typing and copy-pasting more difficult, which is why we provide an alternative markup:

<<<
def hello():
   print "Hello, world !"
>>>

which produces the same result

def hello():
print "Hello, world !"

but involves less typing. The rule for this is that you have <<< and >>> standing on empty lines, and that the lines within these delimiters are either empty or have at least the same indentation as the delimiters.

todo

Kiwi supports internal (within document links) and external links (urls, files, etc). Internal links are expressed like that:

Some text [the link][TARGET] ...

where TARGET is a link to a bilbiographic entry, to a specific target, or is a string that can identify without ambiguity a section.

For instance, if I wanted to reference the “Document header and title” section of this document, I would do:

[previous section][document header]

Additionally, it is possible to omit the TARGET. In that case, the text of the link itself will be used as the target. We could have expressed the previous link like that:

here is a link to the [document header] section

If you want to define a specific anchor for a link in your document, you can simply use the following notation

|ANCHOR|Some text...

Anchors will not be displayed in the resulting document. If you'd like the anchor to contain some text, you can do

|ANCHOR:Some text|

And then the anchor will span the text you indicate

If you'd like the anchor name to be the same as the displayed text, you could do:

|ANCHOR:|