User:Yurchor: Difference between revisions

    From KDE UserBase Wiki
    m (Replaced content with "''Because we separate like ripples on a blank shore''")
    Line 1: Line 1:
    ''Because we separate like ripples on a blank shore''
    ''Because we separate like ripples on a blank shore''
    ==How To Convert UserBase Manual to Docbook==
    ===Preface===
    The current process is not polished, the script code is ugly, not intelligent enough, etc.. The only excuse is that it works somehow [[Image:Smiley.png|16px]].
    If you want to improve the process, have good Python skills, and know the docbook authoring principles, you can improve the procedure.
    ===Preparing Pages to Conversion===
    * Check that the pages of your manual follow the [[Tasks_and_Tools|author guidelines of UserBase]] [[Typographical_Guidelines|typographical guidelines]].
    * Check if every page has its header according to the level of this page in table of contents.
    {|
    |+Reference table
    |-
    ! UserBase
    ! Docbook
    |-
    | =Section=
    | <chapter>
    |-
    | ==Section==
    | <sect1>
    |-
    | ===Section===
    | <sect2>
    |-
    | ====Section====
    | <sect3>
    |-
    | =====Section=====
    | <sect4>
    |}
    * Check if all table cells have space after the pipe character. This rule conforms with [http://en.wikipedia.org/wiki/Help:Table traditional wiki formatting].
    * Make application name formatting consistent (avoid using '''Amarok'''s, do use '''Amarok's''').
    * Ensure that '''all''' images are in PNG format (you can use JPEG (.jpeg, not .jpg) as well, but in this case you should convert your images to PNG later.
    * Remove all non-printable characters from image names.
    ===Export===
    * Prepare the page list (strip from UserBase addresses <nowiki>http://userbase.kde.org</nowiki>). Example for '''Amarok''':
    {{Input|1=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}}
    * Go to the [[Special:Export|export page]].
    * Paste the page list into the '''bigger''' text field.
    * Click on <menuchoice>Export</menuchoice>.
    [[File:XML_export.png|200px|center|thumb|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:
    {{Input|1=svn checkout --depth=files <nowiki>svn://anonsvn.kde.org/home/kde/branches/work/doc/</nowiki>}}
    * Copy '''''Manual.xml''''' to the script folder.
    * Run
    {{Input|1=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
    {{Input|1=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:
    {{Input|1=checkXML index.docbook}}
    * Fix the errors (better on UserBase pages).
    * Convert docbook to HTML:
    {{Input|1=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.
    [[File:K3b_docs.png|200px|center|thumb|K3b docs on UserBase in '''Opera''' and converted page in '''Konqueror'''.]]

    Revision as of 17:38, 6 March 2011

    Because we separate like ripples on a blank shore