Com convertir una manual de UserBase a Docbook

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 consistent (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
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

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.

• Aneu a la pàgina Exporta les pàgines.

• 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 capture 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.

Post-processament

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

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