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

Latest revision as of 09:20, 17 October 2019

Other languages:

English
català
dansk
français
русский
українська

Вступ

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

Якщо ви бажаєте удосконалити процедуру, маєте добрі навички з програмування мовою 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 на назву вашої програми, розмістіть скрипт на вашій сторінці користувача і натисніть кнопку Переглянути. Впорядкуйте отриманий список відповідно до змісту вашого підручника.

Зауваження

Якщо ви працюєте з підручником із 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
```
якщо вам не потрібні ілюстрації.

Warning

З якогось часу стало потрібним додавати рядок
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.

Натисніть Гаразд і зачекайте, доки роботу буде виконано.

Скопіюйте книгу з ~/Calibre Library на ваш пристрій для читання електронних книжок.

@@ Line 1: / Line 1: @@
 <languages />
 ==Вступ==
@@ Line 43: / Line 44: @@
 * Вилучіть всі не-ASCII символи з назв зображень.
-<span id="Export"></span>===Експортування===
+<span id="Export"></span>
+===Експортування===
 * Підготуйте список сторінок (без частин адрес UserBase, <nowiki>http://userbase.kde.org</nowiki>). Приклад для '''Amarok''':
@@ Line 109: / Line 111: @@
 {{Input|1=<nowiki><DPL>
-   nottitlematch = %/__|%/zh-%|%(%)
+   nottitlematch = %/__|%/zh-%|%pt-%|%(%)
-   titlematch = Amarok%
+   titlematch = Appname/Manual%
-   namespace = Main
+   namespace =
    columns = 1
    format = ,\n* [[%PAGE%|%TITLE%]],,
@@ Line 117: / Line 119: @@
 <!--{{-->Змініть '''''Amarok''''' на назву вашої програми, розмістіть скрипт на вашій сторінці користувача і натисніть кнопку <menuchoice>Переглянути</menuchoice>. Впорядкуйте отриманий список відповідно до змісту вашого підручника.
+}}
+{{Note_(uk)|1=Якщо ви працюєте з підручником із Amarok, зважайте на те, що сторінки підручника названо не у повній відповідності із правилами. Можете скористатися
+{{Input|1= titlematch = Amarok/Manual%{{!}}Amarok/QuickStartGuide%}}
+(Зауваження: у взірці немає символів пробілів!)
 }}
@@ Line 137: / Line 144: @@
 * Віддайте команду {{Input|1=python wiki2docbook.py Manual.xml}} якщо потрібно звантажити ілюстрації до підручника (звантаження всіх ілюстрацій може тривати декілька хвилин UserBase, у системі має бути встановлено grep та wget) або командою {{Input|1=python wiki2docbook.py -s Manual.xml}} якщо вам не потрібні ілюстрації.
+{{Warning|1=З якогось часу стало потрібним додавати рядок <br /><code>144.76.227.197 userbase.kde.org</code><br /> to <tt>/etc/hosts</tt>, щоб можна було отримати доступ до UserBase зі скрипту. Зараз цього робити не потрібно. Якщо ви вже додали цей рядок до вашого файла <tt>/etc/hosts</tt>, можете його вилучити.}}
 ===Остаточна обробка===
@@ Line 180: / Line 189: @@
 * Створіть файл скрипту (з назвою <tt>buildpdf.sh</tt>) у каталозі з вашими даними DocBook:
+{{Input|1=
-<!--}}-->{{Input|1=
 <syntaxhighlight lang="bash">#!/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
+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\
@@ Line 194: / Line 202: @@
 	-I $KDEDIR/share/doc/HTML/en/ \
 	-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>svn co svn://anonsvn.kde.org/home/kde/trunk/www/areas/docs/dblatex-cvs-install/</nowiki>}}
 * Внесіть зміни до <tt>dblatex-cvs-install/bin/dblatex</tt> так, щоб вміст файла набув вигляду:
@@ Line 215: / Line 222: @@
 * Оновіть дані за допомогою команди <code>mktexlsr</code>, відданої від імені користувача root.
-* Віддайте команду <code>./buildpdf.sh index.docbook</code>.
+* Віддайте команду <code>./buildpdf.sh index.docbook</code>. У результаті має бути створено готовий до використання файл PDF. Ви можете зупинитися на цьому кроці, якщо не хочете у подальшому поліпшити результат перетворення.
-* Copy all files from <tt>/tmp/tpb-'''''your_user'''''-'''''digits'''''</tt> to the work directory.
+* Скопіюйте всі файли з <tt>/tmp/tpb-'''''ваш-користувач'''''-'''''цифри'''''</tt> до вашого робочого каталогу.
-* Customize and edit <tt>tex</tt> file in [[Special:MyLanguage/Kile|Kile]] as appropriate.
+* Внесіть потрібні зміни до файла <tt>tex</tt> за допомогою [[Special:MyLanguage/Kile|Kile]].
-* Compile PDF file with <keycap>Alt + 6</keycap>.
+* Зберіть файл PDF натисканням комбінації клавіш <keycap>Alt + 6</keycap>.
 === Перетворення даних у формат EPUB ===
@@ Line 229: / Line 236: @@
 * Спочатку перетворіть DocBook на дані у форматі HTML. Скористайтеся для цього командою <code>meinproc4 index.docbook</code>.
-* Start '''Calibre''' and choose <menuchoice>Add books</menuchoice>.
+* Запустіть '''Calibre''' і виберіть пункт <menuchoice>Додати книги</menuchoice>.
-* Select <tt>index.html</tt> in your DocBook folder. Wait until the book is loaded.
+* Виберіть файл <tt>index.html</tt> у теці вашої DocBook. Зачекайте, доки книгу буде завантажено.
-* Choose <menuchoice>Convert books</menuchoice>.
+* Виберіть пункт <menuchoice>Перетворити книги</menuchoice>.
-* Fill the metadata fields as appropriate.
+* Заповніть поля метаданих.
-[[File:calibre.png|350px|center|thumb|Calibre conversion configuration page.]]
+[[File:calibre.png|350px|center|thumb|Сторінка налаштування перетворення Calibre.]]
-* Press <menuchoice>OK</menuchoice> and wait until the work is done.
+* Натисніть <menuchoice>Гаразд</menuchoice> і зачекайте, доки роботу буде виконано.
-* Copy the book from <tt>~/Calibre Library</tt> on your ebook reader.
+* Скопіюйте книгу з <tt>~/Calibre Library</tt> на ваш пристрій для читання електронних книжок.
 [[Category:Власний внесок/uk]]