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

    From KDE UserBase Wiki
    m (Protected "How To Convert a UserBase Manual to Docbook" ([edit=autoconfirmed] (indefinite) [move=autoconfirmed] (indefinite)))
    (Marked this version for translation)
    (16 intermediate revisions by 2 users not shown)
    Line 1: Line 1:
    <languages />
    <languages />
    <translate>
    <translate>
    ==Preface== <!--T:1-->
    ==Preface== <!--T:1-->


    Line 53: Line 54:
    <!--T:11-->
    <!--T:11-->
    * Remove all non-printable characters from image names.
    * Remove all non-printable characters from image names.
    </translate><span id="Export"></span><translate>


    ===Export=== <!--T:12-->
    ===Export=== <!--T:12-->
    Line 58: Line 61:
    <!--T:13-->
    <!--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''':
    </translate>


    <!--T:14-->
    {{Input|1=Amarok/Manual/Introduction
    {{Input|1=Amarok
    Amarok/QuickStartGuide
    Amarok/QuickStartGuide
    Amarok/QuickStartGuide/GettingStarted
    Amarok/QuickStartGuide/GettingStarted
    Line 75: Line 78:
    Amarok/Manual/AmarokWindow/PlaylistPane
    Amarok/Manual/AmarokWindow/PlaylistPane
    Amarok/Manual/ConfiguringAmarok
    Amarok/Manual/ConfiguringAmarok
    Amarok/Manual/AdvancedFeatures
    Amarok/Manual/ConfiguringAmarok/ChangingLayout
    Amarok/Manual/AdvancedFeatures/CollectionScanning
    Amarok/Manual/Organization
    Amarok/Manual/AdvancedFeatures/CoverManager
    Amarok/Manual/Organization/Collection
    Amarok/Manual/AdvancedFeatures/DynamicPlaylists
    Amarok/Manual/Organization/CollectionScanning
    Amarok/Manual/AdvancedFeatures/AutomaticPlaylistGenerator
    Amarok/Manual/Organization/Collection/SearchInCollection
    Amarok/Manual/AdvancedFeatures/ExternalDatabase
    Amarok/Manual/Organization/Collection/OrganizeCollection
    Amarok/Manual/AdvancedFeatures/AFT
    Amarok/Manual/Organization/Collection/RemoteCollections
    Amarok/Manual/AdvancedFeatures/Moodbar
    Amarok/Manual/Organization/Collection/RemoteCollections/Ampache
    Amarok/Manual/AdvancedFeatures/WorkingWithMediaDevices
    Amarok/Manual/Organization/Collection/RemoteCollections/DAAP
    Amarok/Manual/AdvancedFeatures/SavedPlaylists
    Amarok/Manual/Organization/Collection/RemoteCollections/Samba
    Amarok/Manual/AdvancedFeatures/PlaylistFiltering
    Amarok/Manual/Organization/Collection/RemoteCollections/UPnP
    Amarok/Manual/AdvancedFeatures/QueueManager
    Amarok/Manual/Organization/Collection/ExternalDatabase
    Amarok/Manual/AdvancedFeatures/SearchInCollection
    Amarok/Manual/Organization/Collection/WorkingWithMediaDevices
    Amarok/Manual/AdvancedFeatures/TagEditor
    Amarok/Manual/Organization/CoverManager
    Amarok/Manual/AdvancedFeatures/OrganizeCollection
    Amarok/Manual/Organization/TagEditor
    Amarok/Manual/AdvancedFeatures/Transcoding
    Amarok/Manual/Organization/Transcoding
    Amarok/Manual/AdvancedFeatures/ScriptManager
    Amarok/Manual/Organization/ScriptManager
    Amarok/Manual/AdvancedFeatures/RemoteCollections
    Amarok/Manual/Playlist
    Amarok/Manual/AdvancedFeatures/RemoteCollections/Ampache
    Amarok/Manual/Playlist/SavedPlaylists
    Amarok/Manual/AdvancedFeatures/RemoteCollections/DAAP
    Amarok/Manual/Playlist/PlaylistFiltering
    Amarok/Manual/AdvancedFeatures/RemoteCollections/Samba
    Amarok/Manual/Playlist/QueueManager
    Amarok/Manual/AdvancedFeatures/RemoteCollections/UPnP
    Amarok/Manual/Playlist/DynamicPlaylists
    Amarok/Manual/MenuAndCommandReference/AmarokMenu
    Amarok/Manual/Playlist/AutomaticPlaylistGenerator
    Amarok/Manual/MenuAndCommandReference/ViewMenu
    Amarok/Manual/Various
    Amarok/Manual/MenuAndCommandReference/Playlist
    Amarok/Manual/Various/Moodbar
    Amarok/Manual/MenuAndCommandReference/Tools
    Amarok/Manual/Various/AmarokOnOtherPlatforms
    Amarok/Manual/MenuAndCommandReference/Settings
    Amarok/Manual/Various/AmarokOnOtherPlatforms/NonKDE Desktops
    Amarok/Manual/MenuAndCommandReference/Help
    Amarok/Manual/Various/AmarokOnOtherPlatforms/Windows
    Amarok/Manual/KeybindingReference
    Amarok/Manual/Various/AmarokOnOtherPlatforms/OSX
    Amarok/Manual/KeybindingReference/GlobalShortcuts
    Amarok/Manual/Various/TroubleshootingAndCommonProblems
    Amarok/Manual/KeybindingReference/AmarokShortcuts
    Amarok/Manual/Various/FAQ
    Amarok/Manual/TroubleshootingAndCommonProblems
    Amarok/Manual/References
    Amarok/Manual/AmarokOnOtherPlatforms/Non-KDE Desktops
    Amarok/Manual/References/MenuAndCommandReference
    Amarok/Manual/AmarokOnOtherPlatforms/Windows
    Amarok/Manual/References/MenuAndCommandReference/AmarokMenu
    Amarok/Manual/AmarokOnOtherPlatforms/OSX
    Amarok/Manual/References/MenuAndCommandReference/ViewMenu
    Amarok/Manual/FAQ
    Amarok/Manual/References/MenuAndCommandReference/Playlist
    Amarok/Manual/Credits_and_License}}
    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}}


    <translate>
    <!--T:15-->
    <!--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:<!--}}-->
    Line 152: Line 162:
    <!--T:25-->
    <!--T:25-->
    * Copy <tt>Manual.xml</tt> to the script folder.
    * Copy <tt>Manual.xml</tt> to the script folder.
    <!--T:74-->
    * Add a line containing {{Input|1=144.76.227.197 userbase.kde.org}} to the file <tt>/etc/hosts</tt> . (You will need root privileges for this. You only need to do this once.)


    <!--T:26-->
    <!--T:26-->
    Line 185: Line 198:
    * 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.]]
    == Updating Your DocBook from UserBase == <!--T:38-->
    <!--T:39-->
    To update your converted docbook please use the following procedure:
    <!--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}}
    <!--T:42-->
    * Check the docbook, rename the file into index.docbook and commit it with screenshots into your repository.
    == Converting DocBook into Other Format == <!--T:43-->
    === 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.
    <!--T:46-->
    Should you need additional customization please do as follows:
    <!--T:47-->
    * 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:
    <!--T:49-->
    <!--}}-->{{Input|1=
    <syntaxhighlight lang="bash">#!/bin/bash
    <!--T:50-->
    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
    <!--T:51-->
    # 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>}}<!--{{-->
    <!--T:52-->
    * Download KDE styles:
    {{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
    <!--T:54-->
    <!--}}-->{{Input|1=
    <syntaxhighlight lang="bash">#!/bin/sh
    <!--T:55-->
    TEXINPUTS=:/path/to/your/dblatex-cvs-install/share/dblatex/latex//:$TEXINPUTS
    export TEXINPUTS
    <!--T:56-->
    /path/to/your/dblatex-cvs-install/share/dblatex/scripts/dblatex  $*</syntaxhighlight>}}<!--{{-->
    <!--T:57-->
    (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>).
    <!--T:59-->
    * Update paths with <code>mktexlsr</code> from root.
    <!--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.
    <!--T:62-->
    * Customize and edit <tt>tex</tt> file in [[Special:MyLanguage/Kile|Kile]] as appropriate.
    <!--T:63-->
    * Compile PDF file with <keycap>Alt + 6</keycap>.
    === Converting into EPUB === <!--T:64-->
    <!--T:65-->
    * 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.
    <!--T:67-->
    * 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.
    <!--T:69-->
    * Choose <menuchoice>Convert books</menuchoice>.
    <!--T:70-->
    * Fill the metadata fields as appropriate.
    <!--T:71-->
    [[File:calibre.png|350px|center|thumb|Calibre conversion configuration page.]]
    <!--T:72-->
    * 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.


    <!--T:37-->
    <!--T:37-->

    Revision as of 15:43, 27 July 2017

    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 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-%|%(%)
      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.

    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.
    • Add a line containing
      144.76.227.197 userbase.kde.org
      to the file /etc/hosts . (You will need root privileges for this. You only need to do this once.)
    • 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.

    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.2/catalog:/usr/share/apps/ksgmltools2/customization/catalog.xml:/usr/share/sgml/docbook/xml-dtd-4.2/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.