Provided by: manpages-es_1.55-10_all bug

NOMBRE

       man - macros para formatear páginas del manual

SINOPSIS

       groff -Tascii -man fichero ...

       groff -Tps -man fichero ...

       man [seccin] ttulo

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 ttulo seccin fecha fuente manual,

       donde:

              ttulo Es el título de la página del manual (p.ej., MAN).

              seccin
                     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, Distribucin SLS, Distribucin 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 seccin 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">&nbsp;</A> (el
                &nbsp; 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)