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

NOMBRE

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

SINOPSIS

     man mdoc.samples

DESCRIPCIÓN

     Éste es un tutorial para escribir páginas 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 diseño de las páginas dejando la manipulación de las fuentes y
     otros detalles de composición al autor.  En -mdoc, las macros para el diseño de las páginas
     de manual constituyen el dominio de estructura de página que consta de macros para títulos,
     encabezados de sección, visualizaciones y listas; esencialmente, elementos que afectan a la
     posición física del texto en la página formateada.  Además del dominio de estructura de
     página, hay dos dominios más: 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 día a día para describir órdenes, rutinas y ficheros
     BSD relacionados.  Las macros en el dominio de manual manejan nombres de órdenes, argumentos
     y opciones de la línea de órdenes, nombres de función, parámetros de función, nombres de
     ruta, variables, referencias cruzadas a otras páginas de manual, etc.  Estos elementos del
     dominio tienen valor tanto para el autor como para el futuro usuario de la página de manual.
     Es de esperar que la consistencia ganada a través del conjunto de manuales proporcione una
     traducción más fácil a futuras herramientas de documentarión.

     En el conjunto de páginas de manual de UNIX se hace referencia a una entrada de manual
     simplemente como «página 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 línea (aviso).
                      Protección de caracteres especiales.

           2.   ANATOMÍA DE UNA PÁGINA DE MANUAL
                      Modelo de una página de manual.

           3.   MACROS DE TÍTULO.

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

           5.   DOMINIO DE MANUAL
                      Macro de dirección.
                      Nombre del autor.
                      Macro de argumento.
                      Declaración de configuración (sólo sección cuatro).
                      Modificador de orden.
                      Variables definidas.
                      Códigos errno (sólo sección dos).
                      Variables de entorno.
                      Argumento de función.
                      Declaración de funciones.
                      Opciones (flags).
                      Funciones (rutinas de biblioteca).
                      Tipo de función.
                      Órdenes interactivas.
                      Macro de nombre.
                      Opciones.
                      Nombres de rutas.
                      Variables.
                      Referencias cruzadas a páginas de manual.

           6.   DOMINIO DE TEXTO GENERAL
                      Macro AT&T.
                      Macro BSD.
                      Macro FreeBSD.
                      Macro UNIX.
                      Macros de cierre/entrecomillado
                                  Entrecomillado/cierre mediante ángulos.
                                  Entrecomillado/cierre mediante corchetes.
                                  Entrecomillado/cierre mediante comillas dobles.
                                  Entrecomillado/cierre mediante paréntesis.
                                  Entrecomillado/cierre mediante comillas simples.
                                  Macro de prefijo.
                      Macro de texto normal o de no operación.
                      Macro de eliminación de espacios.
                      Referencias cruzadas a secciones.
                      Referencias y citas.
                      Valores devueltos (sólo secciones dos y tres)
                      Nombres de marcas (o acrónimos y nombres de tipos).
                      Argumentos extendidos.

           7.   DOMINIO DE ESTRUCTURA DE PÁGINA
                      Cabecera de sección.
                      Párrafos y espacios entre líneas.
                      Agrupamientos.
                      Ejemplos y visualizaciones (displays).
                      Modos de las fuentes (énfasis, literal y simbólico).
                      Listas etiquetadas y columnas.

           8.   CADENAS PREDEFINIDAS

           9.   DIAGNÓSTICOS

           10.  GROFF, TROFF Y NROFF

           11.  FICHEROS

           12.  FALLOS

IDIOSINCRASIAS DE TROFF

     El paquete -mdoc intenta simplificar el proceso de escribir una página de manual.
     Teóricamente, uno no tiene por qué aprender los detalles más engorrosos de troff(1) para
     usar -mdoc; sin embargo, hay unas pocas limitaciones que son inevitables y es mejor
     quitárselas de en medio. Y, también, esté prevenido, este paquete no es rápido.

   Uso de macros
     Al igual que en troff(1), una macro se invoca colocando un ‘.’ (carácter punto) al principio
     de una línea seguido por el nombre de dos caracteres de la macro. Los argumentos pueden ir a
     continuación de la macro separados por espacios. El carácter punto al principio de la línea
     es el que hace que troff(1) interprete los dos siguientes caracteres como el nombre de una
     macro.  Para colocar un ‘.’ (carácter punto) al principio de una línea en algún contexto
     distinto al de una invocación 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 mayoría de las macros de -mdoc aceptan nueve argumentos y, en casos
     limitados, los argumentos pueden continuar o extenderse por la siguiente línea (vea
     Extensiones).  Unas pocas macros manejan argumentos entrecomillados (vea Paso de espacios en
     blanco en un argumento más abajo).

     La mayoría 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 ejecutará o invocará 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 opción ‘.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

     Aquí las cadenas ‘Fl’ y ‘Ar’ no se interpretan como macros.  A lo largo de este documento y
     en el manual de referencia rápida mdoc(7) que le acompaña, 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 técnica 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 término
     «interpretado».

   Paso de espacios en blanco en un argumento
     Algunas veces se desea pasar como argumento una cadena de caracteres que contiene uno o más
     espacios en blanco. Esto puede ser necesario para vencer el límite de nueve argumentos o
     para especificar argumentos para macros que esperan una disposición particular de los
     elementos de una lista de argumentos.  Por ejemplo, la macro de función ‘.Fn’ espera que el
     primer argumento sea el nombre de una función y que cualesquiera argumentos restantes sean
     parámetros de función.  Siguiendo la forma en la que ANSI C establece la declaración de los
     parámetros de función en la lista de parámetros que se especifica entre paréntesis, se
     garantiza que cada parámetro 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ón: desafortunadamente, la forma más conveniente de pasar espacios entre
     comillas, reasignando los argumentos individuales antes de realizar la interpretación de la
     línea, 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 más la necesitan:

           Cd    Declaración de configuración (sección 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 simbólico.
           %B    Titulos de libro.
           %J    Nombres de revista.
           %O    Notas opcionales para una referencia.
           %R    Título de informe (en una referencia).
           %T    Título de artículo en un libro o revista.

     Una forma de pasar una cadena que contiene espacios en blanco es usar el espacio «sólido» o
     «de longitud fija» ‘\ ’, es decir, un espacio en blanco precedido por un carácter de escape
     ‘\’.  Este método se puede usar con cualquier macro pero tiene el efecto secundario de
     interferir con el ajuste del texto a lo largo de una línea.  Troff ve el espacio en blanco
     sólido como si fuera cualquier otro carácter imprimible y no puede dividir la cadena de
     caracteres en trozos separados por blancos o caracteres de nueva línea como sería de
     esperar. Este método es útil para cadenas que no se espera que se solapen con el final de
     una línea.  Por ejemplo:

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

           fetch(char *str)  también se puede crear mediante ‘.Fn fetch "char *str"’

     Si se omiten los caracteres ‘\’ o las comillas, ‘.Fn’ vería tres argumentos y el resultado
     sería

           fetch(char, *str)

     Para ver un ejemplo de lo que ocurre cuando la lista de parámetros se solapa con el final de
     línea, vea la sección FALLOS.

   Espacios en blanco al final de una línea (aviso)
     Los espacios en blanco al final de una línea 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-línea>.  Si se plantea la necesidad de insertar un
     carácter en blanco al final de una línea, se puede hacer con un espacio de longitud fija y
     el carácter de escape ‘\&’.  Por ejemplo, ‘cadena\ \&’.

   Protección de caracteres especiales
     Los caracteres especiales como el carácter de nueva línea ‘\n’, se tratan reemplazando ‘\’
     con ‘\e’ (por ejemplo, ‘\en’) para conservar la barra invertida (\).

ANATOMÍA DE UNA PÁGINA DE MANUAL

     El cuerpo de una página de manual se puede construir fácilmente a partir de una plantilla
     básica que se puede encontrar en el fichero /usr/share/misc/mdoc.template.  También se
     pueden encontrar varias páginas de manual de ejemplo en /usr/share/examples/mdoc.

   Modelo de una página de manual
           .\" Las siguientes invocaciones son necesarias para todas las páginas
           .\" de manual.
           .Dd Mes día, año
           .Os SISTEMA_OPERATIVO [versión/lanzamiento]
           .Dt TÍTULO_DOCUMENTO [sección número] [volumen]
           .Sh NOMBRE
           .Nm nombre
           .Nd descripción de una línea del nombre
           .Sh SINOPSIS
           .Sh DESCRIPCIÓN
           .\" Las siguientes invocaciones se deberían «descomentar» y usar
           .\" donde fuera apropiado.
           .\" La siguiente invocación sólo es para los valores devueltos
           .\" por las funciones de las secciones 2 y 3.
           .\" .Sh VALORES DEVUELTOS
           .\" La siguiente invocación es sólo para las secciones 1, 6, 7 y 8.
           .\" .Sh ENTORNO
           .\" .Sh FICHEROS
           .\" .Sh EJEMPLOS
           .\" La siguiente invocación es sólo para las secciones 1, 6, 7 y 8.
           .\"    (valores devueltos por una orden (al shell) y
           .\"       diagnósticos de los tipos de fprintf/stderr)
           .\" .Sh DIAGNÓSTICOS
           .\" La siguiente invocación es sólo para el manejo de errores y
           .\" señales de las secciones 2 y 3.
           .\" .Sh ERRORES
           .\" .Sh VÉASE TAMBIÉN
           .\" .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 página de manual o tema se ha
     desarrollado o modificado y el título de la página de manual (en mayúsculas) junto con la
     sección del manual a la que pertenece la página.  Estas macros idenfican a la página y se
     discuten más abajo en MACROS DE TÍTULO.

     El resto de elementos de la plantilla son cabeceras de sección (.Sh); de las que NOMBRE,
     SINOPSIS y DESCRIPCIÓN son obligatorias.  Las cabeceras se discuten en DOMINIO DE ESTRUCTURA
     DE PÁGINA, tras la presentación del DOMINIO DE MANUAL.  Para mostrar el uso de las macros de
     diseño de página, se usan varias macros de contenido; se recomienda informarse sobre las
     macros de contenido antes de hacerlo sobre las macros de diseño de página.

MACROS DE TÍTULO

     Las macros de título son la primera parte del dominio de la estructura de página, pero las
     presentamos en primer lugar y de forma separada para aquellos que deseen empezar a escribir
     una página de manual ya. Tres macros de cabecera indican el título del documento o de la
     página de manual, el sistema operativo y la fecha de la autoría.  Estas macros se invocan
     sólo una vez justo al principio del documento y sólo se usan para construir los encabezados
     y los pies de página.

     .Dt TÍTULO_DOCUMENTO nº_sección [volumen]
             El título del documento es el tema de la página de manual y debe estar en MAYÚSCULAS
             debido a limitaciones de troff.  El número de sección puede ser 1, ..., 8 y, si se
             especifica, se puede omitir el título del volumen. Un título 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 omisión es URM para las secciones 1, 6 y 7; SMM para la
             sección 8; PRM para las secciones 2, 3, 4 y 5.

     .Os sistema_operativo versión
             El nombre del sistema operativo debería ser un acrónimo común, por ejemplo, BSD o
             FreeBSD o ATT.  La versión (`release') debería ser la nomenclatura estándar de
             versión 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
             página. Por ejemplo, un pie de página típico podría ser:

                   .Os BSD 4.3

             o
                   .Os FreeBSD 2.2

             o, para algo producido localmente,

                   .Os CS Department

             El valor por omisión de Berkeley, ‘.Os’ sin argumentos, se ha definido como BSD en
             el fichero /usr/share/tmac/mdoc/doc-common.  Por omisión, su valor verdadero debería
             ser LOCAL.  Dese cuenta que si la macro ‘.Os’ no aparece, la esquina inferior
             izquierda de la página tendrá un aspecto horrible.

     .Dd mes día, año
             Formalmente, la fecha se debería escribir como:

                   25 enero 1989

INTRODUCCIÓN 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 órdenes, subrutinas y ficheros relacionados.  Para describir los tres
     aspectos diferentes de la escritura de una página de manual se usan ligeras variaciones de
     este lenguaje. En primer lugar encontramos la descripción del uso de las invocaciones de
     macros -mdoc.  En segundo lugar aparece la descripción de una orden UNIX con macros -mdoc.
     Y, en tercer lugar, tenemos la descripción verbal de una orden para el usuario; es decir, la
     discusión de una orden en el texto de una página 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 invocación y cualquier cosa que le siga es un argumento a
     procesar.  En el segundo caso, la descripción de una orden UNIX usando las macros de
     contenido es un poco más enrevesada; una línea típica de la orden SINOPSIS podría aparecer
     como:

           filter [-flag] infile outfile

     Aquí, 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 términos 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 discusión de órdenes y de la sintaxis de órdenes incluye los dos
     ejemplos anteriores, pero puede añadir más detalle.  A los argumentos infile y outfile del
     ejemplo anterior se les podría referenciar como operandos o argumentos de fichero.  Algunas
     listas de argumentos de las líneas de órdenes son bastante largas:

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

     Aquí podríamos hablar de la orden make y calificar a makefile como argumento de la opción
     -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ón.  En su lugar, se usa la macro de argumento ‘Ar’ para operandos o
     argumentos de fichero como objetivo, además de para un argumento de opción como variable.
     La línea 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’ sólo 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 puntuación, siempre que cada carácter de puntuación
     vaya precedido por un espacio.  Si tenemos la invocación:

           .Li sptr, ptr),

     El resultado será:

           sptr, ptr),

     El carácter de puntuación no se reconoce y todo se muestra utilizando la fuente `literal'.
     Si el carácter de puntuación se separa precediéndolo por un espacio en blanco:

           .Li sptr , ptr ) ,

     El resultado será:

           sptr, ptr),

     Ahora el carácter de puntuación se reconoce y se muestra utilizando la fuente por omisión,
     distinguiéndolo así de las cadenas en fuente literal.

     Para eliminar el significado especial de un carácter de puntuación protéjalo con ‘\&’.
     Troff está limitado como lenguaje de macros y tiene dificultades cuando se le pasa una
     cadena que contiene un miembro del conjunto matemático, lógico o de entrecomillado:

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

     El problema es que troff puede pensar que realmente se debe realizar la operación o
     evaluación sugerida por uno de estos caracteres.  Para evitar la evaluación accidental de
     estos caracteres, protéjalos con ‘\&’.  La sintaxis típica se muestra en la primera macro de
     contenido, ‘.Ad’, que aparece más abajo,

DOMINIO DE MANUAL

   Macro de dirección
     La macro de dirección identifica una estructura de dirección de la forma dir1[,dir2[,dir3]].

           Uso: .Ad dirección ...
                   .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 está
     documentando, o el nombre del autor de la página de manual real.  Cualquier argumento
     restante tras el nombre se supone que es un carácter de puntuación.

           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 línea de órdenes.

           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ón de configuración (sólo sección cuatro)
     La macro ‘.Cd’ se usa para mostrar la configuración(8) de una interfaz de dispositivo en un
     manual de la sección cuatro.  Este macro acepta argumentos entre comillas (sólo comillas
     dobles).

           device le0 at scode?  producido por: ‘.Cd device le0 at scode?’.

   Modificador de orden
     El modificador de orden es idéntico a la orden ‘.Fl’ (flag) con la excepción de que ‘.Cm’ no
     impone un guión delante de cada argumento.  Tradicionalmente, las opciones se han marcado
     mediante un guión delante, aunque algunas órdenes o subconjuntos de órdenes no los usen.
     Los modificadores de órden también se pueden especificar en conjunción con órdenes
     interactivas tales como órdenes 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ódigos errno (sólo sección dos)
     La macro ‘.Er’ sirve para especificar los valores de error devueltos por las rutinas de
     biblioteca de la sección dos. El segundo ejemplo de abajo muestra el uso de ‘.Er’ con la
     macro de dominio de texto general ‘.Bq’, tal como se haría en una página de la sección 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ón
     La macro ‘.Fa’ se usa para referirse a argumentos de función (parámetros) fuera de la
     sección SINOPSIS del manual o dentro de la sección SINOPSIS cuando la lista de parámetros es
     demasiado larga para la macro ‘.Fn’ y se deben usar las macros de cierre ‘.Fo’ y ‘.Fc’.
     ‘.Fa’ también se puede usar para referirse a miembros de estructura.

           Uso: .Fa argumento_función ...
                   .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ón de funciones
     La macro ‘.Fd’ se usa en la sección 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 sección SINOPSIS, una invocación a ‘.Fd’ provoca un salto de línea (`line break') si
     ya se ha presentado una función y no se ha producido un salto. Esto deja un bonito espacio
     vertical entre la anterior llamada de función y la declaración de la siguiente función.

   Opciones (flags)
     La macro ‘.Fl’ maneja las opciones de la línea de órdenes. La macro antepone un guíon, ‘-’,
     a la opción.  Para opciones de órdenes interactivas, a las que no se les antepone un guión,
     la macro ‘.Cm’ (modificador de orden) es idéntica, pero sin el guión.

           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 guión que representa a la entrada/salida estándar.
     Dese cuenta que dar a ‘.Fl’ un único guión producirá 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] función [[tipo] parámetros ... ]
     .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
     cerrará el paréntesis en ese punto).

     Para las funciones que tienen más de ocho parámetros (y esto es raro), se pueden usar las
     macros ‘.Fo’ (abre función) y ‘.Fc’ (cierra función) junto con ‘.Fa’ (argumento de función)
     para sortear la limitación. 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 sección SINOPSIS, la función
     siempre comenzará al principio de línea.  Si se presenta más de una función en la sección
     SINOPSIS y no se ha especificado el tipo de una función, se producirá un salto de línea
     dejando un bonito espacio vertical entre el nombre de la función actual y el de la anterior.
     Por ahora, ‘.Fn’ no coteja sus límites de palabra con las longitudes de línea de troff y
     puede partir una línea de forma poco elegante.  Este problema se solucionará próximamente.

   Tipo de función
     Esta macro va dirigida a la sección SINOPSIS.  Se puede usar en cualquier otro lugar de la
     página de manual sin problemas, pero su principal propósito es mostrar el tipo de función en
     la forma normal del núcleo para la sección SINOPSIS de las secciones dos y tres (produce un
     salto de línea permitiendo que el nombre de la función aparezca en la siguiente línea).

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

     ‘.Ft’ no es invocable por otras macros.

   Órdenes 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 título 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 página.  Cuando se invoca sin argumentos, ‘.Nm’ repite ese
     nombre inicial con el único propósito de que el autor tenga que hacer menos trabajo.  Nota:
     un nombre de función para un documento de la sección dos o tres se trata con ‘.Nm’ en la
     sección NOMBRE y con ‘.Fn’ en la sección SINOPSIS y restantes.  Para órdenes interactivas,
     como la palabra clave ‘while’ de csh(1), se debe usar la macro ‘.Ic’.  Aunque la macro ‘.Ic’
     es casi idéntica 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 opción alrededor de cualquier argumento que quede en la
     línea de órdenes y coloca cualquier signo de puntuación del final fuera de los corchetes.
     Las macros ‘.Oc’ y ‘.Oo’ se pueden usar a lo largo de una o más líneas.

           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 genéricas:

           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áginas de manual
     La macro ‘.Xr’ espera que el primer argumento sea un nombre de página de manual y el segundo
     argumento, si existe, o un número de sección o un signo de puntuación.  Cualquier argumento
     restante se supone que es un signo de puntuación.

           Uso: .Xr página_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 [Versión/lanzamiento] ...
                   .Bx       BSD
                   .Bx 4.3 .
                             4.3BSD.

     La macro ‘.Bx’ es interpretada e invocable.

   Macro FreeBSD
           Uso: .Fx Versión.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 más cadenas entre un par de caracteres como comillas o paréntesis. Los
     términos entrecomillado y cierre se usan indistintamente a lo largo de este documento. La
     mayoría de las macros de cierre de una línea terminan en una letra minúscula ‘q’ que alude
     al entrecomillado (`quoting'), aunque hay algunas irregularidades. Para cada macro de cierre
     también hay un par de macros de apertura y cierre que terminan en las letras minúsculas ‘o’
     y ‘c’ respectivamente. Estas macros se pueden usar a través de una o más líneas de texto y,
     aunque tienen limitaciones de anidamiento, las macros de entrecomillado de una línea se
     pueden usar dentro de ellas.

            Comilla    Cierre    Apertura   Función                       Resultado
           .Aq        .Ac       .Ao         Cierre entre ángulos          <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 paréntesis       (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 más abajo, todas las macros de entrecomillado
     son interpretadas e invocables. Todas manejan los signos de puntuación adecuadamente siempre
     que dichos signos aparezcan uno a uno y separados por espacios.  Las macros de
     entrecomillado examinan los signos de puntuación de apertura y cierre para determinar si
     éstos aparecen antes o después 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 sólo 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 más 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 función de sufijo análoga.

     Ejemplos de entrecomillado:
           .Aq                   ⟨⟩
           .Aq Ar ctype.h ) ,    ⟨ctype.h⟩),
           .Bq                   []
           .Bq Em griego , francés .
                                 [griego, francés].
           .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 opción ‘.Op’.  Ésta se
     creó 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’ también 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ón
     La macro ‘.No’ (`no-op') es un apaño para palabras en una línea de órdenes de macro que no
     se deben formatear y sigue la sintaxis convencional para las macros de contenido.

   Macro de eliminación de espacios
     La macro ‘.Ns’ elimina los espacios indeseados que hay entre las invocaciones de macros. Es
     útil para las listas de argumentos al viejo estilo donde no hay espacio entre la opción 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 sección dentro del mismo documento.
     Es interpretada y es invocable.

                   .Sx FICHEROS     FICHEROS

   Referencias y citas
     La siguientes macros intentan modestamente manejar las referencias bibliográficas.  Como
     mínimo, las macros hacen que sea conveniente pasar manualmente un subconjunto de referencias
     al estilo de refer(1).

           .Rs     Inicio de referencia.  Inicia una nueva línea y comienza a recopilar
                   información 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 invocación.
           .%B     Título de libro.
           .%C     Ciudad/lugar.
           .%D     Fecha.
           .%J     Nombre de revista.
           .%N     Número de tema.
           .%O     Información opcional.
           .%P     Número de página.
           .%R     Número de informe.
           .%T     Título de artículo.
           .%V     Volumen(es).

     Las macros que comienzan con ‘%’ no son invocables, y son interpretadas sólo para la «macro
     de nombre de marca» que regresa a su invocador (y tampoco de forma muy predecible por el
     momento).  El propósito 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 sección VALOR DEVUELTO.

           Uso: .Rv [-std función]

     ‘.Rv -std alsalir’ generará 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 opción -std sólo es válida para las secciones 2 y 3 de las páginas de manual.

   Nombres de marcas (o acrónimos y nombres de tipos)
     La macro de nombre de marca generalmente es una macro que produce letras en mayúsculas de
     pequeño tamaño para todas las palabras en mayúsculas de más de dos caracteres.

           Uso: .Tn símbolo ...
                   .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 más allá del límite de
     una macro. Las listas de argumentos no pueden extenderse dentro de una macro que espera que
     todos sus argumentos estén en una única línea, como ‘.Op’.

     Aquí tiene un ejemplo de ‘.Xo’ que usa la «macro de modo de espacio» para desactivar el
     espaciado:

           .Sm off
           .It Xo Sy I Ar operación
           .No \en Ar contador No \en
           .Xc
           .Sm on

     Produce

           Ioperación\ncuenta\n

     Otro más:

           .Sm off
           .It Cm S No / Ar anterior_patrón Xo
           .No / Ar nuevo_patrón
           .No / Op Cm g
           .Xc
           .Sm on

     Produce

           S/anterior_patrón/nuevo_patrón/[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 ítems).  Las macros de extensión no se usan con mucha frecuencia y cuando se
     usan normalmente es para extender la lista de argumentos de la macro ‘.It’.
     Desafortunadamente, aquí es también donde las macros de extensión son más 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 situación
     asegúrese de que las macros ‘.Xo’ y ‘.Xc’ se sitúan como se muestra en el tercer ejemplo.
     Si la macro ‘.Xo’ no está sola en la lista de argumentos de ‘.It’, el espaciado será
     impredecible.  La macro ‘.Ns’ (no espacio) no debe ser la primera ni la última macro de una
     línea en esta situación.  Sólo 15 de las 900 páginas de manual (que representan unas 1500
     páginas reales) que acompañan actualmente a BSD usan la macro ‘.Xo’.

DOMINIO DE ESTRUCTURA DE PÁGINA

   Cabeceras de sección
     Las primeras tres macros de cabecera de sección ‘.Sh’ que se listan a continuación son
     necesarias en todas las páginas de manual.  El resto de cabeceras de sección son
     aconsejables a criterio del autor que escribe la página 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 página y la disposición de página por omisión no se establecerán y el resultado
               será bastante desagradable.  La sección NOMBRE consta de, al menos, tres ítems. El
               primero es la macro de nombre ‘.Nm’ que pone nombre al contenido de la página de
               manual. El segundo es la macro de descripción de nombre ‘.Nd’, que separa el
               nombre dado al contenido del tercer ítem, que es la descripción. La descripción
               debería ser lo más breve y clara posible ya que el espacio disponible es pequeño.

     .Sh SINOPSIS
               La sección SINOPSIS describe el uso típico de la materia de una página 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 función ‘.Fn’ se necesita
               para las secciones 2 y 3 de las páginas 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
               sección 4 requieren ‘.Nm’, ‘.Fd’ o una macro ‘.Cd’ de uso de configuración de un
               dispositivo.  Pueden se necesarias otras macros adicionales para producir una
               línea de sinopsis como las mostrada a continuación:

                     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 carácter de tubería ‘|’, por
               lo que una línea de órdenes como:

                     .Op Fl a | Fl b

               no se desmadrará.  Troff normalmente interpreta | como un operador especial.  Vea
               CADENAS PREDEFINIDAS para un carácter | usable en otras situaciones.

     .Sh DESCRIPCIÓN
               En la mayoría de los casos, el primer texto de una sección DESCRIPCIÓN es un breve
               párrafo sobre la orden, función o fichero, seguido por una lista ordenada
               alfabéticamente 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 más abajo).

     Los siguientes encabezados de sección ‘.Sh’ son parte de la estructura preferida de la
     página de manual y se deben usar de forma apropiada para mantener la consistencia.  Se
     listan en el orden en que deberían usarse.

     .Sh ENTORNO
               La sección ENTORNO debería 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 sección EJEMPLOS que hay más abajo
               para más detalles.

     .Sh FICHEROS
               Los ficheros que son usados o creados por la materia de la página de manual
               debería listarse mediante la macro ‘.Pa’ en la sección FICHEROS.

     .Sh VÉASE TAMBIÉN
               Las referencias a otras materias sobre el tema de la página de manual, y las
               referencias cruzadas a otras páginas de manual relevantes, deberían colocarse en
               la sección VÉASE TAMBIÉN.  Las referencias cruzadas se especifican usando la macro
               ‘.Xr’.  Las referencias cruzadas de la sección VÉASE TAMBIÉN deberían ordenarse
               primero por número de sección y, a continuación, coladas en orden alfabético 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, función de biblioteca o fichero sigue una implementación específica
               como IEEE Std 1003.2 (“POSIX.2”) o ANSI X3.159-1989 (“ANSI C89”) debería hacerse
               notar aquí.  Si la orden no sigue ningún estándar, su historia debería constar en
               la sección HISTORIA.

     .Sh HISTORIA
               Para cualquier orden que no siga ningún estándar específico, se debería explicar
               brevemente su historia en esta sección.

     .Sh AUTORES
               Cualquier reconocimiento o crédito debería colocarse aquí.

     .Sh DIAGNÓSTICOS
               Los diagnósticos de una orden deberían ubicarse en esta sección.

     .Sh ERRORES
               El manejo específico de errores, especialmente de funciones de biblioteca
               (secciones 2 y 3 de las páginas de manual) debería ir aquí.  Para especificar un
               valor de ‘errno’ se usa la macro ‘.Er’.

     .Sh FALLOS
               Los problemas ostensibles del tema van aquí...

     Se pueden añadir secciones ‘.Sh’ especificadas por el usuario; por ejemplo, esta sección se
     creó con:

                   .Sh DOMINIO DE LA ESTRUCTURA DE PÁGINA

   Párrafos y espacios entre líneas.
     .Pp     Se puede usar la orden de párrafo ‘.Pp’ para insertar una línea 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 opción
             -compact).

   Agrupamientos
     Por ahora, el único agrupamiento (`keep') que se implementa es para palabras. Las macros son
     ‘.Bk’ (comienza agrupamiento) y ‘.Ek’ (finaliza agrupamiento).  La única opción que acepta
     ‘.Bk’ es -words y es útil para evitar saltos de línea en mitad de las opciones. En el
     ejemplo para los argumentos de la línea de órdenes de make (vea Lo que hay en un nombre), el
     agrupamiento evitó que nroff colocara la opción y el argumento en líneas separadas (antes se
     usaba realmente la macro de opción para evitar esto, pero se abandonó cuando se tomó la
     decisión (religiosa) de forzar márgenes justificados a la derecha en troff, ya que las
     opciones en general se mostraban de forman espantosa cuando se extendían a través de una
     línea casi vacía. Es necesario trabajar más las macros de agrupamiento y es necesario añadir
     una opción -line.)

   Ejemplos y visualizaciones
     Hay cinco tipos de visualización (`display'): uno para sangrar una única línea, ‘.D1’, otro
     para mostrar una única línea literal, ‘.Dl’, y tres más para bloques (literal, ajustada e
     irregular) que usan las macros ‘.Bd’ (comienza visualización) y ‘.Ed’ (finaliza
     visualización).

     .D1    (D-uno) Muestra una línea 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 línea de texto literal sangrado.  La macro de ejemplo ‘.Dl’ se ha
            usado a lo largo de todo este fichero. Permite mostrar sangrada una línea de texto.
            Su fuente por omisión es (literal) de anchura fija. Es interpretada y reconocerá
            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 visualización. La visualización 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-visualización [-offset valor_desplazamiento] [-compact]

            El tipo de visualización 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, útil para código fuente o texto
                                   simple tabulado o espaciado).
            -file nombre_fichero   Se lee y se muestra el fichero cuyo nombre sigue a la opción
                                   -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 después:

                                   left        Ajusta el bloque al margen izquierdo actual; éste
                                               es el modo por omisión 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 omisión o tabulador.  El valor de sangrado por
                                               omisión también lo utiliza la visualización ‘.D1’
                                               por lo que se nos garantiza que los tipos de
                                               visualización quedarán 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
                                               omisión.
                                   right       Esto ajusta a la izquierda el bloque a unas dos
                                               pulgadas del borde derecho de la página.  Esta
                                               macro necesita trabajarse más y puede que tal vez
                                               nunca haga lo correcto en troff.

     .Ed    Finaliza visualicación.

   Modos de las fuentes
     Hay cinco macros para cambiar la apariencia del texto de una página 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 escribiría.

                  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 énfasis simbólica es generalmente una macro para negrita, bien en el
            sentido simbólico, bien en su uso tradicional en inglés.

                  Uso: .Sy símbolo ...
                          .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 visualización. Se pueden usar columnas dentro de listas, pero todavía no se han probado
     las listas dentro de columnas.

     Además, se pueden especificar varios atributos de lista como el ancho de una etiqueta, el
     desplazamiento de la lista y el nivel de compactación de la misma (si se permiten o no
     líneas vacías entre ítems). La mayor parte de este documento se ha formateado con una lista
     de estilo «etiqueta» (-tag).  Para ver otros estilos, a continuación 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 podría resultar
     un poco molesto tras haber leído muchas páginas de listas «etiquetadas».  Los siguientes
     tipos de listas son aceptados por ‘.Bl’:

     -bullet
     -item
     -enum
     Estos tres son los tipos de lista más simples. Una vez que se ha especificado la macro
     ‘.Bl’, los elementos de la lista se indican simplemente mediante una línea compuesta
     únicamente por la macro ‘.It’.  Por ejemplo, el código fuente para una lista simple
     enumerada se parecería a:

                 .Bl -enum -compact
                 .It
                 El ítem uno viene aquí.
                 .It
                 Y el ítem dos aquí.
                 .It
                 El tercer y último ítem viene aquí.
                 .El

     El resultado:

               1.   El ítem uno viene aquí.
               2.   Y el ítem dos aquí.
               3.   El tercer y último ítem viene aquí.

     Una construcción de lista simple con viñetas (círculos en este caso):

                 .Bl -bullet -compact
                 .It
                 La viñeta uno viene aquí.
                 .It
                 La viñeta dos aquí.
                 .El

     Produce:
               ·   La viñeta uno viene aquí.
               ·   La viñeta dos aquí.

     -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 sólo para los tipos de lista inset, hang y tag y no es
     invocable.  Aquí tiene un ejemplo de etiquetas insertadas (`inset'):

           Tag La lista etiquetada (también llamada «párrafo etiquetado») es el tipo de lista más
           comúnmente usado en los manuales de Berkeley.

           Diag Las listas diag crean listas de diagnóstico para la sección cuatro y son
           similares a las listas inset salvo que ignoran las macros invocables.

           Hang Las etiquetas colgadas son cuestión de gusto.

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

           Inset Las etiquetas insertadas son útiles para los bloques de control de párrafos y
           son valiosas para convertir manuales -mdoc a otros formatos.

     Aquí tiene el texto fuente que produce el ejemplo anterior:

           .Bl -inset -offset indent
           .It Em Tag
           La lista etiquetada (también llamada «párrafo etiquetado»)
           es el tipo de lista más comúnmente usado en los manuales
           de Berkeley.
           .It Em Diag
           Las listas
           .Em diag
           crean listas de diagnóstico para la sección cuatro y son
           similares a las listas
           .Em inset
           salvo que ignoran las macros invocables.
           .It Em Hang
           Las etiquetas colgadas son cuestión de gusto.
           .It Em Ohang
           Las etiquetas que sobresalen son bonitas cuando el espacio
           está limitado.
           .It Em Inset
           Las etiquetas insertadas son útiles para los bloques de
           control de párrafos y son valiosas para convertir manuales
           .Nm -mdoc
           a otros formatos.
           .El

     Aquí tiene una lista colgada con dos elementos:

           Las     etiquetas colgadas se parecen a las listas etiquetadas cuando la etiqueta es
                   más pequeña que el ancho de etiqueta.

           Las grandes etiquetas de listas colgadas se mezclan con el párrafo a diferencia de las
                   etiquetas de párrafos etiquetados.

     Y el texto sin formatear que lo creó:

           .Bl -hang -offset indent
           .It Em Las
           etiquetas colgadas se parecen a las listas etiquetadas
           cuando la etiqueta es más pequeña que el ancho de
           etiqueta.
           .It Em Las grandes etiquetas de listas colgadas
           se mezclan con el párrafo a diferencia de las etiquetas
           de párrafos etiquetados.
           .El

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

           SL      tiempo de espera del proceso (segundos bloqueado)
           PAGEIN  número de operaciones de E/S de disco producidas por referencias que el
                   proceso ha hecho a páginas no cargadas en memoria.
           UID     identificador de usuario númerico del propietario del proceso
           PPID    identificador numérico 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
           número de operaciones de
           .Tn E/S
           de disco producidas por referencias que el proceso
           ha hecho a páginas no cargadas en memoria.
           .It UID
           identificador de usuario númerico del propietario
           del proceso
           .It PPID
           identificador numérico 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 omisión de una opción (`flag').  Todas
                         las macros invocables tienen un valor de anchura por omisión.
                         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 intentará determinar una anchura apropiada.  Si el primer argumento de ‘.It’ es
     una macro invocable, se usará el ancho por omisión 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 están predefinidas y se pueden usar siempre que se precedan con la
     secuencia de interpretación 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 interpretación se
     puede usar en cualquier parte del texto.

           Cadena     Nroff     Troff
           <=         <=        ≤
           >=         >=        ≥
           Rq         ''        ”
           Lq         ``        “
           ua         ^         ↑
           aa         '         ´
           ga         `         `
           q          "         "
           Pi         pi        π
           Ne         !=        ≠
           Le         <=        ≤
           Ge         >=        ≥
           Lt         <         >
           Gt         >         <
           Pm         +-        ±
           If         infinity  ∞
           Na         NaN       NaN
           Ba         |         |

     Nota: La cadena con nombre ‘q’ se debe escribir como ‘\*q’ ya que sólo es un carácter.

DIAGNÓSTICOS

     Las herramientas de depuración de -mdoc son limitadas, pero pueden ayudar a detectar errores
     sutiles como la colisión de un nombre de argumento con un registro interno o nombre de
     macro. (¿Un qué?). Un registro es una clase de almacenamiento aritmético 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 <mayúscula><minúscula> como ‘Ar’, <minúscula><mayúscula>
     como ‘aR’ o <letra mayúscula o minúscula><dígito> como ‘C1’.  Y para liar más las cosas,
     troff tiene sus propios registros internos que son o bien dos caracteres en minúsculas o
     bien un punto más una letra o un metacarácter.  En uno de los ejemplos de la introducción se
     mostró cómo evitar la interpretación de un nombre de macro con una secuencia de escape ‘\&’.
     Ésta también 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 invocación, se producirá un comportamiento impredecible. En general,
     siempre que no aparezcan en la salida grandes porciones de texto cuando deberían o
     desaparezcan pequeñas 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 diabólica, por lo que aquí tiene una forma de descubrir si sus
     argumentos son válidos o no: la macro de depuración ‘.Db’ (debug) muestra la interpretación
     de la lista de argumentos para la mayoría de las macros. Las macros como la macro ‘.Pp’
     (párrafo) no contiene información de depuración. 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 depuración situada encima y debajo de un
     problema creado artificialmente (un argumento de opción ‘aC’ que debería 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 línea indica el nombre de la macro invocadora, que aquí es ‘.Op’, y el número de
     línea donde aparece.  Si hay uno o más ficheros involucrados (especialmente cuando se
     incluye texto de otro fichero) el número de línea puede ser falso. Si sólo hay un fichero,
     debe ser correcto.  La segunda línea da el número 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 línea muestra el espacio asignado a una
     clase y el tipo de la clase.  El problema aquí es que el argumento aC no debería ser
     ejecutable. Los cuatro tipos de clases son: cadena (`string'), ejecutable (`executable'),
     puntuación de cierre (`closing punctuation') y puntuación de apertura (`opening
     punctuation'). La última línea muestra toda la lista de argumentos tal como fue leída. 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 encontró un registro de nombre ‘\&aC’ y el tipo se clasificó
     como cadena (string).

     Otros diagnósticos 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 página, y las cabeceras y pies de página que se producen
     normalmente en dichos saltos con nroff, para hacer más eficiente la visualición en línea del
     manual.  Por ahora, groff con -Tascii expulsa el resto imaginario de una página cuando se
     llega al final del fichero.  La inhibición de los saltos de página 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 instalación 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 página de manual
     /usr/share/examples/mdoc/*    varias páginas de manual de ejemplo

VÉASE TAMBIÉN

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

FALLOS

     Todavía no se han resuelto la inserción indeseada de guiones en los guiones de un argumento
     de opción, lo que produce contratiempos ocasionales (saltos de línea en los guiones) en la
     sección DESCRIPCIÓN.

     Las cadenas predefinidas no aparecen en la documentación.

     No se ha añadido la sección 3f a las rutinas de cabecera.

     Se debería cambiar la fuente de ‘.Nm’ en la sección NOMBRE.

     Es necesario añadir una comprobación a ‘.Fn’ para evitar separaciones si la longitud de la
     línea es demasiado corta. Ocasionalmente separa el último paréntesis y algunas veces produce
     un resultado absurdo cuando una línea se encuentra en modo de relleno.

     El método usado cuando se usa nroff para evitar los saltos de página de cabeceras y pies de
     página (distintos a la cabecera y al pie de página iniciales) inserta ocasionalmente una
     línea parcialmente rellena (vacía) en lo que sería el final de la página.

     Las macros de lista y visualización no hacen ningún tipo de agrupamiento y desde luego
     deberían ser capaces de ello.