.jpg/1280px-Sed_stream_editor_(cropped).jpg)
Una página de manual (abreviatura de página de manual ) es una forma de documentación de software que se encuentra generalmente en un sistema operativo Unix o similar a Unix . Los temas que se tratan incluyen programas informáticos (incluidas las llamadas a bibliotecas y sistemas ), convenciones y estándares formales e incluso conceptos abstractos. Un usuario puede invocar una página de manual emitiendo el comando .man
De forma predeterminada, mannormalmente se utiliza un programa buscapersonas de terminal como moreo lesspara mostrar su salida.
Las páginas man se consideran a menudo una forma de documentación de software en línea o en línea , [1] aunque el mancomando no requiere acceso a Internet, desde los tiempos en que los manuales impresos fuera de banda eran la norma.
Antes de Unix (por ejemplo, GCOS ), la documentación consistía en páginas impresas, disponibles en las instalaciones de los usuarios (personal, estudiantes...), organizadas en carpetas de acero, bloqueadas entre sí en un estante de lectura de acero monolítico, atornillado a una mesa o mostrador, con páginas organizadas para actualizaciones de información modulares, reemplazos, erratas y adiciones. [ cita requerida ]
En los dos primeros años de la historia de Unix , no existía documentación. [2] 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 por insistencia [ cita requerida ] de su gerente Doug McIlroy en 1971. Aparte de las páginas de manual, el Manual del Programador también acumuló 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 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 y las páginas de manual impresas formaron el Volumen 1. [3]
Las versiones posteriores de la documentación imitaron la brevedad de las primeras páginas del 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 las Ediciones Sexta y Séptima . [2] Las versiones del software recibieron su nombre según 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. [4]
Para la Cuarta Edición, las páginas de manual se formatearon utilizando el paquete de composición tipográfica troff [2] y su conjunto de -manmacros (que fueron completamente revisadas entre la Sexta y Séptima Ediciones del Manual , [3] pero que 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 de manual se consideró un gran avance. Hasta el día de hoy, virtualmente cada aplicación de línea de comandos de Unix viene con una página de manual, y muchos usuarios de Unix perciben la falta de páginas de manual de un programa como un signo de baja calidad; de hecho, algunos proyectos, como Debian , se esfuerzan por escribir páginas de manual 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 -manmacros por las más 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 "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 [5] pero primero se restringió [6] y luego se eliminó en 2017 [7] después de ser finalmente encontrado. [8]
El formato predeterminado de las páginas de manual es troff , con el paquete de macros man (orientado a la apariencia) o mdoc (orientado a la semántica). Esto permite componer una página de manual en PostScript , PDF y otros formatos para visualizarla o imprimirla.
Algunos sistemas Unix tienen un paquete para el comando man2html , que permite a los usuarios navegar por sus páginas de manual utilizando un navegador HTML. Los sistemas con groff y man-db deberían utilizar en su lugar la salida HTML nativa de mayor calidad ( man --html ). El programa WoMan (de "WithOut man") de GNU Emacs permite navegar por las páginas de manual desde el editor. [9]
En 2010, OpenBSD dejó de usar troff para formatear páginas de manual y lo reemplazó por mandoc , un compilador/formateador especializado para páginas de manual con soporte nativo para salida en PostScript , HTML , XHTML y la terminal. Su objetivo es admitir solo un subconjunto de troff utilizado en páginas de manual, específicamente aquellas que usan macros mdoc.
Muchos sitios web ofrecen acceso en línea a páginas de manuales de varios sistemas similares a Unix.
En febrero de 2013, la comunidad BSD vio el lanzamiento de un nuevo servicio de código abierto mdoc.su, que unificó y acortó el acceso a los scripts man.cgi de los principales proyectos BSD modernos a través de un servicio único de acortamiento de URL determinista basado en nginx para las páginas man de *BSD. [10] [11] [12]
Para Linux, se ha creado un servicio man7.org para ofrecer manuales específicos del sistema. [13] Un servicio ManKier ofrece una selección más amplia y también integra las páginas TLDR. [14]
Para leer una página del manual de un comando de Unix, un usuario puede escribir:
hombre <nombre_del_comando>Tradicionalmente, se hace referencia a las páginas mediante la notación "nombre(sección)": por ejemplo, . La sección hace referencia a diferentes formas en las que se puede hacer referencia al tema: por ejemplo, como una llamada al sistema, o un comando o paquete de shell (línea de comandos), o un archivo de configuración de un paquete, o como una construcción 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 llamadas del sistema , comandos de usuario o paquetes de macros . Algunos ejemplos son and o and . La sintaxis para acceder a la sección del manual que no es la predeterminada varía entre las diferentes implementaciones de man.
En Solaris e illumos, por ejemplo, la sintaxis para leer 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 del manual.
El manual se divide generalmente en ocho secciones numeradas. La mayoría de los sistemas actuales (por ejemplo, BSD , [15] macOS , Linux , [16] y Solaris 11.4) heredan el esquema de numeración utilizado por Research Unix . [17] [18] Mientras que System V utiliza un orden diferente: [19]
Las API POSIX están presentes en las secciones 2 y 3, donde la sección 2 contiene las API que se implementan como llamadas del sistema y la sección 3 contiene las API que se implementan como rutinas de biblioteca.
En algunos sistemas están disponibles algunas de las siguientes secciones:
Algunas secciones se subdividen mediante 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 subsección 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 mancaché almacenan en caché las versiones formateadas de las últimas páginas vistas. Una forma es la página cat , que simplemente se envía al buscapersonas para su visualización.
Todas las páginas del manual siguen un diseño común que está optimizado para su presentación en una pantalla de texto ASCII simple , posiblemente sin ningún tipo de resaltado o control de fuentes. Las secciones presentes pueden incluir: [21] : ESTRUCTURA DEL MANUAL
Puede haber otras secciones, pero no están bien estandarizadas en las páginas del manual. Algunos ejemplos comunes son: OPCIONES, ESTADO DE SALIDA, VALOR DE RETORNO, ENTORNO, ERRORES, ARCHIVOS, AUTOR, INFORME DE ERRORES, HISTORIAL y DERECHOS DE AUTOR.
Las páginas de manual pueden escribirse en las manmacros antiguas, las docmacros nuevas o una combinación de ambas ( mandoc). [22] El manconjunto de macros proporciona funciones mínimas de texto enriquecido , 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. [23] El mdoclenguaje más nuevo 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. [21] Tanto el proyecto mandoc como el groff consideran mdocel formato preferido para los nuevos documentos. [24]
Aunque las páginas de manual son, para troff, texto diseñado con tipografía Roman de 10 puntos , esta distinción suele ser discutible porque las páginas de manual se visualizan en la terminal (TTY) en lugar de diseñarse en papel. Como resultado, la macro de "fuente pequeña" rara vez se utiliza. [25] Por otro lado, el terminal admite texto en negrita y cursiva a través de ECMA-48 , y groff grottylos emite según se solicita cuando detecta un terminal compatible. Sin embargo, el mandoc de BSD solo admite texto en negrita y subrayado (como reemplazo de cursiva) a través de la secuencia de retroceso y luego tachado de la máquina de escribir, que debe traducirse a ECMA-48 por less. [26] [27]
Algunas herramientas se han utilizado para convertir documentos en un formato menos artificial a páginas de manual. Algunos ejemplos incluyen el de GNU help2man, que toma una --helpsalida y algún contenido adicional para generar una página de manual. [28] 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. [29] 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 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 [30] que escribió un convertidor mdoc(7) independiente.
Las páginas de manual suelen estar escritas en inglés, pero puede haber traducciones a otros idiomas disponibles en el sistema. Se sabe que GNU man-dby mandoc manbuscan páginas de manual localizadas en subdirectorios. [31] [16] : Descripción general [15]
Pocas alternativas manhan gozado de tanta popularidad, con la posible excepción del sistema " " del Proyecto GNU , un sistema de hipertexto temprano y simple . También existe un esfuerzo de terceros conocido como páginas TLDR ( ) que proporciona ejemplos simples para casos de uso comunes, similares a una hoja de trucos . [32]infotldr
Además, algunas aplicaciones GUI de Unix (en particular aquellas creadas con los entornos de desarrollo GNOME y KDE ) ahora proporcionan documentación para el usuario final en HTML e incluyen visores HTML integrados, por ejemplo, yelppara leer la ayuda dentro de la aplicación. También está previsto que un sistema HTML en Emacs reemplace a texinfo. [33]
infoaproposSimultáneamente con el trabajo en man(7), se apoyará activamente a mdoc(7) y se promoverá su uso.
