User:Yurchor: Difference between revisions

From KDE UserBase Wiki
(Converting docs)
No edit summary
 
(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'''.]]

Latest revision as of 16:31, 27 January 2012

Because we separate like ripples on a blank shore