Comment convertir un manuel UserBase en Docbook

Préface

Le processus actuel n'est pas peaufiné, le code du script n'est pas beau, pas assez intelligent, etc.. La seule excuse est qu'il fonctionne tout de même

.

Si vous voulez améliorer le processus, que vous avez une bonne expérience de Python, et que vous connaissez les principes d'utilisation de docbook, vous pouvez améliorer la procédure. Veuillez contacter Yurchor si vous vous sentez prêt à apporter votre aide.

Préparation des pages pour Conversion

• Vérifiez que les pages de votre manuel suivent les instructions pour les auteurs de UserBase et les instructions typographiques.

• Vérifiez dans la table des matières, que chaque page a son titre aligné avec son niveau respectif d'indentation.

Tableau de référence

UserBase	Docbook	Comment
==Section==	<chapter>
===Section===	<sect1>
====Section====	<sect2>
=====Section=====	<sect3>
======Section======	<sect4>	Evitez si possible d'utiliser ce dernier niveau

• Vérifiez que toutes les cellules ont un espace avant la barre verticale '|' . Cette règle est conforme au formatage wiki standard.

• Rétablisser la cohérence du nom de l'application (évitez d'utiliser Amaroks, mais adoptez plutôt Amarok's).

• Vérifiez que toutes les images sont au format PNG.

• Supprimez tous les caractères non imprimables des noms d'images.

Exporter

• Préparez la liste des pages (extraire des adresses UserBase http://userbase.kde.org). Exemple pour 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

Astuce

Vous pouvez obtenir la liste complète des pages pour votre application avec le script suivant :

<DPL>
  nottitlematch = %/__|%/zh-%|%(%)
  titlematch = Amarok%
  namespace = Main
  columns = 1
  format = ,\n* [[%PAGE%|%TITLE%]],,
</DPL>

Remplacez Amarok par le nom de votre application, mettez-le sur votre page utilisateur, et cliquez sur Aperçu (Preview). Réarrangez la liste en fonction de la table des matières de votre manuel.

• Allez sur la page d'exportation.

• Collez la liste des pages dans le bigger champ texte.

• 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/

• Copier Manual.xml dans le dossier du script.

• 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 traitement

• Renommer Manual.xml.docbook en index.docbook.

• Vérifiez que la conversion s'est bien réalisée :

  checkXML index.docbook

• Corrigez les erreurs (mieux sur les pages UserBase).

• Convertir docbook en 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.