Provided by:
manpages-es_1.55-4_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 man‐
ual 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 dis‐
tinto 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á uti‐
lizando.
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 Progra‐
mador 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 sigu‐
ientes:
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á des‐
fasada. 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 pro‐
pios 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 uti‐
liza 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 repe‐
tir. 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 men‐
sajes 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 pro‐
grama.
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 imple‐
mente.
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 rela‐
cionados. 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 (nor‐
mal), 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 referen‐
ciar 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 porta‐
bilidad). 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 predomi‐
nante 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 san‐
grado 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 pre‐
dominante un nuevo valor de 0,5 pulgadas. Como resultado,
todos los párrafos siguientes se sangrarán hasta el correspon‐
diente .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 simpli‐
fica 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. Termi‐
nará 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 ade‐
cuado). 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: ”
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 man‐
ual 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 correc‐
tamente. 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 sigu‐
ientes 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 tra‐
ducciones (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.kernel‐
notes.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 defini‐
ciones 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 tran‐
sició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.
apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7),
whatis(1)