Cómo crear una página de manual en Linux

¿Quiere que su nuevo programa de Linux tenga un aspecto profesional? Dale un man página. Le mostraremos la forma más fácil y rápida de hacerlo.

Las páginas del hombre

Puede haber algo de verdad en el viejo chiste de Unix, «el solo comando que necesitas saber es man. » los man Las páginas 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 un man página de una utilidad o comando que ha escrito lo eleva de un código útil a un paquete de Linux absolutamente formado. La gente espera un man página que se proporcionará para un programa que se ha escrito para Linux. Si es compatible de forma nativa con Linux, man La página es obligatoria si desea que su programa sea tomado en serio.

Históricamente el man las páginas se han escrito usando un conjunto de macros de formato. Cuando llamas a man para abrir una página, llama groff para leer el archivo y generar una salida formateada, según las macros del archivo. La salida se canaliza a less, y posteriormente mostrado para ti.

A menos que crees man páginas a menudo, escribir una e insertar manualmente las macros es un trabajo duro. El acto de crear un man página que se analiza correctamente y se ve bien puede superar su objetivo de proporcionar una descripción concisa, pero completa, de su comando.

Debe concentrarse en su contenido, no luchar contra un oscuro conjunto de macros.

RELACIONADO: Cómo utilizar el comando man de Linux: secretos ocultos y conceptos básicos

pandoc al rescate

los pandoc programa lee archivos de marcado y genera otros nuevos en aproximadamente 40 lenguajes de marcado y formatos de documento diferentes, incluido el del man página. Transforma totalmente el man procedimiento de escritura de páginas para que no tenga que luchar 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 install pandoc

En Manjaro, escriba:

sudo pacman -Syu pandoc

RELACIONADO: Cómo utilizar pandoc para convertir archivos en la línea de comandos de Linux

Secciones de una página de manual

man Las páginas contienen secciones que siguen una convención de nomenclatura estándar. Las secciones tu man las necesidades de la página están dictadas por la sofisticación del comando que está describiendo.

Mínimamente, la mayoría de las páginas de manual contienen estas secciones:

• Nombre: El nombre del comando y un breve resumen que describe su función.
• Sinopsis: Una descripción concisa 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 alternativas de la línea de comandos y lo que hacen.
• Ejemplos de: Algunos ejemplos de uso común.
• Valores de salida: Los posibles códigos de retorno y sus significados.
• Insectos: Una lista de errores y peculiaridades conocidos. A veces, esto se complementa con (o se reemplaza por) un link al rastreador de problemas del proyecto.
• Autor: La persona o personas que escribieron el comando.
• Derechos de autor: Su mensaje de derechos de autor. Estos además suelen incluir el tipo de licencia bajo la cual se lanza el programa.

Si observas algunos de los más complicados man páginas, verá que además hay muchas otras secciones. A modo de ejemplo, intente man man. A pesar de esto, no tiene que incluirlos todos, solo los que verdaderamente necesita. man las páginas no son lugar para la palabrería.

Algunas otras secciones que verá con bastante frecuencia son:

• Ver además: 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 a conocer o prestar atención.
• Historia: Un historial de cambios para el comando.

Secciones del manual

El manual de Linux se compone de todos los man páginas, que posteriormente se divide en estas secciones numeradas:

1. Programas ejecutables: O comandos de shell.
2. Llamadas al sistema: Funciones proporcionadas por el kernel.
3. Llamadas a la biblioteca: Funciones dentro de las bibliotecas de programas.
4. Archivos especiales.
5. Convenciones y formatos de archivo: A modo de ejemplo, «/ etc / passwd».
6. Juegos.
7. Diverso: Convenciones y paquetes de macros, como groff.
8. Comandos de administración del sistema: Regularmente reservado para root.
9. Rutinas del kernel: No suele instalarse de forma predeterminada.

Cada man La página debe indicar a qué sección pertenece, y además debe almacenarse en la ubicación adecuada para esa sección, como veremos más adelante. los man las páginas de comandos y utilidades pertenecen a la sección uno.

El formato de una página de manual

los groff El formato macro no es fácil de analizar visualmente. Por el contrario, la rebaja es muy sencilla.

A continuación se muestra una página de manual en groff.

La misma página se muestra a continuación en rebajas.

Materia delantera

Las primeras tres líneas forman algo llamado asunto principal. Todos estos deben comenzar con un signo de porcentaje (%), sin espacios iniciales, excepto 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 man encabezado de página. Por convención, el nombre del comando está en mayúsculas, aún cuando encontrará muchos que no lo son. Todo lo que sigue al nombre del comando y al número de sección del manual se convierte en la sección izquierda del pie de página. Es conveniente utilizar 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 del man página. No es necesario que agregue una sección «Autores», solo incluya al menos un nombre aquí.
• La tercera línea: La fecha, que además se convierte en la parte central del pie de página.

Nombre

Las secciones se indican a través de líneas que comienzan con un signo de número (#), que es el marcado que indica un encabezado en el marcado. El signo de número (#) debe ser el primer carácter de la línea, seguido de un espacio.

La sección de nombre cuenta con una línea sencilla que incluye el nombre del comando, un espacio, un guión (-), un espacio y posteriormente 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 comandos. 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 significa que el nombre se mostrará en negrita en el man página. Un solo asterisco (*) a ambos lados de un texto hace que el man página para mostrarla subrayada.

De forma predeterminada, un salto de línea va seguido de una línea en blanco. Para forzar una ruptura dura sin una línea en blanco, puede utilizar una barra invertida al 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.

Usando dos signos numéricos (##) al comienzo de una línea crea un título de nivel dos. Puede usarlos para dividir su descripción en partes más pequeñas.

Opciones

La sección de alternativas contiene una descripción de las alternativas de la línea de comandos que se pueden utilizar con el comando. Por convención, estos se muestran en negrita, por lo tanto incluya dos asteriscos (**) antes y después de ellos. Incluya la descripción de texto de las alternativas en la próxima línea y comience con dos puntos (:), seguido de un espacio.

Si la descripción es lo suficientemente breve, man lo mostrará en la misma línea que la opción de línea de comandos. Si es demasiado largo, se muestra como un párrafo con sangría que comienza en la línea debajo de la opción de línea de comandos.

Ejemplos de

La sección de ejemplos contiene una selección de diferentes formatos de línea de comandos. Tenga en cuenta que empezamos las líneas descriptivas con dos puntos (:), del mismo modo que hicimos con la sección de alternativas.

Valores de salida

Esta sección enumera los valores de retorno que su comando envía al procedimiento de llamada. Este podría ser el shell si lo llamó desde la línea de comandos, o un script si lo lanzó desde un script de shell. Empezamos las líneas descriptivas con dos puntos (:) en esta sección además.

Insectos

La sección de errores enumera los errores conocidos, las trampas o las peculiaridades que las personas deben conocer. Para proyectos open source, es común incluir aquí un link 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 man página en su editor favorito. La mayoría de los que admiten el resaltado de sintaxis estarán al tanto de las rebajas y colorearán el texto para resaltar los títulos, así como en negrita y subrayarlo. Eso es genial en la medida de lo factible, pero no estás viendo un renderizado man página, que es la verdadera prueba 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 de la terminal:

pandoc ms.1.md -s -t man | /usr/bin/man -l -

Una vez que haya usado este comando, puede presionar la flecha hacia arriba para repetirlo y posteriormente presionar Enter.

Este comando además invoca pandoc en el archivo de rebajas (aquí, se llama «ms.1.md»):

• los -s (independiente) genera una completa de arriba a abajo man página, en lugar de solo texto en man formato.
• los -t La opción (tipo de salida) con el operador «man» indica pandoc para generar su salida en man formato. No hemos dicho pandoc para enviar su salida a un archivo, por lo que se enviará a stdout.

Además estamos canalizando esa salida a man con el -l (archivo local) opción. Dice man no buscar a través del man base de datos buscando el man página. En su lugar, debería abrir el archivo nombrado. Si el nombre del archivo es -, man tomará su entrada de stdin.

Esto se reduce a que puede guardar desde su editor y presionar Q para cerrar man si se está ejecutando en la ventana de la terminal. Después, puede presionar la flecha hacia arriba, seguida de Enter para ver una versión renderizada de su man página, justo dentro man.

RELACIONADO: ¿Qué son stdin, stdout y stderr en Linux?

Creando tu página man

Una vez que haya completado su man página, debe crear una versión final y posteriormente instalarla en su sistema. El siguiente comando dice pandoc para generar un man página llamada «ms.1»:

pandoc ms.1.md -s -t man -o ms.1

Esto sigue la convención de nombrar el man página después del comando que describe y agregando el número de sección del manual como si fuera una extensión de archivo.

Esto crea un archivo «ms.1», que es nuestro nuevo man página. ¿Dónde lo ponemos? Este comando nos dirá dónde man busca man páginas:

manpath

Los resultados nos dan la próxima información:

• / usr / share / man: La ubicación de la biblioteca estándar de man páginas. No agregamos páginas a esta biblioteca.
• / usr / local / share / man: Este link simbólico apunta a «/ usr / local / man».
• / usr / local / man: Aquí es donde debemos colocar nuestro nuevo man página.

Tenga en cuenta que las diferentes secciones del manual están contenidas en sus propios directorios: man1, man2, man3, etc. Si el directorio de la sección no existe, debemos crearlo.

Para hacerlo, escribimos lo siguiente:

sudo mkdir /usr/local/man/man1

Después copiamos el archivo «ms.1» al directorio correcto:

sudo cp ms.1 /usr/local/man/man1

man espera el man páginas a comprimir, por lo tanto usaremos gzip para comprimirlo:

sudo gzip /usr/local/man/man1/ms.1

Para hacer man agregue el nuevo archivo a su base de datos, escriba lo siguiente:

sudo mandb

¡Eso es todo! Ahora podemos llamar a nuestro nuevo man página igual que cualquier otra escribiendo:

man ms

Nuestro nuevo man se encuentra y se muestra la página.

Se parece a cualquier otro man página, 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.

Además hemos generado automáticamente una sección de «Autores». El pie de página además incluye el número de versión del software, la fecha y el nombre del comando, tal como se establece en la página principal.

Si deseas . . .

Una vez pandoc ha creado tu man página, además puede editar de forma directa el archivo en la groff formato macro antes de moverlo a la man directorio de páginas, y gzip eso.