How To Convert a UserBase Manual to Docbook/uk: Difference between revisions
(Created page with "{{Note_(uk)|1=Якщо ви працюєте з підручником із Amarok, зважайте на те, що сторінки підручника названо не...") |
(Updating to match new version of source page) |
||
| Line 121: | Line 121: | ||
}} | }} | ||
{{ | {{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%}} | {{Input|1= titlematch = Amarok/Manual%{{!}}Amarok/QuickStartGuide%}} | ||
( | (Note: No space characters in title pattern!) | ||
}} | }} | ||
| Line 189: | Line 189: | ||
* Створіть файл скрипту (з назвою <tt>buildpdf.sh</tt>) у каталозі з вашими даними DocBook: | * Створіть файл скрипту (з назвою <tt>buildpdf.sh</tt>) у каталозі з вашими даними DocBook: | ||
{{Input|1= | |||
<syntaxhighlight lang="bash">#!/bin/bash | <syntaxhighlight lang="bash">#!/bin/bash | ||
export SGML_CATALOG_FILES=/usr/share/sgml/docbook/sqml-dtd-4. | 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 \ | ./dblatex-cvs-install/bin/dblatex -d -b pdftex --style \ | ||
kdestyle\ | kdestyle\ | ||
| Line 203: | Line 202: | ||
-I $KDEDIR/share/doc/HTML/en/ \ | -I $KDEDIR/share/doc/HTML/en/ \ | ||
-X \ | -X \ | ||
$1</syntaxhighlight>}} | $1</syntaxhighlight>}} | ||
* Отримайте стилі KDE: | * Отримайте стилі KDE: | ||
{{Input|1=<nowiki>git clone git://anongit.kde.org/websites/docs-kde-org.git</nowiki>}} | {{Input|1=<nowiki>git clone git://anongit.kde.org/websites/docs-kde-org.git</nowiki>}} | ||
Revision as of 17:10, 27 January 2019
Вступ
Так, поточна процедура доволі кострубата, код скрипту не дуже-то і красивий, скрипт недостатньо «розумний» тощо. Єдиним виправданням може слугувати те, що цей спосіб якось працює 
.
Якщо ви бажаєте удосконалити процедуру, маєте добрі навички з програмування мовою 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 на назву вашої програми, розмістіть скрипт на вашій сторінці користувача і натисніть кнопку . Впорядкуйте отриманий список відповідно до змісту вашого підручника.
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!)
- Перейдіть на сторінку експортування.
- Вставте список сторінок до поля для введення тексту.
- Натисніть кнопку .
- Збережіть файл. У подальшому ми використовуватимемо для файла назву Manual.xml.
Перетворення
- Встановіть пакунок Subversion.
- Отримайте найсвіжішу версію скрипту перетворення:
svn checkout --depth=files svn://anonsvn.kde.org/home/kde/branches/work/doc/
- Скопіюйте Manual.xml до теки скрипту.
- Додайте рядок, що міститиме
144.76.227.197 userbase.kde.org
, до файла /etc/hosts . (Для цього вам знадобляться права доступу адміністратора. Цю зміну слід зробити лише один раз.)
- Віддайте команду
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, а потім надішліть їх до сховища коду.
Оновлення вашого підручника у форматі 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 на ваш пристрій для читання електронних книжок.