ກວດສອບເອກະສານຂອງທ່ານໂດຍໃຊ້ Vale

ທີມງານເອກະສານ Fedora <https://discussion.fedoraproject.org/tag/docs-team> v1.1, 2024-08-30
Vale ແມ່ນເຄື່ອງມືແບບ command-line ທີ່ຊ່ວຍໃຫ້ທ່ານກວດສອບການຂຽນຂອງທ່ານເພື່ອຫາຂໍ້ຜິດພາດທາງໄວຍາກອນ ແລະ ຮູບແບບຕາມກົດລະບຽບທີ່ກຳນົດໄວ້. Vale ຈະປ່ຽນຄູ່ມືຮູບແບບຂອງທ່ານໃຫ້ເປັນຊຸດໄຟລ໌ YAML ທີ່ຮອງຮັບກັບ Vale ແລະ ສາມາດປັບແຕ່ງໄດ້ສູງ.

ຕິດຕັ້ງ Vale ໃນຄອມພິວເຕີຂອງທ່ານ

ທ່ານສາມາດຕິດຕັ້ງ Vale ໃນຄອມພິວເຕີຂອງທ່ານ, ຫຼື ໃຊ້ເວີຊັນ container ດ້ວຍ Podman.

ເພື່ອຕິດຕັ້ງ Vale ໃນຄອມພິວເຕີຂອງທ່ານ ໃຫ້ໃຊ້ຕົວຕິດຕັ້ງທີ່ມີຢູ່ສຳລັບ Windows, macOS, ແລະ Linux.

ຖ້າທ່ານກຳລັງໃຊ້ Fedora, ທ່ານສາມາດຕິດຕັ້ງ Vale ຈາກ repository Copr mczernek/vale. ກະລຸນາຮັບຊາບວ່າ Copr ບໍ່ໄດ້ຮັບການສະໜັບສະໜູນຢ່າງເປັນທາງການຈາກໂຄງລ່າງພື້ນຖານຂອງ Fedora. ການນຳໃຊ້ແພັກເກັດເຫຼົ່ານີ້ແມ່ນຄວາມສ່ຽງຂອງທ່ານເອງ.

$ sudo dnf copr enable mczernek/vale && sudo dnf install vale

ທ່ານສາມາດໃຊ້ Vale ເວີຊັນ container ໄດ້ ຫາກທ່ານບໍ່ຕ້ອງການຕິດຕັ້ງມັນໄວ້ໃນເຄື່ອງ.

podman run --rm -v ${PWD}:/docs -w /docs jdkato/vale:latest <your_file.adoc>

ຫາກທ່ານຕິດຕັ້ງ Vale ໄວ້ໃນເຄື່ອງແລ້ວ, ໃຫ້ກວດສອບວ່າ Vale ພ້ອມໃຊ້ງານຫຼືບໍ່ໂດຍໃຊ້ຄຳສັ່ງ vale -v:

$ vale -v
vale version 2.21.2 (ເວີຊັນຂອງທ່ານອາດຈະແຕກຕ່າງກັນ ຂຶ້ນກັບວ່າທ່ານຕິດຕັ້ງ Vale ຕອນໃດ)

ຄູ່ມືຮູບແບບຂອງ Red Hat ແລະ ໄຟລ໌ການຕັ້ງຄ່າ Vale ທີ່ຈຳເປັນ ແມ່ນໄດ້ຖືກຕິດຕັ້ງ ແລະ ພ້ອມໃຊ້ງານແລ້ວໃນ repository ທີ່ທ່ານ fork ມາຈາກໜ້າ Fedora Docs ຫຼັກໃນ GitLab.

ທ່ານສາມາດກວດສອບໄດ້ໂດຍການເບິ່ງໄຟລ໌ .vale.ini ໃນລາຍການໄຟລ໌ຂອງ fork ຂອງທ່ານໃນບັນຊີ GitLab. ທ່ານບໍ່ຈຳເປັນຕ້ອງດາວໂຫຼດ ຫຼື ຕິດຕັ້ງໄຟລ໌ຮູບແບບເພີ່ມເຕີມໃດໆ.

ໃຊ້ Vale ເພື່ອກວດສອບໄຟລ໌ ຫຼື ໂຟນເດີ

ໃນການນຳໃຊ້ Vale, ໃຫ້ປະຕິບັດດັ່ງນີ້:

  1. ສ້າງ ຫຼື ແກ້ໄຂໄຟລ໌ໃນ repository Fedora Docs ຂອງທ່ານ. ເບິ່ງ ວິທີການສ້າງ ແລະ ນຳໃຊ້ສະພາບແວດລ້ອມການຂຽນ Fedora ໄວ້ໃນເຄື່ອງ ສຳລັບຂັ້ນຕອນການ fork, clone, ແລະ ຈັດການ repository Git ໃນຄອມພິວເຕີຂອງທ່ານ.

  2. ລັນ Vale linter ກັບໄຟລ໌. ທ່ານສາມາດລັນ Vale ກັບໄຟລ໌ດຽວ, ຫຼາຍໄຟລ໌, ແລະ ໂຟນເດີກໍໄດ້.

  3. ເຮັດການອັບເດດໄຟລ໌ເພື່ອແກ້ໄຂຂໍ້ຜິດພາດ, ຄຳເຕືອນ, ຫຼື ຄຳແນະນຳຕ່າງໆ.

  4. ລັນ Vale linter ຄືນໃໝ່ເພື່ອໃຫ້ແນ່ໃຈວ່າໄຟລ໌ຜ່ານການກວດສອບ.

ເມື່ອໄຟລ໌ຂອງທ່ານຜ່ານການກວດສອບແລ້ວ, ທ່ານສາມາດ commit ວຽກຂອງທ່ານ ແລະ push ໄປຍັງ fork ຂອງທ່ານໃນ GitLab, ແລ້ວເປີດ merge request ໄດ້.

ຄຳສັ່ງ ແລະ ຜົນການສະແດງຂອງ Vale

ວິທີລັນ Vale ກັບໄຟລ໌ດຽວ:

$ vale filename

ວິທີລັນ Vale ກັບຫຼາຍໄຟລ໌:

$ vale filename 1 filename 2

ວິທີລັນ Vale ກັບທຸກໄຟລ໌ໃນໂຟນເດີ:

$ vale directoryname/

Vale ຈະສະແດງລາຍການຜົນກວດສອບໂດຍລະບຸຕຳແໜ່ງໃນໄຟລ໌, ລະດັບຄວາມຮຸນແຮງ, ຄຳແນະນຳວິທີແກ້ໄຂ, ແລະ ການອ້າງອີງຮູບແບບທີ່ກວດພົບ. ຕົວຢ່າງ:

11:1   suggestion  Define acronyms and             RedHat.Definitions
                    abbreviations (such as 'TOC')
                    on first occurrence if they're
                    likely to be unfamiliar.
15:54  error       Use 'for example' rather than   RedHat.TermsErrors
                    'e.g.'.
15:59  warning     Use correct American English    RedHat.Spelling
                    spelling. Did you really mean
                    'Quickdocs'?

ຖ້າໄຟລ໌ສະແດງລາຍການຜົນກວດສອບທີ່ຍາວຫຼາຍ, ໃຫ້ໃຊ້:

$ vale --no-wrap filename

ຄຳສັ່ງນີ້ຈະສະແດງແຕ່ລະຜົນການກວດສອບໃນແຖວດຽວ. ມັນມີປະໂຫຍດຫຼາຍໃນເວລາທີ່ກວດສອບຫຼາຍໄຟລ໌ ຫຼື ທຸກໄຟລ໌ໃນໂຟນເດີ.

Vale ມີຜົນການກວດສອບຢູ່ສາມລະດັບ ເຊິ່ງຈະສະແດງຢູ່ທາງລຸ່ມສຸດຂອງຜົນການລັນ: error, warning, ແລະ suggestion.

✖ 1 error, 3 warnings and 4 suggestions in 1 file.

  • error: ນີ້ແມ່ນສິ່ງທີ່ຂັດຂວາງ (blocker), ທ່ານຕ້ອງແກ້ໄຂຂໍ້ຜິດພາດທີ່ພົບໃນໄຟລ໌ໃຫ້ໝົດ.

  • warning: ນີ້ບໍ່ແມ່ນສິ່ງທີ່ຂັດຂວາງ, ແຕ່ແມ່ນສິ່ງທີ່ທ່ານຕ້ອງໄດ້ແກ້ໄຂເພື່ອໃຫ້ສອດຄ່ອງກັບຄູ່ມືຮູບແບບຂອງ Red Hat.

  • suggestion: ນີ້ບໍ່ແມ່ນສິ່ງທີ່ຂັດຂວາງ, ແຕ່ແມ່ນສິ່ງທີ່ທ່ານຄວນກວດສອບ ແລະ ພະຍາຍາມແກ້ໄຂເພື່ອໃຫ້ສອດຄ່ອງກັບຄູ່ມືຮູບແບບຂອງ Red Hat.

ຫາກທ່ານຕ້ອງການເບິ່ງສະເພາະຜົນການກວດສອບໃດໜຶ່ງ, ໃຫ້ໃຊ້ flag --minAlertLevel level. ນີ້ມີປະໂຫຍດຫຼາຍຖ້າທ່ານມີລາຍການຜົນກວດສອບຈຳນວນຫຼາຍ ແລະ ຕ້ອງການຈັດການແຕ່ລະລະດັບເທື່ອລະຢ່າງ.

--minAlertLevel suggestion (ສະແດງ suggestion, warning, ແລະ error)

--minAlertLevel warning (ສະແດງ warning ແລະ error)

--minAlertLevel error (ສະແດງສະເພາະ error)

ຕົວຢ່າງ, ເພື່ອສະແດງສະເພາະຜົນການກວດສອບລະດັບ error ໃນໄຟລ໌, ໃຫ້ໃຊ້:

$ vale --no-wrap --minAlertLevel error filename

ວິທີການອ່ານຜົນການກວດສອບຂອງ Vale

Vale ສະແດງຜົນການກວດສອບຕາມເລກແຖວ ແລະ ຕຳແໜ່ງ (ບາງຄັ້ງເອີ້ນວ່າ column). ມັນຍັງສະແດງກົດລະບຽບຮູບແບບທີ່ກວດພົບເນື້ອຫາດັ່ງກ່າວ.

ຕົວຢ່າງ, ຂໍ້ຜິດພາດນີ້ຢູ່ໃນແຖວທີ 15, ເລີ່ມຕົ້ນທີ່ຕຳແໜ່ງທີ 54

15:54  error    Use 'for example' rather than 'e.g.'.        RedHat.TermsErrors
15 ** Editor in chief for specific documentation areas, e.g. Quickdocs
                                                        ^ position 54

ກວດສອບວ່າ Text Editor ຂອງທ່ານສະແດງເລກແຖວ ແລະ ຕຳແໜ່ງ. Editor ສ່ວນໃຫຍ່ຈະມີວິທີການເປີດໃຊ້ການສະແດງຜົນນີ້.

ໂດຍປົກກະຕິແລ້ວ Vale ຈະບອກທ່ານຢ່າງຊັດເຈນວ່າຕ້ອງເຮັດແນວໃດເພື່ອແກ້ໄຂແຖວນັ້ນ, ເຊິ່ງໃນກໍລະນີນີ້ແມ່ນໃຫ້ໃຊ້ 'for example' ແທນ 'e.g.'

ລັນ Vale ຄືນໃໝ່ເພື່ອໃຫ້ແນ່ໃຈວ່າຂໍ້ຜິດພາດໄດ້ຖືກແກ້ໄຂແລ້ວ. ສືບຕໍ່ລັນ Vale ຈົນກວ່າຈະບໍ່ມີ error, warning, ແລະ suggestion ທີ່ຄ້າງຢູ່.

ວິທີຄົ້ນຫາຄຳແນະນຳໃນການແກ້ໄຂຜົນການກວດສອບຂອງ Vale

ທຸກໆຜົນການກວດສອບທີ່ Vale ສົ່ງກັບມາຈະສະແດງການອ້າງອີງຮູບແບບຂອງ Red Hat ທີ່ກວດພົບຄຳ ຫຼື ວະລີນັ້ນໆ. ເຊິ່ງຈະຢູ່ທ້າຍສຸດຂອງແຕ່ລະຜົນການກວດສອບ, ໃນຮູບແບບ RedHat.style_name.

ໄຟລ໌ເຫຼົ່ານີ້ຢູ່ໃນໂຟນເດີ .vale ຢູ່ຊັ້ນເທິງສຸດຂອງ repository ຂອງທ່ານ, ໃນໂຟນເດີຍ່ອຍ styles/RedHat.

ໄຟລ໌ຮູບແບບທັງໝົດຈະອ້າງອີງກັບໄປທີ່ຄູ່ມືການອ້າງອີງທີ່ເບິ່ງແຍງໂດຍ Red Hat ໃນໜ້າ Vale for writers at Red Hat.

ໂດຍທົ່ວໄປແລ້ວ ທ່ານສາມາດຫາຄຳແນະນຳໄດ້ຢູ່ທີ່ນັ້ນກ່ຽວກັບສິ່ງທີ່ຕ້ອງປ່ຽນແປງເພື່ອແກ້ໄຂຜົນການກວດສອບລະດັບ error ຫຼື warning.

ຫາກທ່ານຕ້ອງການເບິ່ງເນື້ອຫາຂອງໄຟລ໌ຮູບແບບສະເພາະ, ທ່ານສາມາດເຂົ້າເບິ່ງໄດ້ທີ່ໜ້າ GitHub vale-at-red-hat.

ຫາກທ່ານຍັງມີຄຳຖາມ ຫຼື ຕ້ອງການຄວາມຊ່ວຍເຫຼືອໃນການຕັດສິນໃຈວ່າຈະປ່ຽນແປງແນວໃດ, ໃຫ້ຝາກຄຳຖາມໄວ້ໃນຫ້ອງ Fedora Documentation ທີ່ Fedora Chat.

ຂໍ້ມູນເພີ່ມເຕີມ

ເອກະສານຂອງ Vale: https://vale.sh/docs/

ຄູ່ມືຮູບແບບການຂຽນທາງເຕັກນິກຂອງ Red Hat: https://stylepedia.net/

ແນວທາງສຳລັບເອກະສານຂອງ Red Hat: https://redhat-documentation.github.io/

ຄູ່ມືຮູບແບບ Fedora Docs: https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/style-guide/

ຄູ່ມືນີ້ສະແດງວິທີການນຳໃຊ້ Vale ຜ່ານ command line, ແຕ່ກໍມີ ປລັກອິນ ຫຼື ແພັກເກັດ ສຳລັບ Text Editor ຍອດນິຍົມຫຼາຍໆໂຕ.

Want to help? Learn how to contribute to Fedora Docs ›