Uso de macros¶

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:

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

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¶

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

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:

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

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)¶

Protección de caracteres especiales¶

Modelo de una página de manual¶

.\" Las siguientes invocaciones son necesarias para todas las páginas
.\" de manual.
.Dd Mes día, año
.Os SISTEMA_OPERATIVO [versión/lanzamiento]
.Dt TÍTULO_DOCUMENTO [sección número] [volumen]
.Sh NOMBRE
.Nm nombre
.Nd descripción de una línea del nombre
.Sh SINOPSIS
.Sh DESCRIPCIÓN
.\" Las siguientes invocaciones se deberían «descomentar» y usar
.\" donde fuera apropiado.
.\" La siguiente invocación sólo es para los valores devueltos
.\" por las funciones de las secciones 2 y 3.
.\" .Sh VALORES DEVUELTOS
.\" La siguiente invocación es sólo para las secciones 1, 6, 7 y 8.
.\" .Sh ENTORNO
.\" .Sh FICHEROS
.\" .Sh EJEMPLOS
.\" La siguiente invocación es sólo para las secciones 1, 6, 7 y 8.
.\"    (valores devueltos por una orden (al shell) y
.\"	  diagnósticos de los tipos de fprintf/stderr)
.\" .Sh DIAGNÓSTICOS
.\" La siguiente invocación es sólo para el manejo de errores y
.\" señales de las secciones 2 y 3.
.\" .Sh ERRORES
.\" .Sh VÉASE TAMBIÉN
.\" .Sh CONFORME A
.\" .Sh HISTORIA
.\" .Sh AUTORES
.\" .Sh FALLOS

Los primeros elementos de la plantilla son las macros (.Dd, .Os, .Dt); la fecha del documento, el sistema operativo para el que el fuente de la página de manual o tema se ha desarrollado o modificado y el título de la página de manual (en mayúsculas) junto con la sección del manual a la que pertenece la página. Estas macros idenfican a la página y se discuten más abajo en MACROS DE TÍTULO.

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

Lo que hay en un nombre...¶

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’ 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:

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:

Aquí podríamos hablar de la orden make y calificar a makefile como argumento de la opción -f, o hablar del operando de fichero opcional objetivo. En el contexto verbal, dicho detalle puede evitar confusiones, si bien el paquete -mdoc no tiene una macro para el argumento de una opción. En su lugar, se usa la macro de argumento ‘Ar’ para operandos o argumentos de fichero como objetivo, además de para un argumento de opción como variable. La línea de la orden make se obtuvo a partir de:

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

Las macros ‘.Bk’ y ‘.Ek’ se explican en Agrupamientos.

Sintaxis general¶

El resultado será:

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:

El resultado será:

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,

Macro de dirección¶

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

Nombre del autor¶

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

Macro de argumento¶

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)¶

Modificador de orden¶

Variables definidas¶

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

Códigos errno (sólo sección dos)¶

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

Variables de entorno¶

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

Argumento de función¶

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

Declaración de funciones¶

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’ 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)¶

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:

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¶

‘.Ft’ no es invocable por otras macros.

Órdenes interactivas¶

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

Macro de nombre¶

La macro ‘.Nm’ es interpretada e invocable.

Opciones¶

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’ es interpretada e invocable.

Variables¶

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’ es interpretada e invocable. Es un error llamar a ‘.Xr’ sin argumentos.

Macro AT&T¶

Uso: .At [v6 | v7 | 32v | V.1 | V.4] ...

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

Macro BSD¶

La macro ‘.Bx’ es interpretada e invocable.

Macro FreeBSD¶

Uso: .Fx Versión.lanzamiento ...

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

Macro UNIX¶

La macro ‘.Ux’ es interpretada e invocable.

Macros de cierre y de entrecomillado¶

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:

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¶

Macro de eliminación de espacios¶

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¶

Referencias y citas¶

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¶

‘.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 ‘.Tn’ es interpretada y es invocable por otras macros.

Argumentos extendidos¶

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

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

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

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’.

Cabeceras de sección¶

.Sh NOMBRE

La macro ‘.Sh NOMBRE’ es obligatoria. Si no se especifica, los encabezados, pies de página y la disposición de página por omisión no se establecerán y el resultado será bastante desagradable. La sección NOMBRE consta de, al menos, tres ítems. El primero es la macro de nombre ‘.Nm’ que pone nombre al contenido de la página de manual. El segundo es la macro de descripción de nombre ‘.Nd’, que separa el nombre dado al contenido del tercer ítem, que es la descripción. La descripción debería ser lo más breve y clara posible ya que el espacio disponible es pequeño.

.Sh SINOPSIS

La sección SINOPSIS describe el uso típico de la materia de una página de manual. Las macros que se necesitan son ‘.Nm’, ‘.Cd’ y ‘.Fn’ (y, posiblemente las macros ‘.Fo’, ‘.Fc’, ‘.Fd’ y ‘.Ft’). La macro de nombre de función ‘.Fn’ se necesita para las secciones 2 y 3 de las páginas de manual. La macro de orden y de nombre general ‘.Nm’ se necesita para las secciones 1, 5, 6, 7 y 8. Los manuales de la sección 4 requieren ‘.Nm’, ‘.Fd’ o una macro ‘.Cd’ de uso de configuración de un dispositivo. Pueden se necesarias otras macros adicionales para producir una línea de sinopsis como las mostrada a continuación:

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

Se han usado las siguientes macros:

.Nm cat

.Op Fl benstuv

.Op Fl

.Ar

Nota: Las macros ‘.Op’, ‘.Fl’, y ‘.Ar’ reconocen el carácter de tubería ‘|’, por lo que una línea de órdenes como:

.Op Fl a | Fl b

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

.Sh DESCRIPCIÓN

En la mayoría de los casos, el primer texto de una sección DESCRIPCIÓN es un breve párrafo sobre la orden, función o fichero, seguido por una lista ordenada alfabéticamente de las opciones y de sus explicaciones respectivas. Para crear tal lista se usan las macros de comienzo de lista ‘.Bl’, elemento de lista ‘.It’ y final de lista ‘.El’ (vea Listas y columnas más abajo).

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

.Sh ENTORNO

La sección ENTORNO debería revelar cualesquiera variables de entorno relacionadas y dar pistas sobre su comportamiento y/o uso.

.Sh EJEMPLOS

Hay varias formas de crear ejemplos. Vea la sección EJEMPLOS que hay más abajo para más detalles.

.Sh FICHEROS

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

.Sh VÉASE TAMBIÉN

Las referencias a otras materias sobre el tema de la página de manual, y las referencias cruzadas a otras páginas de manual relevantes, deberían colocarse en la sección VÉASE TAMBIÉN. Las referencias cruzadas se especifican usando la macro ‘.Xr’. Las referencias cruzadas de la sección VÉASE TAMBIÉN deberían ordenarse primero por número de sección y, a continuación, coladas en orden alfabético y separadas por comas. Por ejemplo:

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

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

.Sh CONFORME A

Si la orden, función de biblioteca o fichero sigue una implementación específica como IEEE Std 1003.2 (“POSIX.2”) o ANSI X3.159-1989 (“ANSI C89”) debería hacerse notar aquí. Si la orden no sigue ningún estándar, su historia debería constar en la sección HISTORIA.

.Sh HISTORIA

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

.Sh AUTORES

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

.Sh DIAGNÓSTICOS

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

.Sh ERRORES

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

.Sh FALLOS

Los problemas ostensibles del tema van aquí...

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

.Sh DOMINIO DE LA ESTRUCTURA DE PÁGINA

Párrafos y espacios entre líneas.¶

.Pp

Se puede usar la orden de párrafo ‘.Pp’ para insertar una línea en blanco donde sea necesario. La macro no es necesaria tras una macro ‘.Sh’ o ‘.Ss’ o antes de una macro ‘.Bl’ (la macro ‘.Bl’ inserta un espacio vertical a menos que se use la opción -compact).

Agrupamientos¶

Ejemplos y visualizaciones¶

.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¶

.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¶

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.