Como converter um manual UserBase para Dockbook

Prefácio

O processo atual não é refinado, o código do script é feio, não inteligente o suficiente, etc... A única desculpa é que de algum modo ele funciona

.

Se você deseja melhorar o processo, tem bons conhecimentos de Python e sabe os princípios de criação do docbook, você pode melhorar o procedimento. Por favor, entre em contato com Yurchor se você puder ajudar.

Preparando páginas para a conversão

• Verifique se as páginas do seu manual seguem o guia do autor do UserBase e guia tipográfico.

• Verifique se cada página tem seu título de acordo com o nível da página na tabela de conteúdo.

Reference table

UserBase	Docbook	Comment
==Section==	<chapter>
===Section===	<sect1>
====Section====	<sect2>
=====Section=====	<sect3>
======Section======	<sect4>	Evite usar esse último nível se possível

• Verifique se todas as células da tabela tem espaço depois do caractere pipe. Essa regra está em conformidade com a formatação traditional da wiki.

• Faça uma formatação consistente do nome do aplicativo (evite usar Amaroks, use Amarok's).

• Se certifique para que todas as imagens estejam no formato PNG.

• Remover todos os caracteres não imprimíveis dos nomes da imagem.

Exportar

• Prepare a lista da página (lista de endereço do UserBase http://userbase.kde.org). Exemplo para 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

Você pode obter a lista completa de páginas para seu aplicativo com o seguinte script:

<DPL>
  nottitlematch = %/__|%/zh-%|%(%)
  titlematch = Amarok%
  namespace = Main
  columns = 1
  format = ,\n* [[%PAGE%|%TITLE%]],,
</DPL>

Replace Amarok with the name of your application, put it on your user page, and click on Preview. Rearrange the list according to the ToC of your manual.

• Go to the export page.

• Paste the page list into the bigger text field.

• Click on Export.

Export of Amarok manual pages

• Save the file. The saved file will be called Manual.xml in what follows.

Conversion

• Install Subversion package for your system.

• Checkout the latest version of conversion script:

  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-processing

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