Verifique Su Documentación Utilizando Vale
Vale es una herramienta de línea de comando que le permite verificar la gramática y los errores de estilo contra un conjunto de reglas de estilo. Vale codifica sus guías de estilo en una colección de archivos YAML compatibles con Vale y es altamente personalizable. La documentación de Fedora usa la guía de estilo Red Hat. antes de crear una solicitud de fusión para cualquier documentación o actualización de documentación, necesitará ejecutar Vale sobre su texto.
Instalar Vale en su ordenador
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.
Si está utilizando Fedora, puede instalar desde el repositorio Copr mczernek/vale. Tenca cuidado que Copr no está mantenido oficialmente por la infraestructura de Fedora. Utilice paquetes a su propio riesgo.
$ 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 (su versión podría ser diferente dependiendo de cuando instaló 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
Para ejecutar Vale en un solo archivo:
$ 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 sugerencia Defina acrónimos y RedHat.Definitions
abreviaciones (tales como 'TOC')
en el primer suceso si están
enlazados para ser no usual.
15:54 error Utilice 'por ejemplo' en vez de RedHat.TermsErrors
'p.ej.'
15:59 avisos Utilice el deletreo correcto de RedHat.Spelling
Inglés Americano
¿Realmente significó '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 tiene tres niveles de resultados que listará en la parte inferior de la salida: error, aviso, y sugerencia.
✖ 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.
-
aviso: esto no es un bloqueador, pero es algo que necesita reparar para conforme a la guía de estilo de Red Har.
-
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
Como interpretar los resultados de Vale
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 en jefe para áreas de documentación especificada, por ejemplo Quickdocs
^ posición 54
Verifique que su editor de texto muestre números y posición de línea. Muchos editores de texto tendrán una manera de habilitar esta vista.
Vale usualmente le dirá que necesita hacer para reparar la línea, la cual en este caso está para ser utilizado 'por ejemplo' en vez de 'p.ej.'
Re-ejecute Vale para verificar que el error ahora está resuelto. Continúe ejecutando Vale para vaciar todos los errores, avisos y sugerencias.
Como encontrar guías para corregir resultados de Vale
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/
Guía de Estilo para Escritura Técnica de Red Hat: https://stylepedia.net/
Líneas de Guía para Documentación de Red Hat: https://redhat-documentation.github.io/
Guía de Estilo de Docs de Fedora: https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/style-guide/
Esta guía muestra como utilizar Vale desde la línea de comandos, pero plugins or packages están disponibles para editores de varios textos comunes.
Want to help? Learn how to contribute to Fedora Docs ›