How to import OTRS manuals into MediaWiki

From OtterHub - OTRS Community Wiki
Jump to: navigation, search

This document describes the procedure for importing OTRS official manuals such as OTRS Admin Manual or OTRS Developer Manual into a wiki which are powerd by MediaWiki. This document also contains step-by-step instructions for setting up Eclipse IDE and its workspace for this task.

Overview

The OTRS manuals such as Admin Manual and Developer Manual are written and are managed as DocBook documents, in common with many other open source communities, as a de facto standard for creating documentation for many open source projects. DocBook enables its users to create document content in a presentation-neutral form that captures the logical structure of the content; that content can then be published in a variety of formats, including HTML, XHTML, EPUB, PDF, man pages and HTML Help, without requiring users to make any changes to the source. In addition, the OTRS manuals can be translated and their editions are controlled by using CVS and po4a in combination with DocBook architecture. Please refer OTRS Developer Manual for more details about the documentation management policy of OTRS.org.

Wiki software, including MediaWiki which is mostly well known as the wiki software that powers wikipedia, is another new standard for documentation sharing. A wiki is a website that allows the creation and editing of any number of interlinked web pages via a web browser using a simplified markup language or a WYSIWYG text editor. Wikis are typically powered by wiki software and are often used collaboratively by multiple users. Examples include community websites, corporate intranets, knowledge management systems, and note services. The software can also be used for personal notetaking. OTRS.org also provides OTRS Wiki too with MediaWiki for collaboration use in OTRS community.

Unfortunately, both maintainers of OTRS DocBook documents and OTRS-Wiki users don't use other resources good enough due to incompatibilities between DocBook and MediaWiki at present. In my personal opinion, DocBook approach is too complicated for ordinary users to contribute to maintain or translate OTRS manuals. On the other hand, HTML pages of OTRS manuals which are generated by DocBook XSL are not so visual rich and easy to reference as expected in Today.

In order to solve this situation, we provide mwconv.xsl and related files as a tentative and comparatively simple simple solution. This XML stylesheet can translates OTRS DocBook XML documents into a MediaWiki XML exported dump files. This xsl is optimized for existing OTRS manuals, but should be used for other docbook documents with some improvements.

Examples

You can read imported OTRS manuals on active MediaWiki site as below.

Note: LoT, "Appendix B. configuration parameter" pages and internal links to these configuration parameter descriptions are not available on this site at the moment.

Breaf descriptions about provided files

mvconv
|
+ <manual-id>           e.g. doc-admin, doc-developer, etc.
| |
| + <language-id>       e.g. en, de, ru, etc.
|   |
|   + build.xml         Specific build configuration files for each OTRS manuals and
|   |                   languages, in which transformation parameters are specified.
|   |
|   + book-merged.xml   A work file.  xinclude ant task merges multiple docbook files
|   |                   into one complete package for xslt ant task.
|   |
|   + book-exported.xml Conversion result file, which can be imported 
|
+ build.xml             Common build configuration file.  Do not run this file directly
|                       since this file are called from each specific build files.
|
+ mvconv.xsl            XML stylesheet to convert an OTRS docbook manual into a MediaWiki
|                       importable XML dump files.
|
+ replace.properties    Replace Filter File for replace ant task to perform the post
                        processing on book-exported.xml.

Setting up Eclipse IDE

This section describes how to setting up a total processing environment for OTRS docbook manuals from start to finish by using Eclipse for newbies, whether your operating system is Windows, Linux or Mac OS X.

mvconv.xsl itself can work on any xslt processors, such as Xalan or Saxon, so if you already have processing environment for OTRS docbook manuals, your may download mwconv.xsl form our repository and use it on your own environment.

Install Java

Since Eclipse was originally written for the Java platform, it still requires a Java Runtime Environment (JRE) or a Java Development Kit (JDK).

If your system does not have Java installed, you can download a JRE installer package from ORACLE Java website or from java.com. At the time of this writing the latest stable version of JRE is Version 6 Update 27. If you are not familiar with Java development, you should find out Java SE 6 JRE, but not other JDK, JavaFX, NetBeans or Java EE.

To find out if you have Java installed, and which version it is, you can open a command prompt or shell and type in:

java -version

Install Eclipse IDE

There are no installer package used to install Eclipse. Its installation process is so simple.

  1. Visit [http://www.eclipse.org/download/ Eclipse Downloads page in Eclipse website.
  2. Select your operating system Choose you system in Eclipse Indigo (3.7) Packages for pulldown box.
  3. Find out Eclipse Classic 3.7 and click appropriate download link according to the Kernel of your operating system.
  4. Extract download archive file.
  5. Place extracted folder to appropriate location in your file system, e.g. C:\Eclipse (Windows) or /usr/local/eclipse (Linux).

First run of Eclipse

Once you installed eclipse, you should now be able to run it. Double-click the eclipse.exe or eclipse icon in installation folder above, or start the appropriate script in Linux.

  1. Immediately after the splash screen will appear, Eclipse will ask you for your workspace location. It is good idea to use the default workspace if you use Eclipse for this project only. You may check Use this as the default and do not ask again and click OK button.
  2. Welcome to Eclipse pane will appear. Click x (Close) button on Welcome tab to close it.

Install some additional plug-ins

You should install some additional plug-ins for dealing with SVN, XML and XSL.

  1. Execute Help > Install new software... menu.
  2. Install dialog box with Available Software pane will appear.
  3. Select Indigo - http://download.eclipse.org/release/indigo in Work with: pull-down list.
  4. Expand Collaboration and Web, XML, Java EE and OSGi Enterprise Development entries and find out the entries below and check them.
    Collaboration
    + (Check) Subversion SVN Team Provider (Incubation)
    Web, XML, Java EE and OSGi Enterprise Development
    + (Check) Eclipse XML Editor Tools
    + (Check) Eclipse XSL Development Tools
  5. Click Next > button.
  6. Install Details pane will appear. Click Next > button.
  7. Review Licenses pane will appear. Click I accept the term of the license agreements if you agree with them, and click Finish button.
  8. Installing Software dialog box will appear. Please wait a moment.
  9. Software Updates dialog box will appear. Click Restart Now button.
  10. Eclipse IDE will be restarted.

Install SVN Connectors

You should install at least one Subversive SVN connector for Subversive plugin. When you see Install Connectors dialog after restarting Eclipse, follow the instructions below.

  1. When Install Connectors dialog box with Subversive Connector Discovery pane will appear, check SVN Kit 1.3.5 or later and click Finish.
  2. Install dialog box with Install pane will appear. Click Next > button.
  3. Install Details pane will appear. Click Next > button.
  4. Review Licenses pane will appear. Select I accept the term of the license agreements if you agree them, then click Finish button.
  5. Installing Software dialog box will appear. wait a moment.
  6. If Security Warning dialog box will appear during the installation, click OK button.
  7. Software Updates dialog box will appear. Click Restart Now button to restart Eclipse IDE.

Configure Eclipse IDE

  1. Execute Window > Preferences menu.
  2. Preferences dialog box will appear. Select Ant in the left box to show Ant pane.
  3. Check Always run new Ant configurations in the same JRE as the workspace.
  4. Click OK.

Open XML perspective

  1. Execute Window > Open Perspective > Other... menu.
  2. Open Perspective dialog box will appear. Select XML item and click OK button.

Preparation of projects

Now, you can prepare projects on your workspace.

Prepare doc-admin project

  1. Execute File > New > Project... menu.
  2. New Project dialog box with Select a wizard pane will appear.
  3. Expand General folder and select Project wizard, then click Next > button.
  4. Project pane will appear. Type "doc-admin" in Project name: box and click Finish button.
  5. Right click doc-admin folder in Package Explorer pane and execute Team > Share Project... context menu.
  6. Share Project dialog box will appear. Select CVS item and click Next > button.
  7. Enter Repository Location Information pane will appear. Type or select as below.
    Host: source.otrs.org
    Repository path: /home/cvs
    User: anonymous
    Password: cvs
    Connection type: pserver
    Select Use default port
    Check Save password
  8. Click Next > button.
  9. Enter Module Name pane will appear. Select Use project name as module name as default and click Next > button.
  10. If Password Required dialog box will appear, type "cvs" in password: box and check Save password (could trigger secure storage login), then click OK button.
  11. Select Tag pane will appear. Select HEAD and click Next > button. Wait a moment for checking out all doc-admin contents.
  12. Share Project Resources pane will appear. Uncheck Launch the Comment wizard and click Finish button.

Prepare doc-developer and other projects

  1. Execute File > New > Project... menu.
  2. New Project dialog box with Select a wizard pane will appear. Expand General folder and select Project wizard, then click Next > button.
  3. Project pane will appear. Type "doc-developer" in Project name: box and click Finish button.
  4. Right click doc-admin folder in Package Explorer pane and execute Team > Share Project... context menu.
  5. Share Project dialog with Share Project with CVS Repository pane will appear. Select Use exsiting repository location: radio button and repository :pserver:anonymous@source.otrs.org:/home/cvs, then click Next >.
  6. Enter Module Name pane will appear. Select Use project name as module name as default and click Next > button.
  7. If Password Required dialog box will appear, type "cvs" in password: box and check Save password (could trigger secure storage login), then click OK button.
  8. Select Tag pane will appear. Select HEAD and click Next > button. Wait a moment for checking out all doc-developer contents.
  9. Share Project Resources pane will appear. Uncheck Launch the Commit wizard and click Finish button.

Prepare mwconv project

  1. Execute File > New > Project... menu.
  2. New Project dialog box with Select a wizard pane will appear.
  3. Expand General folder and select Project wizard, then click Next > button.
  4. Project pane will appear. Type "mwconv" in Project name: box and click Finish button.
  5. Right click doc-admin folder in Package Explorer pane and execute Team > Share Project... context menu.
  6. Share Project dialog with Share Project pane appear. Select SVN in Select a repository type: box and click Next > button.
  7. Share Project Wizard dialog box with Enter Repository Location Information pane will appear. Type information as below.
    In General tab:
    URL: http://open-support.info/svn/otrs/
  8. Click Next > Button.
  9. Specify the project(s) location pane will appear. Select Advanced Mode and click Next > button.
  10. Enter a commit comment pane will appear. Uncheck Launch the Commit Dialog for the shared resources and click Finish button.
  11. Operation in progress... message will appear. Wait a moment.
  12. If warning message "The project "mvconv" already exist in repository and has some content. To connect the local project to the specific location, the repository folder content should be checked out. Please consider that applying local changes can cause resource conflicts. For example, if local file has the same name as the remote directory the working copy of the file will be obstructed. Do you wish to proceed?" will appear, click Yes button.

Performing the OTRS manual conversion

Update doc-admin DocBook files

Update your local OTRS Admin Manual DocBook XML sources in doc-admin project to their latest OTRS CVS repository version.

  1. Right click doc-admin project folder in Project Explorer pane.
  2. Execute Team > Update in context menu.
  3. If Password Required dialog box will appear, type "cvs" into Password: box and check Save password (could trigger secure storage login), then click OK button.
  4. Updating doc-admin message will appear. Wait a moment.

Replace Configuration Option Reference

In OTRS Admin Manual, all-config-parameters.xml should be replaced with a file which were generated by xml2docbook.pl on your OTRS installation.

Proceed conversion

  1. Expand doc-admin folder in mwconv project via Project Explorer pane.
  2. Expand your objective language folder in mwconv folder.
  3. Right click build.xml in the folder above, then execute Run As > Ant Build context menu. Be patient as it can take tens of minutes.
  4. file book-exported.xml in same folder above will be generated (or updated if it already exists). You can import this file via Special:Import page or importDump.php.

Build parameters

Each specific build.xml files can contain build parameters as below.

Property name Explanation Default value
book.name The wiki root pagename of exported manual. Book:Doc-admin (en)
book.form mwconv.xsl produces semantic templates for each page for document management, multilingual or sequential page navigation. This template contains parameters below:
{{book
|master page= 'master page for multilingual page navigation'
|lang=        'language code for multilingual page navigation'
|status=      'page status for document management'
|heading=     'page heading'
|title=       'page title'
|next=        'next page pagename for page navigation'
|prev=        'previous page pagename for page navigation'
}} 
book
book.master.page Specifies 'master page' parameter value in semantic template above. blank
book.lang Specifies 'lang' parameter value in semantic template above. en
book.status Specifies 'status' parameter value in semantic template above. effective
template.name.prefix Specifies transformed template identifier prefix. mwconv.xsl transforms almost DocBook elements into MediaWiki templates except some basic elements such as <para>, <title> etc. For example,
<important>
<para>
text
</para>
</important>

will be transformed to

{{docbook important
|text
}}
docbook_
image.name.prefix Specifies image file name identifier prefix. For example, <screenshot> element in source xml as below
<screeninfo>Homepage OTRS.org</screeninfo>
<graphic fileref="screenshots/homepage-otrs.png"
scale="40" srccredit="Homepage OTRS.org"/>
</screenshot>

will be transformed to

[[File:doc-admin-screenshots-homepage-otrs.png
|thumb|center|600px|Figure: OTRS Homepage.]]
doc-admin-
image.size Specifies MediaWiki image resizing option value, snce MediaWiki don't have relative resizing option in contrast DocBook 'scale' attribute. 600px
table.class class name for table element wikitable
timestamp Specifies the source of timestamps of each wiki pages.

cvs-id : with $id$ cvs keyword substitution comments in DocBook xml source files.
now    : with current date-time.

cvs-id
chunk

yes : to generate multiple wiki pages in exported xml.
no  : to generate one monolithic wiki page in exported xml.
Note: Only value 'yes' is available for this parameter at the moment.

yes
chunk.section.depth Specifies depth to which sections should be chunked.

Note: Only value '1' is available for this parameter at the moment.

1
chapter.autolabel Specifies the labeling format for Chapter headings.

Note: Only value '1' is available for this parameter at the moment.

1
chapter.autolabel.prefix Specifies page heading prefix in chapter cover pages, for chapter heading translation. Chapter
chapter.autolabel.suffix Specifies page heading suffix in chapter cover pages, for chapter heading translation. blank
appendix.autolabel Specifies the labeling format for Appendix headings.

Note: Only value 'A' is available for this parameter at the moment.

1
appendix.autolabel.prefix Specifies page heading prefix in appendix cover pages, for appendix heading translation. Apendix
appendix.autolabel.suffix Specifies page heading suffix in appendix cover pages, for appendix heading translation. blank
toc.title Specifies TOC title in cover pages. Table of contents

Configuration settings of MediaWiki

Installing Semantic-MediaWiki and Semantic Forms plug-ins

We strongly recommend to install Semantic-MediaWiki and Semantic forms into your wiki site, if you want to integrate your OTRS system into Wiki site, or if you want to use a wiki site as a front page of OTRS.

By using SMW and Semantic Forms, not only your wiki will become more programmable, but also the data in your wiki will become reusable from OTRS, e.g. user login information, user information which are written in user pages, etc.

Customizing namespace

We recommend to prepare a custom namespace such as "Book" for imported manual pages, while mwconv can convert OTRS manuals to export into main namespace, because the independent namespace have additional benefits, e.g. it can provide different licensing policy, access permission or subpage configuration, it can provide custom edit form via Semantic Forms.

To customize namespace, please refer Using custom namespaces page in MediaWiki manual. The code below shows an example of LocalSetting.php setting.

define("NS_BOOK", 500);       # Specify appropriate namespace number.
define("NS_BOOK_TALK", 501);  # Specify NS_BOOK + 1.
$wgExtraNamespaces[NS_BOOK] = "Book";
$wgExtranamespaces[NS_BOOK_TALK] = "Book_talk";
$wgNamespacesWithSubpage[NS_BOOK] = true;

Disable restrict display title

MediaWiki grobal variable $wgRestrictDisplayTitle should be disabled at LocalSettings.php as below.

$wgRestrictDisplayTitle = false;

Extending maximum execution time in php

If you want to import book_exported.xml via Special:Import, you will have to extend maximum execution time of php to avoid "Fatal error: Maximum execution time of 30 seconds exceeded" error. Following example shows how to configure php.ini.

max_execution_time = 240;

Don't forget to restart Apache after making the changes.

# /etc/init.d/httpd restart

Preparation of the semantic template

Since mwconv.xsl produces a semantic template which named "Book" per page in exported xml, you have to prepare this custom template.

Following code is one of the most simple examples of such semantic templates, which can work without Semantic-Mediawiki, but with Parser Functions extension. You may change template name which is specified with build parameter "book.name".

  • Template:Book
{{DISPLAYTITLE:{{{heading|}}}{{#if:{{{heading|}}}|. }}{{{title|}}} }}
{|
| align="left"   | {{#if:{{{prev|}}}|[[{{{prev}}}|<Prev]]}}
| align="center" | {{#if:{{#titleparts|{{PAGENAME}}|-1}}|{{NAMESPACE}}:{{BASEPAGENAME}}|Up]]}}
| align="right"  | {{#if:{{{next|}}}|[[{{{next}}}|Next>]]}}
|}

Preparation of DocBook templates

mwconv.xsl basically transforms DocBook elements into MediaWiki templates, except some basic elements such as <para> or <title> to workaround the transclusion limitation of MediaWiki. This means that we have to prepare some custom templates for converted manuals.

Following codes are the most simple examples of such templates, whiches can work without Semantic-MediaWiki. You may change prefixed identifier 'Docbook' which is specified with the build parameter 'template.name.prefix'.

  • Template:Docbook example
<span id="{{{id|}}}">'''{{{title|}}}'''</span>

{{{1|}}}
  • Template:Docbook important
{| class="wikitable" width="100%"
| width="80px" align="center" | '''Important'''
| {{{1|}}}
|}

This code appears as below:

Important important message
  • Template:Docbook note
{| class="wikitable" width="100%"
| width="80px" align="center" | '''Note'''
| {{{1|}}}
|}

This code appears as below:

Note note message
  • Template:Docbook warning
{| class="wikitable" width="100%"
| width="80px" align="center" | '''Warning'''
| {{{1|}}}
|}

This code appears as below:

Warning warning message

Note

The OTRS manual can be converted from DocBook to MediaWiki only and it is irreversible due to the transclusion limitation of MediaWiki. It means that you shouldn't edit OTRS manuals on MediaWiki and they should be protected from unauthorized users.

However there is no need to be disappointed, since OTRS .pot and .po files can be imported into MediaWiki full reversibly, so we can perform OTRS manual translation tasks on MediaWiki more quickly, easily, collaboratively and autonomously, while keeping backward compatibility with traditional way of using DocBook and po4a. We intend to explain this procedure in further how-to document.

mwconv project is still under development, so your any feedback would be appreciated.

We hope that you will enjoy OTRS more with its additional visual rich, easy to use and more collaborative documentation on Wiki in all languages.