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

    From KDE UserBase Wiki
    (Updating to match new version of source page)
    (Created page with "{{Note_(uk)|1=Якщо ви працюєте з підручником із Amarok, зважайте на те, що сторінки підручника названо не...")
    (One intermediate revision by the same user not shown)
    Line 111: Line 111:


    {{Input|1=<nowiki><DPL>
    {{Input|1=<nowiki><DPL>
       nottitlematch = %/__|%/zh-%|%(%)
       nottitlematch = %/__|%/zh-%|%pt-%|%(%)
       titlematch = Amarok%
       titlematch = Appname/Manual%
       namespace = Main
       namespace =  
       columns = 1
       columns = 1
       format = ,\n* [[%PAGE%|%TITLE%]],,
       format = ,\n* [[%PAGE%|%TITLE%]],,
    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
    {{Note_(uk)|1=Якщо ви працюєте з підручником із Amarok, зважайте на те, що сторінки підручника названо не у повній відповідності із правилами. Можете скористатися
    {{Input|1= titlematch = Amarok/Manual%{{!}}Amarok/QuickStartGuide%}}
    {{Input|1= titlematch = Amarok/Manual%{{!}}Amarok/QuickStartGuide%}}
    (Note: No space characters in title pattern!
    (Зауваження: у взірці немає символів пробілів!)
    }}
    }}



    Revision as of 06:17, 8 August 2018

    Other languages:

    Вступ

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

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

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

    • Переконайтеся, що кожна зі сторінок має заголовок, відповідно до її місця у змісті підручника.
    Довідкова таблиця
    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%
    (Зауваження: у взірці немає символів пробілів!)


    • Вставте список сторінок до більшого поля для введення тексту.
    • Натисніть кнопку Експортувати.
    Експортуванян сторінок підручника з Amarok
    • Збережіть файл. У подальшому ми використовуватимемо для файла назву 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, а потім надішліть їх до сховища коду.
    Документація з K3b на UserBase у Opera та перетворена сторінка у Konqueror.

    Оновлення вашого підручника у форматі 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.2/catalog:/usr/share/apps/ksgmltools2/customization/catalog.xml:/usr/share/sgml/docbook/xml-dtd-4.2/docbook
    
    ./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 на ваш пристрій для читання електронних книжок.