Com convertir un manual de UserBase a Docbook

Other languages:

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.

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/

Copy Manual.xml to the script folder.

Run
```
python wiki2docbook.py Manual.xml
```
if you want to download all screenshots (it takes some time to download all images from UserBase, grep and wget should be installed), or
```
python wiki2docbook.py -s Manual.xml
```
if you need not to download images.

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.

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