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
Sie können Vale auf Ihrem Rechner installieren oder eine containerisierte Version mit Podman verwenden.
Um Vale auf Ihrem Rechner zu installieren, verwenden Sie eines der verfügbaren Installationsprogramme für Windows, macOS und Linux.
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
Sie können die containerisierte Version von Vale verwenden, wenn Sie es nicht lokal installieren möchten.
podman run --rm -v ${PWD}:/docs -w /docs jdkato/vale:latest <Ihre_Datei.adoc>
Wenn Sie Vale lokal installiert haben, überprüfen Sie mit dem Befehl vale -v, ob Vale verfügbar ist:
$ vale -v vale version 2.21.2 (your version may be different depending on when you installed Vale)
Die Stilrichtlinien von Red Hat und die erforderlichen Vale-Konfigurationsdateien sind bereits installiert und in dem Repository verfügbar, das Sie von der Hauptseite Fedora Docs in GitLab geforkt haben.
Sie können dies überprüfen, indem Sie in der Dateiliste Ihres Forks in Ihrem GitLab-Konto nach einer .vale.ini-Datei suchen. Sie müssen keine zusätzlichen Stildateien herunterladen oder installieren.
Vale zum Überprüfen von Dateien oder Verzeichnissen verwenden
Um Vale zu verwenden, gehen Sie wie folgt vor:
-
Erstellen oder bearbeiten Sie eine Datei in Ihrem lokalen Fedora-Dokumentations-Repository. Unter Einen lokalen Arbeitsablauf für Fedora-Dokumentation anlegen und verwenden finden Sie Anweisungen zum Forken, Klonen und Verwalten von Git-Repositories auf Ihrem Rechner.
-
Führen Sie den Vale-Linter auf die Datei aus. Sie können Vale auf eine einzelne Datei, mehrere Dateien oder Verzeichnisse anwenden.
-
Bearbeiten Sie die Datei, um etwaige Fehler oder Warnungen zu beheben oder Verbesserungsvorschläge anzuwenden.
-
Führen Sie den Vale-Linter erneut aus, um zu überprüfen, ob die Datei die erforderlichen Prüfungen besteht.
Wenn Ihre Datei erfolgreich geprüft wurde, können Sie Ihre Arbeit committen und in Ihren Fork auf GitLab pushen und einen Merge Request öffnen.
Vale-Befehle und -Ausgaben
To run Vale on a single file:
$ vale Dateiname
So wenden Sie Vale auf mehrere Dateien an:
$ vale Dateiname 1 Dateiname 2
So wenden Sie Vale auf alle Dateien in einem Verzeichnis an:
$ vale Verzeichnisname/
Vale liefert eine Ergebnisliste mit Angabe der Position in der Datei, des Schweregrades, eines Hinweises zur Behebung des Fehlers und der Stilreferenz, die der Fehlermeldung zugrunde liegt. Zum Beispiel:
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'?
Wenn eine Datei eine lange Ergebnisliste zurückgibt, verwenden Sie Folgendes:
$ vale --no-wrap Dateiname
Dadurch wird jedes Ergebnis in einer eigenen Zeile ausgegeben. Dies ist auch nützlich, wenn man viele Dateien oder alle Dateien in einem Verzeichnis überprüft.
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.
-
error: Dies ist schwerwiegend, und Sie müssen alle in der Datei gefundenen Fehler beheben.
-
warning: This is a not a blocker, but is something that you need to fix to conform to the Red Hat style guide.
-
suggestion: Dies ist nicht schwerwiegend, aber etwas, das Sie überprüfen und versuchen sollten, zu beheben, um es an die Stilrichtlinien von Red Hat anzupassen.
Um gezielt nach einer bestimmten Ergebnisstufe zu suchen, verwenden Sie den Parameter --minAlertLevel Stufe. Dies ist hilfreich, wenn Sie eine lange Ergebnisliste haben und jeweils nur Meldungen einer bestimmten Ergebnisstufe (d.h. eines bestimmten Schweregrads) bearbeiten möchten.
--minAlertLevel suggestion (zeigt Meldungen für „suggestion“, „warning“ und „error“)
--minAlertLevel warning (zeigt Meldungen für „warning“ und „error“)
--minAlertLevel error (zeigt nur Meldungen für „error“)
Um beispielsweise nur Ergebnisse anzuzeigen, die in der Datei als fehlerhaft gekennzeichnet sind, verwenden Sie Folgendes:
$ vale --no-wrap --minAlertLevel error Dateiname
How to interpret Vale results
Vale zeigt die Ergebnisse nach Zeilennummer und Position (manchmal auch „column“ genannt) an. Außerdem wird die Stilrichtlinie angezeigt, aufgrund der der Inhalt beanstandet wurde.
Dieser Fehler befindet sich beispielsweise in Zeile 15, beginnend an Position 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
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
Jedes von Vale zurückgegebene Ergebnis enthält die Red Hat-Stilreferenz, die das betreffende Wort oder die betreffende Phrase markiert hat. Diese befindet sich am Ende jedes Ergebnisses im Format RedHat.Stilname.
Diese Dateien befinden sich in einem .vale-Verzeichnis in der obersten Verzeichnisebene Ihres lokalen Repositorys, in einem styles/RedHat-Unterverzeichnis.
Alle Stildateien verweisen auf den von Red Hat gepflegten Referenzleitfaden auf der Seite Vale for writers at Red Hat.
Dort finden Sie in der Regel Anleitungen, was Sie ändern müssen, um etwaige Fehler oder Warnmeldungen zu beheben.
Wenn Sie den Inhalt einer bestimmten Stildatei einsehen möchten, können Sie auf der Seite vale-at-red-hat auf GitHub nachschauen.
Wenn Sie noch Fragen haben oder Hilfe bei der Entscheidung benötigen, welche Änderungen vorgenommen werden sollen, stellen Sie eine Frage im Fedora-Dokumentations-Raum im Fedora Chat.
Weitere Informationen
Vale-dokumentation: 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 ›