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

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:

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.