How To Convert a UserBase Manual to Docbook: Difference between revisions
m (add hint for the page list) |
No edit summary |
||
| Line 1: | Line 1: | ||
<languages> | |||
<translate> | |||
==Preface== | ==Preface== | ||
| Line 7: | Line 9: | ||
==Preparing Pages for Conversion== | ==Preparing Pages for Conversion== | ||
* Check that the pages of your manual follow the [[Tasks_and_Tools|author guidelines of UserBase]] and [[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]]. | ||
* 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. | ||
:{| | |||
|+Reference table | |+Reference table | ||
|- | |- | ||
| Line 32: | Line 36: | ||
| ''Avoid using this last level if possible'' | | ''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]. | * 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'''). | * Make application name formatting consistent (avoid using '''Amarok'''s, do use '''Amarok's'''). | ||
* Ensure that | |||
* Ensure that ''all'' images are in PNG format. | |||
* Remove all non-printable characters from image names. | * Remove all non-printable characters from image names. | ||
| Line 40: | Line 48: | ||
* 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''': | ||
{{Input|1=Amarok | {{Input|1=Amarok | ||
Amarok/QuickStartGuide | Amarok/QuickStartGuide | ||
| Line 93: | Line 102: | ||
Amarok/Manual/Credits_and_License}} | 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> | {{Tip|1=You can obtain the full list of pages for your application with the following script:<!--}}--> | ||
{{Input|1=<nowiki><DPL> | |||
nottitlematch = %/__|%/zh-%|%(%) | nottitlematch = %/__|%/zh-%|%(%) | ||
titlematch = Amarok% | titlematch = Amarok% | ||
| Line 100: | Line 111: | ||
format = ,\n* [[%PAGE%|%TITLE%]],, | format = ,\n* [[%PAGE%|%TITLE%]],, | ||
</DPL></nowiki>}} | </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. | |||
<!--{{-->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]]. | * Go to the [[Special:Export|export page]]. | ||
* Paste the page list into the | |||
* Paste the page list into the <menuchoice>bigger</menuchoice> text field. | |||
* Click on <menuchoice>Export</menuchoice>. | * Click on <menuchoice>Export</menuchoice>. | ||
[[File:XML_export.png|350px|center|thumb|Export of | [[File:XML_export.png|350px|center|thumb|Export of Amarok manual pages]] | ||
* Save the file. The saved file will be called | |||
* Save the file. The saved file will be called <tt>Manual.xml</tt> in what follows. | |||
===Conversion=== | ===Conversion=== | ||
* Install Subversion package for your system. | * 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>}} | * 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 | |||
* Run | * Copy <tt>Manual.xml</tt> to the script folder. | ||
{{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 | * 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. | ||
{{Input|1=python wiki2docbook.py -s Manual.xml}} | |||
if you need not to download images. | |||
===Post-processing=== | ===Post-processing=== | ||
* Rename | * Rename <tt>Manual.xml.docbook</tt> to <tt>index.docbook</tt>. | ||
* Check if conversion was done correctly: | |||
{{Input|1=checkXML index.docbook}} | * Check if conversion was done correctly: {{Input|1=checkXML index.docbook}} | ||
* Fix the errors (better on UserBase pages). | * Fix the errors (better on UserBase pages). | ||
* Convert docbook to HTML: | |||
{{Input|1=meinproc4 index.docbook}} | * Convert docbook to HTML: {{Input|1=meinproc4 index.docbook}} | ||
* 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). | ||
* Replace big images by thumbnails using '''convert''' from '''ImageMagick''' | * Replace big images by thumbnails using '''convert''' from '''ImageMagick''' | ||
* 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. | ||
* Fix application name according to KDE entity list. | * Fix application name according to KDE entity list. | ||
* Copy | |||
[[File:K3b_docs.png|350px|center|thumb|K3b docs on UserBase in | * 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:Contributing]] | |||
</translate> | |||
Revision as of 10:04, 4 June 2011
<languages>
Preface
The current process is not polished, the script code is ugly, not intelligent enough, etc.. The only excuse is that it works somehow 
.
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.
Preparing Pages for Conversion
- Check that the pages of your manual follow the author guidelines of UserBase and 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 traditional wiki formatting.
- 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.
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
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 . Rearrange the list according to the ToC of your manual.
- Go to the export page.
- Paste the page list into the text field.
- Click on .
- 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:
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), orpython 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:
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.
