styles and 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
---
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)

🔗Вміст

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

  • All content should be authored in plain markdown without shortcodes and HTML should be kept to an absolute minimum, if used at all

  • Мінімалізм є абсолютно необхідним. Віддається перевага меншій кількості слів

  • Файли розмітки markdown повинні бути якомога коротшими

  • Дотримуйтесь норм написання великих літер, присутніх у графічному інтерфейсі програми – а саме всі заголовки мають бути в нижньому регістрі, за винятком імен глав найвищого рівня. Аналогічно, використовуйте нижній регістр, посилаючись на імена модулів та елементи керування.

  • Заголовки у файлі не повинні перевищувати три рівня (###)

  • Первинна мова створення контенту – англійська. По можливості уникайте ідіоматичних виразів, оскільки англійську версію документації можуть читати люди, для яких англійська мова не є рідною

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

  • Використовуйте виноски зображень, якщо вам потрібно анотувати зображення (тобто позначте частини зображення буквою або цифрою, а потім поясніть значення у тексті, що слідує за зображенням). Не розміщуйте слова безпосередньо на зображенні для анотацій, оскільки це ускладнює локалізацію. Див. цю сторінку для прикладу.

  • Зміни у вмісті слід пропонувати за допомогою запиту на прийняття змін (pull request) в GitHub або подібного механізму

  • Ваші подання будуть відредаговані – не сприймайте це особисто

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

  • Посилайтеся на іменовані клавіші клавіатури за допомогою CamelCase (Ctrl, Shift, Alt, Esc, AltGr, CapsLock, PageUp, PageDown)

  • Посилайтеся на клавіші з однією літерою в нижньому регістрі (це дозволяє уникнути плутанини між, наприклад, Ctrl+H і Ctrl+Shift+h). Лапки можуть допомогти з роз’ясненням (як от: натисніть “h”, щоб побачити список активних прискорювачів)

  • Посилайтеся на дії миші з використанням нижнього регістру з кількома словами, об’єднаними дефісом (scroll, click, single-click, double-click, right-click)

  • З’єднуйте комбінації клавіш/дій знаком плюс (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, де це можливо.

active-icon Елемент керування, доступ до якого здійснюється за допомогою кнопки зі значком
Коли елемент керування активується за допомогою значка, зробіть скріншот значка за допомогою стандартної теми (darktable-elegant-grey) та додайте його перед іменем елемента керування
Ім’я поля зі списком
Поля зі списком часто мають кілька опцій, які всі потрібно відображати з окремими визначеннями. Використовуйте марковані списки з курсивом для значень поля.
  • перше значення: Що означає перше значення
  • друге значення: Що означає друге значення

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

🔗Примітки

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

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

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

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

🔗Посилання

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

🔗Зображення

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

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

icon
Щоб вставити зображення як значок, включіть #icon після імені зображення в посиланні. Розмітка ![squirrel icon](./contributing/contributing.png#icon) видає наступне: squirrel icon
ширина зображення
Ви можете встановити ширину зображення на 25, 33, 50, 66, 75 або 100 відсотків ширини відтвореної сторінки, включивши після назви зображення у посилання #wxx, де xx – бажана ширина. Наприклад:
![squirrel](./contributing/squirrel.png#w25) виведе
squirrel
![squirrel](./contributing/squirrel.png#w75) виведе
squirrel
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 squirrel
за замовчуванням
За замовчуванням зображення подаються як блокові елемент зі 100% шириною. Отже, ![squirrel](./contributing/squirrel.png#w100) і ![squirrel](./contributing/squirrel.png) є еквівалентними, і обидва видають наступне:
squirrel

translations