man - macros para formatear páginas del manual
groff -Tascii -man fichero ...
groff -Tps -man fichero ...
man [sección] título
Esta página del manual describe el paquete de macros
groff tmac.an (a menudo llamado el paquete de macros man) y
convenciones relacionadas para crear páginas de manual (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.
La primera orden en una página de manual (después de
las líneas de comentarios) debería ser
.TH título sección fecha fuente
manual,
donde:
- título
- Es el título de la página del manual (p.ej.,
MAN).
- sección
- Es el número de sección donde debería ir la
página (p.ej., 7).
- fecha
- Esta es la fecha de la última revisión (la fecha
debería cambiarse cada vez que se modifica la página, ya que
ésta es la forma mas genérica de llevar un control de la
versión.
- fuente
- Indica cual es la fuente de la orden.
Para ficheros binarios, se utilizan nombres como: GNU,
NET-2, Distribución SLS, Distribución
MCC.
Para llamadas al sistema, se especifica la versión
actual del núcleo: Linux 0.99.11.
Para llamadas a las bibliotecas, se especifica la fuente de la
función: GNU, BSD 4.3, Linux DLL 4.4.1.
- manual
- Indica el título del manual (p.ej., Manual del Programador de
Linux).
Dése cuenta que las páginas de manual de BSD con
formato mdoc comienzan con la orden Dd, no con la orden
TH.
Tradicionalmente, las secciones del manual se definen como las
siguientes:
- 1 Comandos
- Son órdenes que el usuario puede ejecutar desde el
intérprete de órdenes.
- 2 Llamadas al sistema
- Son funciones que el núcleo debe ejecutar.
- 3 Llamadas a bibliotecas
- La mayoría de las funciones libc, tales como
qsort(3))
- 4 Ficheros especiales
- Ficheros que se encuentran en /dev)
- 5 Formatos de ficheros y convenciones
- El formato de /etc/passwd y otros ficheros legibles.
- 6 Juegos
- 7 Paquetes de macros y convenciones
- Describe la estructura estándar del sistema de ficheros, protocolos
de red, ASCII y otros códigos de caracteres, esta página de
man y otras cosas.
- 8 Órdenes para la administración del sistema
- Órdenes como mount(8), muchas de las cuales sólo
pueden ser ejecutadas por el superusuario.
- 9 Rutinas del núcleo
- Esta es una sección de manual obsoleta. Una vez se pensó que
una buena idea sería documentar aquí el núcleo de
Linux, pero, en realidad, se ha documentado muy poco y la
documentación que existe ya está desfasada. Existen mejores
fuentes de información para los desarrolladores del
núcleo.
Las secciones se empiezan con .SH seguido del
encabezamiento. Si el nombre contiene espacios y aparece en la misma linea
que el .SH, entonces se debe poner el encabezamiento dentro de
comillas dobles. Los encabezamientos tradicionales o sugeridos son: NOMBRE,
SINOPSIS, DESCRIPCIóN, VALOR DEVUELTO, ESTADO DE SALIDA, TRATAMIENTO
DE ERRORES, ERRORES, OPCIONES, USO, EJEMPLOS, FICHEROS, ENTORNO,
DIAGNÓSTICOS, SEGURIDAD, CONFORME A, NOTAS (u OBSERVACIONES), FALLOS,
AUTOR y VÉASE TAMBIÉN. Donde se aplique un encabezamiento
tradicional, por favor, úselo. Este tipo de consistencias puede hacer
que la información sea más fácil de comprender. Sin
embargo, sientase libre de crear sus propios encabezamientos si hacen
más fácil la comprensión de las cosas. El único
encabezamiento obligatorio es el NOMBRE, que debe ser la primera
sección y cuya siguiente línea debe ser una
descripción, de una línea, del programa:
.SH NOMBRE
ajedrez \- el juego de ajedrez
Es muy importante respetar este formato. Nótese que después del
nombre de la órden hay una barra invertida antes del guión. Esta
sintaxis la utiliza el programa makewhatis(8) para crear una base de
datos de descripciones breves para las órdenes whatis(1) y
apropos(1).
Otras secciones tradicionales poseen los siguientes
contenidos:
- SINOPSIS
- Brevemente describe la interfaz de la orden o función. Para las
órdenes, muestra la sintáxis de la orden y sus argumentos
(incluyendo las opciones). La negrita se utiliza para el texto literal y
la itálica para indicar los argumentos que son reemplazables. Los
corchetes ([]] rodean argumentos opcionales, las barras verticales (|)
separan alternativas y las elipses (...) se pueden repetir. Para las
funciones, muestra cualquier declaración de datos o directivas
#include necesarias, seguidas por la declaración de la
función.
- DESCRIPCIÓN
- Explica lo que la orden, función o formato hace y cómo
interactúa con ficheros o con la entrada estándar, y lo que
produce en la salida estándar o en la salida de error
estándar. Omite detalles internos o de implementación a
menos que sean críticos para comprender la interfaz. Describe el
caso usual. Para información sobre opciones, use la sección
OPTIONS. Si existe algún tipo de gramática de entrada
o conjunto complejo de subórdenes, considere el describirla en una
sección de USO aparte (y sólo coloque un resumen en
la sección DESCRIPCIÓN).
- VALOR
DEVUELTO
- Da una lista de los valores que la rutina de biblioteca devolverá
al invocador y las condiciones que hacen que se devuelvan esos
valores.
- ESTADO DE
SALIDA
- Lista los posibles valores del estado de salida de un programa y las
condiciones que hacen que se devuelvan esos valores.
- OPCIONES
- Describe las opciones aceptadas por el programa y cómo aquellas
cambian su comportamiento.
- USO
- Describe la gramática de cualquier sublenguaje que éste
implemente.
- EJEMPLOS
- Muestra uno o más ejemplos describiendo como se utiliza la
función, fichero u orden.
- FICHEROS
- Lista los ficheros que el programa o función usa, tales como
ficheros de configuración, ficheros de inicio y ficheros sobre los
que el programa trabaja directamente. Da las rutas completas de estos
ficheros y usa el proceso de instalación para modificar la parte de
directorios para concordar con las preferencias de los usuarios. Para
muchos programas, el lugar de instalación por defecto es /usr/local
por lo que su página de manual debería usar /usr/local como
base.
- ENTORNO
- Lista todas las variables de entorno que afectan a su programa o
función y cómo aquellas le afectan.
- DIAGNÓSTICOS
- Da una breve descripción de los mensajes de error más
comunes y cómo hacerles frente. No necesita explicar mensajes de
error del sistema o señales fatales que puedan aparecer durante la
ejecución de cualquier programa a menos que sean especiales de
alguna forma para su programa.
- SEGURIDAD
- Trata sobre problemas de seguridad y sus implicaciones. Advierte sobre
configuraciones o entornos que se deben evitar, órdenes que pueden
tener implicaciones para la seguridad, etc., especialmente si no son
obvios. Tratar la seguridad en una sección aparte no es necesario.
Si es fácil de entender, coloque la información sobre
seguridad en las otras secciones (tales como DESCRIPCIÓN o
USO). No obstante, por favor, ¡incluya la información
sobre seguridad en algún lugar!
- CONFORME
A
- Describe cualquier estándar o convención que ésta
implemente.
- NOTA
- Proporciona diversas notas.
- FALLOS
- Lista limitaciones, defectos o inconveniencias conocidos y otras
actividades cuestionables.
- AUTOR
- Lista los autores de la documentación o programa de tal manera que
pueda enviarles un correo para informarles de cualquier fallo.
- VÉASE
TAMBIÉN
- Lista páginas de manual relacionadas en orden alfabético,
posiblemente seguidas de otras páginas o documentos relacionados.
Convencionalmente, ésta es la última sección.
Aunque el mundo UNIX tiene muchas convenciones arbitrarias para
las páginas del manual, la existencia de cientos de páginas
del manual Linux definen nuestros estándares de fuentes:
- Para funciones, los argumentos siempre se especifican usando
itálicas, incluso en la sección SINOPSIS, mientras
que el resto de la función se escribe en negrita:
int myfunction(int argc, char
**argv);
- Los nombres de ficheros van siempre en letra itálica (p.ej.,
/usr/include/stdio.h), excepto en la sección SINOPSIS, donde
los ficheros van en negrita (p.ej., #include <stdio.h>).
- Las macros especiales que suelen ir en mayúsculas, van en negrita
(p.ej., MAXINT).
- Cuando enumeramos una lista de códigos de error, estos van en
negrita (esta lista normalmente usa la macro .TP).
- Referencias a otras páginas del manual (o de algún tema
dentro de la página actual) van en negrita. Si se incluye el
número de sección del manual, se debe dar en tipo de letra
Romana (normal), sin espacios (p.ej., man(7)).
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 órden 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 por el bien de la portabilidad). Los argumentos se delimitan por
espacios. Si el argumento contiene espacios, se deben usar comillas dobles.
Todos los argumentos se imprimen uno al lado del otro sin espacios entre
medio, de esta forma, la orden .BR se puede usar para especificar una
palabra en negrita seguido por un signo de puntuación en romano. Si
no se da ningún argumento, la orden se aplica a la siguiente
línea de texto.
A continuación hay otras macros relevantes y cadenas
predefinidas. A no ser que se indique lo contrario, todas las macros
provocan una ruptura (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 indentados que hay a continuación pueden usar el
mismo sangrado sin reespecificar el valor del sangrado. Un párrafo
normal (no 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. Trate a ens o ems como unidades de sangrado, 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:
- .LP
- Lo mismo que .PP (comienza un nuevo párrafo).
- .P
- Lo mismo que .PP Comienza un nuevo párrafo y restaura el
sangrado predominante.
- .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.
- .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.
- .UR u
- Comienza un enlace de hipertexto para la URI (URL) u.
Terminará con la correspondiente orden UE. Cuando se genera
HTML esto debería traducirse en la orden HTML <A
HREF="u">. Hay una excepción: si
u es el valor especial ":", entonces no se genera
ningún tipo de enlace de hipertexto hasta después de la
orden UE de cierre (esto permite deshabilitar los enlaces de
hipertexto en frases como LALR(1) donde el
enlace no es adecuado). Estas "macros" de enlaces de hipertexto
son nuevas y muchas herramientas no harán nada con ellas, pero, ya
que muchas herramientas (incluyendo troff) simplemente ignoran las macros
indefinidas (o, en el peor de los casos, insertan su texto), es seguro
insertarlas.
- .UE
- Finaliza la orden UR correspondiente. Al generar HTML esto se debe
traducir a </A>.
- .UN u
- Crea un sitio de hipertexto con nombre llamado u. No incluye una
orden UE correspondiente. Al generar HTML esto se debe traducir en
la orden HTML <A NAME="u"
id="u"> </A> (el
es opcional cuando no se necesita soporte para Mosaic).
- .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).
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: ”
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.
Por todos los medios, incluya URLs (o URIs) completas en el propio
texto. Herramientas tales como man2html(1) pueden convertirlas
automáticamente en enlaces de hipertexto. También puede usar
la nueva macro UR para identificar enlaces a información
relacionada. Si incluye URLs, use la URL completa (por ej.,
<http://www.kernelnotes.org>) para garantizar que las herramientas
puedan encontrar automáticamente las URLs.
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
fichero 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 '\" 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)
/usr/share/groff/[*/]tmac/tmac.an
/usr/man/whatis
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.
- —
- James Clark (jjc@jclark.com) escribió la implementación del
paquete de macros.
- —
- Rickard E. Faith (faith@cs.unc.edu) escribió la versión
inicial de esta página de manual.
- —
- Jens Schweikhardt (schweikh@noc.fdn.de) escribió el mini-COMO
`Linux Man-Page' (que influyó en esta página de
manual).
- —
- David A. Wheeler (dwheeler@ida.org) modificó en profundidad esta
página de manual, añadiendo información detallada
sobre secciones y macros.