Como converter um manual UserBase para Dockbook

    From KDE TechBase
    Revision as of 14:04, 29 April 2012 by Aracele (talk | contribs) (Created page with "* Copie <tt>index.docbook</tt> e imagens para sua pasta <tt>/doc</tt> e faça o commit deles para o repositório. [[File:K3b_docs.png|350px|center|thumb|Os documentos do K3b no U...")
    (diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
    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.