Como converter um manual UserBase para Dockbook

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Other languages:

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>

Substitua Amarok pelo nome de seu aplicativo, coloque na sua página de usuário e clique em Preview. Reorganize a lista de acordo com o ToC de seu manual.

Vá para página de exportação.

Cole a lista de página dentro do campo de texto maior.

Clique em Export.

Salve o arquivo. O arquivo salvo será chamado no Manual.xml que se segue.

Conversão

Instale o pacote Subversion para seu sistema.

Faça o checkout da última versão do script de conversão:

svn checkout --depth=files svn://anonsvn.kde.org/home/kde/branches/work/doc/

Copie Manual.xml para a pasta de script.

Execute
```
python wiki2docbook.py Manual.xml
```
se você deseja baixar todos os screenshots (leva algum tempo para baixar todas as imagens do UserBase, grep e wget devem estar instalados) ou execute
```
python wiki2docbook.py -s Manual.xml
```
se você não precisa baixar as imagens.

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.