ຮູບແບບ ແລະ ຂໍ້ກຳນົດ (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 ຂອງແອັບພລິເຄຊັນ – ນັ້ນຄື ຫົວຂໍ້ ແລະ ຊື່ທັງໝົດໃຫ້ໃຊ້ຕົວພິມນ້ອຍ, ຍົກເວັ້ນຊື່ບົດໃນລະດັບສູງສຸດ. ໃນທຳນອງດຽວກັນ, ໃຫ້ໃຊ້ຕົວພິມນ້ອຍທັງໝົດເມື່ອອ້າງອີງເຖິງຊື່ໂມດູນ ແລະ ປຸ່ມຄວບຄຸມ.

  • ຫົວຂໍ້ໃນໄຟລ໌ບໍ່ຄວນເກີນລະດັບສາມ (###)

  • ພາສາຫຼັກໃນການຂຽນແມ່ນພາສາອັງກິດ. ຫຼີກເວັ້ນການໃຊ້ສຳນວນພາສາຖ້າເປັນໄປໄດ້ ເນື່ອງຈາກເອກະສານພາກພາສາອັງກິດອາດຈະຖືກອ່ານໂດຍຜູ້ທີ່ບໍ່ໄດ້ໃຊ້ພາສາອັງກິດເປັນພາສາແມ່

  • ໃຫ້ຄິດສະເໝີວ່າຜູ້ອ່ານກຳລັງເປີດແອັບພລິເຄຊັນຢູ່ຂະນະທີ່ອ່ານຄູ່ມື ແລະ ໃຫ້ໃສ່ຮູບພາບສະເພາະບ່ອນທີ່ມັນຊ່ວຍອະທິບາຍຟັງຊັນທີ່ຊັບຊ້ອນເທົ່ານັ້ນ

  • ໃຊ້ 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 ຫຍໍ້ໜ້າຫາກເປັນໄປໄດ້.

active-icon ປຸ່ມຄວບຄຸມທີ່ເຂົ້າເຖິງຜ່ານປຸ່ມທີ່ມີໄອຄອນ
ເມື່ອປຸ່ມຄວບຄຸມຖືກເປີດໃຊ້ດ້ວຍໄອຄອນ, ໃຫ້ຖ່າຍຮູບໜ້າຈໍຂອງໄອຄອນນັ້ນໂດຍໃຊ້ທີມມາດຕະຖານຂອງ darktable (darktable-elegant-grey) ແລະ ເພີ່ມມັນໄວ້ກ່ອນຊື່ຂອງປຸ່ມຄວບຄຸມ
ຊື່ combobox ໃນ GUI
Combobox ມັກຈະມີຫຼາຍຕົວເລືອກ ເຊິ່ງທັງໝົດຕ້ອງຖືກສະແດງດ້ວຍຄຳຈຳກັດຄວາມແຍກກັນ. ໃຫ້ໃຊ້ລາຍການແບບຈ້ຳ (bulleted lists) ພ້ອມດ້ວຍ ຕົວອຽງ ສຳລັບຄ່າໃນ combobox.
  • ຄ່າທຳອິດ: ຄວາມໝາຍຂອງຄ່າທຳອິດ
  • ຄ່າທີສອງ: ຄວາມໝາຍຂອງຄ່າທີສອງ

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

🔗ໝາຍເຫດ (notes)

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

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

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

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

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

translations