Com convertir un manual de UserBase a Docbook

    From KDE UserBase Wiki
    This page is a translated version of the page How To Convert a UserBase Manual to Docbook and the translation is 94% complete.
    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ó

    • 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-%|%(%)
      titlematch = Amarok%
      namespace = Main
      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 Vista prèvia. 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!)


    • Enganxeu la llista de pàgines al camp de text més gran.
    • Feu clic a Exporta.
    S'exportaran les pàgines de manual de Amarok.
    • 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.
    • 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), o
      python wiki2docbook.py -s Manual.xml
      si no necessiteu descarregar les imatges.

    Warning

    At some point in the past it became necessary to add a line containing
    144.76.227.197 userbase.kde.org
    to /etc/hosts in order to access UserBase from the script. This is no longer the case. If you already added such a line to your /etc/hosts, then you should remove it again.


    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.
    La documentació de K3b a UserBase en Opera i la pàgina convertida en el Konqueror.

    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
    
    • Descarregueu els estils de KDE:
    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.
    • Executeu ./buildpdf.sh index.docbook.
    • 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 Afegeix llibres.
    • Seleccioneu index.html a la carpeta de DocBook. Espereu fins que el llibre estigui carregat.
    • Escolliu Converteix llibres.
    • Ompliu els camps de metadades segons correspongui.
    Pàgina de configuració de la conversió a Calibre.
    • 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.