Provided by:
manpages-es_1.55-9_all 
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 pgina 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 implementacin: 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 maysculas) 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 TTULO.
El resto de elementos de la plantilla son cabeceras de sección (.Sh); de
las que NOMBRE, SINOPSIS y DESCRIPCIN son obligatorias. Las cabeceras
se discuten en DOMINIO DE ESTRUCTURA DE PGINA, 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
opcin. 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 Funcin 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, francs].
.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
Ioperacin\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_patrn/nuevo_patrn/[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
DESCRIPCIN 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 VASE TAMBIN.
Las referencias cruzadas se especifican usando la macro ‘.Xr’.
Las referencias cruzadas de la sección VASE TAMBIN 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 C”) 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 DESCRIPCIN.
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.