Porque le estoy cogiendo el gusto a ese formato y necesito herramientas suaves que no me entorpezcan.

El artículo que me ha dado la idea es Man pages with Markdown and Pandoc de Grabriele Musco. Muy sencillo de entender y con un buen ejemplo y refencias directas.

pandoc, del que ya he hablado antes, es un programa que permite la conversión entre diferentes formatos de texto. Algunos con más acierto que otros pero de excelentes resultados en casi todos los que he probado.

En este caso pretendo tener plantillas para las páginas de manual más usadas para construir paquetes de software: páginas de configuración (man 5), páginas de programas (man 1) y páginas diversas (man 7) como las que uso para todo el paquete. Según el artículo hay dos dialectos -por llamarlos de alguna manera- de pandoc que deben usarse para que la conversión funcione correctamente.

El primero es Metadata blocks que proporciona información normalizada de ciertos párrafos del documento que comienzan con el carácter porcentaje (»%»). En este caso la extensión que precisamos es pandoc_title_block y es siempre analizada aunque sólo se emplea si se usa el parámetro »–standalone» de »pandoc».

En el caso del escritor de páginas de manual utiliza la primera línea para obtener lo siguiente:

% PANDOC(1) Pandoc User Manuals | Version 4.0

• El título de la página de manual »PANDOC»
• La sección de manual donde se encuentra »(1)» (sin espacios que lo separen.
• Texto en el pie de página »Pandoc User Manuals».
• Texto en la cabecera »Version 4.0» (separado por una barra vertical).

El segundo son las listas con definiciones (definition lists), un tipo de lista de elementos donde cada uno puede llevar uno o varios párrafos descriptivos. Es idóneo para describir parámetros de uso de un programa u opciones de configuración.

 `--cron` 
 :  Este parámetro provoca una copia de seguridad de todas 
 las cuentas de correo definidas en `/etc/backups-gmail/email.lists`.
 

 `--email ` *direccion*
 : Este parámetro realiza una copia de seguridad de la dirección indicada como argumento.
 

 `--config ` *archivo*
 :  Define el archivo de configuración a emplear en lugar de los valores predeterminados. 

Para crear la página de manual se necesita una plantilla que sólo se tenga que rellenar después:

% programa(seccion) package description | version

# NAME

 nombre_del_programa - descripción_corta_del_programa

# USAGE

 $ nombre_del_programa [lista_de_parametros] [otros]

Ejemplo sencillo e ilustrativo de uso del programa. No se suele leer más allá de esta sección (como mucho la siguiente que implica a los parámetros). 

# OPTIONS

Si el programa acepta parámetros en la llamada se describen en esta sección. Si no se puede borrar por completo. 

--parametro1 
: explicación del parámetro en varios párrafos si es necesario
--parametro2 
: explicación del parámetro en varios párrafos si es necesario 

# DESCRIPTION

Descripción completa del programa y sus características. Puede incluir varias subsecciones para separar mejor los tópicos utilizando niveles inferiores de encabezado (##, ###, etc.).

# DIAGNOSTICS

Lista de mensajes de error y avisos que la aplicación puede llegar a generar, con una explicación completa de cada problema, las causas probables y cualquier remedio que pueda adoptarse. 

 En el caso de códigos de estado de salida (al estilo UNIX) la lista debe incluirlos también.

# CONFIGURATION AND ENVIRONMENT

Una descripción completa de cualquier configuración en el sistema que pueda usarse en el programa, comenzando por variables de entorno y siguiendo por archivos de configuración y su contenido. 

# DEPENDENCIES

Este programa depende de los siguientes programas o bibliotecas:

  - programa1
  - programa2 

# INCOMPATIBILITIES

Lista de aspectos o funcionamiento con los que son incompatibles, incluyendo la presencia de otros programas problemáticos. 

# BUGS AND LIMITATIONS

Lista de errores o posibles situaciones de error. Si no los tiene se puede indicar lo siguiente:

No hay actualmente errores conocidos en este programa.

# AUTHOR

Víctor Moral victor@taquiones.net

# LICENCE AND COPYRIGHT

Copyright (c) 2020 < Víctor Moral >. All rights reserved.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program.  If not, see https://www.gnu.org/licenses/.

Y luego proceder a convertirla en una página de manual con una invocación simple:

$ pandoc --standalone --to man manual.md > manual.1

El resultado se puede instalar directamente en el directorio correspondiente.