Як перетворити підручник з UserBase на підручник у форматі Docbook
Вступ
Так, поточна процедура доволі кострубата, код скрипту не дуже-то і красивий, скрипт недостатньо «розумний» тощо. Єдиним виправданням може слугувати те, що цей спосіб якось працює .
Якщо ви бажаєте удосконалити процедуру, маєте добрі навички з програмування мовою Python, добре знайомі з принципами створення підручників у форматі docbook, ви можете докласти власних зусиль до покращення процесу. Будь ласка, зв’яжіться з користувачем Yurchor, якщо ви бажаєте допомогти.
Приготування сторінок до перетворення
- Переконайтеся, що всі сторінки вашого підручника відповідають настановам для авторів UserBase та настановам з форматування.
- Переконайтеся, що кожна зі сторінок має заголовок, відповідно до її місця у змісті підручника.
Довідкова таблиця 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-%|%pt-%|%(%) titlematch = Appname/Manual% namespace = columns = 1 format = ,\n* [[%PAGE%|%TITLE%]],, </DPL>Змініть Amarok на назву вашої програми, розмістіть скрипт на вашій сторінці користувача і натисніть кнопку . Впорядкуйте отриманий список відповідно до змісту вашого підручника.
titlematch = Amarok/Manual%|Amarok/QuickStartGuide%(Зауваження: у взірці немає символів пробілів!)
- Перейдіть на сторінку експортування.
- Вставте список сторінок до поля для введення тексту.
- Натисніть кнопку .
- Збережіть файл. У подальшому ми використовуватимемо для файла назву 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
якщо вам не потрібні ілюстрації.
144.76.227.197 userbase.kde.org
to /etc/hosts, щоб можна було отримати доступ до UserBase зі скрипту. Зараз цього робити не потрібно. Якщо ви вже додали цей рядок до вашого файла /etc/hosts, можете його вилучити.
Остаточна обробка
- Перейменуйте Manual.xml.docbook на index.docbook.
- Переконайтеся, що перетворення виконано без помилок:
checkXML index.docbook
- Виправте помилки форматування (краще на сторінках UserBase).
- Перетворіть документ у формат HTML:
meinproc4 index.docbook
- Переконайтеся, що сторінки HTML буде показано правильно (всі зображення має бути показано, посилання мають працювати).
- Замініть великі зображення на зменшені варіанти за допомогою програми convert з пакунка ImageMagick.
- Виправте посилання у docbook так, щоб перехід за ними здійснювався до розділів docbook, а не до сторінок UserBase, якщо це можливо.
- Виправте записи назви програми відповідно до списку записів (entity) KDE.
- Скопіюйте index.docbook та зображення до вашої теки /doc, а потім надішліть їх до сховища коду.
Оновлення вашого підручника у форматі DocBook з UserBase
Щоб оновити перетворений вами підручник у форматі docbook, будь ласка, виконайте такі дії:
- Повторно експортуйте дані у форматі XML з UserBase. Докладніший опис експорутвання наведено у розділі Експортування.
- Скористайтеся скриптом для оновлення вмісту (заголовок з резюме та ключовими словами, а також завершальний розділ буде збережено):
python wiki2docbook.py -r index.docbook Manual.xml
- Перевірте docbook, перейменуйте файл на index.docbook і надішліть його разом з новими знімками вікон до вашого сховища коду.
Перетворення даних у форматі DocBook на дані у інших форматах
Перетворення на дані у форматі PDF
Зазвичай, перетворювати DocBook вручну не потрібно. Перетворені у автоматичному режимі PDF можна знайти на сайті документації до KDE.
Якщо ви бажаєте виконати додаткове налаштування, будь ласка, скористайтеся такою послідовністю дій:
- Встановіть один з дистрибутивів LaTeX (наприклад TeXLive).
- Створіть файл скрипту (з назвою buildpdf.sh) у каталозі з вашими даними DocBook:
#!/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
- Отримайте стилі KDE:
git clone git://anongit.kde.org/websites/docs-kde-org.git
- Внесіть зміни до dblatex-cvs-install/bin/dblatex так, щоб вміст файла набув вигляду:
#!/bin/sh TEXINPUTS=:/path/to/your/dblatex-cvs-install/share/dblatex/latex//:$TEXINPUTS export TEXINPUTS /шлях/до/вашого/dblatex-cvs-install/share/dblatex/scripts/dblatex $*
(Замініть /шлях/до/вашого/ на адресу відповідного каталогу)
- Скопіюйте стилі KDE (/dblatex-cvs-install/share/dblatex/latex/contrib/) до якогось з каталогів TeX, де їх зможе виявити система LaTeX (наприклад, до /usr/share/texmf-dist/tex/latex/kde).
- Оновіть дані за допомогою команди
mktexlsr
, відданої від імені користувача root.
- Віддайте команду
./buildpdf.sh index.docbook
. У результаті має бути створено готовий до використання файл PDF. Ви можете зупинитися на цьому кроці, якщо не хочете у подальшому поліпшити результат перетворення.
- Скопіюйте всі файли з /tmp/tpb-ваш-користувач-цифри до вашого робочого каталогу.
- Внесіть потрібні зміни до файла tex за допомогою Kile.
- Зберіть файл PDF натисканням комбінації клавіш Alt + 6.
Перетворення даних у формат EPUB
- Встановіть у вашій системі пакунок програми Calibre.
- Спочатку перетворіть DocBook на дані у форматі HTML. Скористайтеся для цього командою
meinproc4 index.docbook
.
- Запустіть Calibre і виберіть пункт .
- Виберіть файл index.html у теці вашої DocBook. Зачекайте, доки книгу буде завантажено.
- Виберіть пункт .
- Заповніть поля метаданих.
- Натисніть і зачекайте, доки роботу буде виконано.
- Скопіюйте книгу з ~/Calibre Library на ваш пристрій для читання електронних книжок.