How To Convert a UserBase Manual to Docbook

Preface

The current process is not polished, the script code is ugly, not intelligent enough, etc.. The only excuse is that it works somehow

.

If you want to improve the process, have good Python skills, and know the docbook authoring principles, you can improve the procedure. Please contact Yurchor if you are able to help.

Preparing Pages for Conversion

• Check that the pages of your manual follow the author guidelines of UserBase and typographical guidelines.

• Check if every page has its header according to the level of this page in table of contents.

Reference table

UserBase	Docbook	Comment
==Section==	<chapter>
===Section===	<sect1>
====Section====	<sect2>
=====Section=====	<sect3>
======Section======	<sect4>	Avoid using this last level if possible

• Check if all table cells have space after the pipe character. This rule conforms with traditional wiki formatting.

• Make application name formatting consistent (avoid using Amaroks, do use Amarok's).

• Ensure that all images are in PNG format.

• Remove all non-printable characters from image names.

Export

• Prepare the page list (strip from UserBase addresses http://userbase.kde.org). Example for Amarok:

Amarok
Amarok/QuickStartGuide
Amarok/QuickStartGuide/GettingStarted
Amarok/QuickStartGuide/TheAmarokWindow
Amarok/QuickStartGuide/TheMusicCollection
Amarok/QuickStartGuide/Playlists
Amarok/QuickStartGuide/TheContextView
Amarok/QuickStartGuide/HowToDealWithProblems
Amarok/QuickStartGuide/Glossary
Amarok/Manual/AmarokWindow
Amarok/Manual/AmarokWindow/Toolbar
Amarok/Manual/AmarokWindow/MediaSources
Amarok/Manual/AmarokWindow/ContextPane
Amarok/Manual/AmarokWindow/PlaylistPane
Amarok/Manual/ConfiguringAmarok
Amarok/Manual/AdvancedFeatures
Amarok/Manual/AdvancedFeatures/CollectionScanning
Amarok/Manual/AdvancedFeatures/CoverManager
Amarok/Manual/AdvancedFeatures/DynamicPlaylists
Amarok/Manual/AdvancedFeatures/AutomaticPlaylistGenerator
Amarok/Manual/AdvancedFeatures/ExternalDatabase
Amarok/Manual/AdvancedFeatures/AFT
Amarok/Manual/AdvancedFeatures/Moodbar
Amarok/Manual/AdvancedFeatures/WorkingWithMediaDevices
Amarok/Manual/AdvancedFeatures/SavedPlaylists
Amarok/Manual/AdvancedFeatures/PlaylistFiltering
Amarok/Manual/AdvancedFeatures/QueueManager
Amarok/Manual/AdvancedFeatures/SearchInCollection
Amarok/Manual/AdvancedFeatures/TagEditor
Amarok/Manual/AdvancedFeatures/OrganizeCollection
Amarok/Manual/AdvancedFeatures/Transcoding
Amarok/Manual/AdvancedFeatures/ScriptManager
Amarok/Manual/AdvancedFeatures/RemoteCollections
Amarok/Manual/AdvancedFeatures/RemoteCollections/Ampache
Amarok/Manual/AdvancedFeatures/RemoteCollections/DAAP
Amarok/Manual/AdvancedFeatures/RemoteCollections/Samba
Amarok/Manual/AdvancedFeatures/RemoteCollections/UPnP
Amarok/Manual/MenuAndCommandReference/AmarokMenu
Amarok/Manual/MenuAndCommandReference/ViewMenu
Amarok/Manual/MenuAndCommandReference/Playlist
Amarok/Manual/MenuAndCommandReference/Tools
Amarok/Manual/MenuAndCommandReference/Settings
Amarok/Manual/MenuAndCommandReference/Help
Amarok/Manual/KeybindingReference
Amarok/Manual/KeybindingReference/GlobalShortcuts
Amarok/Manual/KeybindingReference/AmarokShortcuts
Amarok/Manual/TroubleshootingAndCommonProblems
Amarok/Manual/AmarokOnOtherPlatforms/Non-KDE Desktops
Amarok/Manual/AmarokOnOtherPlatforms/Windows
Amarok/Manual/AmarokOnOtherPlatforms/OSX
Amarok/Manual/FAQ
Amarok/Manual/Credits_and_License

 

Tip
You can obtain the full list of pages for your application with the following script: <DPL> nottitlematch = %/__|%/zh-%|%(%) titlematch = Amarok% namespace = Main columns = 1 format = ,\n* [[%PAGE%|%TITLE%]],, </DPL> Replace Amarok with the name of your application, put it on your user page, and click on Preview. Rearrange the list according to the ToC of your manual.

• Go to the export page.

• Paste the page list into the bigger text field.

• Click on Export.

Export of Amarok manual pages

• Save the file. The saved file will be called Manual.xml in what follows.

Conversion

• Install Subversion package for your system.

• Checkout the latest version of conversion script:

  svn checkout --depth=files svn://anonsvn.kde.org/home/kde/branches/work/doc/

• Copy Manual.xml to the script folder.

• Run

  python wiki2docbook.py Manual.xml

  if you want to download all screenshots (it takes some time to download all images from UserBase, grep and wget should be installed), or

  python wiki2docbook.py -s Manual.xml

  if you need not to download images.

Post-processing

• Rename Manual.xml.docbook to index.docbook.

• Check if conversion was done correctly:

  checkXML index.docbook

• Fix the errors (better on UserBase pages).

• Convert docbook to HTML:

  meinproc4 index.docbook

• Check HTML pages (all images should be visible, links should not lead to 404-pages).

• Replace big images by thumbnails using convert from ImageMagick

• Fix links in docbook, so they lead to docbook section, not UserBase pages.

• Fix application name according to KDE entity list.

• Copy index.docbook and images to your /doc folder and commit them to repository.

K3b docs on UserBase in Opera and converted page in Konqueror.