man

NOMBRE

man - macros para formatear páginas de manual

SINOPSIS

groff -Tascii -man fichero ...

groff -Tps -man fichero ...

man [sección] título

Esta página del manual describe el paquete de macros groff an.tmac (a menudo llamado el paquete de macros man). El programador debe usar este paquete de macros cuando escriba o porte páginas del manual para Linux. Al ser bastante compatible con otras versiones, portar páginas del manual no debería dar mayores problemas (con excepción de la distribución incluida en NET-2 BSD, que utiliza un paquete de macros totalmente distinto llamado mdoc. Vea mdoc(7)).

Dése cuenta que las páginas de manual mdoc de NET-2 BSD se pueden usar con groff simplemente especificando la opción -mdoc en vez de la opción -man. De todas formas, se recomienda utilizar la opción -mandoc porque así detecta de forma automática qué paquete de macros se está utilizando.

Por convención, debería usarse cuando se escriban páginas de manual para el paquete man-pages, consulte man-pages(7).

Línea de título

La primera orden en una página de manual (después de las líneas de comentarios que empieza por .\") debería ser

.TH título sección fecha fuente manual

Para más información sobre los argumentos de la orden TH, consulte man-pages(7).

Dése cuenta que las páginas de manual de BSD con formato mdoc comienzan con la orden Dd, no con la orden TH.

Secciones

El inicio de las secciones se etiqueta con .SH seguido del título.

El único encabezado obligatorio es NOMBRE. Debería ser la primera sección e ir seguido de una breve descripción del programa en la siguiente línea:

.SH NOMBRE

nombre \- descripción

Es muy importante respetar este formato así como poner una barra invertida antes del guión que sigue al nombre. La aplicación mandb(8) crea una base de datos con estas descripciones cortas que luego usarán las órdenes whatis(1) y apropos(1). Consulte lexrog(1) para más detalles acerca de la sintaxis de la sección NOMBRE.

En man-pages(7) tiene una lista de otras secciones que pueden aparecer en una página de manual.

Tipos de letra

Las órdenes para seleccionar el tipo de letra son:

.B: Negrita

.BI: Negrita alternándose con itálica (especialmente útil para la especificación de funciones)

.BR: Negrita alternándose con romana (especialmente útil para referenciar a otras páginas de manual)

.I: Itálica

.IB: Itálica alternándose con negrita

.IR: Itálica alternándose con romana

.RB: Romana alternándose con negrita

.RI: Romana alternándose con itálica

.SB: Pequeña alternándose con negrita

.SM: Pequeña (útil para acrónimos)

Tradicionalmente, cada orden puede tener seis argumentos como máximo, pero la implementación de GNU elimina esta limitación (aunque tal vez usted todavía quiera limitarse a 6 argumentos en aras de la portabilidad). Los argumentos se delimitan por espacios y si el propio argumento contiene espacios, se deben usar comillas dobles. Para las macros que producen tipos de letra alternos, los argumentos se imprimirán uno al lado del otro sin espacios intermedios, de modo que la orden &.BR se puede utilizar para especificar una palabra en negrita seguida de un signo de puntuación. Si no se proporcionan argumentos, la orden se aplica a la siguiente línea de texto.

Otras macros y cadenas

A continuación hay otras macros relevantes y cadenas predefinidas. A no ser que se indique lo contrario, todas las macros provocan un salto (fin de la línea actual de texto). Muchas de estas macros configuran o usan el "sangrado predominante". Cualquier macro con el parámetro i debajo, asigna un valor al "sangrado predominante". Las macros pueden omitir la i en cuyo caso se usará el actual sangrado predominante. Como resultado, los párrafos identados que hay a continuación pueden usar el mismo sangrado sin necesidad de redefinir su valor. Un párrafo normal (sin sangrado) restaura el valor del sangrado predominante a su valor por omisión (0,5 pulgadas). Por defecto, un sangrado dado se mide en ens. Intente utiliza siempre ens o ems como unidades de medida en las identaciones, ya que éstas se ajustarán automáticamente a los cambios en el tamaño de las fuentes. Las otras definiciones de macro claves son:

Párrafos Normales

.LP: Lo mismo que .PP (comienza un nuevo párrafo).

.P: Lo mismo que .PP (comienza un nuevo párrafo).

.PP: Comienza un nuevo párrafo y restaura el sangrado predominante.

Sangrado de Margen Relativo

.RS i: Comienza un sangrado de margen relativo: mueve el margen izquierdo i pulgadas a la derecha (si se omite i, se usa el valor del sangrado predominante). Se asigna al sangrado predominante un nuevo valor de 0,5 pulgadas. Como resultado, todos los párrafos siguientes se sangrarán hasta el correspondiente .RE.

.RE: Finaliza un sangrado del margen relativo y restaura el valor anterior del sangrado predominante.

Macros para Párrafos Sangrados

.HP i: Comienza un párrafo con un sangrado colgante (la primera línea del párrafo comienza en el margen izquierdo de los párrafos normales y el resto de líneas del párrafo se sangran).

.IP x i: Párrafo sangrado con una etiqueta colgante opcional. Si se omite la etiqueta x, todo el párrafo siguiente se sangra i pulgadas. Si se da la etiqueta x, ésta se cuelga en el margen izquierdo antes del siguiente párrafo sangrado (esto es como .TP excepto que la etiqueta se incluye con la orden en lugar de al comienzo de la siguiente línea). Si la etiqueta es demasiado larga, el texto tras la etiqueta se bajará a la siguiente línea (el texto no se perderá o se mezclará). Para listas con viñetas, use esta macro con \(bu (bullet) o \(em (em dash) como etiqueta, y para listas numeradas, use como etiqueta el número o letra seguido por un punto. Esto simplifica la traducción a otros formatos.

.TP i: Comienza un párrafo con una etiqueta colgante. La etiqueta se da en la siguiente línea, su resultado es como el de la orden .IP.

Macros de Enlaces de Hipertexto

.UR url: Inserta un enlace de hipertexto a la URI (URL) url con todo el texto hasta la siguiente macro .UE como texto del enlace.

.UE .RI [ trailer ]: Termina el texto del enlace de la anterior macro &.UR, opcionalmente, se puede añadir trailer (si está presente, generalmente es un paréntesis de cierre y / o puntuación al final de la oración). Para los dispositivos de salida que no usan HTML (por ejemplo, man-Tutf8), el texto del enlace va seguido de la URL entre paréntesis angulares; si no hay texto de enlace, se usa para ello la propia URL entre corchetes angulares. (Es posible que los corchetes angulares no estén disponibles en todos los dispositivos de salida). Para el dispositivo de salida HTML, el texto contiene un enlace a la URL; si no hay texto de enlace, se usa la propia URL.

El soporte para estas macros se introdujo en en la versión 1.20 de GNU Troff (05-01-2009) y en Heirloom Doctools Troff en la versión 160217 (17-02-2016).

Otras Macros

.DT: Restablece los tabuladores a sus valores por defecto (cada 0,5 pulgadas). No produce una ruptura.

.PD d: Establece la distancia vertical entre párrafos a d (si se omite, d=0,4v). No produce una ruptura.

.SS t: Subencabezamiento t (como .SH, pero usado para subsecciones dentro de una sección).

Cadenas Predefinidas

El paquete man tiene las siguientes cadenas predefinidas:

\*R: Símbolo de registro: ®

\*S: Cambia al tamaño de fuente por omisión

\*(Tm: Símbolo de marca registrada: (Tm)

\*(lq: Comillas dobles españolas izquierdas: “

\*(rq: Comillas dobles españolas derechas: ”

Subconjunto seguro

Aunque técnicamente man es una paquete de macros troff, en realidad un gran número de otras herramientas procesan ficheros de páginas de manual que no implementan todas las capacidades de troff. Por tanto, es mejor evitar algunas de las capacidades más exóticas de troff cuando sea posible para permitir que esas otras herramientas funcionen correctamente. Evite usar los diferentes preprocesadores de troff (si debe hacerlo, adelante y use tbl(1), pero intente usar las órdenes IP y TP en su lugar para tablas de dos columnas). Evite hacer cálculos. La mayoría de las otras herramientas no podrán procesarlos. Use órdenes simples que se puedan traducir fácilmente a otros formatos. Las siguientes macros troff se consideran seguras (aunque, en muchos casos, serán ignoradas por los traductores): \", ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne, nf, nh, ps, so, sp, ti, tr.

También puede usar muchas secuencias de escape de troff (aquellas secuencias que comienzan por \). Cuando necesite incluir el carácter de barra invertida como texto normal, use \e. Otras secuencias que puede usar, donde x y xx son cualquier carácter y N es cualquier dígito, incluyen: \', \`, \-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx y \f(xx. Evite usar secuencias de escape para dibujar gráficos.

No use el parámetro opcional de bp (break page, salto de página). Use sólo valores positivos para sp (vertical space, espacio vertical). No defina una macro ( de) con el mismo nombre que una macro en éste o el paquete de macros mdoc, con un significado diferente. Es probable que tales redefiniciones se ignoren. Todo sangrado positivo ( in) debería ir acompañado por el correspondiente sangrado negativo (aunque debería usar las macros RS y RE en su lugar). La condición (if,ie) sólo debería tener 't' o 'n' como condición. Sólo se deberían utilizar traducciones ( tr) que se puedan ignorar. Los cambios de fuente ( ft y las secuencias de escape \f) sólo debería tener los valores 1, 2, 3, 4, R, I, B, P o CW (la orden ft también puede no tener parámetros).

Si usa otras capacidades diferentes a éstas, compruebe el resultado cuidadosamente con diferentes herramientas. Una vez que haya confirmado que la capacidad adicional es segura, permita que el que mantiene este documento conozca la secuencia u orden segura que debería añadirse a esta lista.

ARCHIVOS

/usr/share/groff/[*/]tmac/an.tmac

/usr/man/whatis

NOTAS

Intente por todos los medios incluir URL (o URI) completas en el propio texto. Herramientas tales como man2html(1) pueden convertirlas automáticamente en enlaces de hipertexto. También puede usar las macros UR y UE para identificar enlaces a información relacionada. Si incluye URL, use la URL completa (por ejemplo: http://www.kernel.org para garantizar que las distintas aplicaciones puedan encontrarlas automáticamente.

Las herramientas que procesan estos ficheros deben abrir el fichero y examinar el primer carácter distinto de espacio. Un punto (.) o una comilla simple (') al principio de una línea indica un archivo basado en troff (tal como man o mdoc). Un menor (<) indica un fichero basado en SGML/XML (tal como HTML o Docbook). Cualquier otra cosa sugiere un simple texto ASCII (por ej., el resultado de un "catman").

Muchas páginas de manual comienzan con q]\" seguido por un espacio y una lista de caracteres que indican cómo se va a procesar la página. Por el bien de la portabilidad a traductores que no se basan en troff, recomendamos que evite usar cualquier otra cosa que no sea tbl(1). Linux puede detectar eso automáticamente. Sin embargo, tal vez quiera incluir esta información de tal manera que su página man pueda ser tratada por otros sistemas (menos capaces). Aquí tiene las definiciones de los preprocesadores invocados por los siguientes caracteres:

e: eqn(1)

g: grap(1)

p: pic(1)

r: refer(1)

t: tbl(1)

v: vgrind(1)

ERRORES

La mayoría de las macros describen aspectos del formato (por ej., el tipo de las fuentes y el espaciado) en vez de marcar contenidos semánticos (por ej., este texto es una referencia a otra página), en comparación con formatos como mdoc y Docbook (incluso HTML tiene más marcas semánticas). Esto hace que sea más difícil modificar el formato man para diferentes medios, para hacer el formateo consistente para un medio dado y para insertar automáticamente referencias cruzadas. El adherirse al subconjunto seguro descrito antes debe facilitar la transición automática a un formato diferente de página de referencia en el futuro.

La macro de Sun TX no está implantada.

VÉASE TAMBIÉN

apropos(1), groff(1), lexgrog(1), man(1), man2html(1), groff_mdoc(7), whatis(1), groff_man(7), groff_www(7), man-pages(7), mdoc(7)

TRADUCCIÓN

La traducción al español de esta página del manual fue creada por Diego Novillo <[email protected]>, Miguel Angel Sepulveda <[email protected]>, Jordi Gili <[email protected]>, Juan Piernas <[email protected]> y Marcos Fouces <[email protected]>

Esta traducción es documentación libre; lea la GNU General Public License Version 3 o posterior con respecto a las condiciones de copyright. No existe NINGUNA RESPONSABILIDAD.

Si encuentra algún error en la traducción de esta página del manual, envíe un correo electrónico a [email protected]

5 Febrero 2023