¿Dónde escribo una entrada manual al crear un paquete deb? ¿Hay alguna regla de formato o mejor práctica que se deba respetar?
Soy muy nuevo en la creación de paquetes deb. Siguiendo algunos tutoriales, acabo de crear un paquete que se instala/ejecuta muy bien, así que ahora me gustaría escribir algo de documentación para que man myFancyPackage devuelva algo en lugar de ninguna entrada manual para myFancyPackage .
Desafortunadamente, ninguno de los tutoriales que encontré habla sobre la creación manual.
Hay muchos métodos para crear un paquete Debian, pero la "mejor práctica" actual es utilizar las herramientas proporcionadas por Debhelper. En el caso de las páginas de manual, existe una herramienta llamada dh_installman (lea su página de manual ) que dh llama automáticamente. Si usó dh_make o similar para crear una plantilla para su paquete, entonces habrá una invocación de dh en su archivo debian/rules .
dh_installman funciona leyendo el archivo debian/manpages o debian/nameofyourpackage.manpages . Este archivo tiene una lista de rutas que apuntan a las páginas man de su paquete. Las rutas son relativas a la raíz de su paquete. Aquí tienes un ejemplo de un paquete real. Luego, este programa instalará correctamente sus páginas man en el directorio correcto.
Entonces, para resumir, solo tiene que crear debian/package.manpages y llenarlo con las rutas a sus páginas man. Estas rutas deben ser relativas a la raíz de su paquete. Si usted, el empaquetador, está escribiendo las páginas de manual, debe colocarlas en el directorio Debian/ .
Las páginas de manual se componían tradicionalmente en un lenguaje de composición llamado roff usando un paquete de macros llamado an (por lo que la línea de comando era roff -man , sic), pero pocas personas escriben roff sin procesar.
Hay varios formatos de documentación SGML y XML que tienen la capacidad de generar fuentes de páginas de man , aunque en la actualidad, Markdown probablemente esté ganando terreno como el estándar de facto para la nueva documentación. El principal éxito de Google para mí es https://github.com/remarkjs/remark-man , aunque definitivamente también te sugiero que consultes pandoc .
# NAME Markdown - popular text markup language # SYNOPSIS man markdown # DESCRIPTION This is a popular lightweight syntax to generate styled text from an editor-friendly text source. It is used on [Stack Overflow][1], [Github][2], and increasingly on blogging and authoring platforms. [1]: https://stackoverflow.com/ [2]: https://github.com/También mencionaré el formato POD , que tiene una larga historia en la comunidad de Perl y muchas características en común con los formatos ligeros más recientes y populares. A menos que tenga otras razones para que le guste, no lo elegiría para la documentación nueva, pero solía ser moderadamente popular incluso fuera del mundo de Perl cuando era una de las únicas opciones con un formato fuente legible por humanos, obvio semántica, y una cadena de herramientas y un ecosistema de soporte versátiles y bien mantenidos. Algunos probablemente dirían que todavía lo es.
=head1 NAME Pod::Example - Example POD document =head1 SYNOPSIS pod2man thisdoc.pod >thisdoc.1 =head1 DESCRIPTION Lightweight syntax for subheads, hyperlinks, indented lists, and not much else. Natively supported in Perl source files to facilitate a crude form of literate programming.