Hvordan man konverterer en UserBase manual til 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 100% complete.

    Forord

    Den aktuelle proces er ikke finslebet, skriptkoden er grim og ikke intelligent nok osv. Den eneste undskyldning er, at det kræver noget arbejde .

    Hvis du ønsker at forbedre processen, er vel bekendt med Python og kender principperne for at skrive docbook-dokumenter, så kan du forbedre proceduren. Kontakt Yurchor, hvis du kan hjælpe.

    Forbered en side for konvertering

    • Tjek, at hver side har en overskrift svarende til sidens niveau i indholdsfortegnelsen.
    Referencetabel
    UserBase Docbook Kommentar
    ==Section== <chapter>
    ===Section=== <sect1>
    ====Section==== <sect2>
    =====Section===== <sect3>
    ======Section====== <sect4> Undgå så vidt muligt at bruge dette sidste niveau
    • Sørg for, at formatteringen af programnavne er konsistent (undgå at bruge Amaroks, brug Amarok's — i danske oversættelser skal apostroffen dog normalt ikke være der).
    • Sørg for, at alle billeder er i PNG-format.
    • Fjern alle ikke-printbare tegn fra billednavne.

    Eksport

    • Forbered sidelisten (fjern UserBase-adressedelen http://userbase.kde.org). Eksempel for 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

    Tip

    Du kan få din manuals fulde sideliste med følgende skript:
    <DPL>
      nottitlematch = %/__|%/zh-%|%pt-%|%(%)
      titlematch = Appname/Manual%
      namespace = 
      columns = 1
      format = ,\n* [[%PAGE%|%TITLE%]],,
    </DPL>
    Erstat Amarok med navnet på dit program, Skriv det ind på din brugerside og klik på Forhåndsvisning. Arrangér listen på samme måde som i manualens indholdsfortegnelse.


    Note

    Hvis du arbejder på Amarok-manualen, så vær opmærksom på, at den ikke følger konventionerne for navngivning af sider helt. Du kan bruge
    titlematch = Amarok/Manual%|Amarok/QuickStartGuide%
    (Bemærk: Ingen mellemrumstegn i titelmønsteret!)


    • Kopiér sidelisten ind i det store tekstfelt.
    • Klik på Eksporter.
    Eksport af Amaroks manualsider
    • Gem filen. Den gemte fil vil blive kaldt Manual.xml i det følgende.

    Konvertering

    • Installér pakken Subversion på dit system.
    • For at udtjekke den seneste udgave af konverteringsskriptet kører du:
      svn checkout --depth=files svn://anonsvn.kde.org/home/kde/branches/work/doc/
    • Kopiér Manual.xml til skriptmappen.
    • Kør
      python wiki2docbook.py Manual.xml
      hvis du ønsker at downloade alle skærmbilleder (det tager nogen tid at hente alle billeder fra UserBase; du skal have grep og wget installeret), eller
      python wiki2docbook.py -s Manual.xml
      hvis du ikke behøver at downloade billederne.

    Advarsel

    På et tidspunkt blev det nædvendigt at føje en linje med
    144.76.227.197 userbase.kde.org
    til /etc/hosts for at kunne tilgå UserBase fra script'et. Dette er ikke længere tilfældet. Hvis du allerede har føjet sådan en linje til din /ext/hosts, så bør du fjerne den igen.


    Efterbehandling

    • Omdøb Manual.xml.docbook til index.docbook.
    • Tjek, at konverteringen er foretaget korrekt:
      checkXML index.docbook
    • Ret fejlene (det er bedst at gøre det på UserBase siderne).
    • Konvertér docbook til HTML:
      meinproc4 index.docbook
    • Tjek HTML-siderne (alle billeder skal kunne ses, links må ikke føre til 404-sider).
    • Erstat store billeder med miniaturer ved at bruge convert fra ImageMagic
    • Ret links i docbook'en, sådan at de fører til afsnit i docbook'en, ikke til UserBase-sider.
    • Ret programnavnet så det stemmer overens med KDE's "entity list".
    • Kopiér index.docbook og billeder til din /doc-mappe og commit dem til arkivet.
    Dokumentation for K3b på UserBase i Opera og den konverterede side i Konqueror.

    Opdatering af din DocBook fra UserBase

    For at opdatere din konverterede docbook skal du følge denne procedure:

    • Geneksportér XML fra UserBAse. Se afsnittet Eksport.
    • Brug scriptet til at opdatere indholdet (headere med sammenfatning, nøgleord og sidefod vil blive bevaret):
      python wiki2docbook.py -r index.docbook Manual.xml
    • Check dockbook'en, omdøb filen til index.docbooc og commit dem med skærmbilleder til dit arkiv.

    Konvertér DocBook til andre formater

    Konvertering til PDF

    Det er som regel ikke nødvendigt at konvertete DocBook manuelt. Du kan downloade de konverterede PDF'er fra KDE's dokumentationssite

    Skulle du have brug for yderligere tilpasning, så gør således:

    • Sørg for at du har en LaTeX-distribution installeret (som regel TeXLive).
    • Lav følgende scriptfil (med navnet buildpdm.sh) i din DocBook-mappe:
    #!/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-stilene:
    git clone git://anongit.kde.org/websites/docs-kde-org.git
    • Tilpas dblatex-cvs-install/bin/dblatex således
    #!/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  $*
    

    (Ændr /path/to/your/ passende)

    • Kopiér KDE-stilene (/dblatex-cvs-install/share/dblatex/latex/contrib/) til en TeX-mappe, hvor den kan findes af LaTeX-installationen (jeg har kopieret dem til /usr/share/texmf-dist/tex/latex/kde).
    • Opdatér stierne med mktexlsr fra root.
    • Kør ./buildpdf.sh index.docbook. Dette skulle give dig en PDF fil klar til brug.
    • Kopiér alle filer fra /tmp/tpb-din_bruger-cifre til arbejdsmappen.
    • Tilpas og redigér tex-filen med Kile efter behov.
    • Kompilér PDF-filen med Alt + 6.

    Konvertering til EPUB

    • Sørg for at Calibre er installeret på din maskine.
    • Konvertér først din DocBook til HTML. Brug meinproc4 index.docbook til dette.
    • Start Calibre og vælg Tilføj bøger.
    • Vælg index.html i din DocBook-mappe. Vent til bogen er indlæst.
    • Vælg Konvertér bøger.
    • Udfyld metadata-felterne.
    Indstillingsdialog til Calibre-konvertering.
    • Klik OK og vent til arbejdet er gjort.
    • Kopiér bogen fra ~/Calibre Library på din ebogslæser.