How To Convert a UserBase Manual to Docbook - Revision history

AnneW: Marked this version for translation

2011-07-05T13:17:45Z

Marked this version for translation

AnneW: Created page with " == Preface == The current process is not polished, the script code is ugly, not intelligent enough, etc.. The only excuse is that it works somehow {{S..."

2011-07-04T15:45:41Z

Created page with "<languages /> <translate> == Preface == The current process is not polished, the script code is ugly, not intelligent enough, etc.. The only excuse is that it works somehow {{S..."

New page

<languages />
<translate>
== Preface ==

The current process is not polished, the script code is ugly, not intelligent enough, etc.. The only excuse is that it works somehow {{Smiley}}.

If you want to improve the process, have good Python skills, and know the docbook authoring principles, you can improve the procedure. Please contact [[User_talk:Yurchor|Yurchor]] if you are able to help.

== Preparing Pages for Conversion ==

* Check that the pages of your manual follow the [[Special:myLanguage/Tasks_and_Tools|author guidelines of UserBase]] and [[Special:myLanguage/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
! Comment
|-
| ==Section==
| <chapter>
|-
| ===Section===
| <sect1>
|-
| ====Section====
| <sect2>
|-
| =====Section=====
| <sect3>
|-
| ======Section======
| <sect4>
| ''Avoid using this last level if possible''
|}

* 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.

* 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}}

{{Tip|1=You can obtain the full list of pages for your application with the following script:

{{Input|1=<nowiki><DPL>
nottitlematch = %/__|%/zh-%|%(%)
titlematch = Amarok%
namespace = Main
columns = 1
format = ,\n* [[%PAGE%|%TITLE%]],,
</DPL></nowiki>}}

Replace '''''Amarok''''' with the name of your application, put it on your user page, and click on <menuchoice>Preview</menuchoice>. Rearrange the list according to the ToC of your manual.
}}

* Go to the [[Special:Export|export page]].

* Paste the page list into the <menuchoice>bigger</menuchoice> text field.

* Click on <menuchoice>Export</menuchoice>.
[[File:XML_export.png|350px|center|thumb|Export of Amarok manual pages]]

* Save the file. The saved file will be called <tt>Manual.xml</tt> 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 <tt>Manual.xml</tt> 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 <tt>Manual.xml.docbook</tt> to <tt>index.docbook</tt>.

* 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 <tt>index.docbook</tt> and images to your <tt>/doc</tt> folder and commit them to repository.
[[File:K3b_docs.png|350px|center|thumb|K3b docs on UserBase in Opera and converted page in Konqueror.]]

[[Category:Translator_Help]]

</translate>

@@ Line 1: / Line 1: @@
 <languages />
 <translate>
-== Preface ==
+== Preface == <!--T:1-->
 The current process is not polished, the script code is ugly, not intelligent enough, etc.. The only excuse is that it works somehow {{Smiley}}.
 If you want to improve the process, have good Python skills, and know the docbook authoring principles, you can improve the procedure.  Please contact [[User_talk:Yurchor|Yurchor]] if you are able to help.
-== Preparing Pages for Conversion ==
+== Preparing Pages for Conversion == <!--T:4-->
 * Check that the pages of your manual follow the [[Special:myLanguage/Tasks_and_Tools|author guidelines of UserBase]] and [[Special:myLanguage/Typographical_Guidelines|typographical guidelines]].
 * Check if every page has its header according to the level of this page in table of contents.
 :{|
 |+Reference table
@@ Line 37: / Line 42: @@
 |}
 * 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.
 * Remove all non-printable characters from image names.
-===Export===
+===Export=== <!--T:12-->
 * Prepare the page list (strip from UserBase addresses <nowiki>http://userbase.kde.org</nowiki>). Example for '''Amarok''':
 {{Input|1=Amarok
 Amarok/QuickStartGuide
@@ Line 102: / Line 113: @@
 Amarok/Manual/Credits_and_License}}
 {{Tip|1=You can obtain the full list of pages for your application with the following script:<!--}}-->
 {{Input|1=<nowiki><DPL>
    nottitlematch = %/__|%/zh-%|%(%)
@@ Line 112: / Line 125: @@
 </DPL></nowiki>}}
 <!--{{-->Replace '''''Amarok''''' with the name of your application, put it on your user page, and click on <menuchoice>Preview</menuchoice>. Rearrange the list according to the ToC of your manual.
 }}
 * Go to the [[Special:Export|export page]].
 * Paste the page list into the <menuchoice>bigger</menuchoice> text field.
 * Click on <menuchoice>Export</menuchoice>.
 [[File:XML_export.png|350px|center|thumb|Export of Amarok manual pages]]
 * Save the file. The saved file will be called <tt>Manual.xml</tt> in what follows.
-===Conversion===
+===Conversion=== <!--T:22-->
 * 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 <tt>Manual.xml</tt> 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===
+===Post-processing=== <!--T:27-->
 * Rename <tt>Manual.xml.docbook</tt> to <tt>index.docbook</tt>.
 * 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 <tt>index.docbook</tt> and images to your <tt>/doc</tt> folder and commit them to repository.
 [[File:K3b_docs.png|350px|center|thumb|K3b docs on UserBase in Opera and converted page in Konqueror.]]
 [[Category:Translator_Help]]
 </translate>