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

    From KDE UserBase Wiki
    (Created page with "=== Перетворення даних у формат EPUB ===")
    (Created page with "* Встановіть у вашій системі пакунок програми '''Calibre'''.")
    Line 225: Line 225:
    === Перетворення даних у формат EPUB ===
    === Перетворення даних у формат EPUB ===


    * Make sure that '''Calibre''' is installed in your system.
    * Встановіть у вашій системі пакунок програми '''Calibre'''.


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

    Revision as of 17:33, 21 November 2011

    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.

    Якщо ви бажаєте виконати додаткове налаштування, будь ласка, скористайтеся такою послідовністю дій:

    • 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
    
    ./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
    
    • Звантажте стилі KDE:
    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
    
    /шлях/до/вашого/dblatex-cvs-install/share/dblatex/scripts/dblatex  $*
    

    (Замініть /шлях/до/вашого/ на адресу відповідного каталогу)

    • 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).
    • Оновіть дані за допомогою команди mktexlsr, відданої від імені користувача root.
    • Віддайте команду ./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.

    Перетворення даних у формат EPUB

    • Встановіть у вашій системі пакунок програми Calibre.
    • 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.