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
Usted puede instalar Vale en su ordenador, o utilizar la versión en contenedor con Podman.
Para instalar Vale en su ordenador use uno de los instaladores disponibles Windows, macOS y 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
Puede utilizar la versión contenida de Vale si no desea instalarla localmente.
podman run --rm -v ${PWD}:/docs -w /docs jdkato/vale:latest <su_archovo.adoc>
Si instaló Vale localmente, verifique que Vale está disponible utilizando el comando vale -v:
$ vale -v vale version 2.21.2 (your version may be different depending on when you installed Vale)
La guía de estilo de Red Hat y los archivos de configuración de Vale requeridos ya están instalados y disponibles en el repositorio bifurcado desde la página principal de Fedora Docs en GitLab.
Puede verificar esto marcando un archivo .vale.inf en el listado de archivo de su bifurcación en su cuenta de GitLab. No necesita descargar o instalar ningún archivo de estilo adicional.
Utilice Vale para comprobar archivos o directorios
Para utilizar Vale, haga lo siguiente:
-
Cree o edite un archivo en su repositorio local de Fedora Docs. Consulte How to create and use a local Fedora authoring environment para instrucciones en como bifurcar, clonar y gestionar repositorios Git en su equipo.
-
Ejecute el enlazador Vale en el archivo. Puede ejecutar Vale en un único archivo, varios archivos, y directorios.
-
Realice las actualizaciones para el archivo para solucionar cualquier error, advertencia o sugerencias.
-
Re-ejecuta el linter Vale para verificar los aprobados del archivo.
Cuando apruebe su archivo, puede realizar su trabajo y empujar a su bifurcación en GitLab, y abrir una petición de unión.
Los comandos y la salida de Vale
To run Vale on a single file:
$ vale nombre-archivo
Para ejecutar Vale en varios archivos:
$ vale nombre_archivo 1 nombre_archivo 2
Para ejecutar Vale en todos los archivos en un directorio:
$ vale nombre-directorio/
Vale devolverá un listado de resultados mostrando el lugar del archivo, el nivel de severidad, un consejo sobre como corregir el resultado, y qué estilo de referencia indicó el resultado. Por ejemplo:
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'?
Si un archivo devuelve un listado largo de resultados, utilice:
$ vale --no-wrap nombre-archivo
Esto imprimirá cada resultado en una línea. Esto además es útil cuando compruebe muchos archivos o todos los archivos dentro de un directorio.
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: esto es un bloqueador, y debe reparar cualquiera de los errores encontrados dentro del archivo.
-
warning: This is a not a blocker, but is something that you need to fix to conform to the Red Hat style guide.
-
sugerencia: esto no es un bloqueador, pero es algo que debe revisar e intentar repararlo para estar conforme a la guía de estilo de Red Hat.
Si desea solo únicamente encontrar un resultado específico, utilice el indicador --minAlertLevel. Esto es útil si tiene un listado largo de resultados que funcionen en un nivel de resultado específico en un tiempo.
--minAlertLevel suggestion (mostrar sugerencia, advertencia y error)
--minAlertLevel warning (muestra advertencia y error)
--minAlertLevel error (solo muestra error)
Por ejemplo, solo muestra los resultados indicados con error en el archivo, utilice:
$ vale --no-wrap --minAlertLevel error nombre de archivo
How to interpret Vale results
Vale muestra los resultados por el número de línea y posición (algunas veces invocada una columna). Además muestra la guía de estilo que indicó el contenido.
Por ejemplo, este error está en la línea 15, comenzando en la posición 54
15:54 error Utilice 'por ejemplo' en vez de 'p.ej.'. 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
Cada resultado devuelto por Vale muestra la referencia de estilo de Red Hat que indicó la palabra o frase. Esto está al final de cada resultado, en el formato de RedHat.style_name.
Estos archivos está en un directorio .vale en el nivel cima de su repositorio local, en un subdirectorio styles/RedHat.
Todos los puntos de archivo de estilo devueltos a la guía de referencia gestionada por Red Hat en la página Vale for writers at Red Hat page.
Usualmente puede encontrar guía en que cambiar para resolver cualquier error o advirtiendo nivel de resultado.
Si desea ver el contenido de un archivo de esto específico, puede examinar la página vale-at-red-hat en el GitHub.
Si aún tiene cuestiones o necesita ayuda para decidir que cambios hacer, envíe una pregunta en la habitación de Fedora Documentation en Fedora Char.
Más información
La documentación de Vale: 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 ›