View View source History

Difference between revisions of "How To Convert a UserBase Manual to Docbook"

Jump to: navigation, search
(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...")
 
(Marked this version for translation)
 
Line 1: Line 1:
 
<languages />
 
<languages />
 
<translate>
 
<translate>
−
== Preface ==  
+
== Preface == <!--T:1-->
  
 +
<!--T:2-->
 
The current process is not polished, the script code is ugly, not intelligent enough, etc.. The only excuse is that it works somehow {{Smiley}}.
 
The current process is not polished, the script code is ugly, not intelligent enough, etc.. The only excuse is that it works somehow {{Smiley}}.
  
 +
<!--T:3-->
 
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.
 
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-->
  
 +
<!--T:5-->
 
* 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 that the pages of your manual follow the [[Special:myLanguage/Tasks_and_Tools|author guidelines of UserBase]] and [[Special:myLanguage/Typographical_Guidelines|typographical guidelines]].
  
 +
<!--T:6-->
 
* Check if every page has its header according to the level of this page in table of contents.
 
* Check if every page has its header according to the level of this page in table of contents.
  
 +
<!--T:7-->
 
:{|
 
:{|
 
|+Reference table
 
|+Reference table
Line 37: Line 42:
 
|}
 
|}
  
 +
<!--T:8-->
 
* 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].
 
* 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].
  
 +
<!--T:9-->
 
* Make application name formatting consistent (avoid using '''Amarok'''s, do use '''Amarok's''').
 
* Make application name formatting consistent (avoid using '''Amarok'''s, do use '''Amarok's''').
  
 +
<!--T:10-->
 
* Ensure that ''all'' images are in PNG format.
 
* Ensure that ''all'' images are in PNG format.
  
 +
<!--T:11-->
 
* Remove all non-printable characters from image names.
 
* Remove all non-printable characters from image names.
  
−
===Export===  
+
===Export=== <!--T:12-->
  
 +
<!--T:13-->
 
* Prepare the page list (strip from UserBase addresses <nowiki>http://userbase.kde.org</nowiki>). Example for '''Amarok''':
 
* Prepare the page list (strip from UserBase addresses <nowiki>http://userbase.kde.org</nowiki>). Example for '''Amarok''':
  
 +
<!--T:14-->
 
{{Input|1=Amarok
 
{{Input|1=Amarok
 
Amarok/QuickStartGuide
 
Amarok/QuickStartGuide
Line 102: Line 113:
 
Amarok/Manual/Credits_and_License}}
 
Amarok/Manual/Credits_and_License}}
  
 +
<!--T:15-->
 
{{Tip|1=You can obtain the full list of pages for your application with the following script:<!--}}-->
 
{{Tip|1=You can obtain the full list of pages for your application with the following script:<!--}}-->
  
 +
<!--T:16-->
 
{{Input|1=<nowiki><DPL>
 
{{Input|1=<nowiki><DPL>
 
   nottitlematch = %/__|%/zh-%|%(%)
 
   nottitlematch = %/__|%/zh-%|%(%)
Line 112: Line 125:
 
</DPL></nowiki>}}
 
</DPL></nowiki>}}
  
 +
<!--T:17-->
 
<!--{{-->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.
 
<!--{{-->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.
 
}}
 
}}
  
 +
<!--T:18-->
 
* Go to the [[Special:Export|export page]].
 
* Go to the [[Special:Export|export page]].
  
 +
<!--T:19-->
 
* Paste the page list into the <menuchoice>bigger</menuchoice> text field.
 
* Paste the page list into the <menuchoice>bigger</menuchoice> text field.
  
 +
<!--T:20-->
 
* Click on <menuchoice>Export</menuchoice>.
 
* Click on <menuchoice>Export</menuchoice>.
 
[[File:XML_export.png|350px|center|thumb|Export of Amarok manual pages]]
 
[[File:XML_export.png|350px|center|thumb|Export of Amarok manual pages]]
  
 +
<!--T:21-->
 
* Save the file. The saved file will be called <tt>Manual.xml</tt> in what follows.
 
* Save the file. The saved file will be called <tt>Manual.xml</tt> in what follows.
  
−
===Conversion===  
+
===Conversion=== <!--T:22-->
  
 +
<!--T:23-->
 
* Install Subversion package for your system.
 
* Install Subversion package for your system.
  
 +
<!--T:24-->
 
* Checkout the latest version of conversion script: {{Input|1=svn checkout --depth=files <nowiki>svn://anonsvn.kde.org/home/kde/branches/work/doc/</nowiki>}}
 
* Checkout the latest version of conversion script: {{Input|1=svn checkout --depth=files <nowiki>svn://anonsvn.kde.org/home/kde/branches/work/doc/</nowiki>}}
  
 +
<!--T:25-->
 
* Copy <tt>Manual.xml</tt> to the script folder.
 
* Copy <tt>Manual.xml</tt> to the script folder.
  
 +
<!--T:26-->
 
* 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.
 
* 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-->
  
 +
<!--T:28-->
 
* Rename <tt>Manual.xml.docbook</tt> to <tt>index.docbook</tt>.
 
* Rename <tt>Manual.xml.docbook</tt> to <tt>index.docbook</tt>.
  
 +
<!--T:29-->
 
* Check if conversion was done correctly: {{Input|1=checkXML index.docbook}}
 
* Check if conversion was done correctly: {{Input|1=checkXML index.docbook}}
  
 +
<!--T:30-->
 
* Fix the errors (better on UserBase pages).
 
* Fix the errors (better on UserBase pages).
  
 +
<!--T:31-->
 
* Convert docbook to HTML: {{Input|1=meinproc4 index.docbook}}
 
* Convert docbook to HTML: {{Input|1=meinproc4 index.docbook}}
  
 +
<!--T:32-->
 
* Check HTML pages (all images should be visible, links should not lead to 404-pages).
 
* Check HTML pages (all images should be visible, links should not lead to 404-pages).
  
 +
<!--T:33-->
 
* Replace big images by thumbnails using '''convert''' from '''ImageMagick'''
 
* Replace big images by thumbnails using '''convert''' from '''ImageMagick'''
  
 +
<!--T:34-->
 
* Fix links in docbook, so they lead to docbook section, not UserBase pages.
 
* Fix links in docbook, so they lead to docbook section, not UserBase pages.
  
 +
<!--T:35-->
 
* Fix application name according to KDE entity list.
 
* Fix application name according to KDE entity list.
  
 +
<!--T:36-->
 
* Copy <tt>index.docbook</tt> and images to your <tt>/doc</tt> folder and commit them to repository.
 
* 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.]]
 
[[File:K3b_docs.png|350px|center|thumb|K3b docs on UserBase in Opera and converted page in Konqueror.]]
  
 +
<!--T:37-->
 
[[Category:Translator_Help]]
 
[[Category:Translator_Help]]
  
 
</translate>
 
</translate>

Latest revision as of 14:17, 5 July 2011

Other languages:English 100% • ‎Finnish 100% • ‎Dutch 55% • ‎Brazilian Portuguese 100% • ‎Ukrainian 100%

Contents

[edit] Preface

The current process is not polished, the script code is ugly, not intelligent enough, etc.. The only excuse is that it works somehow Face-smile.png

.

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

[edit] Preparing Pages for Conversion

  • 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
  • Make application name formatting consistent (avoid using Amaroks, do use Amarok's).
  • Ensure that all images are in PNG format.
  • Remove all non-printable characters from image names.

[edit] Export

  • Prepare the page list (strip from UserBase addresses http://userbase.kde.org). Example for Amarok: 
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
Ktip.png
 
Tip
You can obtain the full list of pages for your application with the following script: 
<DPL>
  nottitlematch = %/__|%/zh-%|%(%)
  titlematch = Amarok%
  namespace = Main
  columns = 1
  format = ,\n* [[%PAGE%|%TITLE%]],,
</DPL>
Replace Amarok with the name of your application, put it on your user page, and click on Preview. Rearrange the list according to the ToC of your manual.


  • Paste the page list into the bigger text field.
  • Click on Export.
Export of Amarok manual pages
  • Save the file. The saved file will be called Manual.xml in what follows.

[edit] Conversion

  • Install Subversion package for your system.
  • Checkout the latest version of conversion script: 
    svn checkout --depth=files svn://anonsvn.kde.org/home/kde/branches/work/doc/
  • Copy Manual.xml to the script folder.
  • Run 
    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 
    python wiki2docbook.py -s Manual.xml
    if you need not to download images.

[edit] Post-processing

  • Rename Manual.xml.docbook to index.docbook.
  • Check if conversion was done correctly: 
    checkXML index.docbook
  • Fix the errors (better on UserBase pages).
  • Convert docbook to HTML: 
    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.
K3b docs on UserBase in Opera and converted page in Konqueror.
Retrieved from ‘http://techbase.kde.org/index.php?title=How_To_Convert_a_UserBase_Manual_to_Docbook&oldid=61938’

This page was last modified on 5 July 2011, at 14:17. This page has been accessed 1,194 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. • Legal