Difference between revisions of "User:Yurchor"

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


Content is available under Creative Commons License SA 4.0 unless otherwise noted.