.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 generalmente se encuentra en un sistema operativo Unix o similar a Unix . 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 de manual emitiendo el comando .man
De forma predeterminada, mannormalmente utiliza un programa de buscapersonas de terminal como moreo lesspara mostrar su salida.
Las páginas de manual a menudo se denominan una forma en línea o en línea de documentación de software, [1] aunque el mancomando no requiere acceso a Internet, lo que se remonta a 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 localmente para los usuarios (personal, estudiantes...), organizadas en carpetas de acero, encerradas juntas en un estante de lectura monolítico de acero, atornilladas a una mesa o mostrador, con páginas organizadas para actualizaciones de información modular, reemplazo, erratas y adiciones. [ cita necesaria ]
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 ante la insistencia [ cita necesaria ] de su gerente Doug McIlroy en 1971. Aparte de las páginas de manual, El Manual del programador también acumuló un conjunto de artículos 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 séptima edición de Research Unix , se dividió en dos volúmenes y las páginas de manual impresas formaban el Volumen 1. [3]
Las versiones posteriores de la documentación imitaron la concisión de las primeras páginas del manual. Ritchie añadió una sección "Cómo empezar" a la introducción de la tercera edición , y Lorinda Cherry proporcionó la referencia de bolsillo "Purple Card" para las ediciones sexta y séptima . [2] 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 séptima edición o versión 7 de Unix. [4]
Para la Cuarta Edición, las páginas de manual fueron formateadas usando el paquete de composición tipográfica troff [2] y su conjunto de -manmacros (que fueron completamente revisados entre la Sexta y Séptima Edición 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 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 en 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 -manmacros antiguas por las más nuevas -mdoc).
Había un huevo de Pascua oculto en la versión man-db del comando man que causaba que el comando devolviera "gimme gimme gimme" 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 [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 man es troff , con el paquete de macros man (orientado a la apariencia) o mdoc (orientado a la semántica). Esto hace posible componer una página de manual en PostScript , PDF y varios otros formatos para verla o imprimirla.
Algunos sistemas Unix tienen un paquete para el comando man2html , que permite a los usuarios navegar por sus páginas man utilizando un navegador HTML. Los sistemas con groff y man-db deberían utilizar la salida HTML nativa de mayor calidad ( man --html ). El programa WoMan de GNU Emacs (de "WithOut man") permite navegar por páginas man desde el editor. [9]
En 2010, OpenBSD desaprobó troff para formatear páginas man en favor de mandoc , un compilador/formateador especializado para páginas man con soporte nativo para salida en PostScript , HTML , XHTML y terminal. Está destinado a admitir solo un subconjunto de troff utilizado en las páginas del 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 mdoc.su de código abierto, que unificó y acortó el acceso a los scripts man.cgi de los principales proyectos BSD modernos a través de un exclusivo servicio de acortamiento de URL determinista basado en nginx para *BSD man. páginas. [10] [11] [12]
Para Linux, se ha configurado un servicio man7.org para ofrecer manuales específicos del sistema. [13] Un servicio ManKier proporciona una selección más amplia y también integra las páginas TLDR. [14]
Para leer una página de manual para un comando de Unix, un usuario puede escribir:
hombre <nombre_comando>Tradicionalmente se hace referencia a las páginas utilizando la notación "nombre(sección)": por ejemplo, . La sección hace referencia a diferentes formas en 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/encabezado de codificación.
El mismo nombre de página puede aparecer en más de una sección del manual, como cuando coinciden los nombres de llamadas al sistema , comandos de usuario o paquetes de macros . Algunos ejemplos son y , o y . La sintaxis para acceder a la sección del manual no predeterminada varía entre las diferentes implementaciones de man.
En Solaris e illusmos, por ejemplo, la sintaxis de lectura es:
hombre -s 3c printf En 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 generalmente se divide 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 el Sistema V usa un orden diferente: [19]
Las API POSIX están presentes en las secciones 2 y 3, donde la sección 2 contiene API que se implementan como llamadas al sistema y la sección 3 contiene API que se implementan como rutinas de biblioteca.
En algunos sistemas, algunas de las siguientes secciones están disponibles:
Algunas secciones se subdividen mediante un sufijo; por ejemplo, en algunos sistemas, la sección 3C es para llamadas a la biblioteca C, 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 queda relegada a la subsección 1M de la sección de comandos principal. Algunos sufijos de subsecciones tienen un significado general en todas las secciones:
(La sección 3 tiende a ser la excepción debido a la gran cantidad de 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 transmite al buscapersonas para su visualización.
Todas las páginas de manual siguen un diseño común optimizado para su presentación en una pantalla de texto ASCII simple , posiblemente sin ningún tipo de resaltado o control de fuente. Las secciones presentes pueden incluir: [21] : ESTRUCTURA DEL MANUAL
Es posible que haya otras secciones presentes, pero no están bien estandarizadas en las páginas de manual. Los ejemplos comunes incluyen: OPCIONES, ESTADO DE SALIDA, VALOR DEVUELTO, ENTORNO, ERRORES, ARCHIVOS, AUTOR, INFORME DE ERRORES, HISTORIAL y DERECHOS DE AUTOR.
Las páginas del manual se pueden escribir en las manmacros antiguas, en las macros nuevas doco en 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, pequeña 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 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. [21] Tanto el proyecto mandoc como el proyecto groff consideran mdocel formato preferido para los nuevos documentos. [24]
Aunque las páginas de manual son, para troff, texto dispuesto en tipo romano de 10 puntos , esta distinción suele ser discutible porque las páginas de manual se ven en la terminal (TTY) en lugar de estar dispuestas 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 lo solicitado cuando detecta un terminal compatible. Sin embargo, el mandoc BSD solo admite texto en negrita y subrayado (como reemplazo de cursiva) a través de la secuencia de retroceso, luego sobretacha de la máquina de escribir, que debe traducirse a ECMA-48 mediante less. [26] [27]
Se han utilizado algunas herramientas para convertir documentos en un formato menos artificial en páginas de manual. Los ejemplos incluyen GNU help2man, que toma una --helpsalida y contenido adicional para generar una página de manual. [28] El manual sería apenas más útil que dicho resultado, 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 conversor man(7) incorporado, de pésima calidad, según el autor de mandoc [30], que escribió un conversor mdoc(7) independiente.
Las páginas de manual generalmente están escritas en inglés, pero es posible que el sistema tenga traducciones a otros idiomas. Se sabe que GNU man-dby el mandoc manbuscan páginas de manual localizadas en subdirectorios. [31] [16] : Descripción general [15]
Pocas alternativas han mangozado de mucha popularidad, con la posible excepción del sistema " " del Proyecto GNU , un sistema de hipertextoinfo temprano y simple . También existe un esfuerzo de terceros conocido como páginas TLDR ( ) que proporciona ejemplos simples para casos de uso comunes, similar a una hoja de referencia . [32]tldr
Además, algunas aplicaciones GUI de Unix (en particular aquellas creadas utilizando los entornos de desarrollo GNOME y KDE ) ahora proporcionan documentación para el usuario final en HTML e incluyen visores HTML integrados, como 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 sobre man(7), se apoyará activamente mdoc(7) y se promoverá su uso.
