Como converter um manual UserBase para Dockbook

From KDE TechBase
This page is a translated version of the page How To Convert a UserBase Manual to Docbook and the translation is 100% complete.
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 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
  • 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.


  • Cole a lista de página dentro do campo de texto maior.
  • Clique em Export.
Exportação manual de páginas do Amarok
  • 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.

Pós-processamento

  • Renomeie Manual.xml.docbook para index.docbook.
  • Verifique se a conversão foi feita corretamente:
    checkXML index.docbook
  • Corrija os erros (melhor em páginas do UserBase).
  • Converta docbook para HTML:
    meinproc4 index.docbook
  • Verifique as páginas HTML (todas as imagens deve ser visíveis, links não devem levar a páginas 404).
  • Substitua imagens grandes por miniaturas usando o convert do ImageMagick
  • Corrija os links no docbook, assim eles levarão à seção do docbook, não a páginas do UserBase.
  • Corrija o nome dos aplicativos de acordo com a lista do KDE.
  • Copie index.docbook e imagens para sua pasta /doc e faça o commit deles para o repositório.
Os documentos do K3b no UserBase no Opera e a página convertida no Konqueror.