Página man

El hombre página en hombre (1), como se ve en varias distribuciones Linux. Esta versión es de hombre-db.

Una página de manual (abreviatura de página de manual) es una forma de documentación de software que normalmente se encuentra en un sistema operativo Unix o similar. Los temas cubiertos incluyen programas de computadora (incluidas llamadas a bibliotecas y sistemas), estándares y convenciones formales, e incluso conceptos abstractos. Un usuario puede invocar una página man emitiendo el comando man.

De forma predeterminada, man normalmente usa un programa buscapersonas de terminal como more o less para mostrar su salida.

Las páginas man a menudo se conocen como una forma de documentación de software en línea o en línea, aunque el comando man no requiere acceso a Internet, que se remonta a los tiempos en que los manuales impresos fuera de banda eran la norma.

Historia

xman, una aplicación X11 temprana para ver páginas manuales

OpenBSD sección 8 página del hombre intro, mostrando en una consola de texto

En los primeros dos años de la historia de Unix, no existía documentación. El Manual del programador de Unix se publicó por primera vez el 3 de noviembre de 1971. Las primeras páginas de manual reales fueron escritas por Dennis Ritchie y Ken Thompson ante la insistencia de su gerente Doug McIlroy en 1971. Aparte de las páginas de manual, el Programmer's Manual también acumularon un conjunto de documentos breves, algunos de ellos tutoriales (por ejemplo, para el uso general de Unix, el lenguaje de programación C y herramientas como Yacc), y otros descripciones más detalladas de las características del sistema operativo. La versión impresa del manual cabía inicialmente en una sola carpeta, pero a partir de PWB/UNIX y la 7.ª edición de Research Unix, se dividió en dos volúmenes y las páginas man impresas formaron el Volumen 1.

Las versiones posteriores de la documentación imitaron las primeras páginas man' brevedad. Ritchie agregó un mensaje "Cómo empezar" sección a la introducción de la Tercera Edición, y Lorinda Cherry proporcionó la "Tarjeta Púrpura" referencia de bolsillo para las ediciones Sexta y Séptima. Las versiones del software recibieron el nombre de la revisión del manual; la séptima edición del Manual del programador de Unix, por ejemplo, vino con la 7.ª edición o versión 7 de Unix.

Para la Cuarta Edición, las páginas del manual se formatearon utilizando el paquete de composición tipográfica troff y su conjunto de macros -man (que se revisaron por completo entre la Sexta y la Séptima Edición del Manual, pero desde entonces no han cambiado drásticamente). En ese momento, la disponibilidad de documentación en línea a través del sistema de páginas del manual se consideró un gran avance. Hasta el día de hoy, prácticamente todas las aplicaciones de línea de comandos de Unix vienen con una página de manual, y muchos usuarios de Unix perciben la falta de páginas de manual de un programa como una señal de baja calidad; de hecho, algunos proyectos, como Debian, se desviven por escribir páginas man para programas que carecen de una. Los descendientes modernos de 4.4BSD también distribuyen páginas de manual como una de las formas principales de documentación del sistema (habiendo reemplazado las antiguas macros -man con las nuevas -mdoc).

Había un huevo de Pascua oculto en la versión man-db del comando man que haría que el comando devolviera "dame, dame, dame" cuando se ejecuta a las 00:30 (una referencia a la canción de ABBA Gimme! Gimme! Gimme! (A Man After Midnight). Se introdujo en 2011 pero primero se restringió y luego se eliminó en 2017 después de que finalmente se encontró.

Formateo

Parte de la FreeBSD hombre (1) página manual, tipografía en formato PDF

El formato predeterminado de las páginas del manual es troff, ya sea con el paquete de macros man (orientado a la apariencia) o mdoc (orientado a la semántica). Esto hace posible escribir una página de manual en PostScript, PDF y varios otros formatos para ver o imprimir.

Algunos sistemas Unix tienen un paquete para el comando man2html, que permite a los usuarios navegar por sus páginas man usando un navegador HTML. Los sistemas con groff y man-db deberían usar la salida HTML nativa de mayor calidad (man --html) en su lugar. El programa GNU Emacs WoMan (de "WithOut man") permite navegar por las páginas man desde el editor.

En 2010, OpenBSD dejó de usar troff para dar formato a las páginas de manual en favor de mandoc, un compilador/formateador especializado para páginas de manual con soporte nativo para salida en PostScript, HTML, XHTML y la terminal. Está destinado a admitir solo un subconjunto de troff utilizado en páginas de manual, específicamente aquellas que usan macros mdoc.

Servicios en línea

Muchos sitios web ofrecen acceso en línea a páginas de manual de varios sistemas similares a Unix.

En febrero de 2013, la comunidad BSD vio el lanzamiento de un nuevo servicio mdoc.su de código abierto, que unificó y acortó el acceso a los scripts man.cgi de los principales proyectos modernos de BSD a través de un exclusivo servicio de acortamiento de URL determinista basado en nginx para el *Páginas man de BSD.

Para Linux, se ha configurado un servicio man7.org para servir manuales específicos del sistema. Un servicio ManKier proporciona una selección más amplia e integra también las páginas TLDR.

Uso de comandos

Para leer una página de manual para un comando de Unix, un usuario puede escribir:

hombre

Las páginas se denominan tradicionalmente mediante la notación "nombre(sección)": por ejemplo, ftp(1). La sección hace referencia a las diferentes formas en que se puede hacer referencia al tema, por ejemplo, como una llamada al sistema, un comando o paquete de shell (línea de comandos), o el archivo de configuración de un paquete, o como una construcción/encabezado de codificación.

El mismo nombre de página puede aparecer en más de una sección del manual, como cuando los nombres de las llamadas al sistema, los comandos de usuario o los paquetes de macros coinciden. Los ejemplos son man(1) y man(7), o exit(2) y exit(3). La sintaxis para acceder a la sección manual no predeterminada varía entre las diferentes implementaciones man.

En Solaris e illumos, por ejemplo, la sintaxis para leer printf(3C) es:

hombre - s 3c printf

En los derivados de Linux y BSD, la misma invocación sería:

hombre 3 printf

que busca printf en la sección 3 de las páginas man.

Secciones del manual

El manual generalmente se divide en ocho secciones numeradas, organizadas de la siguiente manera (en Research Unix, BSD, macOS y Linux):

Las llamadas al sistema POSIX suelen estar presentes en las secciones 2 y 3, donde la sección 2 contiene la documentación de la llamada del sistema del sistema operativo local y la sección 3 contiene la documentación de la llamada del sistema del programador de POSIX. 39;s Manual.

Unix System V usa un esquema de numeración similar, excepto en un orden diferente:

En algunos sistemas, algunas de las siguientes secciones están disponibles:

Algunas secciones se subdividen aún más por medio de un sufijo; por ejemplo, en algunos sistemas, la sección 3C es para las llamadas a la biblioteca C, la 3M es para la biblioteca matemática, etc. Una consecuencia de esto es que la sección 8 (comandos de administración del sistema) a veces se relega a la subsección 1M de la sección de comandos principales. Algunos sufijos de subsecciones tienen un significado general en todas las secciones:

(La Sección 3 tiende a ser la excepción con los muchos sufijos para diferentes idiomas).

Algunas versiones de man almacenan en caché las versiones formateadas de las últimas páginas vistas. Un formulario es la página del gato, simplemente canalizada al buscapersonas para su visualización.

Diseño

Todas las páginas man siguen un diseño común que está optimizado para la presentación en una pantalla de texto ASCII simple, posiblemente sin ninguna forma de resaltado o control de fuentes. Las secciones presentes pueden incluir:

NOMBRE

El nombre del comando o función, seguido de una descripción de una línea de lo que hace.

SYNOPSIS

En el caso de un comando, una descripción formal de cómo ejecutarlo y qué opciones de línea de comandos toma. Para las funciones del programa, una lista de los parámetros que toma la función y que archivo encabezado contiene su declaración.

DESCRIPCIÓN

Una descripción textual del funcionamiento del comando o función.

EXAMPLES

Algunos ejemplos de uso común.

SEE ALSO

Una lista de comandos o funciones relacionados.

Es posible que haya otras secciones, pero no están bien estandarizadas en las páginas del manual. Los ejemplos comunes incluyen: OPCIONES, ESTADO DE SALIDA, VALOR DEVUELTO, ENTORNO, ERRORES, ARCHIVOS, AUTOR, INFORME DE ERRORES, HISTORIAL y DERECHOS DE AUTOR.

Autoría

Las páginas del manual se pueden escribir en el antiguo man, las nuevas macros doc, o una combinación de ambos (mandoc). El conjunto de macros man proporciona funciones mínimas de texto enriquecido, con directivas para la línea de título, encabezados de sección, fuentes (negrita, pequeña o cursiva), párrafos y adición/reducción de sangría. El nuevo lenguaje mdoc es de naturaleza más semántica y contiene macros especializadas para la mayoría de las secciones estándar, como el nombre del programa, la sinopsis, los nombres de las funciones y el nombre de los autores. Esta información se puede utilizar para implementar una búsqueda semántica de manuales por parte de programas como mandoc. Aunque también incluye directivas para controlar directamente el estilo, se espera que las macros especializadas cubran la mayoría de los casos de uso. Tanto el proyecto mandoc como el groff consideran mdoc el preferido formato para nuevos documentos.

Aunque las páginas de manual son, para troff, texto diseñado con letra romana de 10 puntos, esta distinción suele ser discutible porque las páginas de manual se visualizan en la terminal (TTY) en lugar de en papel. Como resultado, la "fuente pequeña" Rara vez se utiliza la macro. Por otro lado, el terminal admite texto en negrita y cursiva a través de ECMA-48, y groff grotty los emite según lo solicitado cuando detecta una terminal compatible. Sin embargo, el mandoc BSD solo admite texto en negrita y subrayado (como reemplazo de la cursiva) a través de la secuencia de retroceso de la máquina de escribir y luego superposición, que debe traducirse a ECMA-48 mediante menos.

Las páginas de manual generalmente están escritas en inglés, pero es posible que haya traducciones a otros idiomas disponibles en el sistema. GNU man-db y mandoc man es conocido por buscar páginas de manual localizadas en subdirectorios.

Alternativas

Pocas alternativas a man han gozado de tanta popularidad, con la posible excepción de "info" del Proyecto GNU. sistema, un sistema de hipertexto temprano y simple. También hay un esfuerzo de terceros conocido como páginas TLDR (tldr) que proporciona ejemplos simples para casos de uso común, similar a una hoja de trucos.

Además, algunas aplicaciones GUI de Unix (particularmente aquellas construidas usando los entornos de desarrollo GNOME y KDE) ahora brindan documentación para el usuario final en HTML e incluyen visores HTML incrustados como yelp para leer la ayuda dentro la aplicación.