How To Convert a UserBase Manual to Docbook/fr: Difference between revisions
ChristianW (talk | contribs) No edit summary |
ChristianW (talk | contribs) (Created page with "{{Warning/fr|1=A un certain moment du passé, il fût nécessaire d'ajouter une ligne contenant <br /><code>144.76.227.197 userbase.kde.org</code><br /> à <tt>/etc/hosts</tt...") |
||
| (2 intermediate revisions by 2 users not shown) | |||
| Line 122: | Line 122: | ||
}} | }} | ||
{{Note|1= | {{Note/fr|1=Si vous travaillez avec la manuel Amarok, soyez conscient qu'il ne se conforme pas complètement aux conventions de nommage des pages du manuel. Vous pouvez utiliser | ||
{{Input|1= titlematch = Amarok/Manual%{{!}}Amarok/QuickStartGuide%}} | {{Input/fr|1= titlematch = Amarok/Manual%{{!}}Amarok/QuickStartGuide%}} | ||
(Note: | (Note: aucun espace dans l'expression du titre!) | ||
}} | }} | ||
| Line 144: | Line 144: | ||
* Copier <tt>Manual.xml</tt> dans le répertooire du script. | * Copier <tt>Manual.xml</tt> dans le répertooire du script. | ||
* | * Lancez {{Input/fr|1=python wiki2docbook.py Manual.xml}} si vous voulez télécharger toutes les captures d'écran (cela prend du temps de ramener toutes les images de UserBase, grep et wget doivent être installés), ou {{Input/fr|1=python wiki2docbook.py -s Manual.xml}} si vous avez seulement besoin de ramener les images. | ||
{{Warning/fr|1=A un certain moment du passé, il fût nécessaire d'ajouter une ligne contenant <br /><code>144.76.227.197 userbase.kde.org</code><br /> à <tt>/etc/hosts</tt> pour accéder à UserBase à partir de scripts. Ce n'est plus le cas. Si vous avez déjà ajouté une telle ligne à votre <tt>/etc/hosts</tt>, alors il faudra l'enlever de nouveau.}} | |||
=== Post-traitement === | === Post-traitement === | ||
| Line 190: | Line 190: | ||
* Créez le fichier script suivant (nommé <tt>buildpdf.sh</tt>) dans votre répertoire DocBook : | * Créez le fichier script suivant (nommé <tt>buildpdf.sh</tt>) dans votre répertoire DocBook : | ||
{{Input|1= | |||
<syntaxhighlight lang="bash">#!/bin/bash | <syntaxhighlight lang="bash">#!/bin/bash | ||
export SGML_CATALOG_FILES=/usr/share/sgml/docbook/sqml-dtd-4. | export SGML_CATALOG_FILES=/usr/share/sgml/docbook/sqml-dtd-4.5/catalog:/usr/share/kf5/kdoctools/customization/catalog.xml:/usr/share/sgml/docbook/xml-dtd-4.5/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 \ | ./dblatex-cvs-install/bin/dblatex -d -b pdftex --style \ | ||
kdestyle\ | kdestyle\ | ||
| Line 205: | Line 203: | ||
-I $KDEDIR/share/doc/HTML/en/ \ | -I $KDEDIR/share/doc/HTML/en/ \ | ||
-X \ | -X \ | ||
$1</syntaxhighlight>}} | $1</syntaxhighlight>}} | ||
* Téléchargez les styles KDE : | * Téléchargez les styles KDE : | ||
{{Input/fr|1=<nowiki>git clone git://anongit.kde.org/websites/docs-kde-org.git</nowiki>}} | {{Input/fr|1=<nowiki>git clone git://anongit.kde.org/websites/docs-kde-org.git</nowiki>}} | ||
Latest revision as of 16:40, 24 October 2019
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 que les pages de votre manuel respectent bien les directives des contributeurs de UserBase ainsi que les règles typographiques.
- 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-%|%pt-%|%(%) titlematch = Appname/Manual% namespace = columns = 1 format = ,\n* [[%PAGE%|%TITLE%]],, </DPL>
Remplacez Amarok par le nom de votre application, mettez le sur votre page utilisateur, et cliquez sur
. Réordonnez la liste en fonction de la table des matières de votre manuel.
Remarque
Si vous travaillez avec la manuel Amarok, soyez conscient qu'il ne se conforme pas complètement aux conventions de nommage des pages du manuel. Vous pouvez utiliser
titlematch = Amarok/Manual%|Amarok/QuickStartGuide%(Note: aucun espace dans l'expression du titre!)
- Allez à la page export.
- Incluez la liste des pages dans le champ texte .
- Cliquez sur .
- 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.
- Lancez
python wiki2docbook.py Manual.xml
si vous voulez télécharger toutes les captures d'écran (cela prend du temps de ramener toutes les images de UserBase, grep et wget doivent être installés), oupython wiki2docbook.py -s Manual.xml
si vous avez seulement besoin de ramener les images.
Attention
A un certain moment du passé, il fût nécessaire d'ajouter une ligne contenant
à /etc/hosts pour accéder à UserBase à partir de scripts. Ce n'est plus le cas. Si vous avez déjà ajouté une telle ligne à votre /etc/hosts, alors il faudra l'enlever de nouveau.
144.76.227.197 userbase.kde.orgà /etc/hosts pour accéder à UserBase à partir de scripts. Ce n'est plus le cas. Si vous avez déjà ajouté une telle ligne à votre /etc/hosts, alors il faudra l'enlever de nouveau.
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
- Corriger les liens dans le docbook, de sorte à ce qu'ils conduisent vers des sections du docbook, et non pas vers des pages de UserBase.
- Corriger le nom de l'application en fonction de la liste des entités KDE.
- Copiez index.docbook et les images dans votre répertoire /doc et validez les dans le dépôt.
Mettre à jour votre DocBook à partir de UserBase
Pour mettre à jour votre docbook converti, veuillez utiliser la procédure suivante :
- Réexportez le XML de UserBase. Voir la section Export .
- Utilisez le script pour mettre à jour le contenu (les entêtes avec le résumé, les mots-clé et les pieds de page seront conservés) :
python wiki2docbook.py -r index.docbook Manual.xml
- Vérifiez le docbook, renommez le fichier en index.docbook et validez le avec les captures d'écran dans votre dépôt.
Convertir le DocBook vers un autre format
Convertir en PDF
Habituellement, il n'y a pas besoin de convertir le DocBook manuellement. Vous pouvez télécharger les PDF convertis à partir du site de Documentation KDE .
Si vous avez besoin d'adaptations supplémentaires, voici comment faire :
- Assurez-vous qu'il y ait une distribution LaTeX d'installée (d'ordinaire, TeXLive).
- Créez le fichier script suivant (nommé buildpdf.sh) dans votre répertoire DocBook :
#!/bin/bash export SGML_CATALOG_FILES=/usr/share/sgml/docbook/sqml-dtd-4.5/catalog:/usr/share/kf5/kdoctools/customization/catalog.xml:/usr/share/sgml/docbook/xml-dtd-4.5/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
- Téléchargez les styles KDE :
git clone git://anongit.kde.org/websites/docs-kde-org.git
- Ajustez dblatex-cvs-install/bin/dblatex ainsi
#!/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 $*
(adaptez /path/to/your/ à la réalité)
- Copiez les styles KDE (/dblatex-cvs-install/share/dblatex/latex/contrib/) vers un répertoire TeX quelconque où il pourra être vu par l'installation de LaTeX (personnellement, je les ai copiés dans /usr/share/texmf-dist/tex/latex/kde).
- Mettez à jour les chemins avec
mktexlsrà partir de la racine.
- Lancez
./buildpdf.sh index.docbook. Ceci doit créer pour vous, un fichier PDF prêt à l'usage. Vous pouvez arrêter à cette étape si vous ne voulez pas le refaire.
- Copiez tous les fichier de /tmp/tpb-nom_utilisateur-chiffres vers le répertoire de travail.
- Adaptez et modifiez le fichier tex dans Kile de manière adéquate.
- Compilez le fichier PDF avec Alt + 6.
Conversion en EPUB
- Assurez-vous que Calibre est installé sur votre système.
- Convertissez votre DocBook en HTML d'abord. Utilisez
meinproc4 index.docbookpour cela.
- Démarrez Calibre et choisissez .
- Choisissez index.html dans votre répertoire DocBook . Attendez le chargement du livre.
- Choisissez .
- Remplissez les champs métadata de manière adéquate.
- Cliquez sur et attendez la fin d'exécution.
- Copiez le livre de ~/Calibre Library vers votre lecteur de livres électroniques.