.\" Copyright (c) 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)mdoc.samples.7	8.2 (Berkeley) 12/30/93
.\"	$Id: mdoc.samples.7,v 1.3 2005/05/24 18:00:32 pepin.jimenez Exp $
.\"
.\" This tutorial sampler invokes every macro in the package several
.\" times and is guaranteed to give a worst case performance
.\" for an already extremely slow package.
.\"
.\" Traducido por Juan Piernas <piernas en ditec.um.es> el 31-marzo-2005
.\"
.Dd Diciembre 30, 1993
.Os
.Dt MDOC.SAMPLES 7
.Sh NOMBRE
.Nm mdoc.samples
.Nd tutorial para escribir
manuales
.Bx
con
.Nm \-mdoc
.Sh SINOPSIS
.Nm man mdoc.samples
.Sh DESCRIPCIÓN
Éste es un tutorial para escribir
páginas de manual
.Bx
con el paquete de macros
.Nm \-mdoc ,
un paquete de formateo basado en
.Em contenidos
y
.Em dominios
para
.Xr troff 1 .
Su predecesor, el paquete
.Xr \-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
.Nm \-mdoc ,
las macros para el diseño de las páginas de manual constituyen el
.Em "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
.Bx
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.
.Pp
En el conjunto de páginas de manual de
.Ux
se hace referencia a una entrada de manual simplemente como «página
man», sin tener en cuenta la longitud real y sin intenciones sexistas.
.Sh 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:
.Bl -enum -offset indent
.It
.Tn "IDIOSINCRASIAS DE TROFF"
.Bl -tag -width flag -compact -offset indent
.It "Uso de macros" .
.It "Paso de espacios en blanco en un argumento" .
.It "Espacios en blanco al final de una línea (aviso)" .
.It "Protección de caracteres especiales" .
.El
.It
.Tn "ANATOMÍA DE UNA PÁGINA DE MANUAL"
.Bl -tag -width flag -compact -offset indent
.It "Modelo de una página de manual" .
.El
.It
.Tn "MACROS DE TÍTULO" .
.It
.Tn "INTRODUCCIÓN A LOS DOMINIOS DE MANUAL Y DE TEXTO GENERAL" .
.Bl -tag -width flag -compact -offset indent
.It "Lo que hay en un nombre..." .
.It "Sintaxis general" .
.El
.It
.Tn "DOMINIO DE MANUAL"
.Bl -tag -width flag -compact -offset indent
.It "Macro de dirección" .
.It "Nombre del autor" .
.It "Macro de argumento" .
.It "Declaración de configuración (sólo sección cuatro)" .
.It "Modificador de orden" .
.It "Variables definidas" .
.It "Códigos errno (sólo sección dos)" .
.It "Variables de entorno" .
.It "Argumento de función" .
.It "Declaración de funciones" .
.It "Opciones (flags)" .
.It "Funciones (rutinas de biblioteca)" .
.It "Tipo de función" .
.\" .It "Header File (including source code)" .
.It "Órdenes interactivas" .
.It "Macro de nombre" .
.It "Opciones" .
.It "Nombres de rutas" .
.It "Variables" .
.It "Referencias cruzadas a páginas de manual" .
.El
.It
.Tn "DOMINIO DE TEXTO GENERAL"
.Bl -tag -width flag -compact -offset indent
.It "Macro AT&T" .
.It "Macro BSD" .
.It "Macro FreeBSD" .
.It "Macro UNIX" .
.It "Macros de cierre/entrecomillado"
.Bl -tag -width flag -compact -offset indent
.It "Entrecomillado/cierre mediante ángulos" .
.It "Entrecomillado/cierre mediante corchetes" .
.It "Entrecomillado/cierre mediante comillas dobles" .
.It "Entrecomillado/cierre mediante paréntesis" .
.It "Entrecomillado/cierre mediante comillas simples" .
.It "Macro de prefijo" .
.El
.It "Macro de texto normal o de no operación" .
.It "Macro de eliminación de espacios" .
.It "Referencias cruzadas a secciones" .
.It "Referencias y citas" .
.It "Valores devueltos (sólo secciones dos y tres)"
.It "Nombres de marcas (o acrónimos y nombres de tipos)" .
.It "Argumentos extendidos" .
.El
.It
.Tn "DOMINIO DE ESTRUCTURA DE PÁGINA"
.Bl -tag -width flag -compact -offset indent
.It "Cabecera de sección" .
.It "Párrafos y espacios entre líneas" .
.It "Agrupamientos" .
.It "Ejemplos y visualizaciones (displays)" .
.It "Modos de las fuentes (énfasis, literal y simbólico)" .
.It "Listas etiquetadas y columnas" .
.El
.It
.Tn "CADENAS PREDEFINIDAS"
.It
.Tn "DIAGNÓSTICOS"
.It
.Tn "GROFF, TROFF Y NROFF"
.It
.Tn "FICHEROS"
.It
.Tn "FALLOS"
.El
.ne 7
.Sh IDIOSINCRASIAS DE TROFF
El paquete
.Nm \-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
.Xr troff 1
para usar
.Nm \-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
.Em no es
rápido.
.Ss Uso de macros
Al igual que en
.Xr troff 1 ,
una macro se invoca colocando un
.Ql \&\.
(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
.Xr troff 1
interprete los dos siguientes caracteres como el nombre de una macro.
Para colocar un
.Ql \&\.
(carácter punto)
al principio de una línea en algún contexto distinto al de una
invocación de macro, preceda el
.Ql \&\.
(punto) con una secuencia
.Ql \e&
de escape.
.Ql \e&
se traduce literalmente en un espacio de ancho cero y nunca se muestra
en la salida.
.Pp
En general, las macros
.Xr troff 1
aceptan hasta nueve argumentos, ignorando cualquier argumento extra.
La mayoría de las macros de
.Nm \-mdoc
aceptan nueve argumentos y, en casos limitados, los argumentos pueden
continuar o extenderse por la siguiente línea (vea
.Sx Extensiones ) .
Unas pocas macros manejan argumentos entrecomillados (vea
.Sx Paso de espacios en blanco en un argumento
más abajo).
.Pp
La mayoría de las macros de dominio de texto general y de manual de
.Nm \-mdoc
son especiales en el sentido de que sus listas de argumentos se
.Em analizan
o
.Em 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
.Ql \&\.
(punto).
Esta es la forma en la que muchas macros se anidan; por ejemplo, la
macro de opción
.Ql \&.Op ,
puede
.Em invocar
las macros de banderas y argumentos
.Ql \&Fl
y
.Ql \&Ar ,
para especificar una bandera opcional con un argumento:
.Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent
.It Op Fl s Ar bytes
se obtiene mediante
.Li \&.Op \&Fl s \&Ar bytes
.El
.Pp
Para evitar que una cadena de dos caracteres se interprete como un
nombre de macro, preceda la cadena con la secuencia de escape
.Ql \e& :
.Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent
.It Op \&Fl s \&Ar bytes
se obtiene mediante
.Li \&.Op \e&Fl s \e&Ar bytes
.El
.Pp
Aquí las cadenas
.Ql \&Fl
y
.Ql \&Ar
no se interpretan como macros.
A lo largo de este documento y en el manual de referencia rápida
.Xr mdoc 7
que le acompaña, las macros cuyas listas de argumentos se analizan en
busca de argumentos invocables se referencian como
.Em interpretadas
y las macros que se pueden invocar desde una lista de argumentos se
referencian como
.Em invocables .
Esto es una
.Em metedura de pata
técnica ya que casi todas las macros de
.Nm \-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».
.Ss 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
.Ql \&.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
.Tn "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,
.Fa int foo .
.Pp
Hay dos formas posibles de pasar un argumento que contiene un espacio.
.Em 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
.Xr troff
de
.Tn AT&T .
No es costosa para
.Xr groff
pero, por el bien de la transportabilidad, ha sido limitada a las
siguientes macros que más la necesitan:
.Pp
.Bl -tag -width 4n -offset indent -compact
.It Li \&Cd
Declaración de configuración (sección 4
.Sx SINOPSIS ) .
.It Li \&Bl
Comienzo de lista (para el indicador del ancho).
.It Li \&Em
Texto emfatizado.
.It Li \&Fn
Funciones (secciones dos y cuatro).
.It Li \&It
Elementos de una lista.
.It Li \&Li
Texto literal.
.It Li \&Sy
Texto simbólico.
.It Li \&%B
Titulos de libro.
.It Li \&%J
Nombres de revista.
.It Li \&%O
Notas opcionales para una referencia.
.It Li \&%R
Título de informe (en una referencia).
.It Li \&%T
Título de artículo en un libro o revista.
.El
.Pp
Una forma de pasar una cadena que contiene espacios en blanco es usar
el espacio «sólido» o «de longitud fija»
.Ql \e\  ,
es decir, un espacio en blanco precedido por un carácter de escape
.Ql \e .
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.
.Xr 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:
.Bl -tag -width "fetch(char *str)" -offset indent
.It Fn fetch char\ *str
se crea mediante
.Ql \&.Fn fetch char\e *str
.It Fn fetch "char *str"
también se puede crear mediante
.Ql \&.Fn fetch "\\*qchar *str\\*q"
.El
.Pp
Si se omiten los caracteres
.Ql \e
o las comillas,
.Ql \&.Fn
vería tres argumentos y el resultado sería
.Pp
.Dl Fn fetch char *str
.Pp
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
.Sx FALLOS .
.Ss Espacios en blanco al final de una línea (aviso)
Los espacios en blanco al final de una línea pueden confudir a
.Xr 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
.Ql \e& .
Por ejemplo,
.Ql cadena\e\ \e& .
.Ss Protección de caracteres especiales
Los caracteres especiales como el carácter de nueva línea
.Ql \en ,
se tratan reemplazando
.Ql \e
con
.Ql \ee
(por ejemplo,
.Ql \een )
para conservar la barra invertida (\\).
.Sh 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
.Pa /usr/share/misc/mdoc.template .
También se pueden encontrar varias páginas de manual de ejemplo en
.Pa /usr/share/examples/mdoc .
.Pp
.Ss Modelo de una página de manual
.Bd -literal -offset indent
\&.\e" Las siguientes invocaciones son necesarias para todas las páginas
\&.\e" 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
\&.\e" Las siguientes invocaciones se deberían «descomentar» y usar
\&.\e" donde fuera apropiado.
\&.\e" La siguiente invocación sólo es para los valores devueltos
\&.\e" por las funciones de las secciones 2 y 3.
\&.\e" .Sh VALORES DEVUELTOS
\&.\e" La siguiente invocación es sólo para las secciones 1, 6, 7 y 8.
\&.\e" .Sh ENTORNO
\&.\e" .Sh FICHEROS
\&.\e" .Sh EJEMPLOS
\&.\e" La siguiente invocación es sólo para las secciones 1, 6, 7 y 8.
\&.\e"    (valores devueltos por una orden (al shell) y
\&.\e"	  diagnósticos de los tipos de fprintf/stderr)
\&.\e" .Sh DIAGNÓSTICOS
\&.\e" La siguiente invocación es sólo para el manejo de errores y
\&.\e" señales de las secciones 2 y 3.
\&.\e" .Sh ERRORES
\&.\e" .Sh VÉASE TAMBIÉN
\&.\e" .Sh CONFORME A
\&.\e" .Sh HISTORIA
\&.\e" .Sh AUTORES
\&.\e" .Sh FALLOS
.Ed
.Pp
Los primeros elementos de la plantilla son las macros
.Pq Li \&.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
.Pq Em 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
.Sx MACROS DE TÍTULO .
.Pp
El resto de elementos de la plantilla son cabeceras de sección
.Pq Li \&.Sh ;
de las que
.Sx NOMBRE ,
.Sx SINOPSIS
y
.Sx DESCRIPCIÓN
son obligatorias.
Las cabeceras se discuten en
.Sx DOMINIO DE ESTRUCTURA DE PÁGINA ,
tras la presentación del
.Sx 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. 
.Sh 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.
.Bl -tag -width 6n
.It Li \&.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
.Tn 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:
.\" .Cl
.\" USD	UNIX User's Supplementary Documents
.\" .Cl
.\" PS1	UNIX Programmer's Supplementary Documents
.Pp
.Bl -column SMM -offset indent -compact
.It Li AMD	Documentos del Manual Ancestral de UNIX
.It Li SMM	Manual del Administrador de Sistemas de UNIX
.It Li URM	Manual de Referencia de UNIX
.It Li PRM	Manual del Programador de UNIX
.El
.Pp
La etiqueta de volumen por omisión es
.Li URM
para las secciones 1, 6 y 7;
.Li SMM
para la sección 8;
.Li PRM
para las secciones 2, 3, 4 y 5.
.\" .Cl
.\" MMI	UNIX Manual Master Index
.\" .Cl
.\" CON	UNIX Contributed Software Manual
.\" .Cl
.\" LOC	UNIX Local Manual
.It Li \&.Os sistema_operativo versión
El nombre del sistema operativo debería ser un acrónimo común, por
ejemplo,
.Tn BSD
o
.Tn FreeBSD
o
.Tn 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:
.Pp
.Dl \&.Os BSD 4.3
.Pp
o
.Dl \&.Os FreeBSD 2.2
.Pp
o, para algo producido localmente,
.Pp
.Dl \&.Os CS Department
.Pp
El valor por omisión de Berkeley,
.Ql \&.Os
sin argumentos, se ha definido como
.Tn BSD
en el fichero
.Pa /usr/share/tmac/mdoc/doc-common .
Por omisión, su valor verdadero debería ser
.Tn LOCAL .
Dese cuenta que si la macro
.Ql \&.Os
no aparece, la esquina inferior izquierda de la página tendrá un
aspecto horrible.
.It Li \&.Dd mes día, año
Formalmente, la fecha se debería escribir como:
.Pp
.ne 5
.Dl 25 enero 1989
.El
.Sh INTRODUCCIÓN A LOS DOMINIOS DE MANUAL Y DE TEXTO GENERAL
.Ss 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
.Nm \-mdoc .
En segundo lugar aparece la descripción de una orden
.Ux
.Em con macros
.Nm \-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.
.Pp
En el primer caso, las macros de
.Xr troff 1
son ellas mismas un tipo de orden; la sintaxis general para una orden
troff es:
.Bd -filled -offset indent
\&.Va argument1 argument2 ... argument9
.Ed
.Pp
.Ql \&.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
.Ux
usando las macros de contenido es un poco más enrevesada;
una línea típica de la orden
.Sx SINOPSIS
podría aparecer como:
.Bd -filled -offset indent
.Nm filter
.Op Fl flag
.Ar infile outfile
.Ed
.Pp
Aquí,
.Nm filter
es el nombre de la orden y la cadena entre corchetes
.Fl flag
es un
.Em argumento de opciones ,
lo que se indica mediante los corchetes.
En términos de
.Nm \-mdoc ,
.Ar infile
y
.Ar outfile
se llaman
.Em argumentos .
Las macros que dieron forma al ejemplo anterior son:
.Bd -literal -offset indent
\&.Nm filter
\&.Op \&Fl flag
\&.Ar infile outfile
.Ed
.Pp
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
.Ar infile
y
.Ar outfile
del ejemplo anterior se les podría referenciar como
.Em operandos
o
.Em argumentos de fichero .
Algunas listas de argumentos de las líneas de órdenes son bastante
largas:
.Bl -tag -width make -offset indent
.It Nm make
.Op Fl eiknqrstv
.Op Fl D Ar variable
.Op Fl d Ar opciones
.Op Fl f Ar makefile
.Bk -words
.Op Fl I Ar directorio
.Ek
.Op Fl j Ar max_tareas
.Op Ar variable=valor
.Bk -words
.Op Ar objetivo ...
.Ek
.El
.Pp
Aquí podríamos hablar de la orden
.Nm make
y calificar a
.Ar makefile
como argumento de la opción
.Fl f ,
o hablar del operando de fichero opcional
.Ar objetivo .
En el contexto verbal, dicho detalle puede evitar confusiones, si bien
el paquete
.Nm \-mdoc
no tiene una macro para el argumento
.Em de una opción .
En su lugar, se usa la macro de argumento
.Ql \&Ar
para operandos o argumentos de fichero como
.Ar objetivo ,
además de para un argumento de opción como
.Ar variable .
La línea de la orden make se obtuvo a partir de:
.Bd -literal -offset indent
\&.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
.Ed
.Pp
Las macros
.Ql \&.Bk
y
.Ql \&.Ek
se explican en
.Sx Agrupamientos .
.Ss Sintaxis general
Las macros de dominio de manual y de texto general comparten una
sintaxis similar con unas pocas diferencias menores:
.Ql \&.Ar ,
.Ql \&.Fl ,
.Ql \&.Nm ,
y
.Ql \&.Pa
sólo difieren cuando se invocan sin argumentos;
.Ql \&.Fn
y
.Ql \&.Xr
imponen un orden a sus listas de argumentos; y las macros
.Ql \&.Op
y
.Ql \&.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:
.Pp
.Dl \&.Li sptr, ptr),
.Pp
El resultado será:
.Pp
.Dl Li sptr, ptr),
.Pp
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:
.Pp
.Dl \&.Li "sptr , ptr ) ,"
.Pp
El resultado será:
.Pp
.Dl Li sptr , ptr ) ,
.Pp
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.
.Pp
Para eliminar el significado especial de un carácter de puntuación
protéjalo con
.Ql \e& .
.Xr 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:
.Bd -literal -offset indent-two
\&{+,\-,/,*,\&%,<,>,<=,>=,=,==,&,`,',"}
.Ed
.Pp
El problema es que
.Xr 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
.Ql \e& .
La sintaxis típica se muestra en la primera macro de contenido,
.Ql \&.Ad ,
que aparece más abajo,
.Sh DOMINIO DE MANUAL
.Ss Macro de dirección
La macro de dirección identifica una estructura de dirección de la
forma dir1[,dir2[,dir3]].
.Pp
.Dl Uso: .Ad dirección ... \*(Pu
.Bl -tag -width ".Ad f1 , f2 , f3 :" -compact -offset 14n
.It Li \&.Ad dir1
.Ad dir1
.It Li \&.Ad dir1\ .
.Ad dir1 .
.It Li \&.Ad dir1\ , fichero2
.Ad dir1 , fichero2
.It Li \&.Ad f1\ , f2\ , f3\ :
.Ad f1 , f2 , f3 :
.It Li \&.Ad dir\ )\ )\ ,
.Ad dir ) ) ,
.El
.Pp
Es un error llamar a
.Ql \&.Ad
sin argumentos.
.Ql \&.Ad
es invocable por otras macros y es interpretada.
.Ss Nombre del autor
La macro
.Ql \&.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.
.Pp
.Dl Uso: .An nombre_autor \*(Pu
.Bl -tag -width ".An Juan Autor ) ) ," -compact -offset 14n
.It Li \&.An Juan\ Autor
.An Juan Autor
.It Li \&.An Juan\ Autor\ ,
.An Juan\ Autor ,
.It Li \&.An Juan\ Autor\ \&Aq\ nadie@FreeBSD.ORG
.An Juan Autor Aq nadie@FreeBSD.ORG
.It Li \&.An Juan\ Autor\ )\ )\ ,
.An Juan Autor ) ) ,
.El
.Pp
La macro
.Ql \&.An
es interpretada y es invocable.
Es un error llamar a
.Ql \&.An
sin argumentos
.Ss Macro de argumento
La macro de argumento
.Ql \&.Ar
se puede usar siempre que se haga referencia a un argumento de la
línea de órdenes.
.Pp
.Dl Uso: .Ar argumento ... \*(Pu
.Bl -tag -width ".Ar fichero1 fichero2" -compact -offset 15n
.It Li \&.Ar
.Ar
.It Li \&.Ar fichero1
.Ar fichero1
.It Li \&.Ar fichero1\ .
.Ar fichero1 .
.It Li \&.Ar fichero1 fichero2
.Ar fichero1 fichero2
.It Li \&.Ar f1 f2 f3\ :
.Ar f1 f2 f3 :
.It Li \&.Ar fichero\ )\ )\ ,
.Ar fichero ) ) ,
.El
.Pp
Si
.Ql \&.Ar
se invoca sin argumentos, se asume
.Ql Ar .
La macro
.Ql \&.Ar
es interpretada y es invocable.
.Ss Declaración de configuración (sólo sección cuatro)
La macro
.Ql \&.Cd
se usa para mostrar la
.Xr 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).
.Pp
.Bl -tag -width "device le0 at scode?" -offset indent
.It Cd "device le0 at scode?"
producido por:
.Ql ".Cd device le0 at scode?" .
.El
.Ss Modificador de orden
El modificador de orden es idéntico a la orden
.Ql \&.Fl
(flag) con la excepción de que
.Ql \&.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
.Sx Opciones .
.Ss Variables definidas
Una variable que se define en un fichero
.Em include
se especifica mediante la macro
.Ql \&.Dv .
.Pp
.Dl Uso: .Dv variable_definida ... \*(Pu
.Bl -tag -width ".Dv MAXHOSTNAMELEN" -compact -offset 14n
.It Li ".Dv MAXHOSTNAMELEN"
.Dv MAXHOSTNAMELEN
.It Li ".Dv TIOCGPGRP )"
.Dv TIOCGPGRP )
.El
.Pp
Es un error llamar a
.Ql \&.Dv
sin argumentos.
.Ql \&.Dv
es interpretada y es invocable.
.Ss Códigos errno (sólo sección dos)
La macro
.Ql \&.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
.Ql \&.Er
con la macro de dominio de texto general
.Ql \&.Bq ,
tal como se haría en una página de la sección dos.
.Pp
.Dl Uso: .Er ERRNOTYPE ... \*(Pu
.Bl -tag -width ".Bq Er ENOTDIR" -compact -offset 14n
.It Li \&.Er ENOENT
.Er ENOENT
.It Li \&.Er ENOENT\ )\ ;
.Er ENOENT ) ;
.It Li \&.Bq \&Er ENOTDIR
.Bq Er ENOTDIR
.El
.Pp
Es un error llamar a
.Ql \&.Er
sin argumentos.
La macro
.Ql \&.Er
es interpretada y es invocable.
.Ss Variables de entorno
La macro
.Ql \&.Ev
especifica una variable de entorno.
.Pp
.Dl Uso: .Ev argumento ... \*(Pu
.Bl -tag -width ".Ev PRINTER ) ) ," -compact -offset 14n
.It Li \&.Ev DISPLAY
.Ev  DISPLAY
.It Li \&.Ev PATH\ .
.Ev PATH .
.It Li \&.Ev PRINTER\ )\ )\ ,
.Ev PRINTER ) ) ,
.El
.Pp
Es un error llamar a
.Ql \&.Ev
sin argumentos.
La macro
.Ql \&.Ev
es interpretada y es invocable.
.Ss Argumento de función
La macro
.Ql \&.Fa
se usa para referirse a argumentos de función (parámetros)
fuera de la sección
.Sx SINOPSIS
del manual o dentro de la sección
.Sx SINOPSIS
cuando la lista de parámetros es demasiado larga para la macro
.Ql \&.Fn
y se deben usar las macros de cierre
.Ql \&.Fo
y
.Ql \&.Fc .
.Ql \&.Fa
también se puede usar para referirse a miembros de estructura.
.Pp
.Dl Uso: .Fa argumento_función ... \*(Pu
.Bl -tag -width ".Fa d_namlen\ )\ )\ ," -compact -offset 14n
.It Li \&.Fa d_namlen\ )\ )\ ,
.Fa d_namlen ) ) ,
.It Li \&.Fa iov_len
.Fa iov_len
.El
.Pp
Es un error llamar a
.Ql \&.Fa
sin argumentos.
.Ql \&.Fa
es interpretada y es invocable.
.Ss Declaración de funciones
La macro
.Ql \&.Fd
se usa en la sección
.Sx SINOPSIS
de las funciones de las secciones dos y tres.
La macro
.Ql \&.Fd
no invoca a otras macros ni es invocable por otras macros.
.Pp
.Dl Uso: .Fd fichero_include (o variable definida)
.Pp
En la sección
.Sx SINOPSIS ,
una invocación a
.Ql \&.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.
.Ss Opciones (flags)
La macro
.Ql \&.Fl
maneja las opciones de la línea de órdenes. La macro antepone un
guíon,
.Ql \- ,
a la opción.
Para opciones de órdenes interactivas, a las que no se les antepone un
guión, la macro
.Ql \&.Cm
(modificador de orden)
es idéntica, pero sin el guión.
.Pp
.Dl Uso: .Fl argumento ... \*(Pu
.Bl -tag -width ".Fl \-s \-t \-v" -compact -offset 14n
.It Li \&.Fl
.Fl
.It Li \&.Fl cfv
.Fl cfv
.It Li \&.Fl cfv\ .
.Fl cfv .
.It Li \&.Fl s v t
.Fl s v t
.It Li \&.Fl -\ ,
.Fl - ,
.It Li \&.Fl xyz\ )\ ,
.Fl xyz ) ,
.El
.Pp
La macro
.Ql \&.Fl
sin argumentos produce un guión que representa a la entrada/salida
estándar.
Dese cuenta que dar a
.Ql \&.Fl
un único guión producirá dos guiones.
La macro
.Ql \&.Fl
es interpretada y es invocable.
.Ss Funciones (rutinas de biblioteca)
La macro .Fn se inspira en las convenciones del C ANSI.
.Bd -literal
Uso: .Fn [tipo] función [[tipo] parámetros ... \*(Pu]
.Ed
.Bl -tag -width ".Fn .int align. .const * char *sptrsxx" -compact
.It Li "\&.Fn getchar"
.Fn getchar
.It Li "\&.Fn strlen ) ,"
.Fn strlen ) ,
.It Li \&.Fn "\\*qint align\\*q" "\\*qconst * char *sptrs\\*q" ,
.Fn "int align" "const * char *sptrs" ,
.El
.Pp
Es un error invocar a
.Ql \&.Fn
sin argumentos.
La macro
.Ql \&.Fn
es interpretada e invocable.
Dese cuenta que cualquier llamada a otra macro supone el final de la
llamada a
.Ql \&.Fn
(se cerrará el paréntesis en ese punto).
.Pp
Para las funciones que tienen más de ocho parámetros (y esto es raro),
se pueden usar las macros
.Ql \&.Fo
(abre función)
y
.Ql \&.Fc
(cierra función) junto con
.Ql \&.Fa
(argumento de función)
para sortear la limitación. Por ejemplo:
.Bd -literal -offset indent
\&.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
.Ed
.Pp
Produce:
.Bd -filled -offset indent
.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
.Ed
.Pp
Las macros
.Ql \&.Fo
y
.Ql \&.Fc
son interpretadas e invocables.
En la sección
.Sx SINOPSIS ,
la función siempre comenzará al principio de línea.
Si se presenta más de una función en la sección
.Sx 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,
.Ql \&.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.
.Ss Tipo de función
Esta macro va dirigida a la sección
.Sx 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
.Sx 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).
.Pp
.Dl Uso: .Ft type ... \*(Pu
.Bl -tag -width "\&.Ft struct stat" -offset 14n -compact
.It Li \&.Ft struct stat
.Ft struct stat
.El
.Pp
.Ql \&.Ft
no es invocable por otras macros.
.Ss Órdenes interactivas
La macro
.Ql \&.Ic
designa una orden interactiva o interna.
.Pp
.Dl Uso: .Ic argumento ... \*(Pu
.Bl -tag -width ".Ic setenv , unsetenvxx" -compact -offset 14n
.It Li \&.Ic :wq
.Ic :wq
.It Li \&.Ic do while {...}
.Ic do while {...}
.It Li \&.Ic setenv\ , unsetenv
.Ic setenv , unsetenv
.El
.Pp
Es un error invocar a
.Ql \&.Ic
sin argumentos.
La macro
.Ql \&.Ic
es interpretada e invocable.
.Ss Macro de nombre
La macro
.Ql \&.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,
.Ql \&.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
.Ql \&.Nm
en la sección
.Sx NOMBRE
y con
.Ql \&.Fn
en la sección
.Sx SINOPSIS
y restantes.
Para órdenes interactivas, como la palabra clave
.Ql while
de
.Xr csh 1 ,
se debe usar la macro
.Ql \&.Ic .
Aunque la macro
.Ql \&.Ic
es casi idéntica a
.Ql \&.Nm ,
no puede recordar el primer argumento con el que fue invocada.
.Pp
.Dl Uso: .Nm argumento ... \*(Pu
.Bl -tag -width ".Nm mdoc.sample" -compact -offset 14n
.It Li \&.Nm mdoc.sample
.Nm  mdoc.sample
.It Li \&.Nm \e-mdoc
.Nm \-mdoc .
.It Li \&.Nm foo\ )\ )\ ,
.Nm foo ) ) ,
.It Li \&.Nm
.Nm
.El
.Pp
La macro
.Ql \&.Nm
es interpretada e invocable.
.Ss Opciones
La macro
.Ql \&.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
.Ql \&.Oc
y
.Ql \&.Oo
se pueden usar a lo largo de una o más líneas.
.Pp
.Dl Uso: .Op opciones ... \*(Pu
.Bl -tag -width ".Op Fl c Ar objfil Op Ar corfil ," -compact -offset indent
.It Li \&.Op
.Op
.It Li ".Op Fl k"
.Op Fl k
.It Li ".Op Fl k ) ."
.Op Fl k ) .
.It Li ".Op Fl k Ar kookfile"
.Op Fl k Ar kookfile
.It Li ".Op Fl k Ar kookfile ,"
.Op Fl k Ar kookfile ,
.It Li ".Op Ar objfil Op Ar corfil"
.Op Ar objfil Op Ar corfil
.It Li ".Op Fl c Ar objfil Op Ar corfil ,"
.Op Fl c Ar objfil Op Ar corfil ,
.It Li \&.Op palabra1 palabra2
.Op palabra1 palabra2
.El
.Pp
Las macros
.Ql \&.Oc
y
.Ql \&.Oo :
.Bd -literal -offset indent
\&.Oo
\&.Op \&Fl k \&Ar kilobytes
\&.Op \&Fl i \&Ar intervalo
\&.Op \&Fl c \&Ar total
\&.Oc
.Ed
.Pp
producen:
.Oo
.Op Fl k Ar kilobytes
.Op Fl i Ar intervalo
.Op Fl c Ar total
.Oc
.Pp
Las macros
.Ql \&.Op ,
.Ql \&.Oc
y
.Ql \&.Oo
son interpretadas e invocables.
.Ss Nombres de rutas (pathnames)
La macro
.Ql \&.Pa
formatea rutas o nombres de ficheros.
.Pp
.Dl Uso: .Pa nombreruta \*(Pu
.Bl -tag -width ".Pa /tmp/fooXXXXX ) ." -compact -offset 14n
.It Li \&.Pa /usr/share
.Pa /usr/share
.It Li \&.Pa /tmp/fooXXXXX\ )\ .
.Pa /tmp/fooXXXXX ) .
.El
.Pp
La macro
.Ql \&.Pa
es interpretada e invocable.
.Ss Variables
Referencia a variables genéricas:
.Pp
.Dl Usage: .Va variable ... \*(Pu
.Bl -tag -width ".Va char s ] ) ) ," -compact -offset 14n
.It Li \&.Va count
.Va count
.It Li \&.Va settimer ,
.Va settimer ,
.It Li \&.Va int\ *prt\ )\ :
.Va int\ *prt ) :
.It Li \&.Va char\ s\ ]\ )\ )\ ,
.Va char\ s ] ) ) ,
.El
.Pp
Es un error llamar a
.Ql \&.Va
sin argumentos.
La macro
.Ql \&.Va
es interpretada e invocable.
.Ss Referencias cruzadas a páginas de manual
La macro
.Ql \&.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.
.Pp
.Dl Uso: .Xr página_manual [1,...,8] \*(Pu
.Bl -tag -width ".Xr mdoc 7 ) ) ," -compact -offset 14n
.It Li \&.Xr mdoc
.Xr mdoc
.It Li \&.Xr mdoc\ ,
.Xr mdoc ,
.It Li \&.Xr mdoc 7
.Xr mdoc 7
.It Li \&.Xr mdoc 7\ )\ )\ ,
.Xr mdoc 7 ) ) ,
.El
.Pp
La macro
.Ql \&.Xr
es interpretada e invocable.
Es un error llamar a
.Ql \&.Xr
sin argumentos.
.Sh DOMINIO DE TEXTO GENERAL
.Ss Macro AT&T
.Bd -literal -offset indent -compact
Uso: .At [v6 | v7 | 32v | V.1 | V.4] ... \*(Pu
.Ed
.Bl -tag -width ".At v6 ) ," -compact -offset 14n
.It Li ".At"
.At
.It Li ".At v6 ."
.At v6 .
.El
.Pp
La macro
.Ql \&.At
.Em no es
interpretada y
.Em no es
invocable. Como mucho acepta dos argumentos.
.Ss Macro BSD
.Dl Uso: .Bx [Versión/lanzamiento] ... \*(Pu
.Bl -tag -width ".Bx 4.3 ) ," -compact -offset 14n
.It Li ".Bx"
.Bx
.It Li ".Bx 4.3 ."
.Bx 4.3 .
.El
.Pp
La macro
.Ql \&.Bx
es interpretada e invocable.
.Ss Macro FreeBSD
.Bd -literal -offset indent -compact
Uso: .Fx Versión.lanzamiento ... \*(Pu
.Ed
.Bl -tag -width ".Fx 2.2 ) ," -compact -offset 14n
.It Li ".Fx 2.2 ."
.Fx 2.2 .
.El
.Pp
La macro
.Ql \&.Fx
.Em no es
es interpretada y
.Em no es
invocable. Como mucho acepta dos argumentos.
.Ss Macro UNIX
.Dl Uso: .Ux ... \*(Pu
.Bl -tag -width ".Ux 4.3 ) ," -compact -offset 14n
.It Li ".Ux"
.Ux
.El
.Pp
La macro
.Ql \&.Ux
es interpretada e invocable.
.Ss 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
.Ql 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
.Ql o
y
.Ql 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.
.Pp
.ne 5
.Bd -filled -offset indent
.Bl -column "comilla " "cierre " "apertura " "Encerrar cadenax(entre XX) " XXcadenaXX
.Em " 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'
.El
.Ed
.Pp
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.
.Bl -tag -width "xEc, xEo"
.It Li \&.Ec , \&.Eo
Estas macros esperan que el primer argumento se corresponda con las
cadenas de apertura y de cierre, respectivamente.
.It Li \&.Ql
La macro para literales entrecomillados se comporta de manera
diferente para
.Xr troff
y
.Xr nroff .
Si se formatea con
.Xr 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.
.It Li \&.Pf
La macro de prefijo no es invocable, pero es interpretada:
.Bl -tag -width "(namexx" -offset indent
.It Li ".Pf ( Fa nombre2"
se convierte en
.Pf ( Fa nombre2 .
.El
.Pp
La macro
.Ql \&.Ns
(no space) realiza la función de sufijo análoga.
.El
.Pp
.ne 4
Ejemplos de entrecomillado:
.Bl -tag -width ".Aq Pa ctype.h ) ,xxxxxxxx" -compact -offset indent
.It Li \&.Aq
.Aq
.It Li \&.Aq \&Ar ctype.h\ )\ ,
.Aq Ar ctype.h ) ,
.It Li \&.Bq
.Bq
.It Li \&.Bq \&Em griego \&, francés \&.
.Bq Em griego , francés .
.It Li \&.Dq
.Dq
.It Li ".Dq cadena abc ."
.Dq cadena abc .
.It Li ".Dq \'^[A-Z]\'"
.Dq \'^[A-Z]\'
.It Li "\&.Ql man mdoc"
.Ql man mdoc
.It Li \&.Qq
.Qq
.It Li "\&.Qq cadena ) ,"
.Qq cadena ) ,
.It Li "\&.Qq cadena Ns ),"
.Qq cadena Ns ),
.It Li \&.Sq
.Sq
.It Li "\&.Sq cadena
.Sq cadena
.El
.Pp
Para un buen ejemplo de macros de cierre anidadas, vea la macro de
opción
.Ql \&.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
.Ql \&.Xo
y
.Ql \&.Xc
también se construyeron a partir de las mismas rutinas subyacentes y
son un buen ejemplo del peor uso de macros de
.Nm \-mdoc .
.Ss Macro de texto normal o de no operación
La macro
.Ql \&.No
(`no-op')
es un apaño para palabras en una línea de órdenes de macro que
.Em no
se deben formatear y sigue la sintaxis convencional para las macros de
contenido.
.Ss Macro de eliminación de espacios
La macro
.Ql \&.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:
.Bl -tag -width ".Op Fl I Ns Ar directorioxx" -offset indent
.It Li ".Op Fl I Ns Ar directorio"
produce
.Op Fl I Ns Ar directorio
.El
.Pp
Nota: la macro
.Ql \&.Ns
siempre invoca a la macro
.Ql \&.No
tras eliminar el espacio a menos que otro nombre de macro le siga.
La macro
.Ql \&.Ns
es interpretada y es invocable.
.Ss Referencias cruzadas a secciones
La macro
.Ql \&.Sx
designa una referencia a una cabecera de sección dentro del mismo
documento.
Es interpretada y es invocable.
.Pp
.Bl -tag -width "Li \&.Sx FICHEROS" -offset 14n
.It Li \&.Sx FICHEROS
.Sx FICHEROS
.El
.Ss 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
.Xr refer 1 .
.Pp
.Bl -tag -width 6n -offset indent -compact
.It Li ".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.
.It Li ".Re"
Fin de referencia.
Se imprime la referencias.
.It Li ".%A"
Autor de lo que se referencia, un nombre por invocación.
.It Li ".%B"
Título de libro.
.It Li ".\&%C"
Ciudad/lugar.
.It Li ".\&%D"
Fecha.
.It Li ".%J"
Nombre de revista.
.It Li ".%N"
Número de tema.
.It Li ".%O"
Información opcional.
.It Li ".%P"
Número de página.
.It Li ".%R"
Número de informe.
.It Li ".%T"
Título de artículo.
.It Li ".%V"
Volumen(es).
.El
.Pp
Las macros que comienzan con
.Ql %
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
.Xr troff Ns / Ns Xr ditroff .
.Ss Valores devueltos
La macro
.Ql \&.Rv
genera texto para usar en la sección
.Sx VALOR DEVUELTO .
.Pp
.Dl Uso: .Rv [-std función]
.Pp
.Ql \&.Rv -std alsalir
generará el siguiente texto:
.Pp
.\" fake chapter 3 to avoid error message from Rv
.ds cH 3
.Rv -std alsalir
.\" and back to 7 again
.ds cH 7
.Pp
La opción
.Fl std
sólo es válida para las secciones 2 y 3 de las páginas de manual.
.Ss 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.
.Pp
.Dl Uso: .Tn símbolo ... \*(Pu
.Bl -tag -width ".Tn ASCII" -compact -offset 14n
.It Li \&.Tn DEC
.Tn DEC
.It Li \&.Tn ASCII
.Tn ASCII
.El
.Pp
La macro
.Ql \&.Tn
es interpretada y es invocable por otras macros.
.Ss Argumentos extendidos
Las macros
.Ql \&.Xo
y
.Ql \&.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
.Ql \&.Op .
.Pp
Aquí tiene un ejemplo de
.Ql \&.Xo
que usa la «macro de modo de espacio» para desactivar el espaciado:
.Bd -literal -offset indent
\&.Sm off
\&.It Xo Sy I Ar operación
\&.No \een Ar contador No \een
\&.Xc
\&.Sm on
.Ed
.Pp
Produce
.Bd -filled -offset indent
.Bl -tag -width flag -compact
.Sm off
.It Xo Sy I Ar operación
.No \en Ar cuenta No \en
.Xc
.Sm on
.El
.Ed
.Pp
Otro más:
.Bd -literal -offset indent
\&.Sm off
\&.It Cm S No \&/ Ar anterior_patrón Xo
\&.No \&/ Ar nuevo_patrón
\&.No \&/ Op Cm g
\&.Xc
\&.Sm on
.Ed
.Pp
Produce
.Bd -filled -offset indent
.Bl -tag -width flag -compact
.Sm off
.It Cm S No \&/ Ar anterior_patrón Xo
.No \&/ Ar nuevo_patrón
.No \&/ Op Cm g
.Xc
.Sm on
.El
.Ed
.Pp
Otro ejemplo de
.Ql \&.Xo
usando macros de cierre:
comprueba el valor de una variable.
.Bd -literal -offset indent
\&.It Xo
\&.Ic .ifndef
\&.Oo \e&! Oc Ns Ar variable
\&.Op Ar operador variable ...
\&.Xc
.Ed
.Pp
Produce
.Bd -filled -offset indent
.Bl -tag -width flag -compact
.It Xo
.Ic .ifndef
.Oo \&! Oc Ns Ar variable
.Op Ar operador variable ...
.Xc
.El
.Ed
.Pp
Todos los ejemplos anteriores han usado la macro
.Ql \&.Xo
en la lista de argumentos de la macro
.Ql \&.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
.Ql \&.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
.Ql \&.Xo
y
.Ql \&.Xc
se sitúan como se muestra en el tercer ejemplo.
Si la macro
.Ql \&.Xo
no está sola en la lista de argumentos de
.Ql \&.It ,
el espaciado será impredecible.
La macro
.Ql \&.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
.Bx
usan la macro
.Ql \&.Xo .
.Sh DOMINIO DE ESTRUCTURA DE PÁGINA
.Ss Cabeceras de sección
Las primeras tres macros de cabecera de sección
.Ql \&.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
.Ql \&.Sh
puede tomar hasta nueve argumentos; es interpretada pero no es
invocable.
.Bl -tag -width ".Sh SINOPSIS"
.It \&.Sh NOMBRE
La macro
.Ql \&.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
.Sx NOMBRE
consta de, al menos, tres ítems. El primero es la macro de nombre
.Ql \&.Nm
que pone nombre al contenido de la página de manual. El segundo es la
macro de descripción de nombre
.Ql \&.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.
.It \&.Sh SINOPSIS
La sección
.Sx SINOPSIS
describe el uso típico de la materia de una página de manual.
Las macros que se necesitan son
.Ql ".Nm" ,
.Ql ".Cd"
y
.Ql ".Fn"
(y, posiblemente las macros
.Ql ".Fo" ,
.Ql ".Fc" ,
.Ql ".Fd"
y
.Ql ".Ft" ) .
La macro de nombre de función
.Ql ".Fn"
se necesita para las secciones 2 y 3 de las páginas de manual. La
macro de orden y de nombre general
.Ql \&.Nm
se necesita para las secciones 1, 5, 6, 7 y 8. Los manuales de la
sección 4 requieren
.Ql ".Nm" , 
.Ql ".Fd"
o una macro
.Ql ".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:
.Pp
.Bd -filled -offset indent
.Nm cat
.Op Fl benstuv
.Op Fl
.Ar
.Ed
.Pp
Se han usado las siguientes macros:
.Pp
.Dl \&.Nm cat
.Dl \&.Op \&Fl benstuv
.Dl \&.Op \&Fl
.Dl \&.Ar
.Pp
.Sy Nota :
Las macros
.Ql \&.Op ,
.Ql \&.Fl ,
y
.Ql \&.Ar
reconocen el carácter de tubería
.Ql \*(Ba ,
por lo que una línea de órdenes como:
.Pp
.Dl ".Op Fl a | Fl b"
.Pp
no se desmadrará.
.Xr Troff
normalmente interpreta \*(Ba como un operador especial.
Vea
.Sx CADENAS PREDEFINIDAS
para un carácter \*(Ba usable en otras situaciones.
.It \&.Sh DESCRIPCIÓN
En la mayoría de los casos, el primer texto de una sección
.Sx 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
.Ql \&.Bl ,
elemento de lista
.Ql \&.It
y final de lista
.Ql \&.El
(vea
.Sx Listas y columnas
más abajo).
.El
.Pp
Los siguientes encabezados de sección
.Ql \&.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.
.Bl -tag -width SINOPSIS
.It \&.Sh ENTORNO
La sección
.Sx ENTORNO
debería revelar cualesquiera variables de entorno relacionadas y dar
pistas sobre su comportamiento y/o uso.
.It \&.Sh EJEMPLOS
Hay varias formas de crear ejemplos. Vea la sección
.Sx EJEMPLOS
que hay más abajo para más detalles.
.It \&.Sh FICHEROS
Los ficheros que son usados o creados por la materia de la página de
manual debería listarse mediante la macro
.Ql \&.Pa
en la sección
.Sx FICHEROS .
.It \&.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
.Sx VÉASE TAMBIÉN .
Las referencias cruzadas se especifican usando la macro
.Ql \&.Xr .
Las referencias cruzadas de la sección
.Sx 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:
.Pp
.Xr ls 1 ,
.Xr ps 1 ,
.Xr group 5 ,
.Xr passwd 5 .
.Pp
Por ahora, las referencias al estilo de
.Xr refer 1
no se tienen en cuenta.
.It \&.Sh CONFORME A
Si la orden, función de biblioteca o fichero sigue una implementación
específica como
.St -p1003.2
o
.St -ansiC
debería hacerse notar aquí.
Si la orden no sigue ningún estándar, su historia debería
constar en la sección
.Sx HISTORIA .
.It \&.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.
.It \&.Sh AUTORES
Cualquier reconocimiento o crédito debería colocarse aquí.
.It \&.Sh DIAGNÓSTICOS
Los diagnósticos de una orden deberían ubicarse en esta sección.
.It \&.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
.Ql errno
se usa la macro
.Ql \&.Er .
.It \&.Sh FALLOS
Los problemas ostensibles del tema van aquí...
.El
.Pp
Se pueden añadir secciones
.Ql \&.Sh
especificadas por el usuario; por ejemplo, esta sección se creó con:
.Bd -literal -offset 14n
\&.Sh DOMINIO DE LA ESTRUCTURA DE PÁGINA
.Ed
.Ss Párrafos y espacios entre líneas.
.Bl -tag -width 6n
.It \&.Pp
Se puede usar la orden de párrafo
.Ql \&.Pp
para insertar una línea en blanco donde sea necesario. La macro no
es necesaria tras una macro
.Ql \&.Sh
o
.Ql \&.Ss
o antes de una macro
.Ql \&.Bl
(la macro
.Ql \&.Bl
inserta un espacio vertical a menos que se use la opción
-compact).
.El
.\" This worked with version one, need to redo for version three
.\" .Pp
.\" .Ds I
.\" .Cw (ax+bx+c) \ is\ produced\ by\ \&
.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
.\" .Cl Cx \t\t
.\" .Li \&.Cx\ (
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Va ax
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Sy \+
.\" .Cx
.\" .Cl Cx \&(\&
.\" .Va ax
.\" .Cx +
.\" .Va by
.\" .Cx +
.\" .Va c )
.\" .Cx \t
.\" .Em is produced by
.\" .Cx \t
.\" .Li \&.Va by
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Sy \+
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Va c )
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Cx
.\" .Cx
.\" .Cw
.\" .De
.\" .Pp
.\" This example shows the same equation in a different format.
.\" The spaces
.\" around the
.\" .Li \&+
.\" signs were forced with
.\" .Li \e :
.\" .Pp
.\" .Ds I
.\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \&
.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
.\" .Cl Cx \t\t
.\" .Li \&.Cx\ (
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Va a
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Sy x
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Cx \e\ +\e\ \e&
.\" .Cx
.\" .Cl Cx \&(\&
.\" .Va a
.\" .Sy x
.\" .Cx \ +\ \&
.\" .Va b
.\" .Sy y
.\" .Cx \ +\ \&
.\" .Va c )
.\" .Cx \t
.\" .Em is produced by
.\" .Cl Cx \t\t
.\" .Li \&.Va b
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Sy y
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Cx \e\ +\e\ \e&
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Va c )
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Cx
.\" .Cx
.\" .Cw
.\" .De
.\" .Pp
.\" The incantation below was
.\" lifted from the
.\" .Xr adb 1
.\" manual page:
.\" .Pp
.\" .Ds I
.\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by
.\" .Cl Cx \t\t
.\" .Li \&.Cx Op Sy ?/
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Nm m
.\" .Cx
.\" .Cl Cx Op Sy ?/
.\" .Nm m
.\" .Ad \ b1 e1 f1
.\" .Op Sy ?/
.\" .Cx \t
.\" .Em is produced by
.\" .Cx \t
.\" .Li \&.Ar \e\ b1 e1 f1
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Op Sy ?/
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Cx
.\" .Cx
.\" .Cw
.\" .De
.\" .Pp
.Ss Agrupamientos
Por ahora, el único agrupamiento (`keep') que se implementa es para
palabras. Las macros son
.Ql \&.Bk
(comienza agrupamiento)
y
.Ql \&.Ek
(finaliza agrupamiento).
La única opción que acepta
.Ql \&.Bk
es
.Fl 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
.Sx Lo que hay en un nombre ) ,
el agrupamiento evitó que
.Xr 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
.Xr 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
.Fl line . )
.Ss Ejemplos y visualizaciones
Hay cinco tipos de visualización (`display'): uno para sangrar una
única línea,
.Ql \&.D1 ,
otro para mostrar una única línea literal,
.Ql \&.Dl ,
y tres más para bloques (literal, ajustada e irregular) que usan las
macros
.Ql \&.Bd
(comienza visualización) y
.Ql \&.Ed
(finaliza visualización).
.Pp
.Bl -tag -width \&.Dlxx
.It Li \&.D1
(D-uno) Muestra una línea de texto sangrado. Esta macro es
interpretada pero no es invocable.
.Pp
.Dl Fl ldghfstru
.Pp
Lo anterior se ha obtenido mediante:
.Li \&.Dl Fl ldghfstru .
.It Li \&.Dl
(D-ele)
Muestra una línea de texto
.Em literal
sangrado.
La macro de ejemplo
.Ql \&.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.
.Pp
.Dl % ls -ldg /usr/local/bin
.Pp
Lo anterior se ha obtenido con:
.Li \&.Dl % ls -ldg /usr/local/bin .
.It Li \&.Bd
Comienza visualización. La visualización de
.Ql \&.Bd
se debe terminar con la macro
.Ql \&.Ed .
Las visualizaciones se pueden anidar dentro de otras visualizaciones y
listas.
.Ql \&.Bd
tiene la siguiente sintaxis:
.Pp
.Dl ".Bd tipo-visualización [-offset valor_desplazamiento] [-compact]"
.Pp
El tipo de visualización debe ser uno de los cuatro tipos siguientes y
puede llevar un indicador de desplazamiento para sangrado:
.\" .Ql \&.Bd .
.Pp
.Bl -tag -width "file nombre_fichero  " -compact
.It Fl ragged
Muestra un bloque de texto tal cual se ha escrito, los bordes del
margen derecho (e izquierdo) se dejan sin ajustar.
.It Fl filled
Muestra un bloque ajustado (formateado). El bloque de texto se
formatea (los bordes se ajustan \- no se dejan sin justificar).
.It Fl literal
Muestra un bloque literal, útil para código fuente o texto simple
tabulado o espaciado).
.It Fl file Ar nombre_fichero
Se lee y se muestra el fichero cuyo nombre sigue a la opción
.Fl file .
Se activa el modo literal y los tabuladores se fijan en intervalos de
8 caracteres de ancho constante, aunque se procesa cualquier orden
.Xr troff/ Ns Nm \-mdoc
del fichero.
.It Fl offset Ar cadena
Si se especifica
.Fl 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:
.Pp
.Bl -tag -width "indent-two" -compact
.It Ar left
Ajusta el bloque al margen izquierdo actual; éste es el modo por
omisión de
.Ql \&.Bd .
.It Ar center
Supuestamente, centra el bloque. Desafortunadamente, por ahora el
bloque simplemente se ajusta a la izquierda alrededor de un imaginario
margen central.
.It Ar 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
.Ql \&.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).
.It Ar indent-two
Sangra el texto dos veces el valor de sangrado por omisión.
.It Ar right
Esto ajusta
.Em 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
.Xr troff .
.El
.El
.It ".Ed"
Finaliza visualicación.
.El
.Ss Modos de las fuentes
Hay cinco macros para cambiar la apariencia del texto de una página de
manual:
.Bl -tag -width \&.Emxx
.It \&.Em
Se puede recalcar o enfatizar el texto con la macro
.Ql \&.Em .
La fuente habitual en este caso es cursiva.
.Pp
.Dl Uso: .Em argumento ... \*(Pu
.Bl -tag -width ".Em vide infra ) ) ," -compact -offset 14n
.It Li ".Em no"
.Em no
.It Li ".Em excede 1024 ."
.Em excede 1024 .
.It Li ".Em vide infra ) ) ,"
.Em vide infra ) ) ,
.El
.Pp
La macro
.Ql \&.Em
es interpretada e invocable.
Es un error llamar a
.Ql \&.Em
sin argumentos.
.It \&.Li
La macro literal
.Ql \&.Li
se puede usar para caracteres especiales, constantes de variables y
cualquier cosa que deba mostrarse tal cual se escribiría.
.Pp
.Dl Uso: .Li argumento ... \*(Pu
.Bl -tag -width ".Li cntrl-D ) ,"  -compact -offset 14n
.It Li \&.Li \een
.Li \en
.It Li \&.Li M1 M2 M3\ ;
.Li M1 M2 M3 ;
.It Li \&.Li cntrl-D\ )\ ,
.Li cntrl-D ) ,
.It Li \&.Li 1024\ ...
.Li 1024 ...
.El
.Pp
La macro
.Ql \&.Li
es interpretada e invocable.
.It \&.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.
.Pp
.Dl Uso: .Sy símbolo ... \*(Pu
.Bl -tag -width ".Sy Aviso importantex" -compact -offset 14n
.It Li \&.Sy Aviso importante
.Sy Aviso importante
.El
.Pp
La macro
.Ql \&.Sy
es interpretada e invocable.
Los argumentos de
.Ql \&.Sy
se pueden entrecomillar.
.It Li \&.Bf
Comienza el modo de fuente.
El modo de fuente
.Ql \&.Bf
se debe finalizar con la macro
.Ql \&.Ef .
Los modos de fuente se pueden anidar dentro de otros modos de fuente.
.Ql \&.Bf
tiene la siguiente sintaxis:
.Pp
.Dl ".Bf modo-fuente"
.Pp
El modo de fuente debe ser uno de los siguientes tres tipos:
.\" .Ql \&.Bf .
.Pp
.Bl -tag -width "file file_name  " -compact
.It Sy \&Em | Fl emphasis
El mismo que si la macro 
.Ql \&.Em
se usara para todo el bloque de texto.
.It Sy \&Li | Fl literal
El mismo que si la macro
.Ql \&.Li
se usara para todo el bloque de texto.
.It Sy \&Sy | Fl symbolic
El mismo que si la macro
.Ql \&.Sy
se usara para todo el bloque de texto.
.El
.It ".Ef"
Finaliza el modo de fuente.
.El
.Ss Listas etiquetadas y columnas
Hay varios tipos de listas que se pueden iniciar con la macro de
comienzo de lista
.Ql ".Bl" .
Los elementos dentro de la lista se especifican con la macro de
item
.Ql ".It"
y cada lista debe terminar con la macro
.Ql ".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.
.Pp
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»
.Pq Fl tag .
Para ver otros estilos, a continuación vamos a usar el tipo de lista
«sobresaliente» (over-hanging)
.Pq Fl ohang
para mostrar los tipos de lista que hay.
Este tipo de lista es bastante popular entre los usuarios de
.Tn 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
.Ql ".Bl" :
.Pp
.Bl -ohang -compact
.It Fl bullet
.It Fl item
.It Fl enum
Estos tres son los tipos de lista más simples. Una vez que se ha
especificado la macro
.Ql ".Bl" ,
los elementos de la lista se indican simplemente mediante una línea
compuesta únicamente por la macro
.Ql ".It" .
Por ejemplo, el código fuente para una lista simple enumerada se
parecería a:
.Bd -literal -offset indent-two
\&.Bl -enum -compact
\&.It
\&El ítem uno viene aquí.
\&.It
\&Y el ítem dos aquí.
\&.It
\&El tercer y último ítem viene aquí.
\&.El
.Ed
.Pp
El resultado:
.Pp
.Bl -enum -offset indent-two -compact
.It
El ítem uno viene aquí.
.It
Y el ítem dos aquí.
.It
El tercer y último ítem viene aquí.
.El
.Pp
Una construcción de lista simple con viñetas (círculos en este caso):
.Bd -literal -offset indent-two
\&.Bl -bullet -compact
\&.It
\&La viñeta uno viene aquí.
\&.It
\&La viñeta dos aquí.
\&.El
.Ed
.Pp
Produce:
.Bl -bullet -offset indent-two -compact
.It
La viñeta uno viene aquí.
.It
La viñeta dos aquí.
.El
.Pp
.It Fl tag
.It Fl diag
.It Fl hang
.It Fl ohang
.It Fl inset
Estos tipos de lista recopilan los argumentos especificados con la macro
.Ql \&.It
y crean una etiqueta que puede ser
.Em insertada
(`inset') en el texto que le sigue,
.Em colgada
(`hanged') del texto que le sigue,
.Em sobresalir
(`overhanged') sin sangrado por arriba del texto que le sigue o ser
.Em etiquetada
(`tag').
Esta lista se ha construido con el tipo de lista
.Ql Fl ohang .
La macro
.Ql \&.It
es interpretada sólo para los tipos de lista
.Em inset ,
.Em hang
y
.Em tag
y no es invocable.
Aquí tiene un ejemplo de etiquetas insertadas (`inset'):
.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
.Pp
Aquí tiene el texto fuente que produce el ejemplo anterior:
.Bd -literal -offset indent
\&.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
.Ed
.Pp
Aquí tiene una lista colgada con dos elementos:
.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
.Pp
Y el texto sin formatear que lo creó:
.Bd -literal -offset indent
\&.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
.Ed
.Pp
La lista etiquetada que viene a continuación usa un indicador de
anchura opcional para controlar el ancho de la etiqueta.
.Pp
.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
.Pp
Y el texto sin formatear:
.Bd -literal -offset indent
\&.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
.Ed
.Pp
Indicadores de anchura aceptables:
.Bl -tag -width Ar -offset indent
.It Fl width Ar "\&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
.Ql \&.Fl
es diez caracteres de ancho constante o, aproximadamente, cinco sextos
de una pulgada.
.It Fl width Ar "24n"
establece el ancho a 24 caracteres de ancho constante o,
aproximadamente, dos pulgadas.
La letra
.Ql n
es absolutamente necesaria para que el escalado funcione correctamente.
.It Fl width Ar "ENAMETOOLONG"
establece el ancho a la longitud de anchura constante de la cadena
dada.
.It Fl width  Ar "\\*qint mkfifo\\*q"
de nuevo, establece el ancho a la anchura constante de la cadena dada.
.El
.Pp
Si no se especifica un ancho para el tipo de lista «etiqueta», la
primera vez que se invoque a
.Ql \&.It
se intentará determinar una anchura apropiada.
Si el primer argumento de
.Ql ".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.
.Sh 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
.Ql \&\e*(xx ,
donde
.Em xx
es el nombre de la cadena definida, o
.Ql \&\e*x ,
donde
.Em x
es el nombre de la cadena.
La secuencia de interpretación se puede usar en cualquier parte del
texto.
.Pp
.Bl -column "Cadena " "Nroff " "Troff " -offset indent
.It Sy "Cadena	Nroff	Troff"
.It Li "<=" Ta \&<\&= Ta \*(<=
.It Li ">=" Ta \&>\&= Ta \*(>=
.It Li "Rq" Ta "''" Ta \*(Rq
.It Li "Lq" Ta "``" Ta \*(Lq
.It Li "ua" Ta ^ Ta \*(ua
.It Li "aa" Ta ' Ta \*(aa
.It Li "ga" Ta \` Ta \*(ga
.\" .It Li "sL" Ta ` Ta \*(sL
.\" .It Li "sR" Ta ' Ta \*(sR
.It Li "q" Ta \&" Ta \*q
.It Li "Pi" Ta pi Ta \*(Pi
.It Li "Ne" Ta != Ta \*(Ne
.It Li "Le" Ta <= Ta \*(Le
.It Li "Ge" Ta >= Ta \*(Ge
.It Li "Lt" Ta < Ta \*(Gt
.It Li "Gt" Ta > Ta \*(Lt
.It Li "Pm" Ta +- Ta \*(Pm
.It Li "If" Ta infinity Ta \*(If
.It Li "Na" Ta \fINaN\fP Ta \*(Na
.It Li "Ba" Ta \fR\&|\fP Ta \*(Ba
.El
.Pp
.Sy Nota :
La cadena con nombre
.Ql q
se debe escribir como
.Ql \e*q
ya que sólo es un carácter.
.Sh DIAGNÓSTICOS
Las herramientas de depuración de
.Nm \-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
.Xr troff
con un nombre de uno o dos caracteres.
Todos los registros internos de
.Nm \-mdoc
para
.Xr troff
y
.Xr ditroff
son de dos caracteres y de la forma <mayúscula><minúscula> como
.Ql \&Ar ,
<minúscula><mayúscula> como
.Ql \&aR
o
<letra mayúscula o minúscula><dígito> como
.Ql \&C\&1 .
Y para liar más las cosas,
.Xr 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
.Ql \e& .
Ésta también es suficiente para los nombres de los registros internos.
.Pp
.\" Every callable macro name has a corresponding register
.\" of the same name (<upper_case><lower_case>).
.\" There are also specific registers which have
.\" been used for stacks and arrays and are listed in the
.\" .Sx Appendix .
.\" .Bd -ragged -offset 4n
.\" [A-Z][a-z]	registers corresponding to macro names (example ``Ar'')
.\" [a-z][A-Z]	registers corresponding to macro names (example ``aR'')
.\" C[0-9]		argument types (example C1)
.\" O[0-9]		offset stack (displays)
.\" h[0-9]		horizontal spacing stack (lists)
.\" o[0-9]		offset (stack) (lists)
.\" t[0-9]		tag stack (lists)
.\" v[0-9]		vertical spacing stack (lists)
.\" w[0-9]		width tag/label stack
.\" .Ed
.\" .Pp
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
.Ql \&.Db
(debug)
muestra la interpretación de la lista de argumentos para la mayoría de
las macros. Las macros como la macro
.Ql \&.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
.Ql \&.Db .
.Pp
.Dl Uso: \&.Db [on | off]
.Pp
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
.Ql \&aC
que debería ser
.Ql \e&aC
para funcionar):
.Bd -literal -offset indent
\&.Db on
\&.Op Fl aC Ar file )
\&.Db off
.Ed
.Pp
La salida resultante:
.Bd -literal -offset indent
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
.Ed
.Pp
La primera línea indica el nombre de la macro invocadora, que aquí es
.Ql \&.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
.Pq Ql \&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
.Ql \&aC
se protege con una secuencia de escape:
.Bd -literal -offset indent
\&.Db on
\&.Em An escaped \e&aC
\&.Db off
.Ed
.Bd -literal -offset indent
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
.Ed
.Pp
El argumento
.Ql \e&aC
aparece con la misma longitud de 2 aun cuando la secuencia
.Ql \e&
produce un ancho de cero, aunque no se encontró un registro de nombre
.Ql \e&aC
y el tipo se clasificó como cadena (string).
.Pp
Otros diagnósticos consisten en instrucciones de uso y son
autoexplicativos.
.Sh GROFF, TROFF y NROFF
El paquete
.Nm \-mdoc
no necesita modo de compatibilidad con
.Xr groff .
.Pp
El paquete inhibe los saltos de página, y las cabeceras y pies de
página que se producen normalmente en dichos saltos con
.Xr nroff ,
para hacer más eficiente la visualición en línea del manual.
Por ahora,
.Xr groff
con
.Fl T Ns Ar ascii
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
.Xr nroff
no sean adecuados para obtener una copia impresa. Existe un registro
de nombre
.Ql \&cR
que se puede establecer a cero en el fichero de estilo de la
instalación local
.Pa /usr/src/share/tmac/doc-nroff
para restaurar el comportamiento anterior.
.Sh FICHEROS
.Bl -tag -width /usr/share/man0/template.doc -compact
.It Pa /usr/share/tmac/tmac.doc
paquete de macros de manual
.It Pa /usr/share/misc/mdoc.template
plantilla para escribir una página de manual
.It Pa /usr/share/examples/mdoc/*
varias páginas de manual de ejemplo
.El
.Sh VÉASE TAMBIÉN
.Xr man 1 ,
.Xr troff 1 ,
.Xr mdoc 7
.Sh 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
.Sx DESCRIPCIÓN .
.Pp
Las cadenas predefinidas no aparecen en la documentación.
.Pp
No se ha añadido la sección 3f a las rutinas de cabecera.
.Pp
Se debería cambiar la fuente de
.Ql \&.Nm
en la sección
.Sx NOMBRE .
.Pp
Es necesario añadir una comprobación a
.Ql \&.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.
.Pp
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.
.Pp
Las macros de lista y visualización no hacen ningún tipo de
agrupamiento y desde luego deberían ser capaces de ello.
.\" Note what happens if the parameter list overlaps a newline
.\" boundary.
.\" to make sure a line boundary is crossed:
.\" .Bd -literal
.\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[]
.\" .Ed
.\" .Pp
.\" produces, nudge nudge,
.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
.\" nudge
.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] .
.\" .Pp
.\" If double quotes are used, for example:
.\" .Bd -literal
.\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q
.\" .Ed
.\" .Pp
.\" produces, nudge nudge,
.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
.\" nudge
.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
.\" nudge
.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" .
.\" .Pp
.\" Not a pretty sight...
.\" In a paragraph, a long parameter containing unpaddable spaces as
.\" in the former example will cause
.\" .Xr troff
.\" to break the line and spread
.\" the remaining words out.
.\" The latter example will adjust nicely to
.\" justified margins, but may break in between an argument and its
.\" declaration.
.\" In
.\" .Xr nroff
.\" the right margin adjustment is normally ragged and the problem is
.\" not as severe.