Cómo crear una página man en Linux
Publicado: 2022-01-29 ¿Quiere que su nuevo programa de Linux luzca profesional? Dale una página de man
. Le mostraremos la forma más fácil y rápida de hacerlo.
Las páginas del hombre
Hay una pizca de verdad en el viejo chiste de Unix, "el único comando que necesitas saber es man
". Las páginas de man
contienen una gran cantidad de conocimientos, y deberían ser el primer lugar al que acudir cuando desee obtener información sobre un comando.
Proporcionar una página de man
para una utilidad o comando que haya escrito lo eleva de un código útil a un paquete de Linux completamente formado. La gente espera que se proporcione una página de man
para un programa que ha sido escrito para Linux. Si está soportando Linux de forma nativa, una página de man
es obligatoria si desea que su programa se tome en serio.
Históricamente, las páginas de man
se han escrito utilizando un conjunto de macros de formato. Cuando llama a man
para abrir una página, llama a groff
para leer el archivo y generar una salida formateada, de acuerdo con las macros en el archivo. La salida se canaliza a less
y luego se muestra para usted.
A menos que cree páginas man
con frecuencia, escribir una e insertar manualmente las macros es un trabajo arduo. El acto de crear una página de man
que analice correctamente y se vea bien puede superar su objetivo de proporcionar una descripción concisa pero completa de su comando.
Debería concentrarse en su contenido, no luchar contra un oscuro conjunto de macros.
RELACIONADO: Cómo usar el comando man de Linux: secretos y conceptos básicos ocultos
pandoc al rescate
El programa pandoc
lee archivos Markdown y genera otros nuevos en aproximadamente 40 lenguajes de marcado y formatos de documentos diferentes, incluido el de la página de man
. Transforma totalmente el proceso de escritura de la página de man
para que no tenga que lidiar con jeroglíficos.
Para comenzar, puede instalar pandoc
en Ubuntu con este comando:
sudo apt-get install pandoc
En Fedora, el comando que necesita es el siguiente:
sudo dnf instalar pandoc
En Manjaro, escriba:
sudo pacman-syu pandoc
RELACIONADO: Cómo usar pandoc para convertir archivos en la línea de comandos de Linux
Secciones de una página man
Las páginas del man
contienen secciones que siguen una convención de nomenclatura estándar. Las secciones que necesita su página de man
están dictadas por la sofisticación del comando que está describiendo.
Como mínimo, la mayoría de las páginas man contienen estas secciones:
- Nombre : el nombre del comando y una frase concisa que describe su función.
- Sinopsis : Una breve descripción de las invocaciones que alguien puede usar para iniciar el programa. Estos muestran los tipos de parámetros de línea de comandos aceptados.
- Descripción : Una descripción del comando o función.
- Opciones : una lista de opciones de línea de comandos y lo que hacen.
- Ejemplos : algunos ejemplos de uso común.
- Valores de salida : los posibles códigos de retorno y sus significados.
- Errores : una lista de errores y peculiaridades conocidas. A veces, esto se complementa con (o se reemplaza por) un enlace al rastreador de problemas para el proyecto.
- Autor : La persona o personas que escribieron el comando.
- Derechos de autor: Su mensaje de derechos de autor. Estos también suelen incluir el tipo de licencia bajo la cual se publica el programa.
Si revisa algunas de las páginas man
más complicadas, verá que también hay muchas otras secciones. Por ejemplo, prueba man man
. Sin embargo, no tiene que incluirlos todos, solo los que realmente necesita. Las páginas del man
no son lugar para la palabrería.
Algunas otras secciones que verá con bastante frecuencia son:
- Ver también : Otros comandos relacionados con el tema que algunos encontrarían útiles o relevantes.
- Archivos : una lista de archivos incluidos en el paquete.
- Advertencias : otros puntos que debe conocer o tener en cuenta.
- Historial : Un historial de cambios para el comando.
Secciones del Manual
El manual de Linux se compone de todas las páginas del man
, que luego se divide en estas secciones numeradas:
- Programas ejecutables: O, comandos de shell.
- Llamadas al sistema: funciones proporcionadas por el kernel.
- Llamadas de biblioteca: funciones dentro de bibliotecas de programas.
- archivos especiales.
- Formatos de archivo y convenciones: Por ejemplo, “/etc/passwd”.
- Juegos.
- Varios: paquetes de macros y convenciones, como
groff
. - Comandos de administración del sistema: generalmente reservados para root.
- Rutinas del kernel: no suelen instalarse de forma predeterminada.
Cada página de man
debe indicar a qué sección pertenece, y también debe almacenarse en la ubicación adecuada para esa sección, como veremos más adelante. Las páginas man
para comandos y utilidades pertenecen a la sección uno.
El formato de una página man
El formato de macro groff
no es fácil de analizar visualmente. Por el contrario, el descuento es pan comido.
A continuación se muestra una página del manual en groff
.
La misma página se muestra a continuación en Markdown.
asunto frontal
Las tres primeras líneas forman algo llamado materia preliminar . Todos deben comenzar con un signo de porcentaje ( %
), sin espacios iniciales, pero uno después, seguido de:
- La primera línea: contiene el nombre del comando, seguido de la sección del manual entre paréntesis, sin espacios. El nombre se convierte en las secciones izquierda y derecha del encabezado de la página de
man
. Por convención, el nombre del comando está en mayúsculas, aunque encontrará muchos que no lo están. Todo lo que sigue al nombre del comando y al número de la sección del manual se convierte en la sección izquierda del pie de página. Es conveniente usar esto para el número de versión del software. - La segunda línea: El(los) nombre(s) del(los) autor(es). Estos se muestran en una sección de autores generada automáticamente de la página del
man
. No es necesario que agregue una sección de "Autores", solo incluya al menos un nombre aquí. - La tercera línea: La fecha, que también se convierte en la parte central del pie de página.
Nombre
Las secciones se indican mediante líneas que comienzan con un signo de número ( #
), que es el marcado que indica un encabezado en Markdown. El signo de número ( #)
debe ser el primer carácter de la línea, seguido de un espacio.
La sección de nombre tiene una línea ágil que incluye el nombre del comando, un espacio, un guión ( -
), un espacio y luego una descripción muy breve de lo que hace el comando.
Sinopsis
La sinopsis contiene los diferentes formatos que puede tomar la línea de comando. Este comando puede aceptar un patrón de búsqueda o una opción de línea de comandos. Los dos asteriscos ( **
) a cada lado del nombre del comando significan que el nombre se mostrará en negrita en la página del man
. Un solo asterisco ( *
) a cada lado de algún texto hace que la página de man
lo muestre subrayado.
De forma predeterminada, un salto de línea va seguido de una línea en blanco. Para forzar una ruptura total sin una línea en blanco, puede usar una barra invertida final ( \
).
Descripción
La descripción explica lo que hace el comando o programa. Debe cubrir los detalles importantes de manera sucinta. Recuerde, no está escribiendo una guía del usuario.
El uso de dos signos numéricos ( ##
) al comienzo de una línea crea un encabezado de nivel dos. Puede usarlos para dividir su descripción en partes más pequeñas.
Opciones
La sección de opciones contiene una descripción de las opciones de la línea de comandos que se pueden usar con el comando. Por convención, estos se muestran en negrita, así que incluya dos asteriscos ( **
) antes y después de ellos. Incluya la descripción de texto de las opciones en la siguiente línea y comience con dos puntos ( :
), seguido de un espacio.
Si la descripción es lo suficientemente corta, man
la mostrará en la misma línea que la opción de la línea de comandos. Si es demasiado largo, se muestra como un párrafo sangrado que comienza en la línea debajo de la opción de línea de comando.
Ejemplos
La sección de ejemplos contiene una selección de diferentes formatos de línea de comandos. Tenga en cuenta que comenzamos las líneas de descripción con dos puntos ( :
), tal como lo hicimos con la sección de opciones.
Valores de salida
Esta sección enumera los valores de retorno que su comando envía al proceso de llamada. Este podría ser el shell si lo llamó desde la línea de comandos, o un script si lo inició desde un script de shell. También comenzamos las líneas descriptivas con dos puntos ( :
) en esta sección.
Insectos
La sección de errores enumera errores conocidos, trampas o peculiaridades que la gente necesita conocer. Para proyectos de código abierto, es común incluir un enlace aquí al rastreador de problemas del proyecto para verificar el estado de cualquier error o informar sobre nuevos.
Derechos de autor
La sección de derechos de autor contiene su declaración de derechos de autor y, por lo general, una descripción del tipo de licencia bajo la cual se publica el software.
Un flujo de trabajo eficiente
Puede editar su página de man
en su editor favorito. La mayoría de los que admiten el resaltado de sintaxis estarán al tanto de la reducción y colorearán el texto para resaltar los encabezados, así como también en negrita y subrayado. Eso es genial hasta donde llega, pero no estás viendo una página de man
renderizada, que es la prueba real en el pudín.
Abra una ventana de terminal en el directorio que contiene su archivo de rebajas. Con él abierto en su editor, guarde periódicamente su archivo en su disco duro. Cada vez que lo haga, puede ejecutar el siguiente comando en la ventana del terminal:
pandoc ms.1.md -s -t hombre | /usr/bin/hombre -l -
Una vez que haya usado este comando, puede presionar la flecha hacia arriba para repetirlo y luego presionar Intro.
Este comando también invoca pandoc
en el archivo de rebajas (aquí, se llama “ms.1.md”):
- La opción
-s
(independiente) genera una páginaman
completa de arriba a abajo, en lugar de solo texto en formatoman
. - La opción
-t
(tipo de salida) con el operador "man" le dice apandoc
que genere su salida en formatoman
. No le hemos dicho apandoc
que envíe su salida a un archivo, por lo que se enviará a la salidastdout
.
También estamos canalizando esa salida a man
con la opción -l
(archivo local). Le dice al man
que no busque a través de la base de datos del man
buscando la página del man
. En su lugar, debería abrir el archivo nombrado. Si el nombre del archivo es -
, man
tomará su entrada de stdin
.
A lo que se reduce esto es que puede guardar desde su editor y presionar Q para cerrar man
si se está ejecutando en la ventana de la terminal. Luego, puede presionar la flecha hacia arriba, seguida de Intro para ver una versión renderizada de su página de man
, justo dentro de man
.
RELACIONADO: ¿Qué son stdin, stdout y stderr en Linux?
Creación de su página de manual
Una vez que haya completado su página de man
, debe crear una versión final y luego instalarla en su sistema. El siguiente comando le dice a pandoc
que genere una página man
llamada “ms.1”:
pandoc ms.1.md -s -t hombre -o ms.1
Esto sigue la convención de nombrar la página del man
después del comando que describe y agregar el número de sección del manual como si fuera una extensión de archivo.
Esto crea un archivo "ms.1", que es nuestra nueva página de man
. ¿Dónde lo ponemos? Este comando nos dirá dónde busca el man
las páginas del man
:
camino de hombre
Los resultados nos dan la siguiente información:
- /usr/share/man: La ubicación de la biblioteca estándar de páginas
man
. No agregamos páginas a esta biblioteca. - /usr/local/share/man: este enlace simbólico apunta a “/usr/local/man”.
- /usr/local/man: Aquí es donde debemos colocar nuestra nueva página
man
.
Tenga en cuenta que las diferentes secciones del manual están contenidas en sus propios directorios: man1, man2, man3, etc. Si el directorio para la sección no existe, debemos crearlo.
Para ello escribimos lo siguiente:
sudo mkdir /usr/local/man/man1
Luego copiamos el archivo “ms.1” al directorio correcto:
sudo cp ms.1 /usr/local/man/man1
man
espera que las páginas man
estén comprimidas, así que usaremos gzip
para comprimirlas:
sudo gzip /usr/local/man/man1/ms.1
Para hacer que man
agregue el nuevo archivo a su base de datos, escriba lo siguiente:
sudo mandb
¡Eso es! Ahora podemos llamar a nuestra nueva página man
igual que cualquier otra escribiendo:
hombre sra.
Nuestra nueva página de man
se encuentra y se muestra.
Se ve como cualquier otra página de man
, con texto en negrita, subrayado y sangrado en los lugares apropiados.
Las líneas de descripción que se ajustan al lado de la opción que describen aparecen en la misma línea. Las líneas que son demasiado largas para caber aparecen debajo de la opción que describen.
También hemos generado automáticamente una sección de "Autores". El pie de página también incluye el número de versión del software, la fecha y el nombre del comando, tal como se define en el documento preliminar.
Si quieres . . .
Una vez pandoc
haya creado su página de man
, también puede editar directamente el archivo en el formato de macro groff
antes de moverlo al directorio de la página de man
y comprimirlo con gzip
.