Provided by: manpages-es_1.55-10_all 
NOMBRE
man - macros para formatear páginas del manual
SINOPSIS
groff -Tascii -man fichero ...
groff -Tps -man fichero ...
man [sección] título
DESCRIPCIÓN
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.
PREÁMBULO
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.
SECCIONES
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.
TIPOS DE LETRA
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.
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 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:
Párrafos Normales
.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.
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 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).
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: ™
\*(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.
OBSERVACIONES
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)
FICHEROS
/usr/share/groff/[*/]tmac/tmac.an
/usr/man/whatis
FALLOS
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.
AUTORES
— 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.
VÉASE TAMBIÉN
apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7), whatis(1)