Full Documentation – .::wiki2xhtml.sf.net

Other language: de

Quickstart		Quickref		Introduction
Doku				Documentation
Usage	Design		PHP	Immersion

This is the main documentation. The documentation is built as seen above. For the first steps it's recommended to start with the introduction. The main documentation (current page) is best used for looking up.

To run wiki2xhtml, you will need the Java Runtime^[1], at least version 1.6. You can either run that program in the command line, or work with the GUI. If you don't set any arguments in the command line (only java -jar wiki2xhtml.jar), the GUI is automatically opened. You get it also by double-clicking the file wiki2xhtml.jar or start.bat, Unix users may execute ./wiki2xhtml.

wiki2xhtml is licensed under the GNU General Public License (GPL).

Please let me know in the wiki2xhtml forum if there is something wrong, not understandable or missing.

Last changes

New since wiki2xhtml 3.4:

Template for Table of Contents
Images: Arguments
Meta Information: Custom meta content

Creating new pages

In the GUI you can select the files which you want to parse and the other files with the buttons:

(only one file can be selected, e.g. the header file)

(to select multiple files; here you can hold the Keys Ctrl or Shift) or

(to select a directory).

Top

The menu is read from a file, so you don't have to add it manually on every page (and after every change …). Each entry is written on a new line in list form. Menu * Links, links.html ** Here, here.html ** There, http://granjow.net In this example the caption “Menu” is being followed by the entry “Links” and a submenu containing two further entries. The first, also optional, line describes how links to the current page are handled. It has to start with #! and may contain the following commands:

link_strong — The link will be displayed in bold type
link_deactivate — The link will be deactivated

The settings named above may also be deactivated explicit by appending a zero (link_strong0). Top

Window title

There are two different ways to set the window title which appears in the Menu Bar, but you can combine them. The first and easier for many pages is writing it (without HTML tags!) into the Common File. The second is: Write it down anywhere in the source text according to the pattern {{Title:…}}.

As I said, you can combine the two possibilities. The title you give in the file is “general” and valid for every page, the second is page-specific—and replaces the general title. By setting a %s in the custom window title you can insert the general title at this position. An example: Your page can be found at sourceforge.net, so you want to set the general title to “– .::sourceforge.net”. The current page is about a game, let's name it “Tetris” (what a strange name!). Now you want the title to look like this: “Tetris – .::sourceforge.net”. What you need is the following code in the source file (with the page's content): [Content] {{Title:Tetris, %p %s}} [Content] Now you have to append the following line containing the general title—which should contain all characters appearing in every window title, including the “–”—in the Common File: {{DefaultTitle:– .::sourceforge.net}} The %p will be replaced by “Page x of y” if the document contains page breaks. Top

Header

Today, the header is often used to lead the user back to the start page—a nice aid! The link back to the start page can be set with {{Homelink:…}} (anywhere in the text or in the Common File). For example a link to sf.net/projects/wiki2xhtml: {{Homelink:http://sf.net/projects/wiki2xhtml}} If you now click the header (usually an image), you get back there. Top

Footer

The footer, a little text at the end of the page, has to be written in a separate file too. It could look like that: <p>This page has been created with <a href="http://sf.net/projects/wiki2xhtml">wiki2xhtml</a> %v.</p> <p>Date of creation: %d</p> The %v will be replaced with the current program version number, the %d with the current date and time. Don't forget the <p>!

You can add the footer file with the argument -f FILE or --footer=FILE: $ java -jar wiki2xhtml help.txt --footer=footer.txt $ java -jar wiki2xhtml help.txt -f footer.txt Top

You can insert one TOC by inserting a {{TOC}} anywhere in the text. The default heading can be replaced by another via the command {{TOC|Alternative heading}}. Top

References

To insert footnotes or references you can use the ref-command. If you use footnotes, its content doesn't disturb in the text. The references can be inserted─usually at the end of the page─with <references />. In the text that may look like this: Footnotes<ref>Via footnotes, annotations and references in the continuous text can be rolled out.</ref> are often more demanding to play as the feet are less agile then the hands. … == Annotations, References == <references /> The result: “Footnotes^[2] are often more demanding to play as the feet are less agile then the hands.”

Tip: You don't set spaces before footnotes. Top

Common File

To simplify the handling of the various settings (like author, language and more; An overview is available in the Quickref), this settings can now be set in one single file.

This “Common File” (here named common.txt) is being handed over with the following argument: $ java -jar wiki2xhtml.jar -c common.txt Top

Page formatting

Headings

For headings, you always should begin with the second level, as the first one is the page title and can exist only once on one page. To add a heading (level 2) with the name “Good Morning”, put two equal signs before and after the name and keep it on an own line(!). The code would look like this: == Good Morning == The page title—the first heading—can be set with {{H1:…}}. Example: {{H1:Photographing without a camera}} Top

Paragraphs

Paragraphs are created when there is an empty line between two lines with text: He stood alone in the room, holding his arm outstretched, as if he was searching for something. Then … suddenly, everything got dark around him! He simply could not sleep when the light is on. Top

Line breaks

Line breaks can be inserted with two backslashes followed by a space:
\\ Top

Page breaks

Page breaks are inserted with the following lines: \\// --- //\\ This pattern was selected because of its good visibility in text.

Attention: Nowiki tags are not regarded!

Formatting

To format your text cursive or bold, put either two or three apostrophes before and after the text. Do not use boldface too often, you should only use it to highlight (important) lemmas. Example: A '''Lemma''' is something a paragraph or a whole text ''is about.'' Top

Links

There are two different kinds of links: Absolute and relative ones. The difference between them is: An absolute, or external, link is usually to an other site like http://www.gimp.org. It does not matter, where you have saved your page, the link stays the same. A relative, or internal, link however is used to link your HTML files among themselves. An example is a link to the file help.txt: If this page you are reading now is located on /home/simon/, the absolute link to the file help.txt would be “/home/simon/help.txt”. And if someone has put this page on a web page (http://anything.org/), the absolute position is “http://anything.org/help.txt” (The absolute position would be relative! :-S).

If you write a single URL like http://sourceforge.net, it is converted to a link and a possible dot, comma or bracket at the end is removed. Recognized are links starting with www, http, https or ftp. If you want to add a description, put both the link and the description (separated with a space) into square brackets: [http://www.scribus.net Scribus] leads to Scribus.

Relative links for navigationning on a web page are marked with two square brackets: [[doc-de.html]] for example links to the German version of this document: doc-de.html. The page name may also be replaced with other text by adding this link text after a space or a pipe symbol (|). See “Escaping Characters” for further information.

Examples: http://www.gimp.org is the link to the GNU Image Manipulation Program. [http://www.gimp.org GIMP] replaces the link name with “GIMP”. [[help.txt This file]] is the source for the file doc.html.

Top

Hint:

If you insert a relative link to a page which you intend to generate, do not forget that the ending is .html afterwards!

Internal links to the current file are deactivated: [[doc.html]] becomes doc.html (see the menu too).

Link and description can be parted with eiter a | or a space. For wiki2xhtml, the bar is more important than a space.

]]>

Anchors

It is also possible to use anchors inside a page. In HTML you can assign elements (e.g. a heading) an unique ID to which you can jump with a link. Headings automatically obtain one, but you can use them also in the text.

Headings own the ID “h_” followed by the heading itself, in slightly changed form. Some special characters like spaces will be removed (More precisely: wiki2xhtml will create an XML Name, all allowed characters are listed here, in unique but a little cryptic form). The easiest way to find out what an ID of a heading is is to insert the wikitext into the GUI’s code window.

You can also insert an own anchor in your text, at the place you want to jump to. This with the command ~~unique name~~. The name mustn't be used more than one time. After that you can link any times to this place.

To set a link on an anchor, you've got to append the target a # followed by the name of the anchor. If the target is located on the same page, you can leave the page name away. Following examples link to the gallery and the heading Tables: ~~gallery~~ … [[doc.html#gallery Galerie]] has got the same target as [[#gallery Galerie]] [[#h_tables Tables]] (Don't forget capitalisation! Top

Images

Inserting an image is simple: If you e.g. have got an image named “img2.jpg”, add the code [[Image:img.jpg|]] to your text. Instead of Image:, Bild: is working too. To add a description to the image, separate it with a vertical line (pipe character) from the image name. [[Image:img.jpg|thumb|Butterwort ''(Pinguicula)'']] You can see the result of this code at the top of the page.

The program creates special pages for images (also in the gallery) if you set the argument thumb. If an image is linked twice from the same page, but with different description, the description from the last image is being taken. If it's linked from different pages, wiki2xhtml will create different description pages.

The images can also be assigned some arguments.

320px – Sets the width of the image, here 320 px. The argument w=auto uses the image's original size, rather than a pre-set value.
caption=… — Replaces the image caption (which otherwise would be simply the image's name).
direct — Directly links to the image without an image page between.
ld=… — Sets a long image description which only appears on the image page
small — Doesn't (de)magnifiy images on the image page (if the image is smaller than set in the page, it is reasonable not to magnify images, but not the other way round).
thumb — Inserts a thumbnail^[3] and creates an image description page (which can be avoided with direct)

Additionally:

arg=… – Additional arguments for the img tag (like CSS formattings)
argLink=… – Additional arguments for the a tag (like for using ShadowBox with your images)
clear, clear:before, clear:after – Can be used if content is written over the image.

Hint: The link to the thumbnail can also be set separately for one image; if e.g. a PDF document (book.pdf) needs a special preview image (cover.png) you can replace the argument thumb by the specific argument thumb=cover.png. Apart from that you should set a default path to thumbnails and simply use thumb.

Examples for inserting images

Without arguments

[[Image:ahorn-300.jpg]]

The image is inserted directly, in original size.

Labeled and resized

[[Image:ahorn-300.jpg|Maple|150px]]

The image obtains a caption Maple, and the image width is set to 150 pixels.

Maple
Maple

Thumbnail

[[Image:ahorn-300.jpg|thumb=ahorn-thumb.jpg|A Maple leaf|ld=Silver Maple ''(Acer saccharinum)'']]

The thumbnail ahorn-thumb.jpg is being used. As image title A maple leaf is set, and additionally a verbose description with the latin name which will be shown on the linked image page.

: A Maple leaf

Directly linked thumbnail

[[Image:ahorn-300.jpg|thumb|direct|thumb=ahorn-thumb.jpg|Silver Maple]]

The verbose description has been left away as by direct linking no image page is created.

: Silver Maple

Hint: You can set a standard image directory with {{DirImages:…}}. To access a file that is not in this standard directory, write a ./ before it (. means the current directory). See the quickref for other settings.

Top

Gallery

You can add a gallery to your page with the tag <gallery. Between the opening and the closing tag you can add an image on a new line (or, if you want, plain text) – see the gallery above. With the argument caption= you can set a caption for the gallery, and if you want to add a description, you can add it after a vertical line. An example code would look like this: <gallery caption="My Gallery"> Image:holiday.jpg Yeah, these were nice times … take a look at the guy on the left ;) Image:sea.jpg|My boat. I have … ehm, borrowed it. </gallery> Top

Image Gallery

: The char “|

Only text leads to a simple field. Also here it is possible – like in the description – to add a Link. The Caption for the gallery is given with the command <gallery caption="…">.

: Sailing boats

Top

Lists

Inserting a list is a little easier here than it would be in HTML: You only need to put a * at the beginning of the line. A ** creates a subordered list entry. To insert an ordered list with digits, use the # instead. * First level ** Second level

Definition lists are another kind of lists. Here they are used e.g. in the FAQ. You can insert them with:

a ; at the beginning to indicate the definition name or: a : (or more than one) at the beginning of the line to explain the entry above.

List elements may be committed elements like CSS formattings. Everything standing after a pipe character (“|”) is regarded as an argument. The argument style="color: #f00;" e.g. colorizes the line red. * style="color: #f00;" | This list element is colorized red.

This list element is colourized red.

Top

Tables

Tables may have a table header at the top. You insert tables according to the following example: {| | ! Windows ! Linux |- ! Music Player | [http://www.apple.com/itunes/ iTunes] | [http://amarok.kde.org/ Amarok] |- ! Photos | [http://picasa.google.com/ Picasa] | [http://www.digikam.org/ digikam] |}

The first cell is being omitted here. That would result the following table:

	Windows	Linux
Music Player	iTunes	Amarok
Photos	Picasa	digikam

That are the basics. To increase the overview of the code (source) you might like to have more than one cell on one line. In that case you can part them with two vertical lines: | Cell 1 | Cell 2 is the same as | Cell 1 || Cell 2

You can also set things like the width of a cell or its background-color. In that case you have to part the arguments from the text content by a vertical line with a space before and after. {| | style="width: 200px; border: 2px solid #000;" | Width of 200 px |}

Width of 200 px

Note: Do not mistake tables for lists!
Further possibilities

Coloured border (border: 1px #98e5b3 solid;), left width is 10 pixel (border-left-width: 10px;), a space of one character at the right (padding-right: 1em;):

style="border: 1px #98e5b3 solid; border-left-width: 10px; padding-right: 1em;" Cell 2

Two pixel space between the cells: cellspacing="2" as argument for the whole table

{| cellspacing="2" style="border: 1px solid;" Cell 2

Single rows can be formatted separately by inserting the arguments after the sign for the new row (|-).

Position of the argument	Scope
Arguments after `{\|`	Whole table
Arguments after `\|-`	Formattings for one row
Arguments after `\|`	Single cell

The necessary code: {| cellspacing="2" style="background-color: #fff0c8;" ! Position of the argument !! Scope |- | | Arguments after {| || Whole table |- style="color: #e9713c; background-color: #fff; font-weight: bold;" | | Arguments after |- || Formattings for one row |- | | Arguments after | || style="font-style: italic;" | Single cell |}

Hint: If there is a | in the cell, the content before it will be (mis)interpreted as argument and cut off. Put a |, separated with spaces, at the beginning of the cell content to avoid this problem (see also above).

Top

Examples, Cites

Horizontal Line

You can insert a horizontal line with four hyphens on a new line. Do not use it, unless it really requires the line. ---- Top

Tips and Hints

Not everything is being done by my program. Some things are simply a little HTML and CSS, and others are something only you can make correctly – e.g. the typography. I will give you a little overview over further possibilities you have got, and how the usual commands sould be used.

Note: In the samples which show you how to compile a source document I will use the file “help.txt” which has to be compiled. A command is marked with a $ at the beginning of the line. The basis command is: $ java -jar wiki2xhtml.jar help.txt This would create the html file, without a menu and such things.

It is possible to compile as much files simultaneously as you want, but you have to write out every file name by hand. The * is not yet supported. Top

Escaping characters

If you want to write for instance a code example for HTML, you cannot write a <p> in the source code, as that would be interpreted as a new paragraph. So you need to “escape” it. The most important chars and their codes are:

< → <
> → > (should be used too!)
& → &
[ → [
\ → \
] → ]
{ → {
| → |
} → }
' → '
— → — (m-dash)
– → – (n-dash)
space →   (non-breaking space)
0 → 0 (a 0, e.g. to mask keyboard input)
$ → $
~ → ~

An other possibility to escape whole expressions which would be parsed by the program is the nowiki-tag. Put it before and after an expression to avoid it being translated from wiki to (x)html. If you e.g. want to avoid that a link (for instance www.google.com) is being recognized, write: <nowiki>www.google.com</nowiki>. The result is that: www.google.com How can you find out this codes by yourself? Quite simple. They are displayed in e.g. OpenOffice.org in the char map (Insert > Special Character). For the character “{” e.g. it says “U+007B (123)”. The number between the brackets can be inserted with &#NUMBER; in the code. Alternatively the Unicode^[4] can be inserted directly, in this case {

In URIs it may have some special characters like a space. If you set a link to such a file, the program can not recognize whether the part after the space belongs to the URI or to the link name. This special characters have got some escape sequences too:

space → %20
[ → %5b
] → %5d
| → %7c

A sample link to a (not existing) document named “with space.html” could look like this: [[with%20space.html with space]]. The result of that example: with space. Alternatively you can use the vertical line (“|”): [[with space.html|with space]]. That leads to the same result: with space.

There is a very good reference in the web where you find all the codes you need. You can find it at w3schools.com. Top

Thumbnails

The charging time of web pages ought to remain as low as possible. The more has to be loaded entering a page, the longer it takes to construct the page and the more the server will be stressed. Thus the (big) original images should not be taken for the (small) preview images─use smaller images of a less resolution and lower file size! Thumbnails may be generated with programs like GIMP or XnView. Unix-User have got a powerful tool with convert from ImageMagick.

The best way to handle thumbnails is to save them in a separate directory. Their name ought to contain the original file name as then they can be used automatically. Good choices are e.g. “imagename_thumb.jpg”, “thumb_imagename_jpg” or, even easier (if the thumbnails are in a separate directory) the filename itself: “imagename.jpg”. Exceptions may be set with thumb=….

Variables (here for the example image dir/image.jpg)

%n – full name with path (dir/image.jpg)
%f – file name (image.jpg)
%d – path (dir)
%w – without extension (image)
%e – extension (.jpg)

Examples (Original filename: image.jpg):

Directory name	Thumbnail name	Entry in the configuration file
thumbs	image.jpg	{{Thumbnails:thumbs/%f}}
thumbs	thumb_image.jpg	{{Thumbnails:thumbs/thumb_%f}}
thumbs	image_thumb.jpg	{{Thumbnails:thumbs/%w_thumb%e}}
thumbs	image.png	{{Thumbnails:thumbs/%w.png}}

Top

Templates

Content which appears multiple times (like the buttons to change the language on this page) can be written into a file in the same directory where also the sources lie. This, in this example tplLang.txt, can be included as follows: {{:tplLang.txt}} The text from the template page runs through the parser too, which means that Wikitext will be recognized. Furthermore, Parameters are supported. If text which should be passed as parameter contains a special character like a pipe symbol or closing curly braces, it can be masked with <![CDATA[text]]>. {{:tplLang.txt|<![CDATA[ “}}” are two closing braces, and “|” is a pipe symbol.. ]]>}} Top

Meta-Information

The (x)html files can contain some more information (“meta-data”). It is/was used by search engines, but today they are often ignored, because like that the search engines can be manipulated. Today they usually search the visible text. wiki2xhtml supports the following keywords:

Description: A short description of the page content.

{{Description:…}}

Keywords: The keywords someone could type to find your page, separated with a comma.

{{Keywords:…}}

Author: The author of the site.

{{Author:…}}

Language: The language used on the current page, e.g. en or de

{{Lang:…}}

Custom: (See also: Wikipedia: Meta element

{{Meta:name=content}} (name/content combinations) {{Meta:anything you like}} (any other combination)

All these commands work either in the Common File or in the text itself. Top

Automatic redirect

You can redirect the user to an other page by inserting the following line in your document: #REDIRECT 2 index.html This redirects him after 2 seconds to the page index.html. Don't forget to depose a note for browsers which don't support redirection! Top

Icon

To use a page icon (Favicon), the following command (anywhere in the text or in the Common File) works: {{Icon:…}} Top

PHP, JavaScript and CSS page specific

Two different commands may be used for page specific PHP, JavaScript, CSS and similar. If the code has to be just at the beginning of the page, also before the html tag as it is necessary for PHP, it can be inserted at the beginning of the page and terminated with the command:  To include CSS, JavaScript and similar, the code has to be enclosed by two tags as shown in the following example for CSS.  <style type="text/css"> body { background-color: #fb0; } </style> 

See also the documentation page to PHP. Top

Typography

Typography is important – also in the web. If you don't consider some simple rules, the text may look terrible or have no sense, but if you do, everything will seem to suit :) I will explain some of them later here and teach the program how to correct common mistakes. Top

Command Line Mode

If you often use wiki2xhtml, you might want to use the command line version, as you can write scripts for it or things like that. When often using the same settings, this way will be much faster as the GUI.

You can get an overview over all available arguments in the shell by adding the argument --help or -h. I want to explain the most important ones here. The $ at the beginning indicates a command in a shell (DOS, bash, …) and does not have to be written.

If you want to create the help files, execute the program with the argument --helpfiles-de: $ java -jar wiki2xhtml.jar --helpfiles

You can leave the reck away (with the head, body and other tags) if you want to have plain HTML code which can be used somewhere else with the argument --only-code. $ java -jar wiki2xhtml.jar --only-code {FILE(S)}

If you want to use wiki2xhtml to generate HTML code for PostNuke: You can remove the line breaks with --remove-newlines (PostNuke sometimes appends a <br /> at the end of every line, what is not desired) and --only-code (which does not insert the HTML code into the reck with the title, header, body tags etc.). The argument --stdout furthermore re-routes the output to the stdout (usually the shell) instead of writing it into a file. The following commands do the same, --pn and --pns are abbreviations. $ java -jar wiki2xhtml.jar --remove-newlines --only-code {Files, Arguments, ...} $ java -jar wiki2xhtml.jar --pn {Files, Arguments, ...} Or: $ java -jar wiki2xhtml.jar --remove-newlines --only-code --stdout {File(s), Arguments, ...} $ java -jar wiki2xhtml.jar --pns {File(s), Arguments, ...}

The argument --standard means the same as -m menu.txt -f footer.txt -c common.txt. The arguments can be overwritten (e.g. with a -v for the verbose mode).

You may also try -v (which is the same as --verbose) for more output. --silent does the opposite; Only the necessary things are printed. --debug enters the debug-mode where you get a lot of (useless) information. Top

References

[↑] You can get Java for free at java.com.
[↑] Via footnotes, annotations and references in the continuous text can be binned.
[↑] Thumbnails have to be created manually!
[↑] http://www.decodeunicode.org/ is a huge reference to Unicode characters. Here you will find everything …

Top

› wiki2xhtml Documentation

Last changes

Table of Contents

Creating new pages

Menu

Window title

Header

Footer

Table of Contents

References

Common File

Page formatting

Headings

Paragraphs

Line breaks

Page breaks

Formatting

Links

Anchors

Images

Examples for inserting images

Gallery

Image Gallery

Lists

Tables

Examples, Cites

Horizontal Line

Tips and Hints

Escaping characters

Thumbnails

Templates

Meta-Information

Automatic redirect

Icon

PHP, JavaScript and CSS page specific

Typography

Command Line Mode

References