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

Other languages:

Вступ

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

.

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

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

Переконайтеся, що всі сторінки вашого підручника відповідають настановам для авторів UserBase та настановам з форматування.

Переконайтеся, що кожна зі сторінок має заголовок, відповідно до її місця у змісті підручника.

Довідкова таблиця
UserBase	Docbook	Коментар
==Розділ==	<chapter>
===Розділ===	<sect1>
====Розділ====	<sect2>
=====Розділ=====	<sect3>
======Розділ======	<sect4>	Намагайтеся уникати використання цього рівні.

Переконайтеся, що у всіх комірках таблиць після символу «|» стоїть пробіл. Це правило узгоджується з традиційним форматуванням у вікі.

Використовуйте однорідне форматування назви програми (не використовуйте форми Amaroks, скористайтеся записом Amarok's).

Перетворіть всі зображення у формат PNG.

Вилучіть всі не-ASCII символи з назв зображень.

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

Підготуйте список сторінок (без частин адрес UserBase, http://userbase.kde.org). Приклад для Amarok:

Amarok
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/AdvancedFeatures
Amarok/Manual/AdvancedFeatures/CollectionScanning
Amarok/Manual/AdvancedFeatures/CoverManager
Amarok/Manual/AdvancedFeatures/DynamicPlaylists
Amarok/Manual/AdvancedFeatures/AutomaticPlaylistGenerator
Amarok/Manual/AdvancedFeatures/ExternalDatabase
Amarok/Manual/AdvancedFeatures/AFT
Amarok/Manual/AdvancedFeatures/Moodbar
Amarok/Manual/AdvancedFeatures/WorkingWithMediaDevices
Amarok/Manual/AdvancedFeatures/SavedPlaylists
Amarok/Manual/AdvancedFeatures/PlaylistFiltering
Amarok/Manual/AdvancedFeatures/QueueManager
Amarok/Manual/AdvancedFeatures/SearchInCollection
Amarok/Manual/AdvancedFeatures/TagEditor
Amarok/Manual/AdvancedFeatures/OrganizeCollection
Amarok/Manual/AdvancedFeatures/Transcoding
Amarok/Manual/AdvancedFeatures/ScriptManager
Amarok/Manual/AdvancedFeatures/RemoteCollections
Amarok/Manual/AdvancedFeatures/RemoteCollections/Ampache
Amarok/Manual/AdvancedFeatures/RemoteCollections/DAAP
Amarok/Manual/AdvancedFeatures/RemoteCollections/Samba
Amarok/Manual/AdvancedFeatures/RemoteCollections/UPnP
Amarok/Manual/MenuAndCommandReference/AmarokMenu
Amarok/Manual/MenuAndCommandReference/ViewMenu
Amarok/Manual/MenuAndCommandReference/Playlist
Amarok/Manual/MenuAndCommandReference/Tools
Amarok/Manual/MenuAndCommandReference/Settings
Amarok/Manual/MenuAndCommandReference/Help
Amarok/Manual/KeybindingReference
Amarok/Manual/KeybindingReference/GlobalShortcuts
Amarok/Manual/KeybindingReference/AmarokShortcuts
Amarok/Manual/TroubleshootingAndCommonProblems
Amarok/Manual/AmarokOnOtherPlatforms/Non-KDE Desktops
Amarok/Manual/AmarokOnOtherPlatforms/Windows
Amarok/Manual/AmarokOnOtherPlatforms/OSX
Amarok/Manual/FAQ
Amarok/Manual/Credits_and_License

Підказка

Отримати повний список сторінок вашої програми можна за допомогою такого скрипту:

<DPL>
  nottitlematch = %/__|%/zh-%|%(%)
  titlematch = Amarok%
  namespace = Main
  columns = 1
  format = ,\n* [[%PAGE%|%TITLE%]],,
</DPL>

Змініть Amarok на назву вашої програми, розмістіть скрипт на вашій сторінці користувача і натисніть кнопку Переглянути. Впорядкуйте отриманий список відповідно до змісту вашого підручника.

Перейдіть на сторінку експортування.

Вставте список сторінок до більшого поля для введення тексту.

Натисніть кнопку Експортувати.

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

Conversion

Install Subversion package for your system.

Checkout the latest version of conversion script:

svn checkout --depth=files svn://anonsvn.kde.org/home/kde/branches/work/doc/

Copy Manual.xml to the script folder.

Run
```
python wiki2docbook.py Manual.xml
```
if you want to download all screenshots (it takes some time to download all images from UserBase, grep and wget should be installed), or
```
python wiki2docbook.py -s Manual.xml
```
if you need not to download images.

Post-processing

Rename Manual.xml.docbook to index.docbook.

Check if conversion was done correctly:
```
checkXML index.docbook
```

Fix the errors (better on UserBase pages).

Convert docbook to HTML:
```
meinproc4 index.docbook
```

Check HTML pages (all images should be visible, links should not lead to 404-pages).

Replace big images by thumbnails using convert from ImageMagick

Fix links in docbook, so they lead to docbook section, not UserBase pages.

Fix application name according to KDE entity list.

Copy index.docbook and images to your /doc folder and commit them to repository.