Com convertir una manual de UserBase a Docbook

From KDE Wiki Sandbox
Revision as of 18:04, 3 July 2011 by Abella (talk | contribs) (Created page with "* Arrangeu el nom de l'aplicació d'acord amb la llista d'entitats del KDE.")

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ó

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


  • 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

  • Canvieu el nom de Manual.xml.docbook a index.docbook.
  • Comproveu si la conversió s'ha realitzat correctament:
    checkXML index.docbook
  • Corregiu els errors (millor sobre les pàgines de UserBase).
  • Convertir docbook a HTML:
    meinproc4 index.docbook
  • Comproveu les pàgines HTML (totes les imatges han de ser visibles, els enllaços no han de donar lloc a pàgines 404).
  • Substituïu les imatges grans per miniatures usant convert de ImageMagick.
  • Arrangeu els enllaços a docbook, de manera que portin a la secció de docbook, no pàgines de UserBase.
  • Arrangeu el nom de l'aplicació d'acord amb la llista d'entitats del KDE.
  • 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.