Comment convertir un manuel UserBase vers Docbook

From KDE UserBase Wiki
Revision as of 15:26, 3 June 2018 by ChristianW (talk | contribs) (Created page with "* Remplacer les grandes images par des vignettes en utilisant '''convert''' de '''ImageMagick'''")
Other languages:

Préface

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

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

Préparer les pages pour la conversion

  • Vérifiez dans la table des matières, que chaque page a son titre indenté conformément au niveau qu'elle doit avoir.
Tableau de référence
UserBase Docbook Commentaire
==Section== <chapter>
===Section=== <sect1>
====Section==== <sect2>
=====Section===== <sect3>
======Section====== <sect4> Ne pas utiliser ce dernier niveau dans la mesure du possible
  • Vérifiez que toutes les cellules des tableaux on un espace après la barre verticale de séparation '|' . Cette règle est conforme au formatage usuel du wiki.
  • Utilisez des noms d'application qui ont un format cohérent (évitez Amaroks, mais utilisez Amarok's).
  • Vérifiez que toutes les images sont au format PNG.
  • Enlevez tous les caractères non imprimables présents dans le nom des images.

Exporter

  • Préparer la liste des pages (extrait des adresses UserBase http://userbase.kde.org). Exemple pour Amarok :
Amarok/Manual/Introduction
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/ConfiguringAmarok/ChangingLayout
Amarok/Manual/Organization
Amarok/Manual/Organization/Collection
Amarok/Manual/Organization/CollectionScanning
Amarok/Manual/Organization/Collection/SearchInCollection
Amarok/Manual/Organization/Collection/OrganizeCollection
Amarok/Manual/Organization/Collection/RemoteCollections
Amarok/Manual/Organization/Collection/RemoteCollections/Ampache
Amarok/Manual/Organization/Collection/RemoteCollections/DAAP
Amarok/Manual/Organization/Collection/RemoteCollections/Samba
Amarok/Manual/Organization/Collection/RemoteCollections/UPnP
Amarok/Manual/Organization/Collection/ExternalDatabase
Amarok/Manual/Organization/Collection/WorkingWithMediaDevices
Amarok/Manual/Organization/CoverManager
Amarok/Manual/Organization/TagEditor
Amarok/Manual/Organization/Transcoding
Amarok/Manual/Organization/ScriptManager
Amarok/Manual/Playlist
Amarok/Manual/Playlist/SavedPlaylists
Amarok/Manual/Playlist/PlaylistFiltering
Amarok/Manual/Playlist/QueueManager
Amarok/Manual/Playlist/DynamicPlaylists
Amarok/Manual/Playlist/AutomaticPlaylistGenerator
Amarok/Manual/Various
Amarok/Manual/Various/Moodbar
Amarok/Manual/Various/AmarokOnOtherPlatforms
Amarok/Manual/Various/AmarokOnOtherPlatforms/NonKDE Desktops
Amarok/Manual/Various/AmarokOnOtherPlatforms/Windows
Amarok/Manual/Various/AmarokOnOtherPlatforms/OSX
Amarok/Manual/Various/TroubleshootingAndCommonProblems
Amarok/Manual/Various/FAQ
Amarok/Manual/References
Amarok/Manual/References/MenuAndCommandReference
Amarok/Manual/References/MenuAndCommandReference/AmarokMenu
Amarok/Manual/References/MenuAndCommandReference/ViewMenu
Amarok/Manual/References/MenuAndCommandReference/Playlist
Amarok/Manual/References/MenuAndCommandReference/Tools
Amarok/Manual/References/MenuAndCommandReference/Settings
Amarok/Manual/References/MenuAndCommandReference/Help
Amarok/Manual/References/KeybindingReference
Amarok/Manual/References/KeybindingReference/GlobalShortcuts
Amarok/Manual/References/KeybindingReference/AmarokShortcuts
Amarok/Manual/References/Credits and License

Astuce

Vous pouvez obtenir la liste complète des pages pour votre application à l'aide du 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. Réordonnez la liste en fonction de la table des matières de votre manuel.


  • Incluez la liste des pages dans le champ texte plus grand .
  • Cliquez sur Exporter.
Export des pages du manuel Amarok
  • Sauvegardez le fichier. Dans ce qui suit, le fichier sauvegardé sera appelé Manual.xml .

Conversion

  • Installer le package Subversion pour votre système .
  • Extrayez 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 répertooire du script.
  • Ajouter une ligne contenant 
    144.76.227.197 userbase.kde.org
    dans le fichier /etc/hosts (il vous faudra des droits root pour cela - à ne faire qu'une fois -).
  • 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 si la conversion s'est bien déroulée : 
    checkXML index.docbook
  • Corrigez les erreurs (mieux sur les pages UserBase).
  • Convertissez le docbook en HTML: 
    meinproc4 index.docbook
  • Vérifiez les pages HTML (toutes les images doivent être visibles, les liens ne doivent pas vers des pages 404).
  • Remplacer les grandes images par des vignettes en utilisant convert de 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.

Updating Your DocBook from UserBase

To update your converted docbook please use the following procedure:

  • Re-export XML from UserBase. See Export section.
  • Use the script to update the content (headers with abstract and keywords and footer will be kept): 
    python wiki2docbook.py -r index.docbook Manual.xml
  • Check the docbook, rename the file into index.docbook and commit it with screenshots into your repository.

Convertir le DocBook vers un autre format

Convertir en PDF

Usually, there is no need to convert DocBook manually. You can download the converted PDFs from KDE Documentation site.

Should you need additional customization please do as follows:

  • Make sure that you have some LaTeX distribution installed (usually, TeXLive).
  • Create the following script file (named buildpdf.sh) in your DocBook directory:
#!/bin/bash

export SGML_CATALOG_FILES=/usr/share/sgml/docbook/sqml-dtd-4.2/catalog:/usr/share/apps/ksgmltools2/customization/catalog.xml:/usr/share/sgml/docbook/xml-dtd-4.2/docbook

# add -d to command below to keep the /tmp folder, so you can examine the generated tex.
./dblatex-cvs-install/bin/dblatex -d -b pdftex --style \
	kdestyle\
	-o $(pwd | awk -F/ '{ print $NF }').pdf \
	-P latex.output.revhistory=0  -P newtbl.use=1 \
	-P imagedata.default.scale=pagebound \
	-P literal.width.ignore=1 \
	-I $KDEDIR/share/doc/HTML/en/ \
	-X \
        $1
  • Download KDE styles:
git clone git://anongit.kde.org/websites/docs-kde-org.git
  • Tweak dblatex-cvs-install/bin/dblatex in like this
#!/bin/sh

TEXINPUTS=:/path/to/your/dblatex-cvs-install/share/dblatex/latex//:$TEXINPUTS
export TEXINPUTS

/path/to/your/dblatex-cvs-install/share/dblatex/scripts/dblatex  $*

(Change /path/to/your/ as appropriate)

  • Copy KDE styles (/dblatex-cvs-install/share/dblatex/latex/contrib/) to some TeX dir where it can be found by LaTeX installation (I have copied them to /usr/share/texmf-dist/tex/latex/kde).
  • Update paths with mktexlsr from root.
  • Run ./buildpdf.sh index.docbook. This should create ready-to-use PDF file for you. You can stop on this step if you do not want to tweak it.
  • Copy all files from /tmp/tpb-your_user-digits to the work directory.
  • Customize and edit tex file in Kile as appropriate.
  • Compile PDF file with Alt + 6.

Conversion en EPUB

  • Make sure that Calibre is installed in your system.
  • Convert your DocBook into HTML first. Use meinproc4 index.docbook for this.
  • Start Calibre and choose Add books.
  • Select index.html in your DocBook folder. Wait until the book is loaded.
  • Choisissez Convertir les livres.
  • Remplissez les champs métadata de manière adéquate.
Calibre conversion configuration page.
  • Press OK and wait until the work is done.
  • Copiez le livre de ~/Calibre Library vers votre lecteur de livres électroniques.
Retrieved from "https://userbase.kde.org/index.php?title=How_To_Convert_a_UserBase_Manual_to_Docbook/fr&oldid=394903"