How to

This article explains how to use the syntax of the tool.

Basic usage

To be able to generate the wiki, you only need at the minimum to specify:

• The input directory
• The output directory

For example on the command-line:

      java -jar docGenerator.jar -input=wiki/input -output=wiki/output

Home page

The home page of the wiki generates an index.html file. To specify the index article, creates a index file.

For example:

   <index>
   This is the index.
   </index>

Articles

To specify an article, creates a regular article file.

For example:

   <article desc="an article">
   This is a very simple article.
   </article>

Regular text

Regular text is just text in the XML content. For example:

   <article desc="an article">
   This is a very simple article.
   </article>

References

A reference to another article in the wiki can be added with the ref element.

For example to reference an article:

   The <ref id="the article" />

To reference an article title or anchor:

   The <ref id="the article#the title" />

To use an alternate text for the link:

   The <ref id="the article#the title" desc="the description"/>

Lists

Lists can be bulleted lists (using the ul element) or numbered lists (using the ol element). it is possible to change the bullet style (see bullet style).

For example:

  <ul>
    <li>first element</li>
    <li>second element</li>
  </ul>

Pre formatted text

The pre element allows to show pre-formatted text, which is text where the formatting is specified in the source. For example:

   <pre>
   first line
   second line
   </pre>

Result:

      first line
      second line

Source code

The pre element s also used to show syntax highlighted content, for example for source code. For example:

<pre syntax="java">
   public void toto(int i) {
   _  System.out.println(i);
   }
</pre>

will have the following result:

   public void toto(int i) {
      System.out.println(i);
   }

New lines, breaks, and tabs

By default, as in html, there is no line break even if you put your text in two lines in the source. For example:

   This is a sentence on the first line
   and the second line

will produce:
This is a sentence on the first line and the second line

However, some elements allow to specify new lines, breaks, and tabs in the text content:

• The br element allows to add a line break. You can also put an empty line in the content to achieve the same thing
• The empty element allows to add an empty line
• The tab element allows to specify a tab

For example:

   This is a sentence on the first line
   <br/>
   and the second line

will produce:
This is a sentence on the first line
and the second line

Text formatting

The most simple way to format text is to use bold, italic, or underlined text:

• Bold text must be in a b element
• Italic text must be in a i element
• Underlined text must be in a u element

For example:

   This is a sentence with <i>a text in italic</i>

Result:
This is a sentence with a text in italic It is also possible to do more complex formatting using the font element:

• "size": the text size, which can be a number value or an HTML font size name
• "color": the text color, using an HTML color name or RGB/RGBA specification
• "background": the text background color, using an HTML color name or RGB/RGBA specification
• "format": the text style, which can be "regular", "italic", "bold", "underline", "sub" or "subscript" (for subscript), or "sup" or "superscript" (for superscript), or a combination of these tags
• "face": the font face of the font

For example:

   This is a sentence with <font color="red" format="bold">a bold text in red</font>
   This is another sentence with <font background="yellow">a text on yellow background</font>
   This is another sentence with <font color="blue" background="yellow">a blue text on yellow background</font>
   This is a sentence with <font format="bold italic">a bold and italic text</font>

Result:
This is a sentence with a bold text in red
This is another sentence with a text on yellow background
This is another sentence with a blue text on yellow background
This is another sentence with a bold and italic text

Chapters and titles

The simplest way to define titles and sub-titles in your wiki is to use the title element. For example:

<article desc="the article">
   text before all chapters (article header)
      
   <title title="first chapter"/>
   text inside the first chapter
      
   <title level="2" title="sub chapter"/>
   text inside the sub-chapter
      
   <title title="second chapter"/>
   text inside the second chapter
</article>

Note that if you don't define the level, it will be assumed to be 1.

Images

To add images in your wiki, you should:

• Create one or several xml files with the images root, which will contain a list of image definitions
• Use the image ids in the img element

For example, with the following image file:

   <images>
     <image id="image1" url="hand.png" />
     <image id="image2" url="crocodile.png" />
   </images>

We can for example have the following img declaration:

   <article desc="article1">
     <img id="image1" width="20%" />
   </article>

Tables

The "table" element allows to define a Table. A table must have the following children:

• "tableHeader" which will define the columns in the table.
• The header will have one "column" child for each column
• The header can be defined to be vertical
• several "row" elements which will define the rows in the table
• The row will have one "cell" child for each cell in the row. Each cell contains its content, and can have a background color if using the "color" attribute

For example:

<table caption="table caption">
   <tableHeader>
      <column>first column</column>
      <column>second column</column>
   </tableHeader>
   <row>
      <cell>name</cell>
      <cell>value</cell>
   </row>
   <row>
      <cell color="#00FF00">name2</cell>
      <cell>value2</cell>
   </row>
</table>

Result:

table caption

first column	second column
name	value
name2	value2

Todos

The "todo" element allows to add a "TODO" in the wiki, optionally with a comment.

For example, the following example shows a simple TODO:

   <todo reason="this is the reason"/>

The todolist element allows to add a list of all TODOs found in the wiki (which is a list of all the todo elements found in the wiki with their associated article.

Articles categories

Categories can be defined for articles. Each article can belong to any number of categories you want. For example:

   <article desc="an article">
   This is a very simple article.
      <cat id="syntax" />
      <cat id="structure" />
   </article>