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

NOMBRE

       man - macros para formatear paginas del manual

SINOPSIS

       groff -Tascii -man fichero ...

       groff -Tps -man fichero ...

       man [secci'on] t'itulo

DESCRIPCI'ON

       Esta  pagina  del manual describe el paquete de macros groff tmac.an (a
       menudo llamado el paquete de macros man)  y  convenciones  relacionadas
       para  crear  paginas  de  manual  (man).  El programador debe usar este
       paquete de macros cuando escriba o porte paginas del manual para Linux.
       Al  ser  bastante  compatible  con  otras versiones, portar paginas del
       manual  no  deberia  dar  mayores  problemas  (con  excepcion   de   la
       distribucion  incluida  en  NET-2 BSD, que utiliza un paquete de macros
       totalmente distinto llamado mdoc. Vea mdoc(7)).

       Dese cuenta que las paginas de manual mdoc de NET-2 BSD se pueden  usar
       con groff simplemente especificando la opcion -mdoc en vez de la opcion
       -man.  De todas formas, se recomienda utilizar la opcion -mandoc porque
       asi  detecta  de  forma  automatica  que  paquete  de  macros  se  esta
       utilizando.

PRE'AMBULO

       La primera orden en una pagina de manual  (despues  de  las  lineas  de
       comentarios) deberia ser

              .TH t'itulo secci'on fecha fuente manual,

       donde:

              t'itulo Es el titulo de la pagina del manual (p.ej., MAN).

              secci'on
                     Es  el  numero  de  seccion  donde  deberia  ir la pagina
                     (p.ej., 7).

              fecha  Esta es la fecha de la ultima revision (la fecha  deberia
                     cambiarse cada vez que se modifica la pagina, ya que esta
                     es la forma mas generica  de  llevar  un  control  de  la
                     version.

              fuente Indica cual es la fuente de la orden.

                     Para  ficheros  binarios,  se utilizan nombres como: GNU,
                     NET-2, Distribuci'on SLS, Distribuci'on MCC.

                     Para llamadas al sistema, se especifica la version actual
                     del nucleo: Linux 0.99.11.

                     Para  llamadas a las bibliotecas, se especifica la fuente
                     de la funcion: GNU, BSD 4.3, Linux DLL 4.4.1.

              manual Indica  el  titulo  del   manual   (p.ej.,   Manual   del
                     Programador de Linux).

       Dese cuenta que las paginas 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  ordenes  que  el  usuario puede ejecutar desde el
                        interprete de ordenes.

              2 Llamadas al sistema
                        Son funciones que el nucleo debe ejecutar.

              3 Llamadas a bibliotecas
                        La mayoria 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  estandar  del   sistema   de
                        ficheros,  protocolos de red, ASCII y otros codigos de
                        caracteres, esta pagina de man y otras cosas.

              8 'Ordenes para la administraci'on del sistema
                        Ordenes como  mount(8),  muchas  de  las  cuales  solo
                        pueden ser ejecutadas por el superusuario.

              9 Rutinas del n'ucleo
                        Esta  es  una  seccion  de manual obsoleta. Una vez se
                        penso que una buena  idea  seria  documentar  aqui  el
                        nucleo  de Linux, pero, en realidad, se ha documentado
                        muy  poco  y  la  documentacion  que  existe  ya  esta
                        desfasada. Existen mejores fuentes de informacion para
                        los desarrolladores del nucleo.

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,
       DESCRIPCIoN, VALOR DEVUELTO, ESTADO DE SALIDA, TRATAMIENTO DE  ERRORES,
       ERRORES,  OPCIONES,  USO,  EJEMPLOS,  FICHEROS,  ENTORNO, DIAGNOSTICOS,
       SEGURIDAD, CONFORME A, NOTAS (u OBSERVACIONES), FALLOS, AUTOR  y  VEASE
       TAMBIEN.  Donde  se  aplique  un encabezamiento tradicional, por favor,
       uselo.  Este tipo de consistencias puede hacer que la  informacion  sea
       mas  facil  de  comprender.  Sin  embargo,  sientase libre de crear sus
       propios encabezamientos si hacen mas facil la comprension de las cosas.
       El  unico  encabezamiento  obligatorio  es  el  NOMBRE, que debe ser la
       primera seccion y cuya siguiente linea debe ser una descripcion, de una
       linea, del programa:

              .SH NOMBRE
              ajedrez \- el juego de ajedrez

       Es  muy importante respetar este formato. Notese que despues del nombre
       de la orden hay una barra invertida antes del guion. Esta  sintaxis  la
       utiliza  el  programa  makewhatis(8)  para  crear  una base de datos de
       descripciones breves para las ordenes whatis(1) y apropos(1).

       Otras secciones tradicionales poseen los siguientes contenidos:

       SINOPSIS      Brevemente describe la interfaz de la  orden  o  funcion.
                     Para  las  ordenes, muestra la sintaxis de la orden y sus
                     argumentos  (incluyendo  las  opciones).  La  negrita  se
                     utiliza  para  el texto literal y la italica 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
                     declaracion de datos o  directivas  #include  necesarias,
                     seguidas por la declaracion de la funcion.

       DESCRIPCI'ON   Explica  lo  que  la orden, funcion o formato hace y como
                     interactua con ficheros o con la entrada estandar,  y  lo
                     que produce en la salida estandar o en la salida de error
                     estandar.  Omite detalles internos o de implementacion  a
                     menos  que  sean  criticos  para  comprender la interfaz.
                     Describe el caso usual. Para informacion sobre  opciones,
                     use   la  seccion  OPTIONS.   Si  existe  algun  tipo  de
                     gramatica de entrada o conjunto complejo  de  subordenes,
                     considere  el describirla en una seccion de USO aparte (y
                     solo coloque un resumen en la seccion DESCRIPCI'ON).

       VALOR DEVUELTO
                     Da una lista de los valores que la rutina  de  biblioteca
                     devolvera 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  como
                     aquellas cambian su comportamiento.

       USO           Describe  la  gramatica de cualquier sublenguaje que este
                     implemente.

       EJEMPLOS      Muestra uno o mas ejemplos describiendo como  se  utiliza
                     la funcion, fichero u orden.

       FICHEROS      Lista  los  ficheros que el programa o funcion usa, tales
                     como ficheros de  configuracion,  ficheros  de  inicio  y
                     ficheros  sobre los que el programa trabaja directamente.
                     Da las rutas completas de estos ficheros y usa el proceso
                     de  instalacion  para  modificar  la parte de directorios
                     para concordar con las preferencias de los usuarios. Para
                     muchos  programas, el lugar de instalacion por defecto es
                     /usr/local por lo que su pagina de  manual  deberia  usar
                     /usr/local como base.

       ENTORNO       Lista  todas  las  variables  de entorno que afectan a su
                     programa o funcion y como aquellas le afectan.

       DIAGN'OSTICOS  Da una breve descripcion de los  mensajes  de  error  mas
                     comunes  y  como  hacerles  frente.  No necesita explicar
                     mensajes de error  del  sistema  o  senales  fatales  que
                     puedan   aparecer   durante  la  ejecucion  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,  ordenes  que  pueden tener implicaciones para la
                     seguridad, etc., especialmente si no son obvios.   Tratar
                     la seguridad en una seccion aparte no es necesario. Si es
                     facil de entender, coloque la informacion sobre seguridad
                     en  las  otras  secciones (tales como DESCRIPCI'ON o USO).
                     No obstante, por favor,  iincluya  la  informacion  sobre
                     seguridad en algun lugar!

       CONFORME A    Describe   cualquier   estandar  o  convencion  que  esta
                     implemente.

       NOTA          Proporciona diversas notas.

       FALLOS        Lista limitaciones, defectos o inconveniencias  conocidos
                     y otras actividades cuestionables.

       AUTOR         Lista  los  autores de la documentacion o programa de tal
                     manera que pueda enviarles un correo para informarles  de
                     cualquier fallo.

       V'EASE TAMBI'EN Lista paginas de manual relacionadas en orden alfabetico,
                     posiblemente  seguidas  de  otras  paginas  o  documentos
                     relacionados.   Convencionalmente,   esta  es  la  ultima
                     seccion.

TIPOS DE LETRA

       Aunque el mundo UNIX tiene muchas  convenciones  arbitrarias  para  las
       paginas  del  manual,  la  existencia  de cientos de paginas del manual
       Linux definen nuestros estandares de fuentes:

              Para funciones, los argumentos  siempre  se  especifican  usando
              italicas,  incluso en la secci'on SINOPSIS, mientras que el resto
              de la funcion se escribe en negrita:
              int myfunction(int argc, char **argv);

              Los nombres de ficheros van siempre  en  letra  italica  (p.ej.,
              /usr/include/stdio.h), excepto en la seccion SINOPSIS, donde los
              ficheros van en negrita (p.ej., #include <stdio.h>).

              Las macros especiales  que  suelen  ir  en  mayusculas,  van  en
              negrita (p.ej., MAXINT).

              Cuando  enumeramos  una  lista de codigos de error, estos van en
              negrita (esta lista normalmente usa la macro .TP).

              Referencias a otras paginas del manual (o de algun  tema  dentro
              de la pagina actual) van en negrita.  Si se incluye el numero de
              seccion del  manual,  se  debe  dar  en  tipo  de  letra  Romana
              (normal), sin espacios (p.ej., man(7)).

       Las ordenes para seleccionar el tipo de letra son:

       .B  Negrita

       .BI Negrita  alternandose  con  italica  (especialmente  util  para  la
           especificacion de funciones)

       .BR Negrita  alternandose   con   romana   (especialmente   util   para
           referenciar a otras paginas de manual)

       .I  Italica

       .IB Italica alternandose con negrita

       .IR Italica alternandose con romana

       .RB Romana alternandose con negrita

       .RI Romana alternandose con italica

       .SB Pequena alternandose con negrita

       .SM Pequena (util para acronimos)

       Tradicionalmente,  cada  orden puede tener seis argumentos como maximo,
       pero la implementacion de GNU elimina esta limitacion (aunque  tal  vez
       usted  todavia  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 puntuacion en romano. Si  no  se  da
       ningun argumento, la orden se aplica a la siguiente linea de texto.

OTRAS MACROS Y CADENAS

       A continuacion hay otras macros relevantes y cadenas predefinidas. A no
       ser que se indique lo contrario, todas las macros provocan una  ruptura
       (fin  de la linea actual de texto). Muchas de estas macros configuran o
       usan el "sangrado predominante". Cualquier macro  con  el  parametro  i
       debajo,  asigna  un valor al "sangrado predominante". Las macros pueden
       omitir la i en cuyo caso se  usara  el  actual  sangrado  predominante.
       Como  resultado,  los parrafos indentados que hay a continuacion pueden
       usar el mismo sangrado sin reespecificar el  valor  del  sangrado.   Un
       parrafo   normal   (no   sangrado)   restaura  el  valor  del  sangrado
       predominante a su valor por omision (0,5 pulgadas).   Por  defecto,  un
       sangrado  dado  se  mide  en  ens.  Trate  a ens o ems como unidades de
       sangrado, ya que estas se ajustaran automaticamente a los cambios en el
       tamano de las fuentes.  Las otras definiciones de macro claves son:

   P'arrafos Normales
       .LP      Lo mismo que .PP (comienza un nuevo parrafo).

       .P       Lo  mismo  que  .PP  Comienza  un  nuevo parrafo 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  parrafos  siguientes   se   sangraran   hasta   el
                correspondiente .RE.

       .RE      Finaliza  un  sangrado del margen relativo y restaura el valor
                anterior del sangrado predominante.

   Macros para P'arrafos Sangrados
       .HP i    Comienza un parrafo con un sangrado colgante (la primera linea
                del  parrafo  comienza  en el margen izquierdo de los parrafos
                normales y el resto de lineas del parrafo se sangran).

       .IP x i  Parrafo sangrado con una etiqueta colgante  opcional.   Si  se
                omite  la  etiqueta  x,  todo el parrafo siguiente se sangra i
                pulgadas. Si se da la etiqueta x, esta se cuelga en el  margen
                izquierdo  antes  del siguiente parrafo sangrado (esto es como
                .TP excepto que la etiqueta se incluye con la orden  en  lugar
                de  al  comienzo  de  la  siguiente linea).  Si la etiqueta es
                demasiado larga, el texto tras la  etiqueta  se  bajara  a  la
                siguiente  linea (el texto no se perdera o se mezclara).  Para
                listas con vinetas, use esta macro con \(bu  (bullet)  o  \(em
                (em  dash)  como  etiqueta,  y para listas numeradas, use como
                etiqueta  el  numero  o  letra  seguido  por  un  punto.  Esto
                simplifica la traduccion a otros formatos.

       .TP i    Comienza  un parrafo con una etiqueta colgante. La etiqueta se
                da en la siguiente linea, 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.
                Terminara con la correspondiente orden UE.  Cuando  se  genera
                HTML  esto  deberia  traducirse en la orden HTML <A HREF="u">.
                Hay una excepcion: si u es el valor especial ":", entonces  no
                se genera ningun tipo de enlace de hipertexto hasta despues 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 haran 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  parrafos 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 seccion).

   Cadenas Predefinidas
       El paquete man tiene las siguientes cadenas predefinidas:

       \*R    Simbolo de registro: (R)

       \*S    Cambia al tamano de fuente por omision

       \*(Tm  Simbolo de marca registrada: tm

       \*(lq  Comillas dobles espanolas izquierdas: "

       \*(rq  Comillas dobles espanolas derechas: "

SUBCONJUNTO SEGURO

       Aunque  tecnicamente man es una paquete de macros troff, en realidad un
       gran numero de otras  herramientas  procesan  ficheros  de  paginas  de
       manual que no implementan todas las capacidades de troff. Por tanto, es
       mejor evitar algunas de las capacidades mas exoticas  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 ordenes IP y
       TP en su lugar para tablas de dos columnas).  Evite hacer calculos.  La
       mayoria  de  las  otras herramientas no podran procesarlos. Use ordenes
       simples que  se  puedan  traducir  facilmente  a  otros  formatos.  Las
       siguientes macros troff se consideran seguras (aunque, en muchos casos,
       seran 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.

       Tambien  puede  usar  muchas  secuencias  de  escape de troff (aquellas
       secuencias que comienzan por \). Cuando necesite incluir el caracter de
       barra  invertida como texto normal, use \e.  Otras secuencias que puede
       usar, donde x y xx son cualquier caracter  y  N  es  cualquier  digito,
       incluyen: \', \, \-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx
       y \f(xx.  Evite usar secuencias de escape para dibujar graficos.

       No use el parametro opcional de bp (break page, salto de pagina).   Use
       solo  valores positivos para sp (vertical space, espacio vertical).  No
       defina una macro (de) con el mismo nombre que una macro en  este  o  el
       paquete  de  macros mdoc, con un significado diferente. Es probable que
       tales redefiniciones se ignoren.  Todo sangrado positivo  (in)  deberia
       ir  acompanado por el correspondiente sangrado negativo (aunque deberia
       usar las macros RS y RE  en  su  lugar).   La  condicion  (if,ie)  solo
       deberia  tener  't'  o  'n'  como condicion.  Solo se deberian utilizar
       traducciones (tr) que se puedan ignorar.  Los cambios de fuente  (ft  y
       las secuencias de escape \f) solo deberia tener los valores 1, 2, 3, 4,
       R, I, B, P o CW (la orden ft tambien puede no tener parametros).

       Si usa otras capacidades diferentes a  estas,  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 deberia anadirse a
       esta lista.

OBSERVACIONES

       Por todos los medios, incluya URLs (o  URIs)  completas  en  el  propio
       texto.    Herramientas   tales  como  man2html(1)  pueden  convertirlas
       automaticamente en enlaces de hipertexto.  Tambien puede usar la  nueva
       macro  UR  para  identificar  enlaces  a  informacion  relacionada.  Si
       incluye     URLs,     use     la     URL     completa     (por     ej.,
       <http://www.kernelnotes.org>)  para  garantizar  que  las  herramientas
       puedan encontrar automaticamente las URLs.

       Las herramientas que procesan estos ficheros deben abrir el  fichero  y
       examinar  el  primer  caracter  distinto de espacio. Un punto (.) o una
       comilla simple (') al principio de una linea 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 paginas de manual comienzan con '\" seguido por un espacio y una
       lista de caracteres que indican como se va a procesar la  pagina.   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 automaticamente.  Sin embargo, tal vez quiera
       incluir esta informacion de tal manera que  su  pagina  man  pueda  ser
       tratada   por   otros   sistemas   (menos  capaces).   Aqui  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  mayoria  de  las macros describen aspectos del formato (por ej., el
       tipo de las fuentes  y  el  espaciado)  en  vez  de  marcar  contenidos
       semanticos  (por  ej.,  este texto es una referencia a otra pagina), en
       comparacion con formatos como mdoc y Docbook (incluso  HTML  tiene  mas
       marcas  semanticas). Esto hace que sea mas dificil modificar el formato
       man para diferentes medios, para hacer el formateo consistente para  un
       medio  dado  y  para insertar automaticamente referencias cruzadas.  El
       adherirse al  subconjunto  seguro  descrito  antes  debe  facilitar  la
       transicion automatica a un formato diferente de pagina de referencia en
       el futuro.

       La macro de Sun TX no esta implantada.

AUTORES

       -- James Clark (jjc@jclark.com) escribio la implementacion del  paquete
          de macros.

       -- Rickard  E.  Faith (faith@cs.unc.edu) escribio la version inicial de
          esta pagina de manual.

       -- Jens Schweikhardt (schweikh@noc.fdn.de) escribio el mini-COMO `Linux
          Man-Page' (que influyo en esta pagina de manual).

       -- David  A.  Wheeler  (dwheeler@ida.org)  modifico en profundidad esta
          pagina de manual, anadiendo informacion detallada sobre secciones  y
          macros.

V'EASE TAMBI'EN

       apropos(1),  groff(1),  man(1),  man2html(1), mdoc(7), mdoc.samples(7),
       whatis(1)