¿Quiere que su nuevo programa de Linux se vea profesional? Dale una página de manual. Le mostraremos la forma más fácil y rápida de hacerlo.
Tabla de contenido
Las páginas del hombre
Hay algo de verdad en el viejo chiste de Unix, «el solo comando que necesitas conocer es el hombre «. Las páginas de manual 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 manual para una utilidad o comando que ha 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 manual para un programa que ha sido escrito para Linux. Si es compatible de forma nativa con Linux, una página de manual es obligatoria si desea que su programa sea tomado en serio.
Históricamente, las páginas de manual se han escrito utilizando un conjunto de macros de formato. Cuando pides al hombre que abra una página, llama a groff a leer el archivo y generar salida formateada, de acuerdo con las macros del archivo. La salida se canaliza a menos y luego mostrado para ti.
A menos que cree páginas de manual con frecuencia, escribir una e insertar manualmente las macros es un trabajo duro. El acto de crear una página de manual 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.
pandoc al rescate
los programa pandoc lee archivos de marcado y genera otros nuevos en aproximadamente 40 lenguajes de marcado y formatos de documento diferentes, incluido el de la página de manual. Transforma totalmente el proceso de escritura de la página de manual 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
Secciones de una página de manual
Las páginas man contienen secciones que siguen una convención de nomenclatura estándar. Las secciones que necesita su página de manual están determinadas por la sofisticación del comando que está describiendo.
Como mínimo, 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 opciones de la 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 conocidos. A veces, esto se complementa con (o se reemplaza por) un enlace al rastreador de problemas del proyecto.
Autor: la persona o personas que escribieron el comando.
Copyright: su mensaje de copyright. Estos también suelen incluir el tipo de licencia bajo la cual se lanza el programa.
Si examina algunas de las páginas de manual 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 de manual 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 a 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 manual, que luego se divide en estas secciones numeradas:
Programas ejecutables: O comandos de shell.
Llamadas al sistema: funciones proporcionadas por el kernel.
Llamadas a bibliotecas: funciones dentro de las bibliotecas de programas.
Archivos especiales.
Convenciones y formatos de archivo: 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 manual 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 de manual para comandos y utilidades pertenecen a la sección uno.
El formato de una página de manual
El formato de macro de groff 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 principal
Las primeras tres líneas forman algo que se llama 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, seguida 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 manual. Por convención, el nombre del comando está en mayúsculas, aunque 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 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 de manual. No es necesario que agregue una sección «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 el descuento. El signo de número (#) debe ser el primer carácter de la línea, seguido de un espacio.
La sección del nombre tiene una línea rápida 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 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 significan que el nombre se mostrará en negrita en la página del manual. Un solo asterisco
a cada lado de un texto hace que la página de manual lo muestre subrayado.
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 usar una barra diagonal inversa ().
Sección de descripción de una página de manual en markdown.
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 título de nivel dos. Puede usarlos para dividir su descripción en partes más pequeñas.
Sección de opciones de una página de manual en markdown.
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 (:), seguidos de un espacio.
Si la descripción es lo suficientemente corta, man la 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.
Sección de ejemplos de una página de manual en markdown.
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 descriptivas con dos puntos (:), tal como hicimos con la sección de opciones.
Salir de la sección de valores de una página de manual en Markdown.
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 lanzó desde un script de shell. También comenzamos las líneas descriptivas con dos puntos (:) en esta sección.
Sección de errores de una página de manual en Markdown.
La sección de errores enumera los errores conocidos, las trampas o las peculiaridades que las personas deben conocer. Para proyectos de código abierto, es común incluir aquí un enlace al rastreador de problemas del proyecto para verificar el estado de cualquier error o informar sobre nuevos.
Sección de copyright de una página de manual en markdown.
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 manual en su editor favorito. La mayoría de los que admiten el resaltado de sintaxis reconocerán las rebajas y colorearán el texto para resaltar los títulos, así como en negrita y subrayado. Eso es genial hasta donde llega, pero no estás viendo una página de manual renderizada, que es la prueba real en el pudín.
pandoc ms.1.md -s -t man | /usr/bin/man -l -
pandoc ms.1.md -s -t man | / usr / bin / man -l – en una ventana de terminal.
Una vez que haya usado este comando, puede presionar la flecha hacia arriba para repetirlo y luego presionar Enter.
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ágina de manual completa de arriba a abajo, en lugar de solo texto en formato man.
La opción -t (tipo de salida) con el operador «man» le dice a pandoc que genere su salida en formato man. No le hemos dicho a pandoc que envíe su salida a un archivo, por lo que se enviará a stdout.
También estamos canalizando esa salida a man con la opción -l (archivo local). Le dice a man que no busque en la base de datos man buscando la página man. 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 terminal. Luego, puede presionar la flecha hacia arriba, seguida de Enter para ver una versión renderizada de su página de manual, justo dentro de man.
Creando tu página man
pandoc ms.1.md -s -t man -o ms.1
pandoc ms.1.md -s -t man -o ms.1 en una ventana de terminal.
Esto sigue la convención de nombrar la página de manual después del comando que describe y agregar el número de sección del manual como si fuera una extensión de archivo.
manpath
manpath en una ventana de terminal.
Los resultados nos dan la siguiente información:
/ usr / share / man: la ubicación de la biblioteca estándar de páginas de manual. 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 de manual.
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.
sudo mkdir /usr/local/man/man1
Para hacerlo, escribimos lo siguiente:
sudo cp ms.1 /usr/local/man/man1
Luego copiamos el archivo «ms.1» al directorio correcto: man espera que las páginas del manual estén comprimidas, así que usaremos gzippara comprimirlo
sudo gzip /usr/local/man/man1/ms.1
:
sudo mandb
sudo mkdir / usr / local / man / man1 en una ventana de terminal.
man ms
man ms en una ventana de terminal.
sección superior de una nueva página de manual.
sección central de la nueva página de manual.
Sección inferior de una nueva página de manual.
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 la página principal.
Si quieres . . .
Una vez que pandoc ha creado su página de manual, también puede editar directamente el archivo en el formato de macro groff antes de moverlo al directorio de la página de manual y gziplo.