styles & conventions

The following details the writing style and documentation conventions used in this manual.

🔗Формат

Цей веб-сайт створений у чистому markdown, використовуючи деякі розширення. Спочатку він був розроблений для роботи з Hugo SSG, але призначений бути достатньо портативним, щоб його можна було легко опублікувати за допомогою іншої програми, якщо потрібно.

Файли повинні відображатися в UTF-8 і не повинні містити перенесення рядків у параграфах.

🔗Структура

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

example-chapter/
   _index.md
   section1-with-subsections/
      subsection1/
         image.png
      _index.md
      subsection1.md
      subsection2.md
   section2.md
   section3.md

A couple of notes on the above structure:

Файли _index.md не містять жодного вмісту (вони містять лише метадані) і використовуються для візуалізації заголовків розділів та записів змісту (переліку глав). У наведеному вище прикладі example-chapter/_index.md визначає заголовок глави та порядок, у якому він відображається в головному змісті. Подібним чином example-chapter/section1-with-subsections/_index.md визначає метадані для першого розділу глави.
Медіафайли повинні міститися в каталозі з тим самим іменем, що і сторінка, до якої вони стосуються. У цьому прикладі, example-chapter/section1-with-subsections/subsection1 містить медіа, пов’язані зі сторінкою subsection1.md.

🔗Метадані

Метадані файлів markdown представлені вгорі сторінки за допомогою yaml. Будь-які метадані можуть бути визначені – розділи довідки про модулі містять досить багато специфічних метаданих, однак наступні визначають деякі мінімальні метадані для прикладу сторінки example-chapter/section1-with-subsections/subsection1.md.

---
title: Sub Section 1 Title
id: subsection1
weight: 10
include_toc: true
---

title: Це повинно містити відображений заголовок вашої сторінки. Щоб включити двокрапку в заголовок, вкладіть заголовок у подвійні лапки.
id: Цей ідентифікатор використовується для ідентифікації сторінки програмою Hugo. Зазвичай це має бути те саме ім’я, що й ім’я файлу (для файлів вмісту) або батьківського каталогу (для файлів _index.md).
weight: Це необов’язкове поле метаданих, що використовується для визначення послідовності подання розділів у Змісті. Якщо поле weight не включено, сторінки за замовчуванням відображатимуться в алфавітному порядку. Наприклад, щоб визначити розділи та підрозділи наведеного прикладу в зворотному порядку, потрібно встановити такі метадані:

   example-chapter/
      section1-with-subsections/
         _index.md               # weight: 30 (розмістити сторінку section1 в кінці example-chapter)
         subsection1.md             # weight: 20 (розмістити сторінку subsection1 в кінці section1)
         subsection2.md             # weight: 10 (розмістити сторінку subsection2 на початку section1)
      section2.md                # weight: 20 (розмітити section2 у середині example-chapter)
      section3.md                # weight: 10 (розмістити section3 на початку example-chapter)

include_toc: Optional; enables or disables the collapsible table of contents. Should only be used on large, complex pages.

🔗Вміст

🔗Загальні вказівки щодо стилю

Весь вміст повинен бути написаний у звичайному markdown без шорткодів, а HTML повинен бути зведений до абсолютного мінімуму, якщо взагалі використовується
Мінімалізм є абсолютно необхідним. Віддається перевага меншій кількості слів
Файли розмітки markdown повинні бути якомога коротшими
Дотримуйтесь норм написання великих літер, присутніх у графічному інтерфейсі програми – а саме всі заголовки мають бути в нижньому регістрі, за винятком імен глав найвищого рівня. Аналогічно, використовуйте нижній регістр, посилаючись на імена модулів та елементи керування.
Заголовки у файлі не повинні перевищувати три рівня (###)
Первинна мова створення контенту – англійська. По можливості уникайте ідіоматичних виразів, оскільки англійську версію документації можуть читати люди, для яких англійська мова не є рідною
Вважайте, що читач відкриває програму під час читання посібника користувача та включайте зображення лише там, де вони сприяють поясненню складної функціональності
Використовуйте виноски зображень, якщо вам потрібно анотувати зображення (тобто позначте частини зображення буквою або цифрою, а потім поясніть значення у тексті, що слідує за зображенням). Не розміщуйте слова безпосередньо на зображенні для анотацій, оскільки це ускладнює локалізацію. Див. цю сторінку для прикладу.
Зміни у вмісті слід пропонувати за допомогою запиту на прийняття змін (pull request) в GitHub або подібного механізму
Ваші подання будуть відредаговані – не сприймайте це особисто

🔗technical information for processing modules

For each of the processing modules there is a special (collapsible) block of technical information at the top:

{{< details summary="Technical information" class="technical-info" >}}

description
: applies a tone mapping curve. inspired by Blender's AgX tone mapper.

purpose
: corrective and creative.

input
: linear, RGB, scene-referred.

processing
: non-linear, RGB.

output
: linear, RGB, display-referred

{{< /details >}}

This should mirror the information available as tooltip upon hovering the mouse over a processing module.

🔗Прискорювачі

Посилайтеся на іменовані клавіші клавіатури за допомогою CamelCase (Ctrl, Shift, Alt, Esc, AltGr, CapsLock, PageUp, PageDown)
Reference single letter keys in upper case. Quotation marks might help with clarification (press “H” to see a list of active shortcuts)
Посилайтеся на дії миші з використанням нижнього регістру з кількома словами, об’єднаними дефісом (scroll, click, single-click, double-click, right-click)
Connect combinations of keys/actions with a plus sign (Ctrl+Shift+H, Shift+double-click)

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

The standard method of presenting information about darktable module controls is with the use of definition lists.

Ім’я елемента керування

Декларація про те, що робить елемент керування. Наприклад “Встановити експозицію в одиницях EV”.

Ви можете включити скільки завгодно абзаців, але спробуйте обмежитись 2 або 3, де це можливо.

Елемент керування, доступ до якого здійснюється за допомогою кнопки зі значком

Коли елемент керування активується за допомогою значка, зробіть скріншот значка за допомогою стандартної теми (darktable-elegant-grey) та додайте його перед іменем елемента керування

Ім’я поля зі списком

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

перше значення: Що означає перше значення

друге значення: Що означає друге значення

Списки визначень також використовуються у всьому документі, скрізь, де має бути визначена іменована частина функціональності. Дивіться, наприклад, darktable-cli.

🔗Примітки

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

Примітка: Це важлива примітка.

🔗Шрифти фіксованої ширини та блоки коду

Шрифти з фіксованою шириною (із використанням символу `) зазвичай слід використовувати лише для блоків коду та при посиланні на імена файлів та параметри командного рядка.

🔗Посилання

Внутрішні посилання повинні бути відносними до поточного файлу та вказувати на дійсний файл розмітки markdown (.md). Почніть посилання або з ./ для представлення поточного каталогу або ../ для представлення батьківського каталогу.

Посилання на модуль обробки мають бути курсивом, напр. Експозиція
Посилання на сервісний модуль мають бути простим текстом, напр. Історія змін
Посилання на розділ верхнього рівня робіть, посилаючись на файл _index.md, наприклад Довідка про модулі
Посилання на вкладку в діалоговому вікні налаштувань: Налаштування > Загальні
Посилання на конкретний параметр налаштувань: Налаштування > Загальні > Мова інтерфейсу
На кожен заголовок на сторінці можна посилатись безпосередньо за допомогою прив’язки: внесок/примітки

🔗Зображення

Роблячи знімки екрана із самої програми Darktable, використовуйте тему Darktable за замовчуванням (darktable-elegant-grey).

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

icon: Щоб вставити зображення як значок, включіть #icon після імені зображення в посиланні. Розмітка ![squirrel icon](./contributing/contributing.png#icon) видає наступне:
ширина зображення: Ви можете встановити ширину зображення на 25, 33, 50, 66, 75 або 100 відсотків ширини відтвореної сторінки, включивши після назви зображення у посилання #wxx, де xx – бажана ширина. Наприклад:; ![squirrel](./contributing/squirrel.png#w25) виведе; ![squirrel](./contributing/squirrel.png#w75) виведе
inline: With the exception of icons, images are included as block elements by default. You can override this by including #inline after the image name. This can be combined with the width setting as follows.; ![squirrel](./contributing/squirrel.png#w25#inline) outputs
за замовчуванням: За замовчуванням зображення подаються як блокові елемент зі 100% шириною. Отже, ![squirrel](./contributing/squirrel.png#w100) і ![squirrel](./contributing/squirrel.png) є еквівалентними, і обидва видають наступне:

translations

English: styles & conventions