Check Your Documentation Using Vale
Vale is a command-line tool that allows you to check your writing for grammar and stylistic errors against a set of style rules. Vale codifies your style guides into a collection of Vale-compatible YAML files and it is highly customizable.
Install Vale on your computer
Voit asentaa Valen tietokoneellesi tai käyttää konttiversiota Podmanin kanssa.
Valen asentamiseen tietokoneellesi käytä jotakin saatavilla olevista asennusohjelmista https://vale.sh/docs/vale-cli/installation/ Windowsille, macOS:lle ja Linuxille].
If you are using Fedora, you can install Vale from the mczernek/vale Copr repository. Be aware that Copr is not officially supported by Fedora infrastructure. Use packages at your own risk.
$ sudo dnf copr enable mczernek/vale && sudo dnf install vale
Voit käyttää Valen konttiversiota, jos et halua asentaa sitä paikallisesti.
podman run --rm -v ${PWD}:/docs -w /docs jdkato/vale:latest <your_file.adoc>
Jos asensit Valen paikallisesti, varmista että Vale on käytettävissä käyttämällä komentoa %vale -v%:
$ vale -v vale version 2.21.2 (your version may be different depending on when you installed Vale)
Red Hat -tyyliopas ja tarvittavat Vale-määritystiedostot ovat jo asennettuina ja saatavilla GitLabin Fedora-dokumentaatio -pääsivulta haarautuneessa repositoriossa.
Voit varmistaa tämän tarkistamalla, onko GitLab-tililläsi haarautumisesi tiedostoluettelossa .vale.ini-tiedostoa. Sinun ei tarvitse ladata tai asentaa mitään ylimääräisiä tyylitiedostoja.
Käytä Valea tiedostojen tai hakemistojen tarkistamiseen
Käyttääksesi Valea, tee seuraavaa:
-
Luo tiedosto paikallisessa Fedora-dokumenttiarkistossa tai muokkaa sitä. Katso ohjeet Git-arkistojen haarautumiseen, kloonaamiseen ja hallintaan tietokoneellasi kohdasta Paikallisen Fedora-sisällöntuotantoympäristön luominen ja käyttäminen.
-
Suorita Vale-linter tiedostolle. Voit suorittaa Valen yhdelle tiedostolle, useille tiedostoille ja hakemistoille.
-
Korjaa tiedostoon mahdolliset virheet, varoitukset tai ehdotukset päivittämällä se.
-
Suorita Vale-linteri uudelleen varmistaaksesi, että tiedosto onnistuu.
Kun tiedostosi on hyväksytty, voit commit-työsi ja push-tiedoston GitLabissa olevaan haarautumaan ja avata yhdistämispyynnön.
Vale-komennot ja tulosteet
To run Vale on a single file:
$ vale tiedostonimi
Valen suorittaminen useille tiedostoille:
$ vale-ohjlman tiedostonimi 1 tiedostonimi 2
Valen suorittaminen kaikille hakemiston tiedostoille:
$ vale directoryname/
Vale palauttaa luettelon tuloksista, jotka näyttävät sijainnin tiedostossa, vakavuustason, vihjeen tuloksen korjaamiseen ja mikä tyyliviittaus merkitsi tuloksen. Esimerkiksi:
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'?
Jos tiedosto palauttaa pitkän tuloslistan, käytä:
$ vale --no-wrap filename
Tämä tulostaa jokaisen tuloksen yhdelle riville. Tästä on hyötyä myös tarkistettaessa useita tiedostoja tai kaikkia hakemiston tiedostoja.
Vale has three levels of results that it will list at the bottom of the output: error, warning, and suggestion.
✖ 1 error, 3 warnings and 4 suggestions in 1 file.
-
virhe: Tämä on esto, ja sinun on korjattava tiedostosta löytyneet virheet.
-
warning: This is a not a blocker, but is something that you need to fix to conform to the Red Hat style guide.
-
ehdotus: Tämä ei ole esto, mutta se on asia, joka sinun on tarkistettava ja yritettävä korjata, jotta se olisi Red Hat -tyylioppaan mukainen.
Jos haluat etsiä vain tiettyä tulosta, käytä --minAlertLevel level -lippua. Tästä on hyötyä, jos sinulla on pitkä tulosluettelo ja haluat työskennellä yhden tietyn tulostason parissa kerrallaan.
--minAlertLevel ehdotus (näyttää ehdotuksen, varoituksen ja virheen)
--minAlertLevel varoitus (näyttää varoituksen ja virheen)
--minAlertLevel error (näyttää vain virheen)
Esimerkiksi, jos haluat näyttää vain tiedostossa virheellisesti merkityt tulokset, käytä:
$vale --no-wrap --myAlertLevel virhetiedoston nimi
How to interpret Vale results
Vale näyttää tulokset rivinumeron ja sijainnin (joskus kutsutaan sarakkeeksi) mukaan. Se näyttää myös tyyliohjeen, joka merkitsi sisällön.
Esimerkiksi tämä virhe on rivillä 15, alkaen kohdasta 54
15:54 virhe Käytä 'esimerkiksi' 'esim':n sijaan. RedHat.TermsErrors
15 ** Editor in chief for specific documentation areas, e.g. Quickdocs
^ position 54
Verify that your text editor shows line numbers and position. Most text editors will have a way to enable this view.
Vale will usually tell you exactly what you need to do to fix the line, which in this case is to use 'for example' instead of 'e.g.'
Rerun Vale to verify that the error is now resolved. Continue running Vale to clear all errors, warnings, and suggestions.
How to find guidance for correcting Vale results
Jokainen Valen palauttama tulos näyttää Red Hat -tyyliviittauksen, joka merkitsi sanan tai lauseen. Tämä on jokaisen tuloksen lopussa muodossa RedHat.tyylin_nimi.
Nämä tiedostot sijaitsevat paikallisen arkistosi ylimmällä tasolla .vale-hakemistossa styles/RedHat-alihakemistossa.
Kaikki tyylitiedostot viittaavat Red Hatin ylläpitämään oppaaseen osoitteessa Vale Red Hatin kirjoittajille -sivu.
Yleensä sieltä löytyy ohjeita siitä, mitä tehdä virheiden tai varoitustasojen korjaamiseksi.
Jos haluat nähdä tietyn tyylitiedoston sisällön, voit tutustua GitHubin vale-at-red-hat -sivuun.
Jos sinulla on vielä kysyttävää tai tarvitset apua muutosten tekemisessä, lähetä kysymys Fedoran dokumentaatiohuoneeseen osoitteessa Fedora-keskustelu.
Lisätietoja
Valen dokumentaatio: https://vale.sh/docs/
Red Hat Technical Writing Style Guide: https://stylepedia.net/
Guidelines for Red Hat Documentation: https://redhat-documentation.github.io/
Fedora Docs Style Guide: https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/style-guide/
This guide shows how to use Vale from the command line, but plugins or packages are available for several common text editors.
Want to help? Learn how to contribute to Fedora Docs ›