How To Convert a UserBase Manual to Docbook: Difference between revisions

From KDE UserBase Wiki
m (Add conversion and updating instructions)
(Marked this version for translation)
 
(15 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<languages />
<languages />
<translate>
<translate>
==Preface== <!--T:1-->
==Preface== <!--T:1-->


Line 15: Line 16:


<!--T:6-->
<!--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 the table of contents.


<!--T:7-->
<!--T:7-->
Line 55: Line 56:


</translate><span id="Export"></span><translate>
</translate><span id="Export"></span><translate>
===Export=== <!--T:12-->
===Export=== <!--T:12-->


Line 126: Line 128:
<!--T:16-->
<!--T:16-->
{{Input|1=<nowiki><DPL>
{{Input|1=<nowiki><DPL>
   nottitlematch = %/__|%/zh-%|%(%)
   nottitlematch = %/__|%/zh-%|%pt-%|%(%)
   titlematch = Amarok%
   titlematch = Appname/Manual%
   namespace = Main
   namespace =  
   columns = 1
   columns = 1
   format = ,\n* [[%PAGE%|%TITLE%]],,
   format = ,\n* [[%PAGE%|%TITLE%]],,
Line 135: Line 137:
<!--T:17-->
<!--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:75-->
{{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!)
}}
}}


Line 163: Line 171:
<!--T:26-->
<!--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.
<!--T:76-->
{{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=== <!--T:27-->
===Post-processing=== <!--T:27-->
Line 194: Line 205:
[[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.]]


== Updating Your DocBook from UserBase ==
== Updating Your DocBook from UserBase == <!--T:38-->


<!--T:39-->
To update your converted docbook please use the following procedure:
To update your converted docbook please use the following procedure:


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


<!--T:41-->
* 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}}
* 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}}


<!--T:42-->
* Check the docbook, rename the file into index.docbook and commit it with screenshots into your repository.
* Check the docbook, rename the file into index.docbook and commit it with screenshots into your repository.


== Converting DocBook into Other Format ==
== Converting DocBook into Other Format == <!--T:43-->


=== Converting into PDF===
=== Converting into PDF=== <!--T:44-->


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


<!--T:46-->
Should you need additional customization please do as follows:
Should you need additional customization please do as follows:


<!--T:47-->
* Make sure that you have some '''LaTeX''' distribution installed (usually, TeXLive).
* Make sure that you have some '''LaTeX''' distribution installed (usually, TeXLive).


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


export SGML_CATALOG_FILES=/usr/share/sgml/docbook/sqml-dtd-4.2/catalog:/usr/share/apps/ksgmltools2/customization/catalog.xml:/usr/share/sgml/docbook/xml-dtd-4.2/docbook
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.
# 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 \
./dblatex-cvs-install/bin/dblatex -d -b pdftex --style \
Line 231: Line 249:
-X \
-X \
         $1</syntaxhighlight>}}
         $1</syntaxhighlight>}}
 
<translate>
<!--T:52-->
* Download KDE styles:
* Download KDE styles:
{{Input|1=<nowiki>svn co svn://anonsvn.kde.org/home/kde/trunk/www/areas/docs/dblatex-cvs-install/</nowiki>}}
{{Input|1=<nowiki>git clone git://anongit.kde.org/websites/docs-kde-org.git</nowiki>}}


<!--T:53-->
* Tweak <tt>dblatex-cvs-install/bin/dblatex</tt> in like this
* Tweak <tt>dblatex-cvs-install/bin/dblatex</tt> in like this


{{Input|1=
<!--T:54-->
<!--}}-->{{Input|1=
<syntaxhighlight lang="bash">#!/bin/sh
<syntaxhighlight lang="bash">#!/bin/sh


<!--T:55-->
TEXINPUTS=:/path/to/your/dblatex-cvs-install/share/dblatex/latex//:$TEXINPUTS
TEXINPUTS=:/path/to/your/dblatex-cvs-install/share/dblatex/latex//:$TEXINPUTS
export TEXINPUTS
export TEXINPUTS


/path/to/your/dblatex-cvs-install/share/dblatex/scripts/dblatex  $*</syntaxhighlight>}}
<!--T:56-->
/path/to/your/dblatex-cvs-install/share/dblatex/scripts/dblatex  $*</syntaxhighlight>}}<!--{{-->


<!--T:57-->
(Change '''''/path/to/your/''''' as appropriate)
(Change '''''/path/to/your/''''' as appropriate)


<!--T:58-->
* 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>).
* 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>).


<!--T:59-->
* Update paths with <code>mktexlsr</code> from root.
* Update paths with <code>mktexlsr</code> from root.


* Run <code>./buildpdf.sh index.docbook</code>.
<!--T:60-->
* 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.  


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


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


<!--T:63-->
* Compile PDF file with <keycap>Alt + 6</keycap>.
* Compile PDF file with <keycap>Alt + 6</keycap>.


=== Converting into EPUB ===
=== Converting into EPUB === <!--T:64-->


<!--T:65-->
* Make sure that '''Calibre''' is installed in your system.
* Make sure that '''Calibre''' is installed in your system.


<!--T:66-->
* Convert your DocBook into HTML first. Use <code>meinproc4 index.docbook</code> for this.
* Convert your DocBook into HTML first. Use <code>meinproc4 index.docbook</code> for this.


<!--T:67-->
* Start '''Calibre''' and choose <menuchoice>Add books</menuchoice>.
* Start '''Calibre''' and choose <menuchoice>Add books</menuchoice>.


<!--T:68-->
* Select <tt>index.html</tt> in your DocBook folder. Wait until the book is loaded.
* Select <tt>index.html</tt> in your DocBook folder. Wait until the book is loaded.


<!--T:69-->
* Choose <menuchoice>Convert books</menuchoice>.
* Choose <menuchoice>Convert books</menuchoice>.


<!--T:70-->
* Fill the metadata fields as appropriate.
* Fill the metadata fields as appropriate.


<!--T:71-->
[[File:calibre.png|350px|center|thumb|Calibre conversion configuration page.]]
[[File:calibre.png|350px|center|thumb|Calibre conversion configuration page.]]


<!--T:72-->
* Press <menuchoice>OK</menuchoice> and wait until the work is done.
* Press <menuchoice>OK</menuchoice> and wait until the work is done.


<!--T:73-->
* Copy the book from <tt>~/Calibre Library</tt> on your ebook reader.
* Copy the book from <tt>~/Calibre Library</tt> on your ebook reader.


Latest revision as of 10:24, 31 August 2019

Other 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 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
  • 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/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

You can obtain the full list of pages for your application with the following script: 
<DPL>
  nottitlematch = %/__|%/zh-%|%pt-%|%(%)
  titlematch = Appname/Manual%
  namespace = 
  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.


Note

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


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

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.

Warning

At some point in the past it became necessary to add a line containing
144.76.227.197 userbase.kde.org
to /etc/hosts in order to access UserBase from the script. This is no longer the case. If you already added such a line to your /etc/hosts, then you should remove it again.


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.

Updating Your DocBook from UserBase

To update your converted docbook please use the following procedure:

  • Re-export XML from UserBase. See Export section.
  • Use the script to update the content (headers with abstract and keywords and footer will be kept): 
    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 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 buildpdf.sh) in your DocBook directory:
#!/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
  • Download KDE styles:
git clone git://anongit.kde.org/websites/docs-kde-org.git
  • Tweak dblatex-cvs-install/bin/dblatex in like this
#!/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  $*

(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 /usr/share/texmf-dist/tex/latex/kde).
  • Update paths with mktexlsr from root.
  • Run ./buildpdf.sh index.docbook. 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 /tmp/tpb-your_user-digits to the work directory.
  • Customize and edit tex file in Kile as appropriate.
  • Compile PDF file with Alt + 6.

Converting into EPUB

  • Make sure that Calibre is installed in your system.
  • Convert your DocBook into HTML first. Use meinproc4 index.docbook for this.
  • Start Calibre and choose Add books.
  • Select index.html in your DocBook folder. Wait until the book is loaded.
  • Choose Convert books.
  • Fill the metadata fields as appropriate.
Calibre conversion configuration page.
  • Press OK and wait until the work is done.
  • Copy the book from ~/Calibre Library on your ebook reader.
Retrieved from "https://userbase.kde.org/index.php?title=How_To_Convert_a_UserBase_Manual_to_Docbook&oldid=441913"