Com convertir una manual de UserBase a Docbook
Outdated translations are marked like this.
Prefaci
El procediment actual no està polit, el codi de l'script és lleig, no prou intel·ligent, etc. L'única excusa és que funciona d'alguna manera .
Si voleu millorar el procediment, teniu bones habilitats amb Python, i coneixeu els principis d'autoria de docbook, podeu millorar el procediment. Si us plau, poseu-vos en contacte amb Yurchor si sou capaç d'ajudar.
Preparar les pàgines per a la conversió
- Assegureu-vos que les pàgines del vostre manual segueixen les directrius d'autor de UserBase i les directrius tipogràfiques.
- Comproveu si cada pàgina conté la seva capçalera en funció al nivell d'aquesta pàgina a la taula de continguts.
Taula de referència UserBase Docbook Comentari ==Secció== <capítol> ===Secció=== <secció1> ====Secció==== <secció2> =====Secció===== <secció3> ======Secció====== <secció4> No utilitzeu aquest últim nivell, si és posible.
- Comproveu si totes les cel tenen espai després del caràcter de canonada. Aquesta norma s'ajusta al format wiki tradicional.
- Feu que el nom de l'aplicació tingui un format compatible (eviteu l'ús de Amaroks, feu Amarok's).
- Assegureu-vos que totes les imatges estan en format PNG.
- Elimineu tots els caràcters no imprimibles dels noms d'imatge.
Exportar
- Prepareu la llista de pàgines (elimineu les adreces de UserBase http://userbase.kde.org). Exemple per a 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
Consell
Podeu obtenir la llista completa de les pàgines per a la vostra aplicació amb el següent script:
<DPL> nottitlematch = %/__|%/zh-%|%pt-%|%(%) titlematch = Appname/Manual% namespace = columns = 1 format = ,\n* [[%PAGE%|%TITLE%]],, </DPL>Substituïu Amarok amb el nom de la vostra aplicació, poseu-ho a la vostra pàgina d'usuari, i feu clic a . Es reordenarà la llista d'acord amb l'índex de continguts del manual.
Note
If You are working with the Amarok manual be aware that it does not fully conform to manual page naming conventions. You can use
titlematch = Amarok/Manual%|Amarok/QuickStartGuide%(Note: No space characters in title pattern!)
- Aneu a la pàgina Exporta les pàgines.
- Enganxeu la llista de pàgines al camp de text .
- Feu clic a .
- Deseu el fitxer. El fitxer desat s'anomenarà Manual.xml en el que segueix.
Convertir
- Instal·leu el paquet Subversion pel vostre sistema.
- Obteniu l'última versió de l'script de la conversió:
svn checkout --depth=files svn://anonsvn.kde.org/home/kde/branches/work/doc/
- Copieu Manual.xml a la carpeta de l'script.
- Add a line containing
144.76.227.197 userbase.kde.org
to the file /etc/hosts . (You will need root privileges for this. You only need to do this once.)
- Executeu
python wiki2docbook.py Manual.xml
si voleu descarregar totes les captures de pantalla (es necessita algun temps per a descarregar totes les imatges des de UserBase, grep i wget han d'estar instal·lats), opython wiki2docbook.py -s Manual.xml
si no necessiteu descarregar les imatges.
Post-processament
- Canvieu el nom de Manual.xml.docbook a index.docbook.
- Comproveu si la conversió s'ha realitzat correctament:
checkXML index.docbook
- Corregiu els errors (millor sobre les pàgines de UserBase).
- Convertir docbook a HTML:
meinproc4 index.docbook
- Comproveu les pàgines HTML (totes les imatges han de ser visibles, els enllaços no han de donar lloc a pàgines 404).
- Substituïu les imatges grans per miniatures usant convert de ImageMagick.
- Arrangeu els enllaços a docbook, de manera que portin a la secció de docbook, no pàgines de UserBase.
- Arrangeu el nom de l'aplicació d'acord amb la llista d'entitats del KDE.
- Copieu index.docbook i les imatges a la vostra carpeta /doc i publiqueu-ho (commit) al repositori.
Actualitzar els DocBook des de UserBase
Per actualitzar els vostres docbook convertits si us plau utilitzeu el següent procediment:
- Feu una exportació XML des de UserBase. Veure la secció Exportar.
- Utilitzeu l'script per actualitzar el contingut (les capçaleres de resum, paraules clau i el peu es mantindrà):
python wiki2docbook.py -r index.docbook Manual.xml
- Comproveu el docbook, reanomeneu el fitxer a index.docbook i publiqueu-lo amb les captures de pantalla al vostre repositori.
Convertir els DocBook a un altre format
Convertir-los a PDF
En general, no hi ha necessitat de convertir els DocBook de forma manual. Podeu descarregar el PDF convertit des del lloc de documentació del KDE.
En cas de necessitar cap personalització addicional, feu el següent:
- Assegureu-vos que teniu alguna distribució de LaTeX instal·lada (normalment, TeXLive).
- Creeu el següent script (anomenat buildpdf.sh) al directori dels 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
- Download KDE styles:
git clone git://anongit.kde.org/websites/docs-kde-org.git
- Ajusteu dblatex-cvs-install/bin/dblatex com segueix
#!/bin/sh TEXINPUTS=:/camí/al/vostre/dblatex-cvs-install/share/dblatex/latex//:$TEXINPUTS export TEXINPUTS /camí/al/vostre/dblatex-cvs-install/share/dblatex/scripts/dblatex $*
(Canvieu /camí/al/vostre/ segons el cas).
- Copieu els estils KDE (/dblatex-cvs-install/share/dblatex/latex/contrib/) a algun directori TeX on es trobi la instal·lació de LaTeX (jo els he copiat a /usr/share/texmf-dist/tex/latex/kde).
- Actualitzeu els camins amb
mktexlsr
des de l'arrel.
- 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.
- Copieu tots els fitxers des de /tmp/tpb-usuari-digits al directori de treball.
- Personalitzeu i editeu el fitxer tex en Kile, segons correspongui.
- Compileu el fitxer PDF amb Alt + 6.
Convertir-los a EPUB
- Assegureu-vos que Calibre està instal·lat al vostre sistema.
- Convertiu en primer lloc els vostres DocBook a HTML. Per a fer-ho utilitzeu
meinproc4 index.docbook
.
- Inicieu el Calibre i escolliu .
- Seleccioneu index.html a la carpeta de DocBook. Espereu fins que el llibre estigui carregat.
- Escolliu .
- Ompliu els camps de metadades segons correspongui.
- Premeu i espereu fins que el treball estigui fet.
- Copieu el llibre des de la ~/Biblioteca del calibre al vostre lector de llibres electrònics.