Hvordan man konverterer en UserBase manual til Docbook
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 manualsiden følger UserBases retningslinjer for forfattere og de typograpfiske retningslinjer.
- 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
- Tjek, at alle tabelceller har mellemrum efter 'pipe'-tegnet. Denne regel er i overensstemmelse med traditionel wiki-formattering.
- 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å . 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!)
- Gå til eksportsiden.
- Kopiér sidelisten ind i det tekstfelt.
- Klik på .
- 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), ellerpython 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
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.
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.
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 .
- Vælg index.html i din DocBook-mappe. Vent til bogen er indlæst.
- Vælg .
- Udfyld metadata-felterne.
- Klik og vent til arbejdet er gjort.
- Kopiér bogen fra ~/Calibre Library på din ebogslæser.