Як перетворити підручник з UserBase на підручник у форматі Docbook

From KDE Wiki Sandbox
Revision as of 17:26, 21 November 2011 by Yurchor (talk | contribs) (Created page with "=== Перетворення на дані у форматі PDF===")
Other languages:

Вступ

Так, поточна процедура доволі кострубата, код скрипту не дуже-то і красивий, скрипт недостатньо «розумний» тощо. Єдиним виправданням може слугувати те, що цей спосіб якось працює .

Якщо ви бажаєте удосконалити процедуру, маєте добрі навички з програмування мовою Python, добре знайомі з принципами створення підручників у форматі docbook, ви можете докласти власних зусиль до покращення процесу. Будь ласка, зв’яжіться з користувачем Yurchor, якщо ви бажаєте допомогти.

Приготування сторінок до перетворення

  • Переконайтеся, що кожна зі сторінок має заголовок, відповідно до її місця у змісті підручника.
Довідкова таблиця
UserBase Docbook Коментар
==Розділ== <chapter>
===Розділ=== <sect1>
====Розділ==== <sect2>
=====Розділ===== <sect3>
======Розділ====== <sect4> Намагайтеся уникати використання цього рівні.
  • Використовуйте однорідне форматування назви програми (не використовуйте форми Amaroks, скористайтеся записом Amarok's).
  • Перетворіть всі зображення у формат PNG.
  • Вилучіть всі не-ASCII символи з назв зображень.

===Експортування===

  • Підготуйте список сторінок (без частин адрес UserBase, http://userbase.kde.org). Приклад для 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
Підказка
Отримати повний список сторінок вашої програми можна за допомогою такого скрипту:
<DPL>
  nottitlematch = %/__|%/zh-%|%(%)
  titlematch = Amarok%
  namespace = Main
  columns = 1
  format = ,\n* [[%PAGE%|%TITLE%]],,
</DPL>
Змініть Amarok на назву вашої програми, розмістіть скрипт на вашій сторінці користувача і натисніть кнопку Переглянути. Впорядкуйте отриманий список відповідно до змісту вашого підручника.


  • Вставте список сторінок до більшого поля для введення тексту.
  • Натисніть кнопку Експортувати.
Експортуванян сторінок підручника з Amarok
  • Збережіть файл. У подальшому ми використовуватимемо для файла назву Manual.xml.

Перетворення

  • Встановіть пакунок Subversion.
  • Отримайте найсвіжішу версію скрипту перетворення:
    svn checkout --depth=files svn://anonsvn.kde.org/home/kde/branches/work/doc/
  • Скопіюйте Manual.xml до теки скрипту.
  • Віддайте команду
    python wiki2docbook.py Manual.xml
    якщо потрібно звантажити ілюстрації до підручника (звантаження всіх ілюстрацій може тривати декілька хвилин UserBase, у системі має бути встановлено grep та wget) або командою
    python wiki2docbook.py -s Manual.xml
    якщо вам не потрібні ілюстрації.

Остаточна обробка

  • Перейменуйте Manual.xml.docbook на index.docbook.
  • Переконайтеся, що перетворення виконано без помилок:
    checkXML index.docbook
  • Виправте помилки форматування (краще на сторінках UserBase).
  • Перетворіть документ у формат HTML:
    meinproc4 index.docbook
  • Переконайтеся, що сторінки HTML буде показано правильно (всі зображення має бути показано, посилання мають працювати).
  • Замініть великі зображення на зменшені варіанти за допомогою програми convert з пакунка ImageMagick.
  • Виправте посилання у docbook так, щоб перехід за ними здійснювався до розділів docbook, а не до сторінок UserBase, якщо це можливо.
  • Виправте записи назви програми відповідно до списку записів (entity) KDE.
  • Скопіюйте index.docbook та зображення до вашої теки /doc, а потім надішліть їх до сховища коду.
Документація з K3b на UserBase у Opera та перетворена сторінка у Konqueror.

Оновлення вашого підручника у форматі DocBook з 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.

Перетворення даних у форматі DocBook на дані у інших форматах

Перетворення на дані у форматі 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:
svn co svn://anonsvn.kde.org/home/kde/trunk/www/areas/docs/dblatex-cvs-install/
  • 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.
  • 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.