ຮູບແບບ ແລະ ຂໍ້ກຳນົດ (styles & conventions)

ຕໍ່ໄປນີ້ແມ່ນລາຍລະອຽດກ່ຽວກັບຮູບແບບການຂຽນ ແລະ ຂໍ້ກຳນົດຂອງເອກະສານທີ່ໃຊ້ໃນຄູ່ມືນີ້.

🔗ຮູບແບບ (format)

ເວັບໄຊນີ້ຖືກຂຽນຂຶ້ນດ້ວຍ markdown ແທ້ໆ, ໂດຍໃຊ້ບາງສ່ວນຂະຫຍາຍ. ໃນເບື້ອງຕົ້ນມັນຖືກອອກແບບມາເພື່ອໃຊ້ກັບ Hugo SSG ແຕ່ກໍຕັ້ງໃຈໃຫ້ມັນສາມາດພົກພາໄດ້ງ່າຍ ເພື່ອໃຫ້ສາມາດສະແດງຜົນດ້ວຍແອັບພລິເຄຊັນອື່ນໄດ້ຫາກຈຳເປັນ.

ໄຟລ໌ຄວນຖືກສະແດງຜົນໃນຮູບແບບ UTF-8 ແລະ ບໍ່ຄວນມີການຂຶ້ນແຖວໃໝ່ (column wrapping) ພາຍໃນປະໂຫຍກ.

🔗ໂຄງສ້າງ

ຕໍ່ໄປນີ້ແມ່ນຕົວຢ່າງໂຄງສ້າງຂອງບົດຫຼັກທີ່ມີບົດຍ່ອຍໃນເວັບໄຊ dtdocs.

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

ບາງຂໍ້ສັງເກດກ່ຽວກັບໂຄງສ້າງຂ້າງເທິງ:

ໄຟລ໌ _index.md ຈະບໍ່ມີເນື້ອຫາໃດໆ (ມີພຽງແຕ່ metadata ເທົ່ານັ້ນ) ແລະ ຖືກໃຊ້ເພື່ອສະແດງຫົວຂໍ້ພາກສ່ວນ ແລະ ລາຍການໃນສານບານ (ToC). ໃນຕົວຢ່າງຂ້າງເທິງ example-chapter/_index.md ກຳນົດຊື່ຂອງບົດຕົວຢ່າງ ແລະ ລຳດັບທີ່ຈະປາກົດໃນສານບານຫຼັກ. ໃນທຳນອງດຽວກັນ example-chapter/section1-with-subsections/_index.md ກໍກຳນົດ metadata ສຳລັບພາກສ່ວນທຳອິດຂອງບົດ.
ໄຟລ໌ສື່ (Media files) ຄວນຖືກເກັບໄວ້ໃນໂຟນເດີທີ່ມີຊື່ດຽວກັນກັບ ໜ້າທີ່ມັນກ່ຽວຂ້ອງ. ໃນຕົວຢ່າງນີ້, example-chapter/section1-with-subsections/subsection1 ມີສື່ທີ່ກ່ຽວຂ້ອງກັບໜ້າ subsection1.md.

🔗ຂໍ້ມູນເສີມ (metadata)

Metadata ສຳລັບໄຟລ໌ markdown ແມ່ນຢູ່ສ່ວນຫົວຂອງໜ້າໂດຍໃຊ້ yaml. ສາມາດກຳນົດ metadata ໃດໆກໍໄດ້ – ສ່ວນການອ້າງອີງໂມດູນຈະມີ metadata ສະເພາະຂ້ອນຂ້າງຫຼາຍ – ແນວໃດກໍຕາມ ຕົວຢ່າງລຸ່ມນີ້ແມ່ນ metadata ພື້ນຖານສຳລັບໜ້າ example-chapter/section1-with-subsections/subsection1.md.

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

title: ສ່ວນນີ້ຄວນມີຊື່ຂອງໜ້າທີ່ຈະຖືກສະແດງຜົນ. ຫາກຕ້ອງການໃສ່ເຄື່ອງໝາຍຈ້ຳສອງ (:) ໃນຊື່, ໃຫ້ຂຽນຊື່ໄວ້ໃນເຄື່ອງໝາຍຄຳເວົ້າ ("").
id: ນີ້ຄື id ທີ່ Hugo ໃຊ້ເພື່ອລະບຸໜ້າເວັບ. ໂດຍປົກກະຕິຄວນເປັນຊື່ດຽວກັນກັບຊື່ໄຟລ໌ (ສຳລັບໄຟລ໌ເນື້ອຫາ) ຫຼື ຊື່ໂຟນເດີຫຼັກ (ສຳລັບໄຟລ໌ _index.md).
weight: ນີ້ແມ່ນຟິລ metadata ທາງເລືອກທີ່ໃຊ້ເພື່ອລຳດັບການສະແດງຜົນໃນສານບານ. ຖ້າບໍ່ໄດ້ໃສ່ weight, ໜ້າເວັບຈະຖືກລຽງຕາມລຳດັບຕົວອັກສອນໂດຍອັດຕະໂນມັດ. ຕົວຢ່າງ, ຖ້າຕ້ອງການລຽງພາກສ່ວນ ແລະ ພາກສ່ວນຍ່ອຍໃນຕົວຢ່າງຂ້າງເທິງແບບຢ້ອນກັບ, ຈະຕ້ອງກຳນົດ metadata ດັ່ງນີ້:

   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: ທາງເລືອກ; ໃຊ້ເພື່ອເປີດ ຫຼື ປິດສານບານແບບພັບໄດ້. ຄວນໃຊ້ສະເພາະໃນໜ້າທີ່ມີເນື້ອຫາຫຼາຍ ແລະ ຊັບຊ້ອນເທົ່ານັ້ນ.

🔗ເນື້ອຫາ (content)

🔗ຄຳແນະນຳຮູບແບບທົ່ວໄປ

ເນື້ອຫາທັງໝົດຄວນຂຽນດ້ວຍ markdown ທຳມະດາໂດຍບໍ່ໃຊ້ shortcodes ແລະ ຄວນໃຊ້ HTML ໃຫ້ໜ້ອຍທີ່ສຸດເທົ່າທີ່ຈະເຮັດໄດ້
ຄວາມລຽບງ່າຍ (Minimalism) ແມ່ນສິ່ງຈຳເປັນທີ່ສຸດ. ຄວນໃຊ້ຄຳສັບໃຫ້ໜ້ອຍແຕ່ໄດ້ໃຈຄວາມ
ໄຟລ໌ Markdown ຄວນມີຄວາມຍາວສັ້ນທີ່ສຸດເທົ່າທີ່ຈະເຮັດໄດ້
ປະຕິບັດຕາມການຕັ້ງຊື່ ແລະ ການໃຊ້ຕົວພິມໃຫຍ່/ນ້ອຍ ຕາມທີ່ປາກົດໃນ GUI ຂອງແອັບພລິເຄຊັນ – ນັ້ນຄື ຫົວຂໍ້ ແລະ ຊື່ທັງໝົດໃຫ້ໃຊ້ຕົວພິມນ້ອຍ, ຍົກເວັ້ນຊື່ບົດໃນລະດັບສູງສຸດ. ໃນທຳນອງດຽວກັນ, ໃຫ້ໃຊ້ຕົວພິມນ້ອຍທັງໝົດເມື່ອອ້າງອີງເຖິງຊື່ໂມດູນ ແລະ ປຸ່ມຄວບຄຸມ.
ຫົວຂໍ້ໃນໄຟລ໌ບໍ່ຄວນເກີນລະດັບສາມ (###)
The primary authoring language is American English (which is what the application uses). Avoid idiomatic language where possible as the English version of the documentation may be read by people for whom English is not their native language
ໃຫ້ຄິດສະເໝີວ່າຜູ້ອ່ານກຳລັງເປີດແອັບພລິເຄຊັນຢູ່ຂະນະທີ່ອ່ານຄູ່ມື ແລະ ໃຫ້ໃສ່ຮູບພາບສະເພາະບ່ອນທີ່ມັນຊ່ວຍອະທິບາຍຟັງຊັນທີ່ຊັບຊ້ອນເທົ່ານັ້ນ
ໃຊ້ image callouts ຫາກເຈົ້າຕ້ອງການອະທິບາຍຮູບພາບ (ເຊັ່ນ: ໝາຍສ່ວນຕ່າງໆຂອງຮູບດ້ວຍຕົວອັກສອນ ຫຼື ຕົວເລກ ແລ້ວອະທິບາຍຄວາມໝາຍໃນຂໍ້ຄວາມຫຼັງຮູບ). ຫ້າມໃສ່ຂໍ້ຄວາມລົງໃນຮູບໂດຍກົງ ເພາະຈະເຮັດໃຫ້ການແປພາສາເຮັດໄດ້ຍາກ. ເບິ່ງຕົວຢ່າງໄດ້ທີ່ ໜ້ານີ້.
ການປ່ຽນແປງເນື້ອຫາຄວນຖືກສະເໜີຜ່ານ pull request ຫຼື ວິທີການທີ່ຄ້າຍຄືກັນ
ສິ່ງທີ່ເຈົ້າສົ່ງມາຈະຖືກກວດແກ້ຮູບແບບ (copy-edited) – ຂໍຢ່າຖືສາກັນ

🔗ຂໍ້ມູນທາງເຕັກນິກສຳລັບໂມດູນການປະມວນຜົນ

ສຳລັບແຕ່ລະໂມດູນການປະມວນຜົນ ຈະມີບລັອກຂໍ້ມູນທາງເຕັກນິກພິເສດ (ແບບພັບໄດ້) ຢູ່ທາງເທິງ:

{{< 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 >}}

ສ່ວນນີ້ຄວນສະແດງຂໍ້ມູນໃຫ້ກົງກັບ tooltip ທີ່ປາກົດຂຶ້ນເມື່ອເອົາເມົ້າໄປວາງໄວ້ເທິງໂມດູນການປະມວນຜົນ.

🔗ທາງລັດຄີບອດ ແລະ ເມົ້າ

ອ້າງອີງເຖິງປຸ່ມຄີບອດໂດຍໃຊ້ຮູບແບບ CamelCase (Ctrl, Shift, Alt, Esc, AltGr, CapsLock, PageUp, PageDown)
ອ້າງອີງເຖິງປຸ່ມຕົວອັກສອນດຽວດ້ວຍຕົວພິມໃຫຍ່. ການໃຊ້ເຄື່ອງໝາຍຄຳເວົ້າອາດຊ່ວຍໃຫ້ແຈ້ງຂຶ້ນ (ກົດ “H” ເພື່ອເບິ່ງລາຍການທາງລັດທີ່ໃຊ້ງານຢູ່)
ອ້າງອີງເຖິງການກະທຳຂອງເມົ້າໂດຍໃຊ້ຕົວພິມນ້ອຍ, ຖ້າມີຫຼາຍຄຳໃຫ້ເຊື່ອມດ້ວຍເຄື່ອງໝາຍຂີດກາງ (scroll, click, single-click, double-click, right-click)
ເຊື່ອມຕໍ່ການກົດປຸ່ມ ຫຼື ການກະທຳທີ່ໃຊ້ຮ່ວມກັນດ້ວຍເຄື່ອງໝາຍບວກ (Ctrl+Shift+H, Shift+double-click)

🔗ລາຍການຄຳຈຳກັດຄວາມ (definition lists)

ວິທີການມາດຕະຖານໃນການສະແດງຂໍ້ມູນກ່ຽວກັບປຸ່ມຄວບຄຸມໂມດູນຂອງ darktable ແມ່ນການໃຊ້ລາຍການຄຳຈຳກັດຄວາມ.

ຊື່ປຸ່ມຄວບຄຸມໃນ GUI

ຄຳອະທິບາຍວ່າປຸ່ມນັ້ນເຮັດຫຍັງ. ຕົວຢ່າງ “ກຳນົດຄ່າການຮັບແສງ (exposure) ໃນຫົວໜ່ວຍ EV”.

ເຈົ້າສາມາດໃສ່ຫຼາຍຫຍໍ້ໜ້າໄດ້ຕາມຕ້ອງການ, ແຕ່ພະຍາຍາມຈຳກັດໄວ້ພຽງ 2 ຫຼື 3 ຫຍໍ້ໜ້າຫາກເປັນໄປໄດ້.

ປຸ່ມຄວບຄຸມທີ່ເຂົ້າເຖິງຜ່ານປຸ່ມທີ່ມີໄອຄອນ

ເມື່ອປຸ່ມຄວບຄຸມຖືກເປີດໃຊ້ດ້ວຍໄອຄອນ, ໃຫ້ຖ່າຍຮູບໜ້າຈໍຂອງໄອຄອນນັ້ນໂດຍໃຊ້ທີມມາດຕະຖານຂອງ darktable (darktable-elegant-grey) ແລະ ເພີ່ມມັນໄວ້ກ່ອນຊື່ຂອງປຸ່ມຄວບຄຸມ

gui combobox name

Comboboxes (ກ່ອງລາຍການເລືອກ) ມັກຈະມີຫຼາຍຕົວເລືອກເຊິ່ງທັງໝົດຕ້ອງໄດ້ຮັບການສະແດງພ້ອມກັບຄຳອະທິບາຍແຍກຕ່າງຫາກ. ໃຫ້ໃຊ້ລາຍການແບບຈ້ຳເມັດ (bulleted lists) ດ້ວຍ ໂຕອຽງ ສຳລັບຄ່າຕ່າງໆໃນ combobox.

ຄ່າທີໜຶ່ງ: ຄວາມໝາຍຂອງຄ່າທີໜຶ່ງ

ຄ່າທີສອງ: ຄວາມໝາຍຂອງຄ່າທີສອງ

ລາຍການຄຳຈຳກັດຄວາມຍັງຖືກໃຊ້ທົ່ວທັງເອກະສານ ໃນບ່ອນໃດກໍຕາມທີ່ຕ້ອງກຳນົດຊື່ຂອງຟັງຊັນ. ເບິ່ງຕົວຢ່າງໄດ້ທີ່ darktable-cli.

🔗ໝາຍເຫດ (notes)

ຖ້າເຈົ້າຕ້ອງການສະແດງໝາຍເຫດທີ່ສຳຄັນໃຫ້ຜູ້ໃຊ້ເຫັນ, ໃຫ້ໃຊ້ຮູບແບບດັ່ງນີ້:

ໝາຍເຫດ: ນີ້ຄືໝາຍເຫດທີ່ສຳຄັນ.

🔗ຟອນແບບຄວາມກວ້າງຄົງທີ່ (fixed-width) ແລະ ບລັອກໂຄດ

ຟອນແບບຄວາມກວ້າງຄົງທີ່ (ໃຊ້ເຄື່ອງໝາຍ `) ໂດຍປົກກະຕິຄວນໃຊ້ສະເພາະກັບບລັອກໂຄດ ແລະ ເມື່ອອ້າງອີງເຖິງຊື່ໄຟລ໌ ຫຼື ພາຣາມິເຕີຄຳສັ່ງ (command line parameters) ເທົ່ານັ້ນ.

🔗ລິ້ງ (links)

ລິ້ງພາຍໃນຕ້ອງເປັນລິ້ງແບບ relative ທີ່ອ້າງອີງຈາກໄຟລ໌ປັດຈຸບັນ ແລະ ຕ້ອງຊີ້ໄປຫາໄຟລ໌ markdown (.md) ທີ່ຖືກຕ້ອງ. ເລີ່ມຕົ້ນລິ້ງດ້ວຍ ./ ເພື່ອແທນໂຟນເດີປັດຈຸບັນ ຫຼື ../ ເພື່ອແທນໂຟນເດີຫຼັກ.

ລິ້ງທີ່ຊີ້ໄປຫາໂມດູນການປະມວນຜົນຄວນເປັນຕົວອຽງ, ເຊັ່ນ exposure
ລິ້ງທີ່ຊີ້ໄປຫາໂມດູນອັດຖະປະໂຫຍດ (utility module) ຄວນເປັນຂໍ້ຄວາມທຳມະດາ, ເຊັ່ນ history stack
ລິ້ງໄປຫາພາກສ່ວນລະດັບສູງສຸດໂດຍການອ້າງອີງໄຟລ໌ _index.md, ເຊັ່ນ module reference
ລິ້ງໄປຫາແທັບໃນໜ້າຕ່າງການຕັ້ງຄ່າ: preferences > general
ລິ້ງໄປຫາການຕັ້ງຄ່າສະເພາະ: preferences > general > interface language
ແຕ່ລະຫົວຂໍ້ພາຍໃນໜ້າສາມາດລິ້ງໄປຫາໄດ້ໂດຍກົງດ້ວຍ anchor link: contributing/notes

🔗ຮູບພາບ (images)

ເມື່ອຖ່າຍຮູບໜ້າຈໍຈາກແອັບພລິເຄຊັນ darktable, ໃຫ້ໃຊ້ທີມມາດຕະຖານ (darktable-elegant-grey).

ສາມາດໃຊ້ຄຳຕໍ່ທ້າຍຊື່ໄຟລ໌ຫຼາຍແບບເພື່ອຄວບຄຸມການສະແດງຜົນຂອງຮູບພາບ.

icon: ເພື່ອແຊກຮູບພາບເປັນໄອຄອນ, ໃຫ້ໃສ່ #icon ຕໍ່ທ້າຍຊື່ຮູບໃນລິ້ງ. ໂຄ້ດ markdown ![squirrel icon](./styles-conventions/contributing.png#icon) ຈະສະແດງຜົນດັ່ງນີ້:
ຄວາມກວ້າງຂອງຮູບ: ເຈົ້າສາມາດກຳນົດຄວາມກວ້າງຂອງຮູບເປັນ 25, 33, 50, 66, 75 ຫຼື 100 ເປີເຊັນ ຂອງຄວາມກວ້າງໜ້າເວັບ ໂດຍການໃສ່ #wxx ຕໍ່ທ້າຍຊື່ຮູບໃນລິ້ງ, ເຊິ່ງ xx ແມ່ນຄ່າຄວາມກວ້າງທີ່ຕ້ອງການ. ຕົວຢ່າງ:; ![squirrel](./styles-conventions/squirrel.png#w25) ຈະສະແດງຜົນ; ![squirrel](./styles-conventions/squirrel.png#w75) ຈະສະແດງຜົນ
inline: ຍົກເວັ້ນໄອຄອນ, ໂດຍປົກກະຕິຮູບພາບຈະຖືກສະແດງເປັນບລັອກ (block elements). ເຈົ້າສາມາດປ່ຽນແປງສິ່ງນີ້ໄດ້ໂດຍການໃສ່ #inline ຕໍ່ທ້າຍຊື່ຮູບ. ເຊິ່ງສາມາດໃຊ້ຮ່ວມກັບການກຳນົດຄວາມກວ້າງໄດ້ດັ່ງນີ້.; ![squirrel](./styles-conventions/squirrel.png#w25#inline) ຈະສະແດງຜົນ
ຄ່າມາດຕະຖານ (default): ໂດຍຄ່າມາດຕະຖານ ຮູບພາບຈະຖືກສະແດງເປັນບລັອກທີ່ມີຄວາມກວ້າງ 100%. ດັ່ງນັ້ນ ![squirrel](./styles-conventions/squirrel.png#w100) ແລະ ![squirrel](./styles-conventions/squirrel.png) ຈຶ່ງມີຄ່າເທົ່າກັນ ແລະ ທັງສອງຈະສະແດງຜົນດັ່ງນີ້: