xsAnyConvert Plugin

Info

The plugin development is currently on hold. This is just the current state of implementation, which could be extended upon your request.

Vote for this plugin or Contact us.
xsAnyConvert
(2) (13)
PluginxsAnyConvert
Description Convert any raw text file into DokuWiki syntax based on dictionaries
Type admin
Author Taggic
Last update 2012-03-15
DW compatible 2011-11-10 (Angua),
2011-05-25 (Rincewind)
Depends DokuWiki on a Stick
Conflicts none
Similar dokumicrobugtracker
Download https://github.com/Taggic/IssueTracker/archives/master
Issues fcon - Issue Tracker issues


Plugin in preparation and not yet published. In the event of interests please send us a ping via our Contact form .

The following test version prepared for TWiki conversion can be tested.
xsanyconvert.zip

Intro

- briefly explain basic idea
- create git repository
- prepare IssueTracker

General Info

Requirements/Dependencies The plugin requires DokuWiki on a Stick of Rincewind or Angua release.

Installation Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually.

Configuration No configuration necessary beside
==> creation of Dictionaries.

Syntax This is an admin plugin therefore no syntax available.


Recent Changes


Examples/Usage

Assumption is that you want to convert a file or set of files or set of files within namespaces from a different wiki system or similar source into DokuWiki syntax. For some reasons such conversions should be done outside your public system. Therefore we are using the DokuWiki on a stick distribution (any other local set-up should do it also).

However, once you have a properly created dictionary the handling is very simple. Just open the Admin area of your DokuWiki on a stick and click on the Convert raw file link to execute the plugin. Now insert the local path to your source directory and the full qualified target namespace like visible on following picture. Filenames and namespaces will be turned to lower case letters due to the requirements of DokuWiki. All blanks within filenames or namespaces will be turned into underline characters.

After definition of source and destination you have to specify the dictionary. Available dictionaries are listed within the select control, please choose the right one. Before you run the final conversion you may use the standardly checked simulate option. That is used to check file access also as displaying the target path. Files lead by a bell icon are already existing and will be replaced by new conversion completely. The plus icon is telling you about a new file, which will be added to the specific namespace.



Once you are satisfied with your settings you may disable the simulate option to leave the dry-run and convert your files. Your result should look similar to this picture.







FAQ

How to create a dictionary ?

The dictionary is a simple mapping of source and target syntax followed by a parameter defining the handling. The following example is for conversion from TWiki Headlines to DokuWiki.

Text Type

Basically it is a simple (text) replacement of TWiki meta characters but keeping the words until the end of line. Please be aware that each character counts so also each blank will be used as such (no trim of parameters !).

'---\+\+\+\+\+([^_]+)',== \1 ==,text
'---\+\+\+\+([^_]+)',=== \1 ===,text
'---\+\+\+([^_]+)',==== \1 ====,text
'---\+\+([^_]+)',===== \1 =====,text
'---\+([^_]+)',====== \1 ======,text

Block Type

The second possible type are blocks where the content inside to be kept as is. The most illustrative case is a code block.

'<pre\>(.*?)</pre\>'is,< code > \1 < /code >,block
'<verbatim\>(.*?)</verbatim\>'is,< code > \1 < /code >,block
'<literal\>(.*?)</literal\>'is,<nowiki> \1 </nowiki>,block

Plugin Extensions

Due to TWiki also has a lot of plugins and functions beside the simple formatting syntax. The following illustrates how to convert standard colors and TreeView with help of DokuWiki plugins. Therefore the plugins color and indexmenu to be installed on our DokuWiki:

'%YELLOW%',<color yellow> ,text
'%RED%',<color red> ,text
'%PINK%',<color pink> ,text
'%PURPLE%',<color purple> ,text
...
...
'%ENDCOLOR%',</color> ,text

'%TREEVIEW{topic="(.*?)" stoplevel="(.*?)" (.*?)}%',{{indexmenu>%ID%#\2|js#default nocookie}},text

Code words

Further there could be syntax not necessary to be converted, which can be deleted like following:

'<noautolink>',DELETE,text
'</noautolink>',DELETE,text
'#([^_]+)Anchor',DELETE,text
'\%TOC\%',DELETE,text
'<nop\>',DELETE,text

The xsanyconvert plugin just loops through the dictionary and will process the parameter according their order inside the dictionary. Therefore ordering parameters does for best results.

The block handling is done beside text conversion. That means a block will be cut and replaced by a place holder. At the end this place holder will be exchanged by the converted block. Between these two main steps the remaining content will be converted by processing all text type parameters.

A few place holder had to be introduced due to php has its own pattern-codes, which would lead into misinterpretation.

placeholdermeaning
%comma% ,
%ucomma% '
%noLF% prevent line feed to keep paragraph

The expressions will be used with php commands:
     preg_match
     preg_replace
     str_ireplace

Understanding of their description and RegEx is basic to create a valid dictionary.

Final Comment

This is a tiny converter to get most of the syntax converted at once. It should be used for some initial and basic conversion. It is not the intention to parse and convert all possible syntax combination and interpret it to 100% correctly. You will detect limits especially for complex functions. The target was to develop a plugin useful for multiple formats and formatting syntax. All the rest of converting (e.g. special link features, multi-functional plugin features, etc.) will be the pleasure of users and their creativity.

The package does contain two TWiki and a HTML page as test objects to see how it works. Further developments or extensions of dictionaries for other sources (e.g. MediaWiki) are welcome and highly appreciated.

Discussion

Please use only the DokuWiki Forum for discussion and Issue Report or git to raise issues.

Potential for improvements

Please use the Contact us form or the Issue Report to send us your wish or Feature Request.

xsanyconvert/start.txt · Last modified: 2014/04/30 09:36 (external edit)

This Wiki is hosted and ruled by Policies of Frister Consultancy Services.
By using this wiki you accept these rules. -> Impressum