Comment convertir un manuel UserBase en Docbook

    From KDE TechBase
    This page is a translated version of the page How To Convert a UserBase Manual to Docbook and the translation is 100% complete.

    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 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.


    • Collez la liste des pages dans le champ texte bigger.
    • Cliquez sur Export.
    Exporter les pages du manuel Amarok
    • Enregistrez le fichier. Dans ce qui suit, il s'appellera Manual.xml .

    Conversion

    • Installez le paquet Subversion sur votre système.
    • Vérifiez la dernière version du script de conversion :
      svn checkout --depth=files svn://anonsvn.kde.org/home/kde/branches/work/doc/
    • Copier Manual.xml dans le dossier du script.
    • Exécutez
      python wiki2docbook.py Manual.xml
      si vous voulez télécharger toutes les captures d'écran (cela prend un moment pour télécharger toutes les images de UserBase; grep et wget doivent aussi être installés), ou
      python wiki2docbook.py -s Manual.xml
      si vous n'avez pas besoin de télécharger les 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
    • Vérifiez les pages HTML (toutes les images doivent être visibles et les liens ne doivent pas aboutir sur les pages 404).
    • Remplacez les grandes images par des vignettes en utilisant convert de ImageMagick
    • Corrigez les liens dans docbook, pour qu'ils pointent vers des sections docbook, et non pas des pages de UserBase.
    • Initialisez le nom de l'application d'après la liste des entités KDE.
    • Copiez index.docbook et les images dans votre répertoire /doc et validez les sur le dépôt.
    Documents K3b de UserBase dans Opera et page convertie dans Konqueror.