página del manual
Documentación del software Unix
La página del manual de la utilidad sed , como se ve en varias distribuciones de Linux .

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.

Historia

xman , una de las primeras aplicaciones X11 para visualizar páginas de manual
Página de introducción del manual de la sección 8 de OpenBSD , que se muestra en una consola de texto

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]

Formato

Parte de la página del manual man(1) de FreeBSD , compuesta en formato PDF

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.

Servicios en línea

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]

Uso del comando

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, ftp(1). 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 macrosman(1) . Algunos ejemplos son and man(7)o exit(2)and exit(3). 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 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 del manual.

Secciones 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]

ComúnSistema VDescripción
11Comandos generales
22Llamadas del sistema
33Funciones de biblioteca , que cubren en particular la biblioteca estándar de C
47Archivos especiales (normalmente dispositivos, los que se encuentran en /dev) y controladores
54Formatos de archivos y convenciones
66Juegos y salvapantallas
75Misceláneas
81MComandos y demonios de administración del sistema

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:

SecciónDescripción
0 Archivos de encabezado de la biblioteca C (Unix v6)
9Rutinas del kernel (FreeBSD, SVR4, Linux) [18] [15]
yoFunciones de la biblioteca LAPACK [20]
norteComandos Tcl / Tk
incógnitaEl sistema X Window

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:

SubsecciónDescripción
pagEspecificaciones POSIX
incógnitaDocumentació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 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.

Disposició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 

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 comandos acepta. En el caso de funciones de programa, una lista de los parámetros que acepta 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.

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.

Autoría

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 ven 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 lo solicitado 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]

Alternativas

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]

Véase también

Referencias

  1. ^ "man(1)". Manual de comandos generales de FreeBSD . Archivado desde el original el 2023-01-30 . Consultado el 2023-07-15 .
  2. ^ abc McIlroy, MD (1987). Un lector de Unix para investigación: extractos anotados del Manual del programador, 1971–1986 (PDF) (Informe técnico). CSTR. Bell Labs. 139. Archivado (PDF) desde el original el 11 de noviembre de 2017. Consultado el 1 de febrero de 2015 .
  3. ^ ab Darwin, Ian; Collyer, Geoffrey. «UNIX Evolution: 1975-1984 Part I - Diversity». Archivado desde el original el 17 de julio de 2012. Consultado el 22 de diciembre de 2012 .Publicado originalmente en Microsystems 5 (11), noviembre de 1984.
  4. ^ Fiedler, Ryan (octubre de 1983). "El tutorial de Unix / Parte 3: Unix en el mercado de los microordenadores". BYTE . p. 132 . Consultado el 30 de enero de 2015 .
  5. ^ "GIT commit 002a6339b1fe8f83f4808022a17e1aa379756d99". Archivado desde el original el 4 de diciembre de 2017 . Consultado el 22 de noviembre de 2017 .
  6. ^ "GIT commit 84bde8d8a9a357bd372793d25746ac6b49480525". Archivado desde el original el 5 de septiembre de 2018. Consultado el 22 de noviembre de 2017 .
  7. ^ "GIT commit b225d9e76fbb0a6a4539c0992fba88c83f0bd37e". Archivado desde el original el 9 de noviembre de 2020. Consultado el 25 de septiembre de 2018 .
  8. ^ "¿Por qué el hombre imprime "dame, dame, dame" a las 00:30?"". Archivado desde el original el 21 de noviembre de 2017 . Consultado el 22 de noviembre de 2017 .
  9. ^ Wright, Francis J. «WoMan: Examinar páginas del manual de Unix «WO (sin) Man»». GNU. Archivado desde el original el 11 de noviembre de 2020. Consultado el 3 de agosto de 2020 .
  10. ^ Pali, Gabor, ed. (12 de mayo de 2013). «Informe trimestral sobre el estado de FreeBSD, enero-marzo de 2013». FreeBSD . Archivado desde el original el 22 de diciembre de 2014 . Consultado el 25 de diciembre de 2014 .
  11. ^ Murenin, Constantine A. (19 de febrero de 2013). "Anuncio de mdoc.su, URLs cortas de páginas del manual". [email protected] (Lista de correo). Archivado desde el original el 7 de agosto de 2014 . Consultado el 25 de diciembre de 2014 .
  12. ^ Murenin, Constantine A. (23 de febrero de 2013). «mdoc.su — URLs breves de páginas de manual para FreeBSD, OpenBSD, NetBSD y DragonFly BSD». Archivado desde el original el 17 de diciembre de 2014. Consultado el 25 de diciembre de 2014 .
  13. ^ "Páginas de manual de Linux en línea". man7.org . Archivado desde el original el 2020-05-07 . Consultado el 2020-05-05 .
  14. ^ "Acerca de". ManKier . Archivado desde el original el 25 de abril de 2020 . Consultado el 5 de mayo de 2020 .
  15. ^ abc man(1) –  Manual de comandos generales de FreeBSD
  16. ^ ab man(1) –  Manual de comandos generales de Linux
  17. ^ "Páginas del manual para la investigación de Unix, octava edición". man.cat-v.org . Archivado desde el original el 2020-06-30 . Consultado el 2020-05-06 .
  18. ^ ab "Manual del programador de Unix - Introducción". www.bell-labs.com . 3 de noviembre de 1971. Archivado desde el original el 1 de junio de 2020 . Consultado el 6 de mayo de 2020 .
  19. ^ "Manuales de System V release 4". bitsavers.trailing-edge.com . Archivado desde el original el 2020-08-03 . Consultado el 2020-05-06 .
  20. ^ "lapack (l) - Páginas del manual de Linux". www.systutorials.com . Archivado desde el original el 2023-03-11 . Consultado el 2021-05-29 .
  21. ^ ab mdoc(7) –  Manual de información miscelánea de FreeBSD
  22. ^ groff_tmac(5)  –  Manual de formatos de archivos de Linux
  23. ^ man(7)  -  Manual de miscelánea de Linux
  24. ^ "Declaración de misión de Groff - 2014". www.gnu.org . Archivado desde el original el 2020-12-03 . Consultado el 2021-01-02 . Simultáneamente con el trabajo en man(7), se apoyará activamente a mdoc(7) y se promoverá su uso.
  25. ^ "man". Manual de GNU Troff . Archivado desde el original el 24 de diciembre de 2019. Consultado el 31 de diciembre de 2019 .
  26. ^ "Cursiva y color en páginas de manual en un terminal virtual de espacio de usuario nosh". jdebp.eu . Archivado desde el original el 28 de enero de 2021 . Consultado el 21 de enero de 2021 .
  27. ^ mandoc(1)  –  Manual de comandos generales de FreeBSD . "Los estilos de fuente se aplican mediante codificación con espacio hacia atrás..."
  28. ^ "Manual de referencia de help2man". Archivado desde el original el 6 de marzo de 2023 . Consultado el 5 de marzo de 2023 .
  29. ^ "Páginas de manual (estándares de codificación GNU)". www.gnu.org . Archivado desde el original el 5 de marzo de 2023 . Consultado el 5 de marzo de 2023 .
  30. ^ Ingo Schwarze. «Nuevo conversor de Markdown mandoc -mdoc -T». ​​undeadly.org . Archivado desde el original el 2023-03-05 . Consultado el 2023-03-05 .– para quejas específicas del autor, véase Ingo Schwarze (28 de febrero de 2014). "Re: Páginas de manual de Groff (tangencial a Future Redux)". Groff (Lista de correo). Archivado desde el original el 5 de marzo de 2023.
  31. ^ "línea de comandos - páginas del manual de Linux en diferentes idiomas". Ask Ubuntu . Archivado desde el original el 2023-03-11 . Consultado el 2020-05-05 .
  32. ^ "Páginas TLDR". tldr.sh . Archivado desde el original el 27 de abril de 2020 . Consultado el 5 de mayo de 2020 .
  33. ^ Raymond, Eric S. "Re: [Groff] páginas de manual (tangencial a Future Redux)". groff (Lista de correo). Archivado desde el original el 2023-03-05 . Consultado el 2023-03-05 – vía lists.gnu.org.
La Guía Wikilibro de Unix tiene una página sobre el tema: Comandos
  • Historial de páginas de manual de UNIX para un historial de fuentes primarias de 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?
  • Páginas del manual de FreeBSD, freebsd.org: también contiene páginas del manual de Darwin, Debian, HP-UX, IRIS, NetBSD, OpenBSD, NextSTEP, SunOS y más
Obtenido de "https://es.wikipedia.org/w/index.php?title=Página_de_manual&oldid=1229638820"