|
|
| (8 intermediate revisions by 2 users not shown) |
| 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 svn://anonsvn.kde.org/home/kde/branches/work/doc/}}
| |
| * Copy '''''Manual.xml'''' to the script folder.
| |
| * Run
| |
| {{Input|1=python wiki2docbook.py Manual.xml}}
| |
| if 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'''.]]
| |
Because we separate like ripples on a blank shore
