Правила розмітки у підручнику з Krita

Тут докладно викладено вимоги до стильового оформлення тексту у форматі restructured для підручника з Krita.

Рекомендуємо ознайомитися із офіційною специфікацією reStructuredText і, оскільки ця специфікація зберігається на sourceforge, збережіть копію на ваш диск (на час написання цього підручника у sourceforge є проблеми із працездатністю серверів):

Посібник користувача:
Довідкова документація:
Специфічна документація до Sphinx:

Існують відмінності між офіційною документацією reStructuredText та документацією sphinx, а також різні способи досягти того самого результату. У цьому підручнику описано рекомендовані способи форматування.

Метадані

Кожна сторінка має розпочинатися з трьох елементів:

  1. Метаопис

    Це загальний опис сторінки. Його буде перетворено на метамітку html, яка використовуватиметься рушіями пошуку:

    .. meta::
    :description:
        Опис.
  2. Список авторів та ліцензування.

    Просто для стеження за тим, хто редагував сторінку, та зазначення авторських прав. Дані має бути закоментовано, щоб комп’ютер не обробляв їх. Умовами ліцензування усього підручника є GDL 1.3, і про це також слід згадати:

    .. metadata-placeholder

   :authors: - Автор 1
             - Автор 2
   :license: GNU free documentation license 1.3 or later.
  3. Індексування термінів.

    Це список термінів, які відокремлено комами, призначений для індексування сторінки у Покажчик. Створений покажчик є доволі корисним для підручника у форматі PDF, а також читачів, яким потрібен пошук значень та прикладів за термінами. Список термінів визначається так:

    .. index:: Ключ, Ключове слово із пробілами, ! Ключове слово основного визначення
  4. Мітка.

    Цей запис призначено для полегшення посилання на сторінку за допомогою коду :ref:`назва_мітки`. Намагайтеся використовувати прості для використання назви змінних:

    .. _назва_мітки:

    Після мітки слід додати заголовок, оскільки :ref:`назва_мітки` використовуватиме текст заголовка як замінник самого посилання.

Заголовки

Заголовки буде створено у такому порядку:

############
Частина/Розділ
############

Для сторінок, які містять багато підсторінок.

===========
Заголовок 1
===========

Починайте сторінки підручника з цього.

Заголовок 2
-----------

Заголовок 3
~~~~~~~~~~~

Заголовок 4
^^^^^^^^^^^

Заголовок 5
'''''''''''

Заголовок 6
"""""""""""

Усі ці правила більшою чи меншою мірою визначила програма для перетворення даних mediawiki Pandoc до reStructuredText. Якщо у вас більше 4 рівнів заголовків, переконайтеся, що сторінка не є надто складною і не потребує поділу на частини.

Іноді потрібне посилання на підрозділ сторінки. Для створення такого посилання додайте мітку над заголовком.

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

Компонування

Посилання слід вказувати так: :ref:`назва_мітки`. Якщо замість самої мітки має бути показано якийсь текст, користуйтеся таким форматом: :ref:`показаний текст <назва_мітки>`.

Для посилань на зовнішні сторінки використовується команда `адреса`_ або `назва посилання <адреса>`_, яку буде показано так: назва посилання.

Pandoc перетворює посилання на `назва_посилання`__ і потім додає .. __ :url наприкінці документа. Це так зване «анонімне посилання», що означає, що залежно порядок посилань наприкінці документа залежатиме від від порядку посилань у тексті. Це може здатися незручним та складним, але як уже є. У цьому полягає причина того, що ми намагаємося уникати таких посилань.

Підрядкові примітки та посилання для подальшого читання

Підрядкові посилання можна створювати у три способи. Найпоширенішим є спосіб із автоматичною нумерацією посилань:

[1] є посиланням на підрядкову примітку 1, а [2] є посиланням на підрядкову примітку 2.

[3] є посиланням на підрядкову примітку 3.

Ось цитата: [CIT2002] .

[CIT2002]

Це цитата. Вона подібна до підрядкової примітки, але мітка у ній є текстовою.

На цитату також можна посилатися. Ось так: `цитата <CIT2002>`_.

Ми не використовуємо підрядкові посилання у підручнику через те, що вважаємо їх занадто академічними для наших читачів. Втім, ми збираємо посилання та документи, які викладають предмет сторінки ширше, наприкінці сторінки. У Sphinx передбачено команду .. seealso:: для визначення зовнішніх посилань, а у reStructuredText використовують .. rubic:: Footnotes для спеціально зібраних підрядкових приміток, оскільки так зручніше для перетворення на код LaTeX.

Зображення

Використання команди image для зображень без підписів:

.. image:: /images/sample.png
   :width: 800
   :align: center
   :alt: Зображення.

І команди для роботи із зображеннями з підписами:

.. figure:: /images/sample.png
   :figwidth: 800
   :align: center
   :alt: Зображення.

   Підпис -- зауважте, як вирівнюється перша літера із використанням параметра :figwidth:.

Остання дає такий результат:

an image.

Підпис — зауважте, що перша літера підпису у команді вирівняна з параметром :figwidth:.

Зображення мають зберігатися у каталозі /images. Використання /images замість images вказує sphinx на те, що шлях до файла не є відносним.

Розмітка у тексті

Ви можете робити фрагмент тексту курсивним або напівжирним за допомогою однією або двох зірочок, відповідно:

*emphasize*
**strong**

Не можна одночасно використовувати *нахилений і напівжирний*, доведеться вибрати щось одне.

Можна створювати нижні індекси та верхні індекси за допомогою команд :sub:`текст` та :sup:`текст`.

Втім, користуйтеся цим дуже обережно! Бажано використовувати наявне семантичне форматування у sphinx за будь-яких умов, оскільки це полегшує перекладачам визначення того, для чого призначено текст:

:menuselection:`Параметри --> Налаштувати Krita…`
:guilabel:`Файл`
:kbd:`Ctrl + Z`
:program:`Krita`

Уникайте випадкового позначення слів зміною стилю шрифту. Текст із частою зміною ваги шрифту не простіше читати.

Посилання на замінники

Ви можете створити певний різновид скорочень для фрагментів тексту або зображень за допомогою такого коду:

.. |shorthand| replace:: щось або ще щось.

Це означає, що якщо ви використаєте |shorthand|, у тексті його буде замінено на «something or the other». Це корисно для зображень і тексту, який має бути форматовано у складний спосіб, наприклад рядка «LaTeX».

У документації Krita використовуються |mouseleft|, |mousemiddle|, |mousescroll| та |mouseright|, які перетворюються на mouseleft, mousemiddle, mousescroll і mouseright, відповідно. Ці коди визначено conf.py sphinx, вони додаються до кожного файла rst.

Для посилань, якщо ви використовуєте посилання багато разів, ви можете написати щось подібне до такого наприкінці файла:

.. _bugzilla: https://bugs.kde.org/
.. _Krita Manual: https://docs.krita.org/

Далі, коли використовуватимете посилання, просто введіть `bugzilla`_, щоб отримати посилання на багзіллу зі словом-замінником посилання у тексті «bugzilla». `Krita Manual`_ буде перетворено на посилання на docs.krita.org із текстом «Krita Manual».

Списки

Упорядковані списки

  1. Яблуко

  2. Груша

  3. Банан

або…

  1. Стіл

  2. Стілець

  3. Шафа.

  1. Август

  2. Нерон

  3. Калігула

  4. Траян

Такі списки визначаються ось так:

1. Яблуко
2. Груша
3. Банан

#. Яблуко
#. Груша
#. Банан

A. Стіл
B. Стілець
C. Шафа

A. Стіл
#. Стілець
#. Шафа

I. Август
#. Нерон
#. Калігула
#. Траян

Неупорядковані списки

  • червоний

  • жовтий

  • зелений

    • морський зелений

    • жовтаво-зелений

    • синьо-зелений

    • темно-зелений

    • смарагдовий

      • темно-смарагдовий

      • світло-смарагдовий

        • дуже світлий смарагдовий.

  • синій

Визначаються ось так:

- червоний
- жовтий
- зелений
    - морська хвиля
    - мідянковий
    - зелено-синій
    - темно-зелений
    - смарагдовий
        - темно-смарагдовий
        - світло-смарагдовий
            - дуже світло-смарагдовий.
- синій

Списки визначень

Наше улюблене! Списки визначень особливо корисні при описів усіх пунктів на бічній панелі із короткими описами щодо кожного з них.

Визначення

Пояснення.

Інший варіант

Пояснення.

Для створення

Створити їх можна так:

Означення
     Пояснення.
Інший варіант
     Пояснення.

Таблиці

Призначення

Тип таблиці

список клавіатурних скорочень

Проста таблиця

таблиця із багатьма стовпчиками

Таблиця із ґраткою

Проста, але довга

Таблиця-список

Створено за допомогою такого коду:

============================= ============
Призначення                   Тип таблиці
============================= ==================
список скорочень              Проста таблиця
багато об'єднаних стовпчиків  Таблиця із ґраткою
Проста, але довга             Таблиця-список
============================= ============

+------------------------------+------------------+
|Призначення                   |Тип таблиці       |
+==============================+==================+
|список скорочень              |Проста таблиця    |
+------------------------------+------------------+
|багато об'єднаних стовпчиків  |Таблиця з ґраткою |
+------------------------------+------------------+
|Проста, але довга             |Таблиця-список    |
+------------------------------+------------------+

.. list-table::
   :header-rows: 1

   - * Призначення
     * Тип таблиці
   - * список скорочень
     * проста таблиця
   - * багато об'єднаних стовпчиків
     * таблиця з ґраткою
   - * проста, але довга
     * таблиця-список

Таблиці із повноцінною ґраткою найкраще використовувати, коли вам потрібні усі можливості таблиці: складні стовпчики та об’єднані рядки, але код таких таблиць є доволі складним. З цієї причини слід віддавати перевагу простому коду малих таблиць, а для довгих таблиць використовувати команду list, з якою простіше працювати.

Попередження та зауваження

Примітка

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

Можна використовувати такі попередження (за порядком критичності):

Підказка

Підказки корисні для зазначення додаткових відомостей щодо теми, яких немає у основному тексті. Приклад підказки: «У openSuse ці пакунки мають інші назви, ніж у Debian».

Порада

Додаткові відомості щодо того, як щось зробити. Приклад: «Ви можете створити шаблон на основі ваших улюблених налаштувань документа» або «Скористайтеся клавішею M для віддзеркалення полотна — це полегшить виявлення помилок під час малювання».

Важливо

Це щось, що варто зауважити, але не обов’язково у негативному сенсі.

Попередження

Загалом, це щось негативне.

Увага

Загальне привернення уваги. Скористайтеся цим, якщо тема є важливою, але не такою важливою, як, наприклад, втрата даних.

Застереження

Це форматування для випадків, коли можлива втрата даних, зокрема через те, що дані не було збережено, або через те, що у додатках Python ще не передбачено можливості скасовування дій.

Небезпека

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

Помилка

Ймовірно, не використовуватимуться у цьому підручнику. Sphinx може створювати такі сповіщення за визначеними вручну умовами, але у нашому варіанті цю можливість типово вимкнено.

Загальне попередження із довільним текстом.

Текст.

Створити його можна так:

.. admonition:: Загальне попередження із довільним текстом.

    Текст

Sphinx також додає:

.. seealso::

    Це корисно для збирання зовнішніх посилань.

Тобто, горизонтальні лінійки можна додавати за допомогою ----.

Команда рубрики

Команда rubric є командою створення заголовка, який на перший погляд виглядає як команда «topic», але якщо тема (topic) складається з декількох абзаців, рубрика це сам заголовок. Ось так:

.. rubric:: Команда рубрики

Отже, коли нею слід користуватися?

Користуйтеся рубриками, лише якщо впевнені, що тема є надто незначною, щоб мати належний заголовок.

Тема

Коли текст відокремлено від загального ходу думки сторінки, тобто він стосується іншої теми, поза межами теми сторінки.

Рубрика

Коли текст відокремлено від загального ходу думки сторінки, але він не потребує окремого заголовка.

Попередження

Лише якщо є семантична відповідність. Це особливо важливо для попереджень щодо небезпеки, оскільки надто часте їхнє використання може призвести до того, що користувач не звертатиме на них уваги.

Фрагменти коду

Вбудовані фрагменти коду можна створити за допомогою ``символів зворотних лапок``.

Багаторядкові фрагменти коду можна створювати, завершуючи попередній щодо них абзац послідовністю символів ::. Виглядає це так:

Це абзац, і ми визначаємо попередньо форматований фрагмент, ось так::

    Не забудьте додати пробіл або табуляцію після, перед початком фрагмента.

Ви також можете скористатися командою .. code::. Якщо ви додасте після неї назву мови програмування, текст буде оброблено відповідно до правил підсвічування синтаксичних конструкцій мови:

.. code:: python

    # Коментар Python
    def my_function():
        alist = []
        alist.append(1)
        string = "hello world"

Перетворюється на

# Коментар Python
def my_function():
    alist = []
    alist.append(1)
    string = "hello world"

щось інше…

// Коментар C++
int myFunction(int i) {
    i += 1;

    // Check if more than 12
    if (i>12) {
        i = 0;
    }
    return i;
}

/* Коментар CSS */
body {
    margin: 0 auto;
    /* is 800 still sensible? */
    max-width:800px;
    font-size:16px;
    color:#333;
    background-color: #eee;
    padding:1em;
    font-family:serif;
    line-height: 1.4;
}

<p>це <span style="font-style:italic">наш</span> <!-- коментар HTML --> абзац.</p>

Інший попередньо форматований текст

Можна
створювати фрагменти із попередньо визначеним форматуванням
тексту
додаванням
до кожного рядка
символу
вертикальної риски

Ось так:

| Зберегти
| форматування
| тексту
| можна додавши
| на початку
| кожного рядка
| символ вертикальної риски

Зазвичай, у підручнику не використовується. Слід використовувати лише за кончої потреби для представлення даних, які потребують точного форматування, але не у випадках, коли використання визначається лише естетичними міркуваннями.

Глосарії, списки термінів та покажчик

Це можливості sphinx.

Покажчик використовується у основному розділі. У поточній версії використовуються лише одинарні записи покажчика (без підлеглих записів).

Глосарії використовуються для деяких розділів щодо пунктів меню, але не для усіх.

Цитати

Цитати мають такий вигляд:

Не певний, чи потрібні цитати у підручнику для користувачів...

-- Wolthera

Це стане цитатою.

Не певний, чи потрібні цитати у підручнику для користувачів…

—Wolthera

Ми подекуди все використовуємо цитати. Намагайтеся додати посилання на ім’я, щоб вказати, чию цитату використано.

Текст, призначений лише для перекладів

Ви можете скористатися наведеним нижче кодом для включення тексту, який має сенс лише для перекладів підручника. Наприклад, ви можете надати читачам перекладеного підручника англійські еквіваленти назви певного пункту з довідковою метою:

.. only:: non_english

    Цей текст буде приховано в англійській версії, але його можна буде перекласти, і його
    буде показано у перекладених версіях.

Нотатки для перекладачів

Якщо ви перекладаєте підручник мовою, у якій не використовуються обмежувальні пробіли для слів (наприклад, китайською або японською), ви можете скористатися екранованим пробілом для відокремлення розмітки і слів. Це, зокрема, корисно для запису посилань на сторінки, ось так:

床前\ `明月 <https://krita.org/>`_\ 光

Зауважте, що під час перекладу на основі файла PO вам слід екранувати зворотну похилу риску ще однією зворотною похилою рискою:

床前\\ `明月 <https://krita.org/>`_\\ 光

The above produces «床前明月光», instead of «床前 明月 光».