Como converter um manual UserBase para Dockbook

    From KDE TechBase
    Revision as of 13:10, 29 April 2012 by Aracele (talk | contribs) (Created page with "* Conserte os erros (melhor em páginas do UserBase).")
    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 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
    • Conserte os erros (melhor em páginas do UserBase).
    • 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.