lexgrog - analiza la información de cabecera en páginas man
lexgrog [
-m|
-c] [
-dfw?V] [
-E
codificación]
archivo ...
lexgrog es una implementación de la tradicional utilidad
“groff guess” en
lex. Lee la lista de archivos en su
línea de órdenes bien como archivos fuente de página man,
bien como páginas preformateadas “cat”, y muestra su
nombre y descripción como se utilizó por
apropos y
whatis, la lista de filtros preprocesados requeridos por la
página man antes de que sea pasada por
nroff o
troff, o
ambos.
Si esta entrada está formateada equivocadamente,
lexgrog
escribirá “parse fallado”; esto puede ser útil
para programas externos que necesiten comprobar la corrección de
páginas man. Si uno de los archivos de entrada de
lexgrog es
“-”, leerá desde la entrada estándar; si
algún archivo de entrada está comprimido, se leerá
automáticamente una versión descomprimida.
-
-d, --debug
- Escribe información de depuración.
-
-m, --man
- Interpreta la entrada como archivos fuente de página
man. Esto es lo predefinido si ni --man ni --cat es
dado.
-
-c, --cat
- Entrada interpretada como páginas
(“cat”) man preformateadas. --man y --cat
pueden no darse simultáneamente.
-
-w, --whatis
- Muestra el nombre y la descripción desde la cabecera
de la página man, tal y como la usan apropos y
whatis. Esto es lo predeterminado si ni --watis ni
--filters está dado.
-
-f, --filters
- Muestra la lista de filtros necesarios para preprocesar la
página man antes de formatear con nroff o troff.
-
-E codificación, --encoding
codificación
- Anula el conjunto de caracteres supuesto para la
página sustituyéndolo por codificación.
-
-?, --help
- Escribe un mensaje de ayuda y termina.
- --usage
- Escribe mensaje breve sobre uso del programa y
termina.
-
-V, --version
- Muestra información sobre la versión.
- 0
- Ejecución del programa correcta.
- 1
- Error de uso.
- 2
-
lexgrog fallo al analizar uno o varios de sus
archivos de entrada.
$ lexgrog man.1
man.1: «man - interfaz para los manuales de referencia del sistema»
$ lexgrog -fw man.1
man.1 (t): «man - interfaz para los manuales de referencia del sistema»
$ lexgrog -c whatis.cat1
whatis.cat1: «whatis - muestra las descripciones de las páginas de manual»
$ lexgrog broken.1
broken.1: fallo del analizador
mandb (el cual emplea el mismo código que
lexgrog) analiza
la sección
NOMBRE situada en la parte superior de cada
página de manual buscando nombres y descripciones de las
características documentadas en cada una. Aunque el analizador es
bastante tolerante, como tiene que hacer frente a un gran número de
formatos diferentes que históricamente se han empleado, algunas veces
puede fallar al extraer la información requerida.
Al utilizar el conjunto de macros tradicional de
man, una sección
correcta
NOMBRE tiene el siguiente aspecto:
.SH NOMBRE foo \- programa que hace algo
Algunos paginadores del manual requieren que la ‘\-’ esté
exactamente como se muestra;
mandb es más tolerante; sin
embargo, por compatibilidad con otros sistemas, no es buena idea retener la
barra invertida.
En el lado izquierdo puede haber varios nombres separados por comas. Los nombres
que contengan espacios en blanco serán ignorados para evitar
comportamiento patológico en ciertas secciones
NOMBRE mal
formadas. El texto en el lado derecho tiene formato libre y puede ocupar
varias líneas. Si se están documentando diversas
características con descripciones diferentes en la misma página
de manual, en tal caso se utiliza la siguiente forma:
.SH NAME esto, aquello \- programas para hacer algo .br baz \- programa para no hacer nada
(Macro que inicia un párrafo nuevo, como .PP, puede utilizarse en lugar
de la macro de salto .br.)
Cuando se utiliza el conjunto de macros
mdoc derivadas de BSD, una
sección
NOMBRE correcta tiene el siguiente aspecto:
.Sh NOMBRE .Nm foo .Nd programa para hacer algo
Hay distintas razones por las que el análisis de whatis suele fallar. A
veces los autores de las páginas de manual sustituyen ‘.SH
NOMBRE’ por ‘.SH MIPROGRAMA’, y entonces
mandb no
puede encontrar la sección desde la cual extraer la información
que necesita. A veces los autores incluyen una sección NOMBRE, pero
colocan texto en formato-libre en lugar de ‘name \-
description’. Sin embargo, debería aceptarse cualquier sintaxis
parecida a la de arriba.
apropos(1),
man(1),
whatis(1),
mandb(8)
lexgrog trata de analizar archivos que contienen peticiones .so, pero
solo podrá hacerlo correctamente si los archivos están
debidamente instalados en la jerarquía de una página de manual.
El código utilizado por
lexgrog para analizar páginas man
fue escrito por:
Wilf. ([email protected]).
Fabrizio Polacco ([email protected]).
Colin Watson ([email protected]).
Colin Watson escribió la actual encarnación del frontal de la
línea de órdenes, así como esta página man.
https://gitlab.com/man-db/man-db/-/issues
https://savannah.nongnu.org/bugs/?group=man-db