Es un hecho muy común que a nadie le gusta escribir documentación. Diablos, a nadie le gusta leerlo tampoco. Pero hay momentos en que tenemos que leerlo para, por ejemplo, terminar el proyecto a tiempo o, especialmente cuando trabajamos en el desarrollo de software, incluso escribirlo. Si solo tiene que leerlo, siempre lo alentamos a que lo haga, pero si tiene que escribir las páginas manuales y necesita un Kickstart, aquí está el artículo para usted. Si trabajó anteriormente con HTML, su vida será más fácil, pero si no está bien. Escribir páginas manuales para Linux no es tan difícil, a pesar del aspecto de las páginas cuando se lee en texto simple. Así que básicamente necesitará algunos conocimientos de Linux y la capacidad de usar un editor de texto. Aprenderá (con ejemplos, por supuesto) los conceptos principales en el formato de texto que se aplica a las páginas del hombre y cómo escribir una página manual simple. Dado que usamos el Yest como ejemplo para nuestro tutorial de desarrollo C, usaremos fragmentos de su página manual para ilustrar nuestro punto durante este artículo.

Un poquito de historia

Se dice que los primeros paquetes manuales escritos son escritos por Dennis Ritchie y Ken Thompson en 1971. El software de formato utilizado fue Troff, y ese formato continúa utilizándose hasta el día de hoy, aunque las herramientas pueden ser diferentes. La herramienta de formato de texto en Linux Systems ahora es Groff, con la 'G' líder proveniente de GNU. La existencia de Groff se debe al hecho de que cuando se escribió Troff, las terminales significaban algo diferente en términos de capacidades que lo que significan hoy. Otro fuerte incentivo para el proyecto GNU para crear Groff fue la licencia de propiedad de Troff. Troff todavía vive en otros sistemas UNIX, como OpenSolaris o Plan9, aunque bajo licencias de código abierto.

Antes de comenzar, debemos decirle algo sobre *Roff: es un software tipográfico, como Tex, por ejemplo, y es un idioma por derecho propio. No transformaremos este artículo en un manual de Groff, ni haremos una lista de diferencias entre Groff y Troff. Este es solo un iniciador para una simple escritura manual de páginas, y si necesita más encontrará mucha documentación en Internet.

Alternativas

Si después de leer esto sentirá que la sintaxis es desalentadora, tenemos una solución para su problema: Pod2man. POD significa documentación antigua y ofrece una sintaxis más simple, y hay Pod2man, que es un módulo Perl (parte de Perlpod) que traduce la documentación escrita en formato POD al formato de manzana. PerlPod también ofrece herramientas para convertir POD en texto o HTML, así que solo consulte la documentación de su distribución sobre cómo instalarlo.

Páginas manuales

Categorías

Las páginas manuales se dividen en categorías, dependiendo de qué tema estén tratando. No difieren en las distribuciones de Linux, pero otros sistemas UNIX tienen diferentes formas de dividir las páginas manuales. Usando

 $ hombre hombre

te dará esas categorías y mucho más con respecto a cómo usar el comando hombre. Las categorías en Linux son las siguientes:

 1 programas ejecutables o comandos de shell
2 llamadas al sistema (funciones proporcionadas por el núcleo)
3 llamadas de biblioteca (funciones dentro de las bibliotecas de programas)
4 archivos especiales (generalmente encontrados en /dev)
5 formatos de archivo y convenciones, por ejemplo, etc
6 juegos
7 Varios (incluidos paquetes y convenciones macro), e.gramo. Hombre (7), Groff (7)
8 Comandos de administración del sistema (generalmente solo para root)
9 rutinas de núcleo [no estándar]

Se le aconseja que lea la página del manual del hombre, porque esta no es un tutorial sobre cómo usar ellos, pero como escribir a ellos.

Diseño de una página manual

Desde hace algunos años, hay un estándar sobre cómo escribir páginas manuales, lo que deben contener y problemas de estilo. Deben ser concisos, respetar el diseño y comprimir tanta información en la menor cantidad de espacio posible. Cuando uno ve un manual de 100 páginas, el primer reflejo será huir.

Muy muy lejos. Por otro lado, una página manual breve pero informativa que le dará al lector lo que él/ella quiere saber será de gran ayuda, en lugar de asustar/aburrir al usuario. Si el programa para el que está escribiendo páginas manuales no está escrito por usted (por completo), trabaje con los desarrolladores hasta que se conforma con el manual. Ahora, queremos evitar ser aburridos o aterradores, comencemos con el diseño.

En primer lugar, el nombre del archivo debe ser $ CommandName.$ categoría, como, por ejemplo, vim.1. Este archivo, cuando está instalado, debe ser GZIPS y copiado en el directorio apropiado, que para VIM debe ser/USR/Share/Man/Man1. El archivo no comprimido es un archivo de texto sin formato, nada más. Leer cualquier página manual le dará una idea sobre cómo debe verse el suyo: nombre, sinopsis, descripción, opciones, ejemplos, ayuda, archivos, ver también, autor y errores. No todos estos son obligatorios, pero se recomienda que les proporcione todos si el espacio es suficiente, para una mejor experiencia de usuario.

El lenguaje de marcado

Como se dijo anteriormente, si está acostumbrado a escribir XML o HTML, encontrará la sintaxis simple. De hecho, es simple de todos modos una vez que te acostumbras. Empezamos con el título, y el primer encabezado es el título de título. Las otras macros generalmente encontradas (el equivalente de las etiquetas en los idiomas de marcado) son encabezados de sujetos y párrafos, Pero más sobre eso más tarde.

El encabezado del título debe contener lo siguiente: nombre, capítulo (categoría) y la fecha en que se modificó la página por última vez. Entonces, para mojarse los pies, así es como debería verse:

.Th Yest 1 "19 de abril de 2010"

Significa que el título de título, y como es una macro, debe estar prefijada. Yest es el nombre de la aplicación, Categoría 1, editada por última vez el 19 de abril de 2010. Antes de ir más allá, es posible que desee insertar algunos comentarios en su archivo antes de que se encienda el título. Estos comienzan con .\ ”(Cotización de inalcanzado de puntos) y puede verse así:

.\ ”Copyright 2004, 2006, 2010 Kimball Hawkins .

.\" Reservados todos los derechos.

Ahora, inserte estas líneas (el encabezado y el comentario por encima) y verifique el resultado con

 $ Groff -Man -Tascii Yest.1

-Tascii instruye a Groff a salir en formato ASCII (texto), pero Groff admite otros tipos de salida. Te invitamos a ver la página del manual de Groff para eso.

A continuación, ahora que sabemos cómo lidiar con los encabezados de títulos, vamos a la sección encabezados. Como habrás adivinado, la macro es .Sh y lo que hace es introducir el nombre, la sinopsis, la descripción, etc. secciones como se escriben anteriormente. Entonces la sintaxis será:

.Mierda Nombre Yest - Utilidad de manipulación de fecha.

.Mierda SINOPSIS .B yest \ fr -help

.PAG .B yest \ fr -licence

.PAG .B yest \ fr -version

.PAG .B yest \ fr [\ fb-idf = \ fistr \ fr] [\ fb-tz = \ fitzone \ fr] [[\ fb- \ fr | \ fb+\ fr] \ fiadjust \ fr [\ fbd \ fr | \ fbh \ fr | \ fbm \ fr]] [\ fidato \ fr] [\ fiformat-string \ fr] .

Mierda Descripción Esto se llama ""Yest"" porque el valor predeterminado es emitir la fecha de ayer de ayer. Esta utilidad sabe sobre el año salto, el tiempo de ahorro de la luz del día y tales variaciones. Esta utilidad agrega o resta días, horas y/o minutos de una fecha determinada, y genera los resultados en el formato especificado. El valor predeterminado, si no se especifica ningún ajuste, es ""-1d""

Por supuesto, esto es solo una parte del manual, pero veamos qué significan las nuevas macros ... B significa Bold, y le recomendamos que peguen este código en un archivo y lo pruebe a medida que avanza, con el comando Groff anterior ... P Standss para el párrafo, porque como puede ver, después de cada .P Hay una doble línea doble en la página formateada. Los \ f* son secuencias de escape de cambio de fuentes, y lo que eso significa es que después de la palabra ""sinopsis"" .B le dice a Groff que imprima en negrita. Sin embargo, después de la palabra ""yest"" que de hecho se imprime en negrita, necesitamos ""-help"" para imprimir con fuentes regulares, por lo que esto es lo que representa. Por el contrario, \ fb significa ""imprimir en negrita"" y se puede usar indistintamente con .B . Usando la lógica, puede comprender lo que \ fl, por ejemplo, representa.

El texto simple, que es un texto que no es un encabezado o una sección, está contenido en los párrafos. Un párrafo simple es delimitado por un .PP Macro, que crea un pequeño espacio vertical entre el párrafo real y el siguiente. Si quieres un párrafo etiquetado, puedes tenerlo con .TP . A continuación hablaremos de sangría.

La sangría relativa significa que el texto está sangrado en relación con el texto anterior y siguiente. Para comenzar una parte de texto relativamente indentada, use .Rs (inicio relativo), y para terminar con él use .RE (fin relativo). Aquí hay un ejemplo:

.RS.7i Si hay espacios o caracteres especiales en la cadena, se debe citar. El programa reconocerá la mayoría de las convenciones de escape \ fbecho \ fR-like como ""\\ n"" (newline) y ""\\ t"" (tab) en \ fiformat-string \ fr, y los escapes octales (\\ 0nn) son compatibles con.

.P Si solo se especifica un ajuste de un día, la cuerda predeterminada \ fiformat \ fr es ""%x"". Si \ fiadjustment \ fr incluye un elemento de tiempo, el valor predeterminado \ fiformat-string \ fr se convierte en ""%x-%r"".

.RE

Como puede ver, puede tener un .P Macro dentro de un texto relativamente sangrado ... P es solo un alias para .PP, por lo que se pueden usar indistintamente. Es posible que hayas notado el "".7i ”después .RS: Eso le dice a Groff que sanque con siete espacios el texto dentro.

Usar tablas es tan sencilla como el uso de la sangría relativa: .TS y .TE. Puede, como se dijo anteriormente, modificar una palabra o un párrafo completo (desde un punto de vista tipográfico, es decir) con macros. Las tres formas en que puedes alterar a un personaje son, como todos saben, audaces, en cursiva y romano. Así por ejemplo, .Bi altera el texto que lo sigue en que aparecerá ambos atrevido y itálico.

Conclusión

Tenga en cuenta que esto puede ser suficiente para comenzar, pero no está completo. Estas no son todas las macros, y si cambia a un sistema BSD, puede encontrar que usan MANDOC en lugar de Groff, por lo que tendrá que hacer algo de aprendizaje usted mismo si desea ser competente. A continuación, lea algunas páginas manuales para ver las principales convenciones que deben respetarse, como poner los argumentos opcionales a su aplicación (si ese es el caso) en los soportes cuadrados o usar para mostrar que al menos uno de los argumentos dentro Los aparatos ortopédicos deben usarse. En general, documentar su software, incluso si su empleador no lo obliga, es bueno para usted y los usuarios de su software. Será considerado como un desarrollador cuidadoso y los usuarios pueden usar su creación más fácilmente, sabiendo lo que pueden y lo que no pueden hacer.

Tutoriales de Linux relacionados:

• Cosas para instalar en Ubuntu 20.04
• Cosas que hacer después de instalar Ubuntu 20.04 fossa focal Linux
• Cómo realizar instalaciones de Linux desatendidas con Kickstart
• Cómo verificar la duración de la batería en Ubuntu
• Cosas que hacer después de instalar Ubuntu 22.04 Jellyfish de Jammy ..
• Una introducción a la automatización, herramientas y técnicas de Linux
• Sistema colgado de Linux? Cómo escapar a la línea de comando y ..
• Cosas para instalar en Ubuntu 22.04
• Mint 20: Mejor que Ubuntu y Microsoft Windows?
• Instale Arch Linux en VMware Workstation