Una página de manual (abreviatura de página del manual ) es una forma de documentación de software que normalmente se encuentran en un Unix o Unix sistema operativo . Los temas cubiertos incluyen programas de computadora (incluidas las llamadas a la biblioteca y al sistema ), estándares y convenciones formales, e incluso conceptos abstractos. Un usuario puede invocar una página de manual emitiendo el man
comando .
De forma predeterminada, man
normalmente utiliza un programa de localizador de terminal como more
o less
para mostrar su salida.
Las páginas de manual se denominan a menudo una forma en línea o en línea de documentación de software, [1] aunque el man
comando no requiere acceso a Internet, ya que se remonta a los tiempos en que los manuales impresos fuera de banda eran la norma.
Historia
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 requerida ] de su gerente Doug McIlroy en 1971. Aparte de las páginas de manual, el Manual del programador también acumulaba 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 encajaba 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 con las páginas de manual impresas formando el Volumen 1. [3]
Las versiones posteriores de la documentación imitaron la concisión de las primeras páginas de manual. Ritchie agregó una sección "Cómo comenzar" 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 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 la 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 -man
macros (que fueron completamente revisadas entre la Sexta y la Séptima Ediciones del Manual , [3] pero no han cambiado drásticamente desde entonces). 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, 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 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 -man
macros antiguas por las más nuevas -mdoc
).
Había un easter egg oculto en la versión man-db del comando man que haría que el comando devolviera "dame, dame, dame" cuando se ejecute a las 00:30 (una referencia a la canción de ABBA Gimme! Gimme! Gimme! (A Man Después de la medianoche) .Se introdujo en 2011 [5], pero primero se restringió [6] y luego se eliminó en 2017 [7] después de ser finalmente encontrado [8].
Formateo
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 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 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 deben utilizar 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. [9]
En 2010, OpenBSD desaprobó troff para formatear 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 utilizados en las páginas del manual, específicamente aquellos que utilizan las macros mdoc.
Servicios en línea
Un buen número de sitios web ofrecen acceso en línea para 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 BSD modernos a través de un servicio único de acortamiento de URL determinista basado en nginx para el hombre * BSD páginas. [10] [11] [12]
Para Linux, se ha configurado un servicio man7.org para servir manuales específicos del sistema. [13] Un servicio de ManKier ofrece una selección más amplia y también integra las páginas TLDR. [14]
Uso de comandos
Para leer una página de manual de un comando de Unix, un usuario puede escribir:
man
Las páginas se denominan tradicionalmente con la notación "nombre (sección)": por ejemplo
,. La sección se refiere 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 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 coinciden los nombres de llamadas al sistema , comandos de usuario o paquetes de macros . Los ejemplos son
y , o y . La sintaxis para acceder a la sección manual no predeterminada varía entre las diferentes implementaciones de man.En Solaris e illumos, 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.
Secciones manuales
El manual generalmente se divide en ocho secciones numeradas, organizadas de la siguiente manera (sobre investigación Unix , BSD , macOS y Linux ): [15] [16] [17] [18]
Sección | Descripción |
---|---|
1 | Comandos generales |
2 | Llamadas al sistema |
3 | Funciones de biblioteca , que cubren en particular la biblioteca estándar de C |
4 | Archivos especiales (generalmente dispositivos, los que se encuentran en / dev) y controladores |
5 | Convenciones y formatos de archivo |
6 | Juegos y salvapantallas |
7 | Diverso |
8 | Comandos y demonios de administración del sistema |
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 al sistema del sistema operativo local y la sección 3 contiene la documentación de la llamada al sistema del Manual del programador POSIX. [ cita requerida ]
Unix System V usa un esquema de numeración similar, excepto en un orden diferente: [19]
Sección | Descripción |
---|---|
1 | Comandos generales |
1 M | Comandos y demonios de administración del sistema |
2 | Llamadas al sistema |
3 | Funciones de la biblioteca C |
4 | Convenciones y formatos de archivo |
5 | Miscelánea |
6 | Juegos y salvapantallas |
7 | Archivos especiales (generalmente dispositivos, los que se encuentran en / dev) y controladores |
En algunos sistemas, algunas de las siguientes secciones están disponibles:
Sección | Descripción |
---|---|
0 | Archivos de encabezado de biblioteca C (Unix v6) |
9 | Rutinas del kernel (FreeBSD, SVR4, Linux) [18] [16] |
l | Funciones de la biblioteca LAPACK [20] |
norte | Comandos Tcl / Tk |
X | El sistema X Window |
Algunas secciones se subdividen aún más 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 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:
Subsección | Descripción |
---|---|
pag | Especificaciones POSIX |
X | Documentación del sistema X Window |
(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 visitadas. Una forma es la página del gato , simplemente canalizada al buscapersonas para su visualización.
Diseño
Todas las páginas de manual 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: [21] ( ESTRUCTURA MANUAL )
- NOMBRE
- El nombre del comando o función, seguido de una descripción de una línea de lo que hace.
- SINOPSIS
- En el caso de un comando, una descripción formal de cómo ejecutarlo y qué opciones de línea de comando toma. Para las funciones del programa, una lista de los parámetros que toma la función y qué archivo de encabezado contiene su declaración.
- DESCRIPCIÓN
- Una descripción textual del funcionamiento del comando o función.
- EJEMPLOS
- Algunos ejemplos de uso común.
- VER TAMBIÉN
- Una lista de comandos o funciones relacionados.
Pueden estar presentes otras secciones, pero no están bien estandarizadas en las páginas de manual. Los ejemplos comunes incluyen: OPCIONES, ESTADO DE SALIDA, VALOR DEVUELTO, MEDIO AMBIENTE, ERRORES, ARCHIVOS, AUTOR, INFORMACIÓN DE ERRORES, HISTORIAL y DERECHOS DE AUTOR.
Autoría
Las páginas del manual se pueden escribir en las man
macros antiguas , en las nuevas doc
o en una combinación de ambas ( mandoc
). [22] El man
conjunto de macros proporciona funciones de texto enriquecido mínimas , 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 mdoc
lenguaje 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 groff consideran mdoc
el formato preferido para los nuevos documentos. [24]
Aunque las páginas de manual son, para troff, texto diseñado con tipo de letra Roman de 10 puntos , esta distinción suele ser discutible porque las páginas de manual se ven en la terminal (TTY) en lugar de 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 los grotty
emite según lo solicitado cuando detecta un terminal de apoyo. 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-luego-golpe de máquina de escribir, que debe traducirse a ECMA-48 por less
. [26] [27]
Las páginas de manual suelen estar escritas en inglés, pero el sistema puede disponer de traducciones a otros idiomas. Se sabe que GNU man-db
y mandoc man
buscan páginas de manual localizadas en subdirectorios. [28] [15] ( Descripción general ) [16]
Alternativas
Pocas alternativas man
han gozado de mucha popularidad, con la posible excepción del sistema " " del Proyecto GNUinfo
, un sistema de hipertexto temprano y simple . También existe un esfuerzo de terceros conocido como páginas TLDR ( tldr
) que proporciona ejemplos simples para casos de uso comunes, similar a una hoja de referencia . [29]
Además, algunas aplicaciones GUI de Unix (en particular las creadas con los entornos de desarrollo GNOME y KDE ) ahora proporcionan documentación para el usuario final en HTML e incluyen visores HTML incrustados, yelp
por ejemplo, para leer la ayuda dentro de la aplicación.
Ver también
- Lista de comandos de Unix
- Lista de aplicaciones del Plan 9
- info
- a propósito
- README
- RTFM
- ManOpen : utilidad de hombre gráfico NeXT / macOS
Referencias
- ^ "man (1) - muestra las páginas de documentación del manual en línea" . Referencia cruzada BSD . FreeBSD . Consultado el 1 de abril de 2019 . Lay resumen .
La utilidad man busca y muestra páginas de documentación del manual en línea.
- ^ a b c McIlroy, MD (1987). Un lector de investigación Unix: extractos comentados del Manual del programador, 1971–1986 (PDF) (Informe técnico). CSTR. Bell Labs. 139.
- ^ a b Darwin, Ian; Collyer, Geoffrey. "Evolución de UNIX: 1975-1984 Parte I - Diversidad" . Consultado el 22 de diciembre de 2012 .Publicado originalmente en Microsystems 5 (11), noviembre de 1984.
- ^ Fiedler, Ryan (octubre de 1983). "El tutorial de Unix / Parte 3: Unix en el mercado de microcomputadoras" . BYTE . pag. 132 . Consultado el 30 de enero de 2015 .
- ^ "Confirmación de GIT 002a6339b1fe8f83f4808022a17e1aa379756d99" . Consultado el 22 de noviembre de 2017 .
- ^ "Confirmación de GIT 84bde8d8a9a357bd372793d25746ac6b49480525" . Consultado el 22 de noviembre de 2017 .
- ^ "GIT commit b225d9e76fbb0a6a4539c0992fba88c83f0bd37e" . Consultado el 25 de septiembre de 2018 .
- ^ " " ¿Por qué el hombre imprime "dame, dame, dame" a las 00:30? " " . Consultado el 22 de noviembre de 2017 .
- ^ Wright, Francis J. "WoMan: Examinar las páginas del manual de Unix" WO (sin) Man " " . GNU . Consultado el 3 de agosto de 2020 .
- ^ Pali, Gabor, ed. (12 de mayo de 2013). "Informe de estado trimestral de FreeBSD, enero-marzo de 2013" . FreeBSD . Consultado el 25 de diciembre de 2014 .
- ^ Murenin, Constantine A. (19 de febrero de 2013). "anunciando mdoc.su, URL de páginas de manual breves" . [email protected] (lista de correo) . Consultado el 25 de diciembre de 2014 .
- ^ Murenin, Constantine A. (23 de febrero de 2013). "mdoc.su - URL de páginas de manual breves para FreeBSD, OpenBSD, NetBSD y DragonFly BSD" . Consultado el 25 de diciembre de 2014 .
- ^ "Páginas de manual de Linux en línea" . man7.org .
- ^ "Acerca de" . ManKier .
- ^ a b - Manual de comandos generales de Linux
- ^ a b c - Manual de comandos generales de FreeBSD
- ^ "Páginas del manual para la investigación de Unix octava edición" . man.cat-v.org .
- ^ a b "Manual del programador de Unix - Introducción" . www.bell-labs.com . 3 de noviembre de 1971.
- ^ "Manuales de System V release 4" . bitsavers.trailing-edge.com .
- ^ "lapack (l) - Páginas de manual de Linux" . www.systutorials.com . Consultado el 29 de mayo de 2021 .
- ^ a b - Manual de información miscelánea de FreeBSD
- ^ - Manual de formatos de archivo de Linux
- ^ - Manual misceláneo de Linux
- ^ "Declaración de la misión de Groff - 2014" . www.gnu.org .
Simultáneamente con el trabajo sobre el hombre (7), se apoyará activamente el mdoc (7) y se promoverá su uso.
- ^ "hombre" . El Manual GNU Troff . Consultado el 31 de diciembre de 2019 .
- ^ "Cursiva y color en las páginas del manual en un terminal virtual con espacio de usuario" . jdebp.eu .
- ^ - Manual de comandos generales de FreeBSD . "Los estilos de fuente se aplican mediante codificación con retroceso ..."
- ^ "línea de comandos: páginas de manual de Linux en diferentes idiomas" . Pregúntale a Ubuntu .
- ^ "Páginas TLDR" . tldr.sh .
enlaces externos
- Historial de páginas de manual de UNIX para obtener un historial de fuentes primarias de 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?
Este artículo se basa en material extraído del Diccionario gratuito de informática en línea antes del 1 de noviembre de 2008 e incorporado bajo los términos de "renovación de licencias" de la GFDL , versión 1.3 o posterior.