How To Convert a UserBase Manual to Docbook/fr: Difference between revisions

From KDE TechBase
(Created page with "Comment convertir un manuel UserBase en Docbook")
 
(Created page with "* Copiez <tt>index.docbook</tt> et les images dans votre répertoire <tt>/doc</tt> et validez les sur le dépôt. File:K3b_docs.png|350px|center|thumb|Documents K3b de UserB...")
 
(44 intermediate revisions by the same user not shown)
Line 1: Line 1:
<languages />
<languages />
== Preface ==  
== Préface ==  


The current process is not polished, the script code is ugly, not intelligent enough, etc.. The only excuse is that it works somehow {{Smiley}}.
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 {{Smiley}}.


If you want to improve the process, have good Python skills, and know the docbook authoring principles, you can improve the procedure.  Please contact [[User_talk:Yurchor|Yurchor]] if you are able to help.
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 [[User_talk:Yurchor|Yurchor]] si vous vous sentez prêt à apporter votre aide.


== Preparing Pages for Conversion ==  
== Préparation des pages pour Conversion ==  


* Check that the pages of your manual follow the [[Special:myLanguage/Tasks_and_Tools|author guidelines of UserBase]] and [[Special:myLanguage/Typographical_Guidelines|typographical guidelines]].
* Vérifiez que les pages de votre manuel suivent les [[Special:myLanguage/Tasks_and_Tools|instructions pour les auteurs de UserBase]] et les [[Special:myLanguage/Typographical_Guidelines|instructions typographiques]].


* Check if every page has its header according to the level of this page in table of contents.
* Vérifiez dans la table des matières, que chaque page a son titre aligné avec son niveau respectif d'indentation.


:{|
:{|
|+Reference table
|+Tableau de référence
|-
|-
! UserBase
! UserBase
Line 33: Line 33:
| ======Section======
| ======Section======
| <sect4>
| <sect4>
| ''Avoid using this last level if possible''
| ''Evitez  si possible d'utiliser ce dernier niveau''
|}
|}


* Check if all table cells have space after the pipe character. This rule conforms with [http://en.wikipedia.org/wiki/Help:Table traditional wiki formatting].
* Vérifiez que toutes les cellules ont un espace avant la barre verticale '|' . Cette règle est conforme au [http://en.wikipedia.org/wiki/Help:Table formatage wiki standard].


* Make application name formatting consistent (avoid using '''Amarok'''s, do use '''Amarok's''').
* Rétablisser la cohérence du nom de l'application (évitez d'utiliser '''Amarok'''s, mais adoptez plutôt '''Amarok's''').


* Ensure that ''all'' images are in PNG format.
* Vérifiez que ''toutes'' les images sont au format PNG.


* Remove all non-printable characters from image names.
* Supprimez tous les caractères non imprimables des noms d'images.


===Export===  
=== Exporter ===  


* Prepare the page list (strip from UserBase addresses <nowiki>http://userbase.kde.org</nowiki>). Example for '''Amarok''':
* Préparez la liste des pages (extraire des adresses UserBase <nowiki>http://userbase.kde.org</nowiki>). Exemple pour '''Amarok''' :


{{Input|1=Amarok
{{Input|1=Amarok
Line 101: Line 101:
Amarok/Manual/Credits_and_License}}
Amarok/Manual/Credits_and_License}}


{{Tip|1=You can obtain the full list of pages for your application with the following script:<!--}}-->
{{Tip/fr|1=Vous pouvez obtenir la liste complète des pages pour votre application avec le script suivant :<!--}}-->


{{Input|1=<nowiki><DPL>
{{Input|1=<nowiki><DPL>
Line 111: Line 111:
</DPL></nowiki>}}
</DPL></nowiki>}}


<!--{{-->Replace '''''Amarok''''' with the name of your application, put it on your user page, and click on <menuchoice>Preview</menuchoice>. Rearrange the list according to the ToC of your manual.
<!--{{-->Remplacez '''''Amarok''''' par le nom de votre application, mettez-le sur votre page utilisateur, et cliquez sur <menuchoice>Aperçu</menuchoice> (Preview). Réarrangez la liste en fonction de la table des matières de votre manuel.
}}
}}


* Go to the [[Special:Export|export page]].
* Allez sur la [[Special:Export|page d'exportation]].


* Paste the page list into the <menuchoice>bigger</menuchoice> text field.
* Collez la liste des pages dans le champ texte <menuchoice>bigger</menuchoice>.


* Click on <menuchoice>Export</menuchoice>.
* Cliquez sur <menuchoice>Export</menuchoice>.
[[File:XML_export.png|350px|center|thumb|Export of Amarok manual pages]]
[[File:XML_export.png|350px|center|thumb|Exporter les pages du manuel Amarok]]


* Save the file. The saved file will be called <tt>Manual.xml</tt> in what follows.
* Enregistrez le fichier. Dans ce qui suit, il s'appellera <tt>Manual.xml</tt> .


===Conversion===  
=== Conversion ===  


* Install Subversion package for your system.
* Installez le paquet Subversion sur votre système.


* Checkout the latest version of conversion script: {{Input|1=svn checkout --depth=files <nowiki>svn://anonsvn.kde.org/home/kde/branches/work/doc/</nowiki>}}
* Vérifiez la dernière version du script de conversion : {{Input|1=svn checkout --depth=files <nowiki>svn://anonsvn.kde.org/home/kde/branches/work/doc/</nowiki>}}


* Copy <tt>Manual.xml</tt> to the script folder.
* Copier <code>Manual.xml</code> dans le dossier du script.


* Run {{Input|1=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 {{Input|1=python wiki2docbook.py -s Manual.xml}} if you need not to download images.
* Exécutez {{Input|1=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 {{Input|1=python wiki2docbook.py -s Manual.xml}} si vous n'avez pas besoin de télécharger les images.


===Post-processing===  
=== Post traitement ===  


* Rename <tt>Manual.xml.docbook</tt> to <tt>index.docbook</tt>.
* Renommer <code>Manual.xml.docbook</code> en  <code>index.docbook</code>.


* Check if conversion was done correctly: {{Input|1=checkXML index.docbook}}
* Vérifiez que la conversion s'est bien réalisée : {{Input|1=checkXML index.docbook}}


* Fix the errors (better on UserBase pages).
* Corrigez les erreurs (mieux sur les pages UserBase).


* Convert docbook to HTML: {{Input|1=meinproc4 index.docbook}}
* Convertir docbook en HTML: {{Input|1=meinproc4 index.docbook}}


* Check HTML pages (all images should be visible, links should not lead to 404-pages).
* Vérifiez les pages HTML (toutes les images doivent être visibles et les liens ne doivent pas aboutir sur les pages 404).


* Replace big images by thumbnails using '''convert''' from '''ImageMagick'''
* Remplacez les grandes images par des vignettes en utilisant '''convert''' de '''ImageMagick'''


* Fix links in docbook, so they lead to docbook section, not UserBase pages.
* Corrigez les liens dans docbook, pour qu'ils pointent vers des sections docbook, et non pas des pages de UserBase.


* Fix application name according to KDE entity list.
* Initialisez le nom de l'application d'après la liste des entités KDE.


* Copy <tt>index.docbook</tt> and images to your <tt>/doc</tt> folder and commit them to repository.
* Copiez <tt>index.docbook</tt> et les images dans votre répertoire <tt>/doc</tt> et validez les sur le dépôt.
[[File:K3b_docs.png|350px|center|thumb|K3b docs on UserBase in Opera and converted page in Konqueror.]]
[[File:K3b_docs.png|350px|center|thumb|Documents K3b de UserBase dans Opera et page convertie dans Konqueror.]]


[[Category:Translator_Help]]
[[Category:Translator_Help]]

Latest revision as of 09:57, 19 May 2019

Other languages:

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.
Retrieved from "https://techbase.kde.org/index.php?title=How_To_Convert_a_UserBase_Manual_to_Docbook/fr&oldid=101977"