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 alla 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
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/AdvancedFeatures
Amarok/Manual/AdvancedFeatures/CollectionScanning
Amarok/Manual/AdvancedFeatures/CoverManager
Amarok/Manual/AdvancedFeatures/DynamicPlaylists
Amarok/Manual/AdvancedFeatures/AutomaticPlaylistGenerator
Amarok/Manual/AdvancedFeatures/ExternalDatabase
Amarok/Manual/AdvancedFeatures/AFT
Amarok/Manual/AdvancedFeatures/Moodbar
Amarok/Manual/AdvancedFeatures/WorkingWithMediaDevices
Amarok/Manual/AdvancedFeatures/SavedPlaylists
Amarok/Manual/AdvancedFeatures/PlaylistFiltering
Amarok/Manual/AdvancedFeatures/QueueManager
Amarok/Manual/AdvancedFeatures/SearchInCollection
Amarok/Manual/AdvancedFeatures/TagEditor
Amarok/Manual/AdvancedFeatures/OrganizeCollection
Amarok/Manual/AdvancedFeatures/Transcoding
Amarok/Manual/AdvancedFeatures/ScriptManager
Amarok/Manual/AdvancedFeatures/RemoteCollections
Amarok/Manual/AdvancedFeatures/RemoteCollections/Ampache
Amarok/Manual/AdvancedFeatures/RemoteCollections/DAAP
Amarok/Manual/AdvancedFeatures/RemoteCollections/Samba
Amarok/Manual/AdvancedFeatures/RemoteCollections/UPnP
Amarok/Manual/MenuAndCommandReference/AmarokMenu
Amarok/Manual/MenuAndCommandReference/ViewMenu
Amarok/Manual/MenuAndCommandReference/Playlist
Amarok/Manual/MenuAndCommandReference/Tools
Amarok/Manual/MenuAndCommandReference/Settings
Amarok/Manual/MenuAndCommandReference/Help
Amarok/Manual/KeybindingReference
Amarok/Manual/KeybindingReference/GlobalShortcuts
Amarok/Manual/KeybindingReference/AmarokShortcuts
Amarok/Manual/TroubleshootingAndCommonProblems
Amarok/Manual/AmarokOnOtherPlatforms/Non-KDE Desktops
Amarok/Manual/AmarokOnOtherPlatforms/Windows
Amarok/Manual/AmarokOnOtherPlatforms/OSX
Amarok/Manual/FAQ
Amarok/Manual/Credits_and_License

Tip

Du kan få din manuals fulde sideliste med følgende skript:

<DPL>
  nottitlematch = %/__|%/zh-%|%(%)
  titlematch = Amarok%
  namespace = Main
  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.

• Gå til eksportsiden.

• 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 (et 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.

Efterbehandling

• Rename Manual.xml.docbook to index.docbook.

• Check if conversion was done correctly:

  checkXML index.docbook

• Fix the errors (better on UserBase pages).

• Convert docbook to HTML:

  meinproc4 index.docbook

• Check HTML pages (all images should be visible, links should not lead to 404-pages).

• Replace big images by thumbnails using convert from ImageMagick

• Fix links in docbook, so they lead to docbook section, not UserBase pages.

• Fix application name according to KDE entity list.

• Copy index.docbook and images to your /doc folder and commit them to repository.

K3b docs on UserBase in Opera and converted page in Konqueror.