Внесок у dtdocs

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

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

Структура та зміст посібника були ретельно обмірковані на основі таких критеріїв:

  1. Посібник повинен бути вичерпним – він повинен описувати всю функціональність, доступну в Darktable
  2. Він повинен мати узгоджену та логічну структуру, і кожен елемент функціональності повинен мати своє логічне місце в цій структурі
  3. Він повинен бути настільки довгим, наскільки це потрібно, але настільки коротким, наскільки це можливо – стислість обов’язкова
  4. Він повинен бути об’єктивним
  5. Функціональність слід пояснити один раз і лише один раз (за винятком вказівок щодо базового робочого процесу в розділі огляду)
  6. Зображення слід включати лише там, де це необхідно для поліпшення розуміння ключових принципів, і вони не повинні містити текст, хіба що цього не уникнути

Нас, як правило, не цікавить:

  1. Реструктуризація посібника
  2. Зміна мови розмітки
  3. Детальні підручники з робочого процесу (хоча ми зацікавлені в їх публікації у блогах darktable.org або pixls.us)

Нас цікавить

  1. Виправлення правопису та граматики
  2. Уточнення тексту
  3. Документація щодо нових функцій

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

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

🔗Формат

Цей веб-сайт створений у чистому 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

Пара приміток щодо вищевказаної структури:

  • Файли _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)

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

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

Ім’я елемента керування
Декларація про те, що робить елемент керування. Наприклад “Встановити експозицію в одиницях 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
За винятком значків, зображення за замовчуванням включаються як блокові елементи. Ви можете замінити це, додавши після імені зображення #inline. Це можна поєднати з налаштуванням ширини наступним чином.
![squirrel](./contributing/squirrel.png#w25#inline) виведе squirrel
за замовчуванням
За замовчуванням зображення подаються як блокові елемент зі 100% шириною. Отже, ![squirrel](./contributing/squirrel.png#w100) і ![squirrel](./contributing/squirrel.png) є еквівалентними, і обидва видають наступне:
squirrel

translations