Provided by: manpages-es_1.55-9_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)