Much work on Ubuntu documentation is performed in wiki. This work often needs to be harvested for inclusion in the Docbook XML source files found in the Subversion Repository.
The most obvious option in porting wiki texts to Docbook is to copy and paste from wiki pages into an XML document and then markup the plain text. This is a long slow process when it comes to long documents. The alternative is to find a method that will automate the markup procedure by taking the wiki source format as you see it in 'edit mode' and covert it. The problem is that there are many wiki text formats so finding a single solution that will covert all formats to Docbook is not easy. The best compromise is to use a number of tools, each best suited to one or more wiki text source formats.
The following tools have been found around the web and produce reasonable results. You can choose to use them or not.
wt2db - http://www.tldp.org/downloads/
Aptconvert - http://www.xmlmind.com/aptconvert.html - link no longer available.
Mylyn Wikitext - http://wiki.eclipse.org/Mylyn/WikiText
The problem with all these tools is that none of them will do a perfect conversion from free or structured type texts to Docbook XML. This is a tricky task even when the markup used in such formats is perfect and there is not much of that in wiki. The best you can hope for is to 'part automate' the markup process.
- If you find other tools that work well, please tell us about them.
Each tool will provide its own method of invocation and passing texts. Please read the documents for each package you intend to use.
The general procedure is as follows:
- Login to wiki.
- Locate the page you want to port.
- Enter 'edit mode' by clicking the 'edit' tab.
- Select and copy (Ctrl+C) the entire wiki text from the web editor.
- Using a text editor, paste the text into a document and save to a text file (foo.txt).
- Use the utility to convert the text to an XML file (foo.xml).
- Edit the resulting Docbook XML to meet the requirement of the project
- Edit and modify the document to suit your document requirements.
- Validate the XML single instance (see XMLProcessing).
- Copy the body of the valid XML instance into position with the target document.
- Change the root and any other tags required in order that the target document will be valid.
- Validate the target document, resolve any issue.
- Commit the target document and delete the source files (rm foo.txt foo.xml).