Export translations

Settings

Group

Language

Format

Export for off-line translation

Export in native format

==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 the 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.
<span id="Export"></span>
===Export===

* Prepare the page list (strip from UserBase addresses <nowiki>http://userbase.kde.org</nowiki>). Example for '''Amarok''':

{{Input|1=Amarok/Manual/Introduction
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/ConfiguringAmarok/ChangingLayout
Amarok/Manual/Organization
Amarok/Manual/Organization/Collection
Amarok/Manual/Organization/CollectionScanning
Amarok/Manual/Organization/Collection/SearchInCollection
Amarok/Manual/Organization/Collection/OrganizeCollection
Amarok/Manual/Organization/Collection/RemoteCollections
Amarok/Manual/Organization/Collection/RemoteCollections/Ampache
Amarok/Manual/Organization/Collection/RemoteCollections/DAAP
Amarok/Manual/Organization/Collection/RemoteCollections/Samba
Amarok/Manual/Organization/Collection/RemoteCollections/UPnP
Amarok/Manual/Organization/Collection/ExternalDatabase
Amarok/Manual/Organization/Collection/WorkingWithMediaDevices
Amarok/Manual/Organization/CoverManager
Amarok/Manual/Organization/TagEditor
Amarok/Manual/Organization/Transcoding
Amarok/Manual/Organization/ScriptManager
Amarok/Manual/Playlist
Amarok/Manual/Playlist/SavedPlaylists
Amarok/Manual/Playlist/PlaylistFiltering
Amarok/Manual/Playlist/QueueManager
Amarok/Manual/Playlist/DynamicPlaylists
Amarok/Manual/Playlist/AutomaticPlaylistGenerator
Amarok/Manual/Various
Amarok/Manual/Various/Moodbar
Amarok/Manual/Various/AmarokOnOtherPlatforms
Amarok/Manual/Various/AmarokOnOtherPlatforms/NonKDE Desktops
Amarok/Manual/Various/AmarokOnOtherPlatforms/Windows
Amarok/Manual/Various/AmarokOnOtherPlatforms/OSX
Amarok/Manual/Various/TroubleshootingAndCommonProblems
Amarok/Manual/Various/FAQ
Amarok/Manual/References
Amarok/Manual/References/MenuAndCommandReference
Amarok/Manual/References/MenuAndCommandReference/AmarokMenu
Amarok/Manual/References/MenuAndCommandReference/ViewMenu
Amarok/Manual/References/MenuAndCommandReference/Playlist
Amarok/Manual/References/MenuAndCommandReference/Tools
Amarok/Manual/References/MenuAndCommandReference/Settings
Amarok/Manual/References/MenuAndCommandReference/Help
Amarok/Manual/References/KeybindingReference
Amarok/Manual/References/KeybindingReference/GlobalShortcuts
Amarok/Manual/References/KeybindingReference/AmarokShortcuts
Amarok/Manual/References/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-%|%pt-%|%(%)
  titlematch = Appname/Manual%
  namespace = 
  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.
}}

{{Note|1=If You are working with the Amarok manual be aware that it does not fully conform to manual page naming conventions. You can use
{{Input|1= titlematch = Amarok/Manual%{{!}}Amarok/QuickStartGuide%}}
(Note: No space characters in title pattern!)
}}

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

{{Warning|1=At some point in the past it became necessary to add a line containing <br /><code>144.76.227.197 userbase.kde.org</code><br /> to <tt>/etc/hosts</tt> in order to access UserBase from the script. This is no longer the case. If you already added such a line to your <tt>/etc/hosts</tt>, then you should remove it again.}}

===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.]]

== Updating Your DocBook from UserBase ==

To update your converted docbook please use the following procedure:

* Re-export XML from UserBase. See [[Special:myLanguage/How_To_Convert_a_UserBase_Manual_to_Docbook#Export|Export]] section.

* Use the script to update the content (headers with abstract and keywords and footer will be kept): {{Input|1= python wiki2docbook.py -r index.docbook Manual.xml}}

* Check the docbook, rename the file into index.docbook and commit it with screenshots into your repository.

== Converting DocBook into Other Format ==

=== Converting into PDF===

Usually, there is no need to convert DocBook manually. You can download the converted PDFs from [http://docs.kde.org/ KDE Documentation] site.

Should you need additional customization please do as follows:

* Make sure that you have some '''LaTeX''' distribution installed (usually, TeXLive).

* Create the following script file (named <tt>buildpdf.sh</tt>) in your DocBook directory:
{{Input|1=
<syntaxhighlight lang="bash">#!/bin/bash

export SGML_CATALOG_FILES=/usr/share/sgml/docbook/sqml-dtd-4.5/catalog:/usr/share/kf5/kdoctools/customization/catalog.xml:/usr/share/sgml/docbook/xml-dtd-4.5/docbook
# add -d to command below to keep the /tmp folder, so you can examine the generated tex.
./dblatex-cvs-install/bin/dblatex -d -b pdftex --style \
	kdestyle\
	-o $(pwd | awk -F/ '{ print $NF }').pdf \
	-P latex.output.revhistory=0  -P newtbl.use=1 \
	-P imagedata.default.scale=pagebound \
	-P literal.width.ignore=1 \
	-I $KDEDIR/share/doc/HTML/en/ \
	-X \
        $1</syntaxhighlight>}}
* Download KDE styles:
{{Input|1=<nowiki>git clone git://anongit.kde.org/websites/docs-kde-org.git</nowiki>}}

* Tweak <tt>dblatex-cvs-install/bin/dblatex</tt> in like this

{{Input|1=
<syntaxhighlight lang="bash">#!/bin/sh

TEXINPUTS=:/path/to/your/dblatex-cvs-install/share/dblatex/latex//:$TEXINPUTS
export TEXINPUTS

/path/to/your/dblatex-cvs-install/share/dblatex/scripts/dblatex  $*</syntaxhighlight>}}

(Change '''''/path/to/your/''''' as appropriate)

* Copy KDE styles (/dblatex-cvs-install/share/dblatex/latex/contrib/) to some TeX dir where it can be found by '''LaTeX''' installation (I have copied them to <tt>/usr/share/texmf-dist/tex/latex/kde</tt>).

* Update paths with <code>mktexlsr</code> from root.

* Run <code>./buildpdf.sh index.docbook</code>. This should create ready-to-use PDF file for you. You can stop on this step if you do not want to tweak it.

* Copy all files from <tt>/tmp/tpb-'''''your_user'''''-'''''digits'''''</tt> to the work directory.

* Customize and edit <tt>tex</tt> file in [[Special:MyLanguage/Kile|Kile]] as appropriate.

* Compile PDF file with <keycap>Alt + 6</keycap>.

=== Converting into EPUB ===

* Make sure that '''Calibre''' is installed in your system.

* Convert your DocBook into HTML first. Use <code>meinproc4 index.docbook</code> for this.

* Start '''Calibre''' and choose <menuchoice>Add books</menuchoice>.

* Select <tt>index.html</tt> in your DocBook folder. Wait until the book is loaded.

* Choose <menuchoice>Convert books</menuchoice>.

* Fill the metadata fields as appropriate.

[[File:calibre.png|350px|center|thumb|Calibre conversion configuration page.]]

* Press <menuchoice>OK</menuchoice> and wait until the work is done.

* Copy the book from <tt>~/Calibre Library</tt> on your ebook reader.

[[Category:Contributing]]