¿Quiere que su nuevo programa de Linux se vea profesional? Dale una manpágina. Le mostraremos la forma más fácil y rápida de hacerlo.
Hay algo de verdad en el viejo chiste de Unix, «el único comando que necesitas saber es man«. Las manpáginas contienen una gran cantidad de conocimientos y deberían ser el primer lugar al que acudir cuando desee aprender sobre un comando.
Proporcionar una manpágina 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 manque se proporcione una página para un programa que ha sido escrito para Linux. Si es compatible de forma nativa con Linux, una manpágina es obligatoria si desea que su programa se tome en serio.
Históricamente, las manpáginas se han escrito utilizando un conjunto de macros de formato. Cuando llama manpara abrir una página, llama groffpara leer el archivo y generar una salida formateada , de acuerdo con las macros del archivo. La salida se canaliza lessy luego se muestra .
A menos que cree manpáginas con frecuencia, escribir una e insertar manualmente las macros es un trabajo duro. El acto de crear una manpágina que se analiza correctamente y se ve bien puede superar su objetivo de proporcionar una descripción concisa, pero completa, de su comando.
Debes concentrarte en tu contenido, no luchar contra un oscuro conjunto de macros.
El pandocprograma lee archivos de marcado y genera otros nuevos en aproximadamente 40 lenguajes de marcado y formatos de documento diferentes, incluido el de la manpágina. Transforma totalmente el manproceso de escritura de páginas para que no tenga que luchar con jeroglíficos.
Para comenzar, puede instalar pandocen 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
manLas páginas contienen secciones que siguen una convención de nomenclatura estándar. Las secciones que mannecesita su página 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:
Si examina algunas de las manpáginas más complicadas , verá que también hay muchas otras secciones. Por ejemplo, inténtalo man man. Sin embargo, no tiene que incluirlos todos, solo los que realmente necesita. manlas páginas no son lugar para la palabrería.
Algunas otras secciones que verá con bastante frecuencia son:
El manual de Linux se compone de todas las manpáginas, que luego se divide en estas secciones numeradas:
groff.Cada manpágina 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 manpáginas de comandos y utilidades pertenecen a la sección uno.
El groffformato 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 formato groff.
La misma página se muestra a continuación en rebajas.
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:
manencabezado de la página. 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.manpágina. No es necesario que agregue una sección «Autores», solo incluya al menos un nombre aquí.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 marcado. El signo de número ( #) debe ser el primer carácter de la línea, seguido de un espacio.
La sección del nombre contiene una breve línea 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.
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 manpágina. Un solo asterisco ( *) a cada lado de un texto hace que la manpágina 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 ( \).
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.
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, la man 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 sangrado que comienza en la línea debajo de la opción de línea de comandos.
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 hicimos con la sección de opciones.
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.
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.
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.
Puede editar su manpá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 subrayado. Eso es genial hasta donde llega, pero no estás mirando una manpágina renderizada , 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 luego presionar Enter.
Este comando también invoca pandocen el archivo de rebajas (aquí, se llama «ms.1.md»):
-sopción (independiente) genera una manpágina completa de arriba a abajo , en lugar de solo un texto en manformato.-topción (tipo de salida) con el operador «man» le dice pandocque genere su salida en manformato. No le hemos dicho pandocque envíe su salida a un archivo, por lo que se enviará a stdout.También estamos canalizando esa salida man con la -lopción (archivo local). Le dice que man no busque en la manbase de datos buscando la manpágina. En su lugar, debería abrir el archivo nombrado. Si el nombre del archivo es -, mantomará 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. Luego, puede presionar la flecha hacia arriba, seguida de Enter para ver una versión renderizada de su manpágina, justo adentro man.
Una vez que haya completado su manpágina, debe crear una versión final y luego instalarla en su sistema. El siguiente comando le dice pandoc que genere una manpágina llamada «ms.1»:
pandoc ms.1.md -s -t man -o ms.1
Esto sigue la convención de nombrar la manpágina 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 manpágina. Donde lo ponemos Este comando nos dirá dónde manbusca las manpáginas:
manpath
Los resultados nos dan la siguiente información:
manpáginas. No agregamos páginas a esta biblioteca.manpá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
Luego copiamos el archivo «ms.1» al directorio correcto:
sudo cp ms.1 / usr / local / man / man1
manespera que las manpáginas estén comprimidas, así que usaremos gzip para comprimirlo :
sudo gzip /usr/local/man/man1/ms.1
Para managregar el nuevo archivo a su base de datos, escriba lo siguiente:
sudo mandb
¡Eso es! Ahora podemos llamar a nuestra nueva manpágina igual que cualquier otra escribiendo:
hombre ms
Nuestra nueva manpágina se encuentra y se muestra.
Tiene el mismo aspecto que cualquier otra manpágina, con texto en negrita, subrayado y sangrado en los lugares apropiados.
Las líneas de descripción que encajan junto a 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 «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.
Una vez que pandochaya creado su manpágina, también puede editar directamente el archivo en el groffformato de macro antes de moverlo al mandirectorio de la página, y gziplo.
El mundo del gaming ha experimentado un crecimiento exponencial en los últimos años. La…
Stokkete/Shutterstock.com ¿Sigue utilizando una unidad flash USB obsoleta para almacenar sus archivos? ¿Por qué no…
LG Los fabricantes siempre intentan mejorar el rendimiento de imagen de los monitores. Como resultado,…
Patty Chan/Shutterstock.com Si cree en lo que ve en las redes sociales, puede pensar en…
Seksan.TH/Shutterstock.com Los servicios de suscripción como Netflix, Game Pass y Spotify nos permiten consumir tantas…
fatmawati achmad zaenuri/Shutterstock El acceso a Internet, oa cualquier otra red, se rige por la…