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

NOMBRE

     mdoc.samples -- tutorial para escribir manuales BSD con -mdoc

SINOPSIS

     man mdoc.samples

DESCRIPCI'ON

     Este es un tutorial para escribir paginas de manual BSD con el paquete de
     macros -mdoc, un paquete de formateo basado en contenidos y dominios para
     troff(1).  Su predecesor, el paquete -man(7), trata el diseno de las
     paginas dejando la manipulacion de las fuentes y otros detalles de
     composicion al autor.  En -mdoc, las macros para el diseno de las paginas
     de manual constituyen el dominio de estructura de p'agina que consta de
     macros para titulos, encabezados de seccion, visualizaciones y listas;
     esencialmente, elementos que afectan a la posicion fisica del texto en la
     pagina formateada.  Ademas del dominio de estructura de pagina, hay dos
     dominios mas: el dominio de manual y el dominio de texto general.  El
     dominio de texto general se define como macros que realizan tareas tales
     como entrecomillar o emfatizar trozos de texto.  El dominio de manual se
     define como macros que son un subconjunto del lenguaje informal usado dia
     a dia para describir ordenes, rutinas y ficheros BSD relacionados.  Las
     macros en el dominio de manual manejan nombres de ordenes, argumentos y
     opciones de la linea de ordenes, nombres de funcion, parametros de
     funcion, nombres de ruta, variables, referencias cruzadas a otras paginas
     de manual, etc.  Estos elementos del dominio tienen valor tanto para el
     autor como para el futuro usuario de la pagina de manual.  Es de esperar
     que la consistencia ganada a traves del conjunto de manuales proporcione
     una traduccion mas facil a futuras herramientas de documentarion.

     En el conjunto de paginas de manual de UNIX se hace referencia a una
     entrada de manual simplemente como <<pagina man>>, sin tener en cuenta la
     longitud real y sin intenciones sexistas.

PRIMEROS PASOS

     Ya que una persona lee normalmente un tutorial cuando desea usar el
     material inmediatamente, se ha supuesto que el usuario de este manual
     puede ser algo impaciente. El material presentado en lo que resta de este
     documento se resume como sigue:

           1.   IDIOSINCRASIAS DE TROFF
                      Uso de macros.
                      Paso de espacios en blanco en un argumento.
                      Espacios en blanco al final de una linea (aviso).
                      Proteccion de caracteres especiales.

           2.   ANATOMIA DE UNA PAGINA DE MANUAL
                      Modelo de una pagina de manual.

           3.   MACROS DE TITULO.

           4.   INTRODUCCION A LOS DOMINIOS DE MANUAL Y DE TEXTO GENERAL.
                      Lo que hay en un nombre....
                      Sintaxis general.

           5.   DOMINIO DE MANUAL
                      Macro de direccion.
                      Nombre del autor.
                      Macro de argumento.
                      Declaracion de configuracion (solo seccion cuatro).
                      Modificador de orden.
                      Variables definidas.
                      Codigos errno (solo seccion dos).
                      Variables de entorno.
                      Argumento de funcion.
                      Declaracion de funciones.
                      Opciones (flags).
                      Funciones (rutinas de biblioteca).
                      Tipo de funcion.
                      Ordenes interactivas.
                      Macro de nombre.
                      Opciones.
                      Nombres de rutas.
                      Variables.
                      Referencias cruzadas a paginas de manual.

           6.   DOMINIO DE TEXTO GENERAL
                      Macro AT&T.
                      Macro BSD.
                      Macro FreeBSD.
                      Macro UNIX.
                      Macros de cierre/entrecomillado
                                  Entrecomillado/cierre mediante angulos.
                                  Entrecomillado/cierre mediante corchetes.
                                  Entrecomillado/cierre mediante comillas
                                        dobles.
                                  Entrecomillado/cierre mediante parentesis.
                                  Entrecomillado/cierre mediante comillas
                                        simples.
                                  Macro de prefijo.
                      Macro de texto normal o de no operacion.
                      Macro de eliminacion de espacios.
                      Referencias cruzadas a secciones.
                      Referencias y citas.
                      Valores devueltos (solo secciones dos y tres)
                      Nombres de marcas (o acronimos y nombres de tipos).
                      Argumentos extendidos.

           7.   DOMINIO DE ESTRUCTURA DE PAGINA
                      Cabecera de seccion.
                      Parrafos y espacios entre lineas.
                      Agrupamientos.
                      Ejemplos y visualizaciones (displays).
                      Modos de las fuentes (enfasis, literal y simbolico).
                      Listas etiquetadas y columnas.

           8.   CADENAS PREDEFINIDAS

           9.   DIAGNOSTICOS

           10.  GROFF, TROFF Y NROFF

           11.  FICHEROS

           12.  FALLOS

IDIOSINCRASIAS DE TROFF

     El paquete -mdoc intenta simplificar el proceso de escribir una pagina de
     manual.  Teoricamente, uno no tiene por que aprender los detalles mas
     engorrosos de troff(1) para usar -mdoc; sin embargo, hay unas pocas
     limitaciones que son inevitables y es mejor quitarselas de en medio. Y,
     tambien, este prevenido, este paquete no es rapido.

   Uso de macros
     Al igual que en troff(1), una macro se invoca colocando un '.' (caracter
     punto) al principio de una linea seguido por el nombre de dos caracteres
     de la macro. Los argumentos pueden ir a continuacion de la macro
     separados por espacios. El caracter punto al principio de la linea es el
     que hace que troff(1) interprete los dos siguientes caracteres como el
     nombre de una macro.  Para colocar un '.' (caracter punto) al principio
     de una linea en algun contexto distinto al de una invocacion de macro,
     preceda el '.' (punto) con una secuencia '\&' de escape.  '\&' se traduce
     literalmente en un espacio de ancho cero y nunca se muestra en la salida.

     En general, las macros troff(1) aceptan hasta nueve argumentos, ignorando
     cualquier argumento extra.  La mayoria de las macros de -mdoc aceptan
     nueve argumentos y, en casos limitados, los argumentos pueden continuar o
     extenderse por la siguiente linea (vea Extensiones).  Unas pocas macros
     manejan argumentos entrecomillados (vea Paso de espacios en blanco en un
     argumento mas abajo).

     La mayoria de las macros de dominio de texto general y de manual de -mdoc
     son especiales en el sentido de que sus listas de argumentos se analizan
     o interpretan (`parse') en busca de nombres de macros invocables.  Esto
     significa que un argumento de la lista de argumentos que coincide con el
     nombre de una macro de dominio de texto general o de manual y que se
     determine como invocable, se ejecutara o invocara cuando se procese. En
     este caso el argumento, aunque sea el nombre de una macro, no va
     precedido por un '.' (punto).  Esta es la forma en la que muchas macros
     se anidan; por ejemplo, la macro de opcion '.Op', puede invocar las
     macros de banderas y argumentos 'Fl' y 'Ar', para especificar una bandera
     opcional con un argumento:

           [-s bytes]         se obtiene mediante .Op Fl s Ar bytes

     Para evitar que una cadena de dos caracteres se interprete como un nombre
     de macro, preceda la cadena con la secuencia de escape '\&':

           [Fl s Ar bytes]    se obtiene mediante .Op \&Fl s \&Ar bytes

     Aqui las cadenas 'Fl' y 'Ar' no se interpretan como macros.  A lo largo
     de este documento y en el manual de referencia rapida mdoc(7) que le
     acompana, las macros cuyas listas de argumentos se analizan en busca de
     argumentos invocables se referencian como interpretadas y las macros que
     se pueden invocar desde una lista de argumentos se referencian como
     invocables.  Esto es una metedura de pata tecnica ya que casi todas las
     macros de -mdoc son interpretadas pero, ya que era engorroso referirse
     constantemente a las macros como invocables y como capaces de invocar a
     otras manos, se ha decidido usar el termino <<interpretado>>.

   Paso de espacios en blanco en un argumento
     Algunas veces se desea pasar como argumento una cadena de caracteres que
     contiene uno o mas espacios en blanco. Esto puede ser necesario para
     vencer el limite de nueve argumentos o para especificar argumentos para
     macros que esperan una disposicion particular de los elementos de una
     lista de argumentos.  Por ejemplo, la macro de funcion '.Fn' espera que
     el primer argumento sea el nombre de una funcion y que cualesquiera
     argumentos restantes sean parametros de funcion.  Siguiendo la forma en
     la que ANSI C establece la declaracion de los parametros de funcion en la
     lista de parametros que se especifica entre parentesis, se garantiza que
     cada parametro sea, al menos, una cadena de dos palabras.  Por ejemplo,
     int foo.

     Hay dos formas posibles de pasar un argumento que contiene un espacio.
     Nota sobre la implementaci'on: desafortunadamente, la forma mas
     conveniente de pasar espacios entre comillas, reasignando los argumentos
     individuales antes de realizar la interpretacion de la linea, era
     bastante costosa de implementar en cuanto a velocidad y espacio para
     todas las macros troff de AT&T.  No es costosa para groff pero, por el
     bien de la transportabilidad, ha sido limitada a las siguientes macros
     que mas la necesitan:

           Cd    Declaracion de configuracion (seccion 4 SINOPSIS).
           Bl    Comienzo de lista (para el indicador del ancho).
           Em    Texto emfatizado.
           Fn    Funciones (secciones dos y cuatro).
           It    Elementos de una lista.
           Li    Texto literal.
           Sy    Texto simbolico.
           %B    Titulos de libro.
           %J    Nombres de revista.
           %O    Notas opcionales para una referencia.
           %R    Titulo de informe (en una referencia).
           %T    Titulo de articulo en un libro o revista.

     Una forma de pasar una cadena que contiene espacios en blanco es usar el
     espacio <<solido>> o <<de longitud fija>> '\ ', es decir, un espacio en
     blanco precedido por un caracter de escape '\'.  Este metodo se puede
     usar con cualquier macro pero tiene el efecto secundario de interferir
     con el ajuste del texto a lo largo de una linea.  Troff ve el espacio en
     blanco solido como si fuera cualquier otro caracter imprimible y no puede
     dividir la cadena de caracteres en trozos separados por blancos o
     caracteres de nueva linea como seria de esperar. Este metodo es util para
     cadenas que no se espera que se solapen con el final de una linea.  Por
     ejemplo:

           fetch(char *str)  se crea mediante '.Fn fetch char\ *str'

           fetch(char *str)  tambien se puede crear mediante '.Fn fetch "char
                             *str"'

     Si se omiten los caracteres '\' o las comillas, '.Fn' veria tres
     argumentos y el resultado seria

           fetch(char, *str)

     Para ver un ejemplo de lo que ocurre cuando la lista de parametros se
     solapa con el final de linea, vea la seccion FALLOS.

   Espacios en blanco al final de una l'inea (aviso)
     Los espacios en blanco al final de una linea pueden confudir a Troff.
     Una medida preventiva inteligente es eliminar globalmente todos los
     espacios en blanco de las secuencias de caracteres <espacio-en-
     blanco><fin-de-linea>.  Si se plantea la necesidad de insertar un
     caracter en blanco al final de una linea, se puede hacer con un espacio
     de longitud fija y el caracter de escape '\&'.  Por ejemplo,
     'cadena\ \&'.

   Protecci'on de caracteres especiales
     Los caracteres especiales como el caracter de nueva linea '\n', se tratan
     reemplazando '\' con '\e' (por ejemplo, '\en') para conservar la barra
     invertida (\).

ANATOM'IA DE UNA P'AGINA DE MANUAL

     El cuerpo de una pagina de manual se puede construir facilmente a partir
     de una plantilla basica que se puede encontrar en el fichero
     /usr/share/misc/mdoc.template.  Tambien se pueden encontrar varias
     paginas de manual de ejemplo en /usr/share/examples/mdoc.

   Modelo de una p'agina de manual
           .\" Las siguientes invocaciones son necesarias para todas las paginas
           .\" de manual.
           .Dd Mes dia, ano
           .Os SISTEMA_OPERATIVO [version/lanzamiento]
           .Dt TITULO_DOCUMENTO [seccion numero] [volumen]
           .Sh NOMBRE
           .Nm nombre
           .Nd descripcion de una linea del nombre
           .Sh SINOPSIS
           .Sh DESCRIPCION
           .\" Las siguientes invocaciones se deberian <<descomentar>> y usar
           .\" donde fuera apropiado.
           .\" La siguiente invocacion solo es para los valores devueltos
           .\" por las funciones de las secciones 2 y 3.
           .\" .Sh VALORES DEVUELTOS
           .\" La siguiente invocacion es solo para las secciones 1, 6, 7 y 8.
           .\" .Sh ENTORNO
           .\" .Sh FICHEROS
           .\" .Sh EJEMPLOS
           .\" La siguiente invocacion es solo para las secciones 1, 6, 7 y 8.
           .\"    (valores devueltos por una orden (al shell) y
           .\"       diagnosticos de los tipos de fprintf/stderr)
           .\" .Sh DIAGNOSTICOS
           .\" La siguiente invocacion es solo para el manejo de errores y
           .\" senales de las secciones 2 y 3.
           .\" .Sh ERRORES
           .\" .Sh VEASE TAMBIEN
           .\" .Sh CONFORME A
           .\" .Sh HISTORIA
           .\" .Sh AUTORES
           .\" .Sh FALLOS

     Los primeros elementos de la plantilla son las macros (.Dd, .Os, .Dt); la
     fecha del documento, el sistema operativo para el que el fuente de la
     pagina de manual o tema se ha desarrollado o modificado y el titulo de la
     pagina de manual (en may'usculas) junto con la seccion del manual a la que
     pertenece la pagina.  Estas macros idenfican a la pagina y se discuten
     mas abajo en MACROS DE T'ITULO.

     El resto de elementos de la plantilla son cabeceras de seccion (.Sh); de
     las que NOMBRE, SINOPSIS y DESCRIPCI'ON son obligatorias.  Las cabeceras
     se discuten en DOMINIO DE ESTRUCTURA DE P'AGINA, tras la presentacion del
     DOMINIO DE MANUAL.  Para mostrar el uso de las macros de diseno de
     pagina, se usan varias macros de contenido; se recomienda informarse
     sobre las macros de contenido antes de hacerlo sobre las macros de diseno
     de pagina.

MACROS DE T'ITULO

     Las macros de titulo son la primera parte del dominio de la estructura de
     pagina, pero las presentamos en primer lugar y de forma separada para
     aquellos que deseen empezar a escribir una pagina de manual ya. Tres
     macros de cabecera indican el titulo del documento o de la pagina de
     manual, el sistema operativo y la fecha de la autoria.  Estas macros se
     invocan solo una vez justo al principio del documento y solo se usan para
     construir los encabezados y los pies de pagina.

     .Dt TITULO_DOCUMENTO no_seccion [volumen]
             El titulo del documento es el tema de la pagina de manual y debe
             estar en MAYUSCULAS debido a limitaciones de troff.  El numero de
             seccion puede ser 1, ..., 8 y, si se especifica, se puede omitir
             el titulo del volumen. Un titulo de volumen puede ser arbitrario
             o uno de los siguientes:

                   AMD    Documentos del Manual Ancestral de UNIX
                   SMM    Manual del Administrador de Sistemas de UNIX
                   URM    Manual de Referencia de UNIX
                   PRM    Manual del Programador de UNIX

             La etiqueta de volumen por omision es URM para las secciones 1, 6
             y 7; SMM para la seccion 8; PRM para las secciones 2, 3, 4 y 5.

     .Os sistema_operativo version
             El nombre del sistema operativo deberia ser un acronimo comun,
             por ejemplo, BSD o FreeBSD o ATT.  La version (`release') deberia
             ser la nomenclatura estandar de version para el sistema
             especificado, por ejemplo, 4.3, 4.3+Tahoe, V.3 o V.4.  Los
             argumentos que no se reconocen se muestran como si se hubieran
             indicado en el pie de pagina. Por ejemplo, un pie de pagina
             tipico podria ser:

                   .Os BSD 4.3

             o
                   .Os FreeBSD 2.2

             o, para algo producido localmente,

                   .Os CS Department

             El valor por omision de Berkeley, '.Os' sin argumentos, se ha
             definido como BSD en el fichero /usr/share/tmac/mdoc/doc-common.
             Por omision, su valor verdadero deberia ser LOCAL.  Dese cuenta
             que si la macro '.Os' no aparece, la esquina inferior izquierda
             de la pagina tendra un aspecto horrible.

     .Dd mes dia, ano
             Formalmente, la fecha se deberia escribir como:

                   25 enero 1989

INTRODUCCI'ON A LOS DOMINIOS DE MANUAL Y DE TEXTO GENERAL

   Lo que hay en un nombre...
     Los nombres de las macros del dominio de manual se derivan del lenguaje
     informal cotidiano usado para describir ordenes, subrutinas y ficheros
     relacionados.  Para describir los tres aspectos diferentes de la
     escritura de una pagina de manual se usan ligeras variaciones de este
     lenguaje. En primer lugar encontramos la descripcion del uso de las
     invocaciones de macros -mdoc.  En segundo lugar aparece la descripcion de
     una orden UNIX con macros -mdoc.  Y, en tercer lugar, tenemos la
     descripcion verbal de una orden para el usuario; es decir, la discusion
     de una orden en el texto de una pagina de manual.

     En el primer caso, las macros de troff(1) son ellas mismas un tipo de
     orden; la sintaxis general para una orden troff es:

           .Va argument1 argument2 ... argument9

     '.Va' es una orden de macro o invocacion y cualquier cosa que le siga es
     un argumento a procesar.  En el segundo caso, la descripcion de una orden
     UNIX usando las macros de contenido es un poco mas enrevesada; una linea
     tipica de la orden SINOPSIS podria aparecer como:

           filter [-flag] infile outfile

     Aqui, filter es el nombre de la orden y la cadena entre corchetes -flag
     es un argumento de opciones, lo que se indica mediante los corchetes.  En
     terminos de -mdoc, infile y outfile se llaman argumentos.  Las macros que
     dieron forma al ejemplo anterior son:

           .Nm filter
           .Op Fl flag
           .Ar infile outfile

     En el tercer caso, la discusion de ordenes y de la sintaxis de ordenes
     incluye los dos ejemplos anteriores, pero puede anadir mas detalle.  A
     los argumentos infile y outfile del ejemplo anterior se les podria
     referenciar como operandos o argumentos de fichero.  Algunas listas de
     argumentos de las lineas de ordenes son bastante largas:

           make  [-eiknqrstv] [-D variable] [-d opciones] [-f makefile]
                 [-I directorio] [-j max_tareas] [variable=valor]
                 [objetivo ...]

     Aqui podriamos hablar de la orden make y calificar a makefile como
     argumento de la opcion -f, o hablar del operando de fichero opcional
     objetivo.  En el contexto verbal, dicho detalle puede evitar confusiones,
     si bien el paquete -mdoc no tiene una macro para el argumento de una
     opci'on.  En su lugar, se usa la macro de argumento 'Ar' para operandos o
     argumentos de fichero como objetivo, ademas de para un argumento de
     opcion como variable.  La linea de la orden make se obtuvo a partir de:

           .Nm make
           .Op Fl eiknqrstv
           .Op Fl D Ar variable
           .Op Fl d Ar opciones
           .Op Fl f Ar makefile
           .Op Fl I Ar directorio
           .Op Fl j Ar max_tareas
           .Op Ar variable=valor
           .Bk -words
           .Op Ar objetivo ...
           .Ek

     Las macros '.Bk' y '.Ek' se explican en Agrupamientos.

   Sintaxis general
     Las macros de dominio de manual y de texto general comparten una sintaxis
     similar con unas pocas diferencias menores: '.Ar', '.Fl', '.Nm', y '.Pa'
     solo difieren cuando se invocan sin argumentos; '.Fn' y '.Xr' imponen un
     orden a sus listas de argumentos; y las macros '.Op' y '.Fn' tienen
     limitaciones de anidamiento.  Todas las macros de contenido son capaces
     de reconocer y de manejar adecuadamente la puntuacion, siempre que cada
     caracter de puntuacion vaya precedido por un espacio.  Si tenemos la
     invocacion:

           .Li sptr, ptr),

     El resultado sera:

           sptr, ptr),

     El caracter de puntuacion no se reconoce y todo se muestra utilizando la
     fuente `literal'. Si el caracter de puntuacion se separa precediendolo
     por un espacio en blanco:

           .Li sptr , ptr ) ,

     El resultado sera:

           sptr, ptr),

     Ahora el caracter de puntuacion se reconoce y se muestra utilizando la
     fuente por omision, distinguiendolo asi de las cadenas en fuente literal.

     Para eliminar el significado especial de un caracter de puntuacion
     protejalo con '\&'.  Troff esta limitado como lenguaje de macros y tiene
     dificultades cuando se le pasa una cadena que contiene un miembro del
     conjunto matematico, logico o de entrecomillado:

                 {+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}

     El problema es que troff puede pensar que realmente se debe realizar la
     operacion o evaluacion sugerida por uno de estos caracteres.  Para evitar
     la evaluacion accidental de estos caracteres, protejalos con '\&'.  La
     sintaxis tipica se muestra en la primera macro de contenido, '.Ad', que
     aparece mas abajo,

DOMINIO DE MANUAL

   Macro de direcci'on
     La macro de direccion identifica una estructura de direccion de la forma
     dir1[,dir2[,dir3]].

           Uso: .Ad direccion ...
                   .Ad dir1     dir1
                   .Ad dir1 .   dir1.
                   .Ad dir1 , fichero2
                                dir1, fichero2
                   .Ad f1 , f2 , f3 :
                                f1, f2, f3:
                   .Ad dir ) ) ,
                                dir)),

     Es un error llamar a '.Ad' sin argumentos.  '.Ad' es invocable por otras
     macros y es interpretada.

   Nombre del autor
     La macro '.An' se usa para especificar el nombre del autor de aquello que
     se esta documentando, o el nombre del autor de la pagina de manual real.
     Cualquier argumento restante tras el nombre se supone que es un caracter
     de puntuacion.

           Uso: .An nombre_autor
                   .An Juan Autor
                                  Juan Autor
                   .An Juan Autor ,
                                  Juan Autor,
                   .An Juan Autor Aq nadie@FreeBSD.ORG
                                  Juan Autor <nadie@FreeBSD.ORG>
                   .An Juan Autor ) ) ,
                                  Juan Autor)),

     La macro '.An' es interpretada y es invocable.  Es un error llamar a
     '.An' sin argumentos

   Macro de argumento
     La macro de argumento '.Ar' se puede usar siempre que se haga referencia
     a un argumento de la linea de ordenes.

           Uso: .Ar argumento ...
                    .Ar                file ...
                    .Ar fichero1       fichero1
                    .Ar fichero1 .     fichero1.
                    .Ar fichero1 fichero2
                                       fichero1 fichero2
                    .Ar f1 f2 f3 :     f1 f2 f3:
                    .Ar fichero ) ) ,  fichero)),

     Si '.Ar' se invoca sin argumentos, se asume 'file ...'.  La macro '.Ar'
     es interpretada y es invocable.

   Declaraci'on de configuraci'on (s'olo secci'on cuatro)
     La macro '.Cd' se usa para mostrar la configuracion(8) de una interfaz de
     dispositivo en un manual de la seccion cuatro.  Este macro acepta
     argumentos entre comillas (solo comillas dobles).

           device le0 at scode?  producido por: '.Cd device le0 at scode?'.

   Modificador de orden
     El modificador de orden es identico a la orden '.Fl' (flag) con la
     excepcion de que '.Cm' no impone un guion delante de cada argumento.
     Tradicionalmente, las opciones se han marcado mediante un guion delante,
     aunque algunas ordenes o subconjuntos de ordenes no los usen.  Los
     modificadores de orden tambien se pueden especificar en conjuncion con
     ordenes interactivas tales como ordenes de editor.  Vea Opciones.

   Variables definidas
     Una variable que se define en un fichero include se especifica mediante
     la macro '.Dv'.

           Uso: .Dv variable_definida ...
                   .Dv MAXHOSTNAMELEN
                                   MAXHOSTNAMELEN
                   .Dv TIOCGPGRP )
                                   TIOCGPGRP)

     Es un error llamar a '.Dv' sin argumentos.  '.Dv' es interpretada y es
     invocable.

   C'odigos errno (s'olo secci'on dos)
     La macro '.Er' sirve para especificar los valores de error devueltos por
     las rutinas de biblioteca de la seccion dos. El segundo ejemplo de abajo
     muestra el uso de '.Er' con la macro de dominio de texto general '.Bq',
     tal como se haria en una pagina de la seccion dos.

           Uso: .Er ERRNOTYPE ...
                   .Er ENOENT
                              ENOENT
                   .Er ENOENT ) ;
                              ENOENT);
                   .Bq Er ENOTDIR
                              [ENOTDIR]

     Es un error llamar a '.Er' sin argumentos.  La macro '.Er' es
     interpretada y es invocable.

   Variables de entorno
     La macro '.Ev' especifica una variable de entorno.

           Uso: .Ev argumento ...
                   .Ev DISPLAY
                               DISPLAY
                   .Ev PATH .  PATH.
                   .Ev PRINTER ) ) ,
                               PRINTER)),

     Es un error llamar a '.Ev' sin argumentos.  La macro '.Ev' es
     interpretada y es invocable.

   Argumento de funci'on
     La macro '.Fa' se usa para referirse a argumentos de funcion (parametros)
     fuera de la seccion SINOPSIS del manual o dentro de la seccion SINOPSIS
     cuando la lista de parametros es demasiado larga para la macro '.Fn' y se
     deben usar las macros de cierre '.Fo' y '.Fc'.  '.Fa' tambien se puede
     usar para referirse a miembros de estructura.

           Uso: .Fa argumento_funcion ...
                   .Fa d_namlen ) ) ,
                                   d_namlen)),
                   .Fa iov_len     iov_len

     Es un error llamar a '.Fa' sin argumentos.  '.Fa' es interpretada y es
     invocable.

   Declaraci'on de funciones
     La macro '.Fd' se usa en la seccion SINOPSIS de las funciones de las
     secciones dos y tres.  La macro '.Fd' no invoca a otras macros ni es
     invocable por otras macros.

           Uso: .Fd fichero_include (o variable definida)

     En la seccion SINOPSIS, una invocacion a '.Fd' provoca un salto de linea
     (`line break') si ya se ha presentado una funcion y no se ha producido un
     salto. Esto deja un bonito espacio vertical entre la anterior llamada de
     funcion y la declaracion de la siguiente funcion.

   Opciones (flags)
     La macro '.Fl' maneja las opciones de la linea de ordenes. La macro
     antepone un guion, '-', a la opcion.  Para opciones de ordenes
     interactivas, a las que no se les antepone un guion, la macro '.Cm'
     (modificador de orden) es identica, pero sin el guion.

           Uso: .Fl argumento ...
                   .Fl          -
                   .Fl cfv      -cfv
                   .Fl cfv .    -cfv.
                   .Fl s v t    -s -v -t
                   .Fl - ,      --,
                   .Fl xyz ) ,  -xyz),

     La macro '.Fl' sin argumentos produce un guion que representa a la
     entrada/salida estandar.  Dese cuenta que dar a '.Fl' un unico guion
     producira dos guiones.  La macro '.Fl' es interpretada y es invocable.

   Funciones (rutinas de biblioteca)
     La macro .Fn se inspira en las convenciones del C ANSI.

     Uso: .Fn [tipo] funcion [[tipo] parametros ... ]
     .Fn getchar                              getchar()
     .Fn strlen ) ,                           strlen()),
     .Fn "int align" "const * char *sptrs",   int align(const * char *sptrs),

     Es un error invocar a '.Fn' sin argumentos.  La macro '.Fn' es
     interpretada e invocable.  Dese cuenta que cualquier llamada a otra macro
     supone el final de la llamada a '.Fn' (se cerrara el parentesis en ese
     punto).

     Para las funciones que tienen mas de ocho parametros (y esto es raro), se
     pueden usar las macros '.Fo' (abre funcion) y '.Fc' (cierra funcion)
     junto con '.Fa' (argumento de funcion) para sortear la limitacion. Por
     ejemplo:

           .Fo "int res_mkquery"
           .Fa "int op"
           .Fa "char *dname"
           .Fa "int class"
           .Fa "int type"
           .Fa "char *data"
           .Fa "int datalen"
           .Fa "struct rrec *newrr"
           .Fa "char *buf"
           .Fa "int buflen"
           .Fc

     Produce:

           int    res_mkquery(int op,    char *dname,   int class,   int type,
           char *data, int datalen, struct rrec *newrr, char *buf, int buflen)

     Las macros '.Fo' y '.Fc' son interpretadas e invocables.  En la seccion
     SINOPSIS, la funcion siempre comenzara al principio de linea.  Si se
     presenta mas de una funcion en la seccion SINOPSIS y no se ha
     especificado el tipo de una funcion, se producira un salto de linea
     dejando un bonito espacio vertical entre el nombre de la funcion actual y
     el de la anterior.  Por ahora, '.Fn' no coteja sus limites de palabra con
     las longitudes de linea de troff y puede partir una linea de forma poco
     elegante.  Este problema se solucionara proximamente.

   Tipo de funci'on
     Esta macro va dirigida a la seccion SINOPSIS.  Se puede usar en cualquier
     otro lugar de la pagina de manual sin problemas, pero su principal
     proposito es mostrar el tipo de funcion en la forma normal del nucleo
     para la seccion SINOPSIS de las secciones dos y tres (produce un salto de
     linea permitiendo que el nombre de la funcion aparezca en la siguiente
     linea).

           Uso: .Ft type ...
                   .Ft struct stat  struct stat

     '.Ft' no es invocable por otras macros.

   'Ordenes interactivas
     La macro '.Ic' designa una orden interactiva o interna.

           Uso: .Ic argumento ...
                   .Ic :wq             :wq
                   .Ic do while {...}  do while {...}
                   .Ic setenv , unsetenv
                                       setenv, unsetenv

     Es un error invocar a '.Ic' sin argumentos.  La macro '.Ic' es
     interpretada e invocable.

   Macro de nombre
     La macro '.Nm' (`name macro') se usa para el titulo del documento o el
     nombre del tema. Tiene la peculiaridad de recordar el primer argumento
     con el que fue llamada, que siempre debe ser el nombre del tema de la
     pagina.  Cuando se invoca sin argumentos, '.Nm' repite ese nombre inicial
     con el unico proposito de que el autor tenga que hacer menos trabajo.
     Nota: un nombre de funcion para un documento de la seccion dos o tres se
     trata con '.Nm' en la seccion NOMBRE y con '.Fn' en la seccion SINOPSIS y
     restantes.  Para ordenes interactivas, como la palabra clave 'while' de
     csh(1), se debe usar la macro '.Ic'.  Aunque la macro '.Ic' es casi
     identica a '.Nm', no puede recordar el primer argumento con el que fue
     invocada.

           Uso: .Nm argumento ...
                   .Nm mdoc.sample
                                mdoc.sample
                   .Nm \-mdoc   -mdoc.
                   .Nm foo ) ) ,
                                foo)),
                   .Nm          mdoc.samples

     La macro '.Nm' es interpretada e invocable.

   Opciones
     La macro '.Op' coloca corchetes de opcion alrededor de cualquier
     argumento que quede en la linea de ordenes y coloca cualquier signo de
     puntuacion del final fuera de los corchetes.  Las macros '.Oc' y '.Oo' se
     pueden usar a lo largo de una o mas lineas.

           Uso: .Op opciones ...
           .Op                    []
           .Op Fl k               [-k]
           .Op Fl k ) .           [-k]).
           .Op Fl k Ar kookfile   [-k kookfile]
           .Op Fl k Ar kookfile ,
                                  [-k kookfile],
           .Op Ar objfil Op Ar corfil
                                  [objfil [corfil]]
           .Op Fl c Ar objfil Op Ar corfil ,
                                  [-c objfil [corfil]],
           .Op palabra1 palabra2  [palabra1 palabra2]

     Las macros '.Oc' y '.Oo':

           .Oo
           .Op Fl k Ar kilobytes
           .Op Fl i Ar intervalo
           .Op Fl c Ar total
           .Oc

     producen: [[-k kilobytes] [-i intervalo] [-c total]]

     Las macros '.Op', '.Oc' y '.Oo' son interpretadas e invocables.

   Nombres de rutas (pathnames)
     La macro '.Pa' formatea rutas o nombres de ficheros.

           Uso: .Pa nombreruta
                   .Pa /usr/share   /usr/share
                   .Pa /tmp/fooXXXXX ) .
                                    /tmp/fooXXXXX).

     La macro '.Pa' es interpretada e invocable.

   Variables
     Referencia a variables genericas:

           Usage: .Va variable ...
                   .Va count   count
                   .Va settimer,
                               settimer,
                   .Va int *prt ) :
                               int *prt):
                   .Va char s ] ) ) ,
                               char s])),

     Es un error llamar a '.Va' sin argumentos.  La macro '.Va' es
     interpretada e invocable.

   Referencias cruzadas a p'aginas de manual
     La macro '.Xr' espera que el primer argumento sea un nombre de pagina de
     manual y el segundo argumento, si existe, o un numero de seccion o un
     signo de puntuacion.  Cualquier argumento restante se supone que es un
     signo de puntuacion.

           Uso: .Xr pagina_manual [1,...,8]
                   .Xr mdoc    mdoc
                   .Xr mdoc ,  mdoc,
                   .Xr mdoc 7  mdoc(7)
                   .Xr mdoc 7 ) ) ,
                               mdoc(7))),

     La macro '.Xr' es interpretada e invocable.  Es un error llamar a '.Xr'
     sin argumentos.

DOMINIO DE TEXTO GENERAL

   Macro AT&T
           Uso: .At [v6 | v7 | 32v | V.1 | V.4] ...
                   .At                    AT&T UNIX
                   .At v6 .               Version 6 AT&T UNIX.

     La macro '.At' no es interpretada y no es invocable. Como mucho acepta
     dos argumentos.

   Macro BSD
           Uso: .Bx [Version/lanzamiento] ...
                   .Bx       BSD
                   .Bx 4.3 .
                             4.3BSD.

     La macro '.Bx' es interpretada e invocable.

   Macro FreeBSD
           Uso: .Fx Version.lanzamiento ...
                   .Fx 2.2 .      FreeBSD 2.2.

     La macro '.Fx' no es es interpretada y no es invocable. Como mucho acepta
     dos argumentos.

   Macro UNIX
           Uso: .Ux ...
                   .Ux         UNIX

     La macro '.Ux' es interpretada e invocable.

   Macros de cierre y de entrecomillado
     El concepto de cierre (`enclosure') es similar al de entrecomillado. El
     objeto es el de encerrar una o mas cadenas entre un par de caracteres
     como comillas o parentesis. Los terminos entrecomillado y cierre se usan
     indistintamente a lo largo de este documento. La mayoria de las macros de
     cierre de una linea terminan en una letra minuscula 'q' que alude al
     entrecomillado (`quoting'), aunque hay algunas irregularidades. Para cada
     macro de cierre tambien hay un par de macros de apertura y cierre que
     terminan en las letras minusculas 'o' y 'c' respectivamente. Estas macros
     se pueden usar a traves de una o mas lineas de texto y, aunque tienen
     limitaciones de anidamiento, las macros de entrecomillado de una linea se
     pueden usar dentro de ellas.

            Comilla    Cierre    Apertura   Funci'on                       Resultado
           .Aq        .Ac       .Ao         Cierre entre angulos          <cadena>
           .Bq        .Bc       .Bo         Cierre entre corchetes        [cadena]
           .Dq        .Dc       .Do         Comillas dobles               ``cadena''
                      .Ec       .Eo         Encerrar cadena (entre XX)    XXcadenaXX
           .Pq        .Pc       .Po         Cierre entre parentesis       (cadena)
           .Ql                              Literal entrecomillado        `st' o cadena
           .Qq        .Qc       .Qo         Comillas dobles rectas        "cadena"
           .Sq        .Sc       .So         Comillas simples              `cadena'

     Excepto para las macros irregulares apuntadas mas abajo, todas las macros
     de entrecomillado son interpretadas e invocables. Todas manejan los
     signos de puntuacion adecuadamente siempre que dichos signos aparezcan
     uno a uno y separados por espacios.  Las macros de entrecomillado
     examinan los signos de puntuacion de apertura y cierre para determinar si
     estos aparecen antes o despues de la cadena que se encierra. Esto hace
     posible cierto grado de anidamiento.

     .Ec, .Eo  Estas macros esperan que el primer argumento se corresponda con
               las cadenas de apertura y de cierre, respectivamente.

     .Ql       La macro para literales entrecomillados se comporta de manera
               diferente para troff y nroff.  Si se formatea con nroff, un
               literal entre comillas siempre se pone entre comillas. Si se
               formatea con troff, un elemento solo se entrecomilla si el
               ancho del elemento es menor que el de tres caracteres de ancho
               constante.  Esto se usa para hacer que las cadenas cortas sean
               mas visibles donde el cambio a fuente literal (ancho constante)
               sea menos apreciable.

     .Pf       La macro de prefijo no es invocable, pero es interpretada:

                     .Pf ( Fa nombre2
                              se convierte en (nombre2.

               La macro '.Ns' (no space) realiza la funcion de sufijo analoga.

     Ejemplos de entrecomillado:
           .Aq                   <>
           .Aq Ar ctype.h ) ,    <ctype.h>),
           .Bq                   []
           .Bq Em griego , frances .
                                 [griego, franc'es].
           .Dq                   ``''
           .Dq cadena abc .      ``cadena abc''.
           .Dq '^[A-Z]'          ``'^[A-Z]'''
           .Ql man mdoc          'man mdoc'
           .Qq                   ""
           .Qq cadena ) ,        "cadena"),
           .Qq cadena Ns ),      "cadena),"
           .Sq                   ''
           .Sq cadena            'cadena'

     Para un buen ejemplo de macros de cierre anidadas, vea la macro de opcion
     '.Op'.  Esta se creo a partir de las mismas macros de cierre subyacentes
     que aquellas presentadas en la lista de arriba.  Las macros de listas de
     argumentos extendidas '.Xo' y '.Xc' tambien se construyeron a partir de
     las mismas rutinas subyacentes y son un buen ejemplo del peor uso de
     macros de -mdoc.

   Macro de texto normal o de no operaci'on
     La macro '.No' (`no-op') es un apano para palabras en una linea de
     ordenes de macro que no se deben formatear y sigue la sintaxis
     convencional para las macros de contenido.

   Macro de eliminaci'on de espacios
     La macro '.Ns' elimina los espacios indeseados que hay entre las
     invocaciones de macros. Es util para las listas de argumentos al viejo
     estilo donde no hay espacio entre la opcion y el argumento:

           .Op Fl I Ns Ar directorio
                             produce [-Idirectorio]

     Nota: la macro '.Ns' siempre invoca a la macro '.No' tras eliminar el
     espacio a menos que otro nombre de macro le siga.  La macro '.Ns' es
     interpretada y es invocable.

   Referencias cruzadas a secciones
     La macro '.Sx' designa una referencia a una cabecera de seccion dentro
     del mismo documento.  Es interpretada y es invocable.

                   .Sx FICHEROS     FICHEROS

   Referencias y citas
     La siguientes macros intentan modestamente manejar las referencias
     bibliograficas.  Como minimo, las macros hacen que sea conveniente pasar
     manualmente un subconjunto de referencias al estilo de refer(1).

           .Rs     Inicio de referencia.  Inicia una nueva linea y comienza a
                   recopilar informacion de la referencia hasta que encuentra
                   la macro de fin de referencia.
           .Re     Fin de referencia.  Se imprime la referencias.
           .%A     Autor de lo que se referencia, un nombre por invocacion.
           .%B     Titulo de libro.
           .%C     Ciudad/lugar.
           .%D     Fecha.
           .%J     Nombre de revista.
           .%N     Numero de tema.
           .%O     Informacion opcional.
           .%P     Numero de pagina.
           .%R     Numero de informe.
           .%T     Titulo de articulo.
           .%V     Volumen(es).

     Las macros que comienzan con '%' no son invocables, y son interpretadas
     solo para la <<macro de nombre de marca>> que regresa a su invocador (y
     tampoco de forma muy predecible por el momento).  El proposito es
     permitir que los nombres de marcas se impriman de forma elegante en la
     salida de troff/ditroff.

   Valores devueltos
     La macro '.Rv' genera texto para usar en la seccion VALOR DEVUELTO.

           Uso: .Rv [-std funcion]

     '.Rv -std alsalir' generara el siguiente texto:

     The alsalir() function returns the value 0 if successful; otherwise the
     value -1 is returned and the global variable errno is set to indicate the
     error.

     La opcion -std solo es valida para las secciones 2 y 3 de las paginas de
     manual.

   Nombres de marcas (o acr'onimos y nombres de tipos)
     La macro de nombre de marca generalmente es una macro que produce letras
     en mayusculas de pequeno tamano para todas las palabras en mayusculas de
     mas de dos caracteres.

           Uso: .Tn simbolo ...
                   .Tn DEC
                          DEC
                   .Tn ASCII
                          ASCII

     La macro '.Tn' es interpretada y es invocable por otras macros.

   Argumentos extendidos
     Las macros '.Xo' y '.Xc' permiten extender una lista de argumentos mas
     alla del limite de una macro. Las listas de argumentos no pueden
     extenderse dentro de una macro que espera que todos sus argumentos esten
     en una unica linea, como '.Op'.

     Aqui tiene un ejemplo de '.Xo' que usa la <<macro de modo de espacio>>
     para desactivar el espaciado:

           .Sm off
           .It Xo Sy I Ar operacion
           .No \en Ar contador No \en
           .Xc
           .Sm on

     Produce

           Ioperaci'on\ncuenta\n

     Otro mas:

           .Sm off
           .It Cm S No / Ar anterior_patron Xo
           .No / Ar nuevo_patron
           .No / Op Cm g
           .Xc
           .Sm on

     Produce

           S/anterior_patr'on/nuevo_patr'on/[g]

     Otro ejemplo de '.Xo' usando macros de cierre: comprueba el valor de una
     variable.

           .It Xo
           .Ic .ifndef
           .Oo \&! Oc Ns Ar variable
           .Op Ar operador variable ...
           .Xc

     Produce

           .ifndef [!]variable [operador variable ...]

     Todos los ejemplos anteriores han usado la macro '.Xo' en la lista de
     argumentos de la macro '.It' (lista de items).  Las macros de extension
     no se usan con mucha frecuencia y cuando se usan normalmente es para
     extender la lista de argumentos de la macro '.It'.  Desafortunadamente,
     aqui es tambien donde las macros de extension son mas remilgadas.  En los
     primeros dos ejemplos se desactivo el espaciado; en el tercero, el
     espaciado se deseaba en parte de la salida pero no en toda. Para que
     estas macros funcionen en esta situacion asegurese de que las macros
     '.Xo' y '.Xc' se situan como se muestra en el tercer ejemplo.  Si la
     macro '.Xo' no esta sola en la lista de argumentos de '.It', el espaciado
     sera impredecible.  La macro '.Ns' (no espacio) no debe ser la primera ni
     la ultima macro de una linea en esta situacion.  Solo 15 de las 900
     paginas de manual (que representan unas 1500 paginas reales) que
     acompanan actualmente a BSD usan la macro '.Xo'.

DOMINIO DE ESTRUCTURA DE P'AGINA

   Cabeceras de secci'on
     Las primeras tres macros de cabecera de seccion '.Sh' que se listan a
     continuacion son necesarias en todas las paginas de manual.  El resto de
     cabeceras de seccion son aconsejables a criterio del autor que escribe la
     pagina de manual.  La macro '.Sh' puede tomar hasta nueve argumentos; es
     interpretada pero no es invocable.

     .Sh NOMBRE
               La macro '.Sh NOMBRE' es obligatoria. Si no se especifica, los
               encabezados, pies de pagina y la disposicion de pagina por
               omision no se estableceran y el resultado sera bastante
               desagradable.  La seccion NOMBRE consta de, al menos, tres
               items. El primero es la macro de nombre '.Nm' que pone nombre
               al contenido de la pagina de manual. El segundo es la macro de
               descripcion de nombre '.Nd', que separa el nombre dado al
               contenido del tercer item, que es la descripcion. La
               descripcion deberia ser lo mas breve y clara posible ya que el
               espacio disponible es pequeno.

     .Sh SINOPSIS
               La seccion SINOPSIS describe el uso tipico de la materia de una
               pagina de manual.  Las macros que se necesitan son '.Nm', '.Cd'
               y '.Fn' (y, posiblemente las macros '.Fo', '.Fc', '.Fd' y
               '.Ft').  La macro de nombre de funcion '.Fn' se necesita para
               las secciones 2 y 3 de las paginas de manual. La macro de orden
               y de nombre general '.Nm' se necesita para las secciones 1, 5,
               6, 7 y 8. Los manuales de la seccion 4 requieren '.Nm', '.Fd' o
               una macro '.Cd' de uso de configuracion de un dispositivo.
               Pueden se necesarias otras macros adicionales para producir una
               linea de sinopsis como las mostrada a continuacion:

                     cat [-benstuv] [-] file ...

               Se han usado las siguientes macros:

                     .Nm cat
                     .Op Fl benstuv
                     .Op Fl
                     .Ar

               Nota: Las macros '.Op', '.Fl', y '.Ar' reconocen el caracter de
               tuberia '|', por lo que una linea de ordenes como:

                     .Op Fl a | Fl b

               no se desmadrara.  Troff normalmente interpreta | como un
               operador especial.  Vea CADENAS PREDEFINIDAS para un caracter |
               usable en otras situaciones.

     .Sh DESCRIPCION
               En la mayoria de los casos, el primer texto de una seccion
               DESCRIPCI'ON es un breve parrafo sobre la orden, funcion o
               fichero, seguido por una lista ordenada alfabeticamente de las
               opciones y de sus explicaciones respectivas. Para crear tal
               lista se usan las macros de comienzo de lista '.Bl', elemento
               de lista '.It' y final de lista '.El' (vea Listas y columnas
               mas abajo).

     Los siguientes encabezados de seccion '.Sh' son parte de la estructura
     preferida de la pagina de manual y se deben usar de forma apropiada para
     mantener la consistencia.  Se listan en el orden en que deberian usarse.

     .Sh ENTORNO
               La seccion ENTORNO deberia revelar cualesquiera variables de
               entorno relacionadas y dar pistas sobre su comportamiento y/o
               uso.

     .Sh EJEMPLOS
               Hay varias formas de crear ejemplos. Vea la seccion EJEMPLOS
               que hay mas abajo para mas detalles.

     .Sh FICHEROS
               Los ficheros que son usados o creados por la materia de la
               pagina de manual deberia listarse mediante la macro '.Pa' en la
               seccion FICHEROS.

     .Sh VEASE TAMBIEN
               Las referencias a otras materias sobre el tema de la pagina de
               manual, y las referencias cruzadas a otras paginas de manual
               relevantes, deberian colocarse en la seccion V'EASE TAMBI'EN.
               Las referencias cruzadas se especifican usando la macro '.Xr'.
               Las referencias cruzadas de la seccion V'EASE TAMBI'EN deberian
               ordenarse primero por numero de seccion y, a continuacion,
               coladas en orden alfabetico y separadas por comas. Por ejemplo:

               ls(1), ps(1), group(5), passwd(5).

               Por ahora, las referencias al estilo de refer(1) no se tienen
               en cuenta.

     .Sh CONFORME A
               Si la orden, funcion de biblioteca o fichero sigue una
               implementacion especifica como IEEE Std 1003.2 (``POSIX.2'') o
               ANSI X3.159-1989 (``ANSI C89'') deberia hacerse notar aqui.  Si
               la orden no sigue ningun estandar, su historia deberia constar
               en la seccion HISTORIA.

     .Sh HISTORIA
               Para cualquier orden que no siga ningun estandar especifico, se
               deberia explicar brevemente su historia en esta seccion.

     .Sh AUTORES
               Cualquier reconocimiento o credito deberia colocarse aqui.

     .Sh DIAGNOSTICOS
               Los diagnosticos de una orden deberian ubicarse en esta
               seccion.

     .Sh ERRORES
               El manejo especifico de errores, especialmente de funciones de
               biblioteca (secciones 2 y 3 de las paginas de manual) deberia
               ir aqui.  Para especificar un valor de 'errno' se usa la macro
               '.Er'.

     .Sh FALLOS
               Los problemas ostensibles del tema van aqui...

     Se pueden anadir secciones '.Sh' especificadas por el usuario; por
     ejemplo, esta seccion se creo con:

                   .Sh DOMINIO DE LA ESTRUCTURA DE PAGINA

   P'arrafos y espacios entre l'ineas.
     .Pp     Se puede usar la orden de parrafo '.Pp' para insertar una linea
             en blanco donde sea necesario. La macro no es necesaria tras una
             macro '.Sh' o '.Ss' o antes de una macro '.Bl' (la macro '.Bl'
             inserta un espacio vertical a menos que se use la opcion
             -compact).

   Agrupamientos
     Por ahora, el unico agrupamiento (`keep') que se implementa es para
     palabras. Las macros son '.Bk' (comienza agrupamiento) y '.Ek' (finaliza
     agrupamiento).  La unica opcion que acepta '.Bk' es -words y es util para
     evitar saltos de linea en mitad de las opciones. En el ejemplo para los
     argumentos de la linea de ordenes de make (vea Lo que hay en un nombre),
     el agrupamiento evito que nroff colocara la opcion y el argumento en
     lineas separadas (antes se usaba realmente la macro de opcion para evitar
     esto, pero se abandono cuando se tomo la decision (religiosa) de forzar
     margenes justificados a la derecha en troff, ya que las opciones en
     general se mostraban de forman espantosa cuando se extendian a traves de
     una linea casi vacia. Es necesario trabajar mas las macros de
     agrupamiento y es necesario anadir una opcion -line.)

   Ejemplos y visualizaciones
     Hay cinco tipos de visualizacion (`display'): uno para sangrar una unica
     linea, '.D1', otro para mostrar una unica linea literal, '.Dl', y tres
     mas para bloques (literal, ajustada e irregular) que usan las macros
     '.Bd' (comienza visualizacion) y '.Ed' (finaliza visualizacion).

     .D1    (D-uno) Muestra una linea de texto sangrado. Esta macro es
            interpretada pero no es invocable.

                  -ldghfstru

            Lo anterior se ha obtenido mediante: .Dl -ldghfstru.

     .Dl    (D-ele) Muestra una linea de texto literal sangrado.  La macro de
            ejemplo '.Dl' se ha usado a lo largo de todo este fichero. Permite
            mostrar sangrada una linea de texto. Su fuente por omision es
            (literal) de anchura fija. Es interpretada y reconocera otras
            macros. Sin embargo, no es invocable.

                  % ls -ldg /usr/local/bin

            Lo anterior se ha obtenido con: .Dl % ls -ldg /usr/local/bin.

     .Bd    Comienza visualizacion. La visualizacion de '.Bd' se debe terminar
            con la macro '.Ed'.  Las visualizaciones se pueden anidar dentro
            de otras visualizaciones y listas.  '.Bd' tiene la siguiente
            sintaxis:

                  .Bd tipo-visualizacion [-offset valor_desplazamiento]
                  [-compact]

            El tipo de visualizacion debe ser uno de los cuatro tipos
            siguientes y puede llevar un indicador de desplazamiento para
            sangrado:

            -ragged                Muestra un bloque de texto tal cual se ha
                                   escrito, los bordes del margen derecho (e
                                   izquierdo) se dejan sin ajustar.
            -filled                Muestra un bloque ajustado (formateado). El
                                   bloque de texto se formatea (los bordes se
                                   ajustan - no se dejan sin justificar).
            -literal               Muestra un bloque literal, util para codigo
                                   fuente o texto simple tabulado o
                                   espaciado).
            -file nombre_fichero   Se lee y se muestra el fichero cuyo nombre
                                   sigue a la opcion -file.  Se activa el modo
                                   literal y los tabuladores se fijan en
                                   intervalos de 8 caracteres de ancho
                                   constante, aunque se procesa cualquier
                                   orden troff/-mdoc del fichero.
            -offset cadena         Si se especifica -offset con una de las
                                   siguientes cadenas, la cadena se interpreta
                                   para indicar el nivel de sangrado del
                                   bloque de texto que aparece despues:

                                   left        Ajusta el bloque al margen
                                               izquierdo actual; este es el
                                               modo por omision de '.Bd'.
                                   center      Supuestamente, centra el
                                               bloque. Desafortunadamente, por
                                               ahora el bloque simplemente se
                                               ajusta a la izquierda alrededor
                                               de un imaginario margen
                                               central.
                                   indent      Sangra el texto en una vez el
                                               valor de sangrado por omision o
                                               tabulador.  El valor de
                                               sangrado por omision tambien lo
                                               utiliza la visualizacion '.D1'
                                               por lo que se nos garantiza que
                                               los tipos de visualizacion
                                               quedaran alineados. A este
                                               sangrado se le asigna
                                               normalmente un valor de 6n o
                                               de, aproximadamente, dos
                                               tercios de una pulgada (seis
                                               caracteres de ancho constante).
                                   indent-two  Sangra el texto dos veces el
                                               valor de sangrado por omision.
                                   right       Esto ajusta a la izquierda el
                                               bloque a unas dos pulgadas del
                                               borde derecho de la pagina.
                                               Esta macro necesita trabajarse
                                               mas y puede que tal vez nunca
                                               haga lo correcto en troff.

     .Ed    Finaliza visualicacion.

   Modos de las fuentes
     Hay cinco macros para cambiar la apariencia del texto de una pagina de
     manual:

     .Em    Se puede recalcar o enfatizar el texto con la macro '.Em'.  La
            fuente habitual en este caso es cursiva.

                  Uso: .Em argumento ...
                          .Em no         no
                          .Em excede 1024 .
                                         excede 1024.
                          .Em vide infra ) ) ,
                                         vide infra)),

            La macro '.Em' es interpretada e invocable.  Es un error llamar a
            '.Em' sin argumentos.

     .Li    La macro literal '.Li' se puede usar para caracteres especiales,
            constantes de variables y cualquier cosa que deba mostrarse tal
            cual se escribiria.

                  Uso: .Li argumento ...
                          .Li \en    \n
                          .Li M1 M2 M3 ;
                                     M1 M2 M3;
                          .Li cntrl-D ) ,
                                     cntrl-D),
                          .Li 1024 ...
                                     1024 ...

            La macro '.Li' es interpretada e invocable.

     .Sy    La macro de enfasis simbolica es generalmente una macro para
            negrita, bien en el sentido simbolico, bien en su uso tradicional
            en ingles.

                  Uso: .Sy simbolo ...
                          .Sy Aviso importante
                                             Aviso importante

            La macro '.Sy' es interpretada e invocable.  Los argumentos de
            '.Sy' se pueden entrecomillar.

     .Bf    Comienza el modo de fuente.  El modo de fuente '.Bf' se debe
            finalizar con la macro '.Ef'.  Los modos de fuente se pueden
            anidar dentro de otros modos de fuente.  '.Bf' tiene la siguiente
            sintaxis:

                  .Bf modo-fuente

            El modo de fuente debe ser uno de los siguientes tres tipos:

            Em | -emphasis    El mismo que si la macro '.Em' se usara para
                              todo el bloque de texto.
            Li | -literal     El mismo que si la macro '.Li' se usara para
                              todo el bloque de texto.
            Sy | -symbolic    El mismo que si la macro '.Sy' se usara para
                              todo el bloque de texto.

     .Ef    Finaliza el modo de fuente.

   Listas etiquetadas y columnas
     Hay varios tipos de listas que se pueden iniciar con la macro de comienzo
     de lista '.Bl'.  Los elementos dentro de la lista se especifican con la
     macro de item '.It' y cada lista debe terminar con la macro '.El'.  Las
     listas se pueden anidar dentro de otras listas y dentro de una
     visualizacion. Se pueden usar columnas dentro de listas, pero todavia no
     se han probado las listas dentro de columnas.

     Ademas, se pueden especificar varios atributos de lista como el ancho de
     una etiqueta, el desplazamiento de la lista y el nivel de compactacion de
     la misma (si se permiten o no lineas vacias entre items). La mayor parte
     de este documento se ha formateado con una lista de estilo <<etiqueta>>
     (-tag).  Para ver otros estilos, a continuacion vamos a usar el tipo de
     lista <<sobresaliente>> (over-hanging) (-ohang) para mostrar los tipos de
     lista que hay.  Este tipo de lista es bastante popular entre los usuarios
     de TeX, pero ahora le podria resultar un poco molesto tras haber leido
     muchas paginas de listas <<etiquetadas>>.  Los siguientes tipos de listas
     son aceptados por '.Bl':

     -bullet
     -item
     -enum
     Estos tres son los tipos de lista mas simples. Una vez que se ha
     especificado la macro '.Bl', los elementos de la lista se indican
     simplemente mediante una linea compuesta unicamente por la macro '.It'.
     Por ejemplo, el codigo fuente para una lista simple enumerada se
     pareceria a:

                 .Bl -enum -compact
                 .It
                 El item uno viene aqui.
                 .It
                 Y el item dos aqui.
                 .It
                 El tercer y ultimo item viene aqui.
                 .El

     El resultado:

               1.   El item uno viene aqui.
               2.   Y el item dos aqui.
               3.   El tercer y ultimo item viene aqui.

     Una construccion de lista simple con vinetas (circulos en este caso):

                 .Bl -bullet -compact
                 .It
                 La vineta uno viene aqui.
                 .It
                 La vineta dos aqui.
                 .El

     Produce:
               +o   La vineta uno viene aqui.
               +o   La vineta dos aqui.

     -tag
     -diag
     -hang
     -ohang
     -inset
     Estos tipos de lista recopilan los argumentos especificados con la macro
     '.It' y crean una etiqueta que puede ser insertada (`inset') en el texto
     que le sigue, colgada (`hanged') del texto que le sigue, sobresalir
     (`overhanged') sin sangrado por arriba del texto que le sigue o ser
     etiquetada (`tag').  Esta lista se ha construido con el tipo de lista
     '-ohang'.  La macro '.It' es interpretada solo para los tipos de lista
     inset, hang y tag y no es invocable.  Aqui tiene un ejemplo de etiquetas
     insertadas (`inset'):

           Tag La lista etiquetada (tambien llamada <<parrafo etiquetado>>) es
           el tipo de lista mas comunmente usado en los manuales de Berkeley.

           Diag Las listas diag crean listas de diagnostico para la seccion
           cuatro y son similares a las listas inset salvo que ignoran las
           macros invocables.

           Hang Las etiquetas colgadas son cuestion de gusto.

           Ohang Las etiquetas que sobresalen son bonitas cuando el espacio
           esta limitado.

           Inset Las etiquetas insertadas son utiles para los bloques de
           control de parrafos y son valiosas para convertir manuales -mdoc a
           otros formatos.

     Aqui tiene el texto fuente que produce el ejemplo anterior:

           .Bl -inset -offset indent
           .It Em Tag
           La lista etiquetada (tambien llamada <<parrafo etiquetado>>)
           es el tipo de lista mas comunmente usado en los manuales
           de Berkeley.
           .It Em Diag
           Las listas
           .Em diag
           crean listas de diagnostico para la seccion cuatro y son
           similares a las listas
           .Em inset
           salvo que ignoran las macros invocables.
           .It Em Hang
           Las etiquetas colgadas son cuestion de gusto.
           .It Em Ohang
           Las etiquetas que sobresalen son bonitas cuando el espacio
           esta limitado.
           .It Em Inset
           Las etiquetas insertadas son utiles para los bloques de
           control de parrafos y son valiosas para convertir manuales
           .Nm -mdoc
           a otros formatos.
           .El

     Aqui tiene una lista colgada con dos elementos:

           Las     etiquetas colgadas se parecen a las listas etiquetadas
                   cuando la etiqueta es mas pequena que el ancho de etiqueta.

           Las grandes etiquetas de listas colgadas se mezclan con el parrafo
                   a diferencia de las etiquetas de parrafos etiquetados.

     Y el texto sin formatear que lo creo:

           .Bl -hang -offset indent
           .It Em Las
           etiquetas colgadas se parecen a las listas etiquetadas
           cuando la etiqueta es mas pequena que el ancho de
           etiqueta.
           .It Em Las grandes etiquetas de listas colgadas
           se mezclan con el parrafo a diferencia de las etiquetas
           de parrafos etiquetados.
           .El

     La lista etiquetada que viene a continuacion usa un indicador de anchura
     opcional para controlar el ancho de la etiqueta.

           SL      tiempo de espera del proceso (segundos bloqueado)
           PAGEIN  numero de operaciones de E/S de disco producidas por
                   referencias que el proceso ha hecho a paginas no cargadas
                   en memoria.
           UID     identificador de usuario numerico del propietario del
                   proceso
           PPID    identificador numerico del padre del proceso
           PRI     prioridad del proceso (valor no positivo cuando el proceso
                   se encuentra en una espera ininterrumpible)

     Y el texto sin formatear:

           .Bl -tag -width "PAGEIN" -compact -offset indent
           .It SL
           tiempo de espera del proceso (segundos bloqueado)
           .It PAGEIN
           numero de operaciones de
           .Tn E/S
           de disco producidas por referencias que el proceso
           ha hecho a paginas no cargadas en memoria.
           .It UID
           identificador de usuario numerico del propietario
           del proceso
           .It PPID
           identificador numerico del padre del proceso
           . It PRI
           prioridad del proceso (valor no positivo cuando el
           proceso se encuentra en una espera ininterrumpible)
           .El

     Indicadores de anchura aceptables:

           -width Fl     establece la anchura al ancho por omision de una
                         opcion (`flag').  Todas las macros invocables tienen
                         un valor de anchura por omision.  Actualmente, el
                         valor de '.Fl' es diez caracteres de ancho constante
                         o, aproximadamente, cinco sextos de una pulgada.

           -width 24n    establece el ancho a 24 caracteres de ancho constante
                         o, aproximadamente, dos pulgadas.  La letra 'n' es
                         absolutamente necesaria para que el escalado funcione
                         correctamente.

           -width ENAMETOOLONG
                         establece el ancho a la longitud de anchura constante
                         de la cadena dada.

           -width "int mkfifo"
                         de nuevo, establece el ancho a la anchura constante
                         de la cadena dada.

     Si no se especifica un ancho para el tipo de lista <<etiqueta>>, la
     primera vez que se invoque a '.It' se intentara determinar una anchura
     apropiada.  Si el primer argumento de '.It' es una macro invocable, se
     usara el ancho por omision de la macro como si el nombre de la macro se
     hubiera dado como ancho.  Sin embargo, si en otro elemento de la lista
     aparece un nombre de macro invocable diferente, se supone el comienzo de
     una nueva lista anidada.

CADENAS PREDEFINIDAS

     Las siguientes cadenas estan predefinidas y se pueden usar siempre que se
     precedan con la secuencia de interpretacion de cadenas de troff '\*(xx',
     donde xx es el nombre de la cadena definida, o '\*x', donde x es el
     nombre de la cadena.  La secuencia de interpretacion se puede usar en
     cualquier parte del texto.

           Cadena     Nroff     Troff
           <=         <=        <=
           >=         >=        >=
           Rq         ''        ''
           Lq         ``        ``
           ua         ^         ^
           aa         '         '
           ga         `         `
           q          "         "
           Pi         pi        pi
           Ne         !=        !=
           Le         <=        <=
           Ge         >=        >=
           Lt         <         >
           Gt         >         <
           Pm         +-        +-
           If         infinity  infinity
           Na         NaN       NaN
           Ba         |         |

     Nota: La cadena con nombre 'q' se debe escribir como '\*q' ya que solo es
     un caracter.

DIAGN'OSTICOS

     Las herramientas de depuracion de -mdoc son limitadas, pero pueden ayudar
     a detectar errores sutiles como la colision de un nombre de argumento con
     un registro interno o nombre de macro. (cUn que?). Un registro es una
     clase de almacenamiento aritmetico de troff con un nombre de uno o dos
     caracteres.  Todos los registros internos de -mdoc para troff y ditroff
     son de dos caracteres y de la forma <mayuscula><minuscula> como 'Ar',
     <minuscula><mayuscula> como 'aR' o <letra mayuscula o minuscula><digito>
     como 'C1'.  Y para liar mas las cosas, troff tiene sus propios registros
     internos que son o bien dos caracteres en minusculas o bien un punto mas
     una letra o un metacaracter.  En uno de los ejemplos de la introduccion
     se mostro como evitar la interpretacion de un nombre de macro con una
     secuencia de escape '\&'.  Esta tambien es suficiente para los nombres de
     los registros internos.

     Si un nombre de registro no protegido con una secuencia de escape aparece
     en la lista de argumentos de una invocacion, se producira un
     comportamiento impredecible. En general, siempre que no aparezcan en la
     salida grandes porciones de texto cuando deberian o desaparezcan pequenas
     cadenas como las etiquetas de las listas, existe el riesgo de que haya un
     malentendido sobre un tipo de argumento en la lista de argumentos.  Su
     madre nunca quiso que recordara esta cosa diabolica, por lo que aqui
     tiene una forma de descubrir si sus argumentos son validos o no: la macro
     de depuracion '.Db' (debug) muestra la interpretacion de la lista de
     argumentos para la mayoria de las macros. Las macros como la macro '.Pp'
     (parrafo) no contiene informacion de depuracion. Todas las macros
     invocables la tienen y se recomienda encarecidamente que siempre que haya
     duda se active la macro '.Db'.

           Uso: .Db [on | off]

     Un ejemplo de un trozo de texto con la macro de depuracion situada encima
     y debajo de un problema creado artificialmente (un argumento de opcion
     'aC' que deberia ser '\&aC' para funcionar):

           .Db on
           .Op Fl aC Ar file )
           .Db off

     La salida resultante:

           DEBUGGING ON
           DEBUG(argv) MACRO: `.Op'  Line #: 2
                   Argc: 1  Argv: `Fl'  Length: 2
                   Space: `'  Class: Executable
                   Argc: 2  Argv: `aC'  Length: 2
                   Space: `'  Class: Executable
                   Argc: 3  Argv: `Ar'  Length: 2
                   Space: `'  Class: Executable
                   Argc: 4  Argv: `file'  Length: 4
                   Space: ` '  Class: String
                   Argc: 5  Argv: `)'  Length: 1
                   Space: ` '  Class: Closing Punctuation or suffix
                   MACRO REQUEST: .Op Fl aC Ar file )
           DEBUGGING OFF

     La primera linea indica el nombre de la macro invocadora, que aqui es
     '.Op', y el numero de linea donde aparece.  Si hay uno o mas ficheros
     involucrados (especialmente cuando se incluye texto de otro fichero) el
     numero de linea puede ser falso. Si solo hay un fichero, debe ser
     correcto.  La segunda linea da el numero de argumento, el argumento
     ('Fl') y su longitud.  Si la longitud de un argumento es de dos
     caracteres, se comprueba el argumento para ver si es ejecutable
     (desafortunadamente, cualquier registro que contiene un valor distinto de
     cero parece ejecutable).  La tercera linea muestra el espacio asignado a
     una clase y el tipo de la clase.  El problema aqui es que el argumento aC
     no deberia ser ejecutable. Los cuatro tipos de clases son: cadena
     (`string'), ejecutable (`executable'), puntuacion de cierre (`closing
     punctuation') y puntuacion de apertura (`opening punctuation'). La ultima
     linea muestra toda la lista de argumentos tal como fue leida. En el
     siguiente ejemplo, la cadena incorrecta 'aC' se protege con una secuencia
     de escape:

           .Db on
           .Em An escaped \&aC
           .Db off

           DEBUGGING ON
           DEBUG(fargv) MACRO: `.Em'  Line #: 2
                   Argc: 1  Argv: `An'  Length: 2
                   Space: ` '  Class: String
                   Argc: 2  Argv: `escaped'  Length: 7
                   Space: ` '  Class: String
                   Argc: 3  Argv: `aC'  Length: 2
                   Space: ` '  Class: String
                   MACRO REQUEST: .Em An escaped &aC
           DEBUGGING OFF

     El argumento '\&aC' aparece con la misma longitud de 2 aun cuando la
     secuencia '\&' produce un ancho de cero, aunque no se encontro un
     registro de nombre '\&aC' y el tipo se clasifico como cadena (string).

     Otros diagnosticos consisten en instrucciones de uso y son
     autoexplicativos.

GROFF, TROFF y NROFF

     El paquete -mdoc no necesita modo de compatibilidad con groff.

     El paquete inhibe los saltos de pagina, y las cabeceras y pies de pagina
     que se producen normalmente en dichos saltos con nroff, para hacer mas
     eficiente la visualicion en linea del manual.  Por ahora, groff con
     -Tascii expulsa el resto imaginario de una pagina cuando se llega al
     final del fichero.  La inhibicion de los saltos de pagina hace que los
     ficheros de nroff no sean adecuados para obtener una copia impresa.
     Existe un registro de nombre 'cR' que se puede establecer a cero en el
     fichero de estilo de la instalacion local /usr/src/share/tmac/doc-nroff
     para restaurar el comportamiento anterior.

FICHEROS

     /usr/share/tmac/tmac.doc      paquete de macros de manual
     /usr/share/misc/mdoc.template
                                   plantilla para escribir una pagina de
                                   manual
     /usr/share/examples/mdoc/*    varias paginas de manual de ejemplo

V'EASE TAMBI'EN

     man(1), troff(1), mdoc(7)

FALLOS

     Todavia no se han resuelto la insercion indeseada de guiones en los
     guiones de un argumento de opcion, lo que produce contratiempos
     ocasionales (saltos de linea en los guiones) en la seccion DESCRIPCI'ON.

     Las cadenas predefinidas no aparecen en la documentacion.

     No se ha anadido la seccion 3f a las rutinas de cabecera.

     Se deberia cambiar la fuente de '.Nm' en la seccion NOMBRE.

     Es necesario anadir una comprobacion a '.Fn' para evitar separaciones si
     la longitud de la linea es demasiado corta. Ocasionalmente separa el
     ultimo parentesis y algunas veces produce un resultado absurdo cuando una
     linea se encuentra en modo de relleno.

     El metodo usado cuando se usa nroff para evitar los saltos de pagina de
     cabeceras y pies de pagina (distintos a la cabecera y al pie de pagina
     iniciales) inserta ocasionalmente una linea parcialmente rellena (vacia)
     en lo que seria el final de la pagina.

     Las macros de lista y visualizacion no hacen ningun tipo de agrupamiento
     y desde luego deberian ser capaces de ello.