página de manual

Una página de manual (man page , por sus siglas en inglés ) es un tipo de documentación de software presente en sistemas operativos Unix y similares . Los temas que abarca incluyen programas, bibliotecas del sistema , llamadas al sistema y, en ocasiones, detalles del sistema local. Los administradores del host local pueden crear e instalar páginas de manual asociadas a dicho host. Un usuario final puede acceder a una página de documentación mediante el comando seguido del nombre del elemento para el que desea consultar la documentación. Estas páginas de manual suelen ser solicitadas por usuarios finales, programadores y administradores que trabajan en tiempo real, pero también pueden formatearse para su impresión.man

Por defecto, mannormalmente utiliza un programa de formato como nroffcon un paquete de macros o mandoc , y también un programa de paginación de terminal como moreo lesspara mostrar su salida en la pantalla del usuario.

Las páginas de manual se suelen considerar una forma en línea de documentación de software, ^{[ 1 ]} aunque el mancomando no requiera acceso a Internet, ya que están disponibles desde una interfaz de línea de comandos mano desde una interfaz gráfica de usuario con un visor de páginas de manual, en lugar de solo ser legibles en formato impreso. La variable de entorno MANPATH suele especificar una lista de rutas de directorio para buscar las distintas páginas de documentación. Las páginas de manual se remontan a la época en que la documentación impresa era la norma.

En algunos programas informáticos, a partir de 1987, la documentación consistía en páginas impresas, disponibles para los usuarios en las instalaciones. ^{[ 2 ]} En algunos sitios, se organizaban en carpetas de acero, unidas en un estante de lectura monolítico de acero, atornillado a una mesa o mostrador, con las páginas organizadas para actualizaciones, reemplazos, erratas y adiciones de información modular. Los manuales populares sobre microcomputadoras se anunciaban a la venta en carpetas de hojas sueltas con actualizaciones periódicas. ^{[ 3 ]}

En los dos primeros años de la historia de Unix , no existía documentación. ^{[ 4 ]} El Manual del Programador de Unix se publicó por primera vez el 3 de noviembre de 1971. Las primeras páginas de manual fueron escritas por Dennis Ritchie y Ken Thompson a instancias de su gerente, Doug McIlroy, en 1971. Además de las páginas de manual, el Manual del Programador también incluía una serie de artículos breves, algunos de ellos tutoriales (por ejemplo, sobre 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 inicialmente cabía en una sola carpeta, pero a partir de PWB/UNIX y la 7.ª edición de Research Unix , se dividió en dos volúmenes, formando las páginas de manual impresas el Volumen 1. ^{[ 5 ]}

Las versiones posteriores de la documentación imitaron la brevedad de las primeras páginas de manual. Ritchie añadió una sección de "Cómo empezar" a la introducción de la tercera edición , y Lorinda Cherry proporcionó la referencia de bolsillo "Tarjeta Púrpura" para la sexta y séptima ediciones. ^{[ 4 ]} 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, venía con la 7.ª edición o versión 7 de Unix. ^{[ 6 ]}

Para la Cuarta Edición, las páginas man se formatearon utilizando el paquete de composición tipográfica troff ^{[ 4 ]} y su conjunto de -manmacros (que fueron completamente revisadas entre la Sexta y la Séptima Edición del Manual , ^{[ 5 ]} 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 man 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 man, y muchos usuarios de Unix perciben la falta de páginas man de un programa como un signo de baja calidad o incompletitud. De hecho, algunos proyectos, como Debian , se esfuerzan por escribir páginas man para programas que carecen de una. Los descendientes modernos de 4.4BSD también distribuyen páginas man como una de las formas principales de documentación del sistema (habiendo reemplazado las antiguas -manmacros con las más nuevas -mdoc).

Había un huevo de Pascua oculto en la versión man-db del comando man que hacía que el comando devolviera "gimme gimme gimme" cuando se ejecutaba a las 00:30 (una referencia a la canción de ABBA Gimme! Gimme! Gimme! (A Man After Midnight) ). Se introdujo en 2011 ^{[ 7 ]} , pero primero se restringió ^{[ 8 ]} y luego se eliminó en 2017 ^{[ 9 ]} después de que finalmente se descubriera. ^{[ 10 ]}

El formato predeterminado de las páginas man es troff , con el paquete de macros man (orientado a la apariencia) o mdoc (orientado a la semántica). Esto permite formatear una página man en PostScript , PDF y otros formatos para su visualización o impresión.

Algunos sistemas Unix tienen un paquete para el comando man2html , que permite a los usuarios explorar 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 ). El programa WoMan (de "WithOut man") de GNU Emacs permite explorar las páginas man desde el editor. ^{[ 11 ]}

En 2010, OpenBSD dejó de usar troff para formatear páginas man y optó por mandoc , un compilador/formateador especializado para páginas man con soporte nativo para la salida en PostScript , HTML , XHTML y la terminal. Su objetivo es admitir únicamente un subconjunto de troff utilizado en las páginas man, concretamente aquellas que emplean macros mdoc.

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

hombre <nombre_del_comando> 

Las páginas se suelen denominar utilizando la notación "nombre(sección)": por ejemplo, ftp(1). La sección se refiere 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), un archivo de configuración de un paquete o una estructura de codificación/encabezado.

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

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

hombre -s 3c printf

En Linux y sus derivados, la misma invocación sería:

hombre 3 printf

que busca printf en la sección 3 de las páginas del manual. Es probable que el nombre del archivo incluya dicha sección. Siguiendo con este ejemplo, printf.3.gz sería un archivo de página del manual comprimido en la sección 3 para printf .

El manual generalmente se divide en ocho secciones numeradas. La mayoría de los sistemas actuales (por ejemplo, BSD , ^{[ 17 ]} macOS , Linux , ^{[ 18 ]} y Solaris 11.4) heredan el esquema de numeración utilizado por Research Unix , ^{[ 19 ] [ 20 ]} mientras que System V utiliza un orden diferente: ^{[ 21 ]}

Las API POSIX están presentes tanto en la sección 2 como en la sección 3, donde la sección 2 contiene API implementadas como llamadas al sistema y la sección 3 contiene API implementadas como rutinas de biblioteca.

En algunos sistemas, pueden incluirse secciones adicionales, como por ejemplo:

Algunas secciones se subdividen aún más mediante un sufijo; por ejemplo, en algunos sistemas, la sección 3C es para las llamadas a la biblioteca C, la 3M para la biblioteca matemática, y así sucesivamente. Como consecuencia, la sección 8 (comandos de administración del sistema) a veces se relega a la subsección 1M de la sección principal de comandos. Algunos sufijos de subsección tienen un significado general en todas las secciones:

(La sección 3 suele ser la excepción, ya que contiene muchos sufijos para diferentes idiomas).

Algunas versiones almacenan en mancaché las versiones formateadas de las últimas páginas visitadas. Un ejemplo es la página del gato , que simplemente se envía al paginador para su visualización.

Todas las páginas de manual siguen un diseño común optimizado para su visualización en una pantalla de texto ASCII simple , posiblemente sin ningún tipo de resaltado o control de fuente. Las secciones presentes pueden incluir: ^{[ 23 ] : ESTRUCTURA DEL MANUAL}

NOMBRE

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

SINOPSIS

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

DESCRIPCIÓN

Descripción textual del funcionamiento del comando o función. En el caso de los programas, esta sección suele incluir explicaciones de las opciones de línea de comandos disponibles.

EJEMPLOS

Algunos ejemplos de uso común.

VER TAMBIÉN

Una lista de comandos o funciones relacionadas.

Es posible que existan otras secciones, pero no están bien estandarizadas en todas las páginas de manual. Algunos ejemplos comunes son: OPCIONES, ESTADO DE SALIDA, VALOR DE RETORNO, ENTORNO, ERRORES, ARCHIVOS, AUTOR, INFORMACIÓN DE ERRORES, HISTORIAL y DERECHOS DE AUTOR.

Las páginas del manual se pueden escribir tanto en las manmacros antiguas como en las nuevas doc. ^{[ 24 ]} El manconjunto de macros proporciona funciones de texto enriquecido mínimas , con directivas para la línea de título, encabezados de sección, fuentes (negrita, minúscula o cursiva), párrafos y adición/reducción de sangría. ^{[ 25 ]} El mdoclenguaje más reciente 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 mediante 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. ^{[ 23 ]} Tanto el proyecto mandoc como el proyecto groff consideran mdocel formato preferido para los nuevos documentos. ^{[ 26 ]}

Aunque las páginas man son, para troff, texto maquetado con tipografía romana de 10 puntos , esta distinción suele ser irrelevante porque las páginas man se visualizan en la terminal (TTY) en lugar de en papel. Como resultado, la macro "fuente pequeña" se usa raramente. ^{[ 27 ]} Por otro lado, la terminal admite texto en negrita y cursiva a través de ECMA-48 , y groff grottylos emite según se solicita cuando detecta una terminal compatible. Sin embargo, el mandoc de BSD solo admite texto en negrita y subrayado (como reemplazo de la cursiva) a través de la secuencia de retroceso y luego sobretachado de la máquina de escribir, que necesita ser traducida a ECMA-48 por less. ^{[ 28 ] [ 29 ]}

Algunas herramientas se han utilizado para convertir documentos en un formato menos artificial a páginas de manual. Ejemplos incluyen GNU help2man, que toma una --helpsalida y algún contenido adicional para generar una página de manual. ^{[ 30 ]} El manual sería apenas más útil que dicha salida, pero para los programas GNU esto no es un problema ya que texinfo es el sistema de documentación principal. ^{[ 31 ]} Varias herramientas, incluidas pandoc , ronn y md2man, admiten la conversión de Markdown a páginas de manual. Todas estas herramientas emiten el manformato, ya que Markdown no es lo suficientemente expresivo como para coincidir con el contenido semántico de mdoc. DocBook tiene un convertidor man(7) incorporado , de pésima calidad, según el autor de mandoc ^{[ 32 ]} que escribió un convertidor mdoc(7) separado.

Las páginas de manual suelen estar escritas en inglés, pero es posible que el sistema ofrezca traducciones a otros idiomas. Se sabe que GNU man-dby mandoc manbuscan páginas de manual localizadas en subdirectorios. ^{[ 33 ] [ 18 ] : Resumen [ 17 ]}

• Lista de comandos de Unix
• Lista de solicitudes del Plan 9
• info
• apropos
• LÉAME
• Lee el manual
• ManOpen – Utilidad gráfica de manual para NeXT / macOS

• Historia de las páginas de manual de UNIX : una fuente primaria que ofrece información histórica sobre las páginas de manual de UNIX.
• Repositorio de páginas de manual de UNIX y Linux con casi 300.000 páginas de manual bien formateadas.
• ¿Qué significan los números en una página de manual?
• Las páginas del manual de FreeBSD , freebsd.org, también incluyen páginas del manual para Darwin, Debian, HP-UX, IRIS, NetBSD, OpenBSD, NextSTEP, SunOS y más.
• El proyecto de páginas man de Linux