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

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

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

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

Експортуванян сторінок підручника з 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

  якщо вам не потрібні ілюстрації.

Остаточна обробка

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

• Виправте записи назви програми відповідно до списку записів (entity) KDE.

• Скопіюйте index.docbook та зображення до вашої теки /doc, а потім надішліть їх до сховища коду.

Документація з K3b на UserBase у Opera та перетворена сторінка у Konqueror.