Help file – wiki2xhtml @ .::wiki2xhtml.sf.net

Other language: (de)

This help file has been created with wiki2xhtml which you find at sourceforge.net.

To run this program, you will need the Java Runtime, at least version 1.5.^[1] 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 the start.sh.

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

What is it?

: Butterwort (Pinguicula)

wiki2xhtml helps you to create your own web page. What you have to do is writing the text in Wikitext, and the rest is being done by the program.

You can also, if you wish, create own designs or use PHP files. Top

Last changes

Menu
Window title (%p)
Page/Line breaks (new)
Links (Anchors)
Images (arguments)
Lists (definition lists)
Tables (further possibilities)
Automatic redirect (new)

Creating new pages

: A part of the GUI in wiki2xhtml 3.2

If you want to parse a new page, you have to write the content into a file with any extension (“.html” is copied only). It has to be simple text, you cannot e.g. write it with Word and save it as a .doc. Windows users can use tools like the (very primitive) “Editor” or someting like Notepad++ (which I personally would prefer) or the a little bigger jEdit. Unix users have got enough good editors.

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)

(if you want to select more than one file at once; Here you can hold the Keys Ctrl or Shift) or

(if you want to add one more file and you have already got chosen some).

To parse the page (means writing the .html-file) by using the command line you have to add the name of the file, where the source wiki code is saved in, to the command. If its name is “helloWorld.txt” the command (without any arguments) would look like that: $ java -jar wiki2xhtml.jar helloWorld.txt

To add a menu to your page, you have to write the links into a file too (see below how that the menu file is constructed). Then, you can give the menu file with the argument -i: $ java -jar wiki2xhtml.jar -i menu.txt helloWorld.txt

You can set the standard page title in a file too (see below) with the argument -c or --common. This title is the one you can see in the title bar. $ java -jar wiki2xhtml.jar -c common.txt -i menu.txt helloWorld.txt or $ java -jar wiki2xhtml.jar --common=common.txt -i menu.txt helloWorld.txt

An example page might look like that: A '''bow''' is an ancient weapon that shoots arrows powered by the elasticity of the bow. Energy is stored in the limbs of the bow and transformed into rapid motion when the string is released, with the string transferring this motion to the arrow. The bow is used for hunting, sport (target shooting), and in historical times was a weapon of war.
[…]

== History ==
The bow seems to have been invented in the late Palaeolithic or early Mesolithic. The oldest indication for its use in Europe comes from the Stellmoor in the Ahrensburg valley north of Hamburg, Germany and date from the late Paleolithic Hamburgian culture (9000–8000 BC). The arrows were made of a pine and consisted of a mainshaft and a 15-20 centimetre (6-8 inches) long foreshaft with a flint point. (Source: Wikipedia: Bow (weapon), Sa 20. Jan 13:39:30 CET 2007)

Hint: If you only need the formatted html code and not the whole file (with the html, header, &hellip tags), e.g. for PostNuke, you can play with the arguments --only-code and --remove-linebreaks or—for PostNuke—directly with --pn or --pns. If you work with the GUI: Open the Code Paste Window and type your text, eventually check “Remove new lines” before. You can close the Code Paste Window with Esc or by unchecking the checkbox. If you click into the window with the generated code, it is copied to the clipboard. Top

Here an example: A menu entry with the name “Links”, referring to the file “links.html”, with a submenu containing links to http://inkscape.org/ with the name “Inkscape” and to http://www.scribus.net with the name “Scribus”. links.html Links *http://inkscape.org/ Inkscape *http://www.scribus.net Scribus 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.

Hint: If you don't specify any title, the default is “wiki2xhtml”. To avoid that, you can set a blank title: A space. Write a {{Title: }} instead of a title. Do not forget the space! 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: This page has been created with <a href="http://sf.net/projects/wiki2xhtml">wiki2xhtml</a> %v. Date of creation: %d The %v will be replaced with the current program version number, the %d with the current date and time. Don't forget the !

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. 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 (e.g. the title- and header-file, …), 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.

For relative links – to navigate inside your page – you need to set two squared brackets before and after the (relative) link. [[help.txt]] leads you to the file “help.txt” in the same directory as this file is: help.txt. It is possible to set a name for the link by either separating it with a space or a vertical line (|). See “Escaping Characters” above 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 help.html.

Top

Hints:

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: [[help.html]] becomes help.html (see the menu too).
> 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 (Tags, characters '"#!?.,:) are removed and spaces are replaced by underlines. The heading “New IDs!” becomes h_new_ids (written lowercase!). 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 {{Mark: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: {{Mark:gallery}} … [[help.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.

pwidth=auto — 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).
caption=… — Replaces the image caption (which otherwise would be simply the image's name).
thumb — Inserts a thumbnail^[3] and creates an image description page (which can be avoided with direct)
thumb=… — Sets the link to the thumbnail. If it is omitted, wiki2xhtml instead uses the standard path (which may be customized).
ld=… — Sets a long image description which only appears on the image page
w=... or width=... – Sets the width of the image
direct — Directly links to the image without an image page

Example: ... [[Image:sunrise.jpg|thumb|Sunrise over the sea|caption=Sunrise|ld=A sunrise like every day on holiday]] ...

Overview

Without arguments: [[Image:ahorn-300.jpg]]





  With text and a width of 100 pixels: [[Image:ahorn-300.jpg|Maple|w=100]]





Maple



  Thumbnail: [[Image:ahorn-300.jpg|thumb|thumb=ahorn-thumb.jpg|Maple leaf|ld=Silver Maple <em>(Acer saccharinum)</em>|caption=Maple leaves]]





Maple leaf




  Thumbnail, linked directly: [[Image:ahorn-300.jpg|thumb|direct|thumb=ahorn-thumb.jpg|Silver Maple]]





Silver Maple



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 &hellip; take a look at the guy on the left ;)

Image:sea.jpg|My boat. I have&nbsp;&hellip; ehm, borrowed it.

</gallery>

Top



Image Gallery

























The char “|” is used to add a description to an image. 





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

|}




Tip: 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

There is a basic support from html to highlight code, the code-tag. You should only use it for examples in normal text. If you want to post more lines, you can set the class to “code”, and the CSS file will tune it a little. Such a code window looks like that:

The code which is being used here is:

<code class="code">

Your text here<br />

A line break (till now) requires a <br />.

</code>

Also possible for commands:

$ echo 'Use “command” instead of “code”'

If you want to insert a cite, you have got the possibility to highlight it like in this example:

… and he spoke: <cite class="example"> Example text </cite>.

And it became a cite.

Top


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.

----This text will come into a new paragraph and is the same as&nbsp;&hellip;


----


&hellip;&nbsp;that.

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:


  < → &lt;
  > → &gt; (should be used too!)
  & → &amp;
  [ → &#91;
  \ → &#92;
  ] → &#93;
  { → &#123;
  | → &#124;
  } → &#125;
  ' → &#39;
  — → &mdash; (m-dash)
  – → &ndash; (n-dash)
  space → &nbsp; (non-breaking space)



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 &#x007B;



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


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 {{Keywords:…
  Author: The author of the site. {{Author:…}}
 Own: Either with {{Meta:name||content}} or, if all content has to be defined, with {{Meta:name="…" content="…"}}



Further, the content's language can bes set (e.g. en or de):

{{Lang:…}}

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, the following command (anywhere in the text or in the Common File) works:

{{Icon:…}}

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 --helpfile:

$ java -jar wiki2xhtml.jar --helpfile




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 
 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 --silent -i navigation.txt --header=header.txt -t title.txt --consistent-gallery. 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

Table of Contents

What is it?

Last changes

Creating new pages

Menu

Window title

Header

Footer

Table of Contents

References

Common File

Page formatting

Headings

Paragraphs

Line breaks

Page breaks

Formatting

Links

Images

Gallery

Image Gallery

Lists

Tables

Examples, Cites

Horizontal Line

Tips and Hints

Escaping characters

Thumbnails

Meta-Information

Automatic redirect

Icon

Typography

Command Line Mode

References

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

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}}