table of contents
- NOMBRE
- SINOPSIS
- DESCRIPCIÓN
- PRIMEROS PASOS
- IDIOSINCRASIAS DE TROFF
- ANATOMÍA DE UNA PÁGINA DE MANUAL
- MACROS DE TÍTULO
- INTRODUCCIÓN A LOS DOMINIOS DE MANUAL Y DE TEXTO GENERAL
- DOMINIO DE MANUAL
- DOMINIO DE TEXTO GENERAL
- DOMINIO DE ESTRUCTURA DE PÁGINA
- CADENAS PREDEFINIDAS
- DIAGNÓSTICOS
- GROFF, TROFF y NROFF
- FICHEROS
- VÉASE TAMBIÉN
- FALLOS
other languages
MDOC.SAMPLES(7) | Miscellaneous Information Manual | MDOC.SAMPLES(7) |
NOMBRE¶
mdoc.samples
—
tutorial para escribir manuales
BSD con
-mdoc
SINOPSIS¶
man mdoc.samples
DESCRIPCIÓN¶
Éste es un tutorial para escribir páginas de manual BSD con el paquete de macros-mdoc
, un paquete de formateo basado en
contenidos y
dominios para
troff(1). Su predecesor, el paquete
-man(7), trata el diseño de las
páginas dejando la manipulación de las fuentes y otros detalles
de composición al autor. En -mdoc
,
las macros para el diseño de las páginas de manual constituyen
el dominio de estructura de página que
consta de macros para títulos, encabezados de sección,
visualizaciones y listas; esencialmente, elementos que afectan a la
posición física del texto en la página formateada.
Además del dominio de estructura de página, hay dos dominios
más: el dominio de manual y el dominio de texto general. El dominio de
texto general se define como macros que realizan tareas tales como
entrecomillar o emfatizar trozos de texto. El dominio de manual se define como
macros que son un subconjunto del lenguaje informal usado día a
día para describir órdenes, rutinas y ficheros
BSD relacionados. Las macros en el dominio de manual
manejan nombres de órdenes, argumentos y opciones de la línea de
órdenes, nombres de función, parámetros de
función, nombres de ruta, variables, referencias cruzadas a otras
páginas de manual, etc. Estos elementos del dominio tienen valor tanto
para el autor como para el futuro usuario de la página de manual. Es de
esperar que la consistencia ganada a través del conjunto de manuales
proporcione una traducción más fácil a futuras
herramientas de documentarión.
En el conjunto de páginas de manual de UNIX se
hace referencia a una entrada de manual simplemente como «página
man», sin tener en cuenta la longitud real y sin intenciones sexistas.
PRIMEROS PASOS¶
Ya que una persona lee normalmente un tutorial cuando desea usar el material inmediatamente, se ha supuesto que el usuario de este manual puede ser algo impaciente. El material presentado en lo que resta de este documento se resume como sigue:- 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.
- ANATOMÍA DE UNA PÁGINA DE MANUAL
- Modelo de una página de manual.
- MACROS DE TÍTULO.
- INTRODUCCIÓN A LOS DOMINIOS DE MANUAL Y DE TEXTO GENERAL.
- Lo que hay en un nombre....
- Sintaxis general.
- 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.
- 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.
- 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.
- CADENAS PREDEFINIDAS
- DIAGNÓSTICOS
- GROFF, TROFF Y NROFF
- FICHEROS
- 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
\&
’:
- [Fl s Ar bytes]
- se obtiene mediante
.Op \&Fl s \&Ar bytes
Fl
’ y
‘Ar
’ no se interpretan como macros. A lo
largo de este documento y en el manual de referencia rápida
mdoc(7) que le acompaña, las macros cuyas
listas de argumentos se analizan en busca de argumentos invocables se
referencian como interpretadas y las macros que
se pueden invocar desde una lista de argumentos se referencian como
invocables. Esto es una
metedura de pata técnica ya que casi todas
las macros de -mdoc
son interpretadas pero,
ya que era engorroso referirse constantemente a las macros como invocables y
como capaces de invocar a otras manos, se ha decidido usar el término
«interpretado».
Paso de espacios en blanco en un argumento¶
Algunas veces se desea pasar como argumento una cadena de caracteres que contiene uno o más espacios en blanco. Esto puede ser necesario para vencer el límite de nueve argumentos o para especificar argumentos para macros que esperan una disposición particular de los elementos de una lista de argumentos. Por ejemplo, la macro de función ‘.Fn
’ espera que el primer argumento sea
el nombre de una función y que cualesquiera argumentos restantes sean
parámetros de función. Siguiendo la forma en la que ANSI C
establece la declaración de los parámetros de función en
la lista de parámetros que se especifica entre paréntesis, se
garantiza que cada parámetro sea, al menos, una cadena de dos palabras.
Por ejemplo, int foo.
Hay dos formas posibles de pasar un argumento que contiene un espacio.
Nota sobre la implementación:
desafortunadamente, la forma más conveniente de pasar espacios entre
comillas, reasignando los argumentos individuales antes de realizar la
interpretación de la línea, era bastante costosa de implementar
en cuanto a velocidad y espacio para todas las macros
troff de AT&T. No es costosa para
groff pero, por el bien de la transportabilidad,
ha sido limitada a las siguientes macros que más la necesitan:
Cd
- Declaración de configuración (sección 4 SINOPSIS).
Bl
- Comienzo de lista (para el indicador del ancho).
Em
- Texto emfatizado.
Fn
- Funciones (secciones dos y cuatro).
It
- Elementos de una lista.
Li
- Texto literal.
Sy
- Texto simbólico.
%B
- Titulos de libro.
%J
- Nombres de revista.
%O
- Notas opcionales para una referencia.
%R
- Título de informe (en una referencia).
%T
- Título de artículo en un libro o revista.
\
’, 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 \*qchar *str\*q
’
\
’ o las
comillas, ‘.Fn
’ vería tres
argumentos y el resultado sería
fetch
(char,
*str)
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
.Dd
, .Os
,
.Dt
); la fecha del documento, el sistema operativo
para el que el fuente de la página de manual o tema se ha desarrollado
o modificado y el título de la página de manual
(en mayúsculas) junto con la
sección del manual a la que pertenece la página. Estas macros
idenfican a la página y se discuten más abajo en
MACROS DE
TÍTULO.
El resto de elementos de la plantilla son cabeceras de sección
(.Sh
); de las que
NOMBRE,
SINOPSIS y
DESCRIPCIÓN son
obligatorias. Las cabeceras se discuten en
DOMINIO
DE ESTRUCTURA DE PÁGINA, tras la presentación del
DOMINIO DE MANUAL. Para
mostrar el uso de las macros de diseño de página, se usan varias
macros de contenido; se recomienda informarse sobre las macros de contenido
antes de hacerlo sobre las macros de diseño de página.
MACROS DE TÍTULO¶
Las macros de título son la primera parte del dominio de la estructura de página, pero las presentamos en primer lugar y de forma separada para aquellos que deseen empezar a escribir una página de manual ya. Tres macros de cabecera indican el título del documento o de la página de manual, el sistema operativo y la fecha de la autoría. Estas macros se invocan sólo una vez justo al principio del documento y sólo se usan para construir los encabezados y los pies de página..Dt TÍTULO_DOCUMENTO nº_sección [volumen]
- El título del documento es el tema de la página de manual y
debe estar en MAYÚSCULAS debido a limitaciones de troff. El
número de sección puede ser 1, ..., 8 y, si se
especifica, se puede omitir el título del volumen. Un título
de volumen puede ser arbitrario o uno de los siguientes:
AMD
Documentos del Manual Ancestral de UNIX SMM
Manual del Administrador de Sistemas de UNIX URM
Manual de Referencia de UNIX PRM
Manual del Programador de UNIX 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:
o
.Os BSD 4.3
o, para algo producido localmente,.Os FreeBSD 2.2
El valor por omisión de Berkeley, ‘.Os CS Department
.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
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
make
- [] [
-eiknqrstv
] [-D
variable] [-d
opciones] [-f
makefile] [-I
directorio] [-j
max_tareasvariable=valor] [objetivo ...]
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
.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),
sptr,
ptr),
.Li sptr , ptr ) ,
sptr
,
ptr
),
\&
’.
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:
{+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}
\&
’. 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)),
.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)),
.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)),
.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
’ 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
]
.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
’ 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
.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)
.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
’ 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 \*qint align\*q \*qconst * char *sptrs\*q
,- int
align
(const * char *sptrs),
.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
int
res_mkquery
(int op,
char *dname, int
class, int type,
char *data, int
datalen, struct rrec *newrr,
char *buf, int
buflen);.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
’ 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
.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]
.Oc
’ y
‘.Oo
’:
.Oo .Op Fl k Ar kilobytes .Op Fl i Ar intervalo .Op Fl c Ar total .Oc
[]
[]
[]
]
Las macros ‘-k
kilobytes-i
intervalo-c
total.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).
.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])),
.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
’ 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
’ no
es interpretada y no es invocable. Como mucho
acepta dos argumentos.
Macro BSD¶
Uso: .Bx [Versión/lanzamiento]
...
.Bx
’ es interpretada e
invocable.
Macro FreeBSD¶
Uso: .Fx Versión.lanzamiento ...
.Fx 2.2 .
- FreeBSD 2.2.
.Fx
’ no
es es interpretada y no es invocable. Como
mucho acepta dos argumentos.
Macro UNIX¶
Uso: .Ux ...
.Ux
- UNIX
.Ux
’ es interpretada e
invocable.
Macros de cierre y de entrecomillado¶
El concepto de cierre (`enclosure') es similar al de entrecomillado. El objeto es el de encerrar una o más cadenas entre un par de caracteres como comillas o paréntesis. Los términos entrecomillado y cierre se usan indistintamente a lo largo de este documento. La mayoría de las macros de cierre de una línea terminan en una letra minúscula ‘q
’ que alude al entrecomillado
(`quoting'), aunque hay algunas irregularidades. Para cada macro de cierre
también hay un par de macros de apertura y cierre que terminan en las
letras minúsculas ‘o
’ y
‘c
’ respectivamente. Estas macros se
pueden usar a través de una o más líneas de texto y,
aunque tienen limitaciones de anidamiento, las macros de entrecomillado de una
línea se pueden usar dentro de ellas.
Comilla | Cierre | Apertura | Función | Resultado | |
.Aq | .Ac | .Ao | Cierre entre ángulos | <cadena> | |
.Bq | .Bc | .Bo | Cierre entre corchetes | [cadena] | |
.Dq | .Dc | .Do | Comillas dobles | ``cadena'' | |
.Ec | .Eo | Encerrar cadena (entre XX) | XXcadenaXX | ||
.Pq | .Pc | .Po | Cierre entre paréntesis | (cadena) | |
.Ql | Literal entrecomillado | `st' o cadena | |||
.Qc | .Qo | Comillas dobles rectas | cadena | ||
.Sq | .Sc | .So | Comillas simples | `cadena' |
.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.
.Ns
’ (no space) realiza la función de sufijo análoga.
.Aq
- ⟨⟩
.Aq Ar ctype.h ) ,
- ⟨ctype.h⟩),
.Bq
- []
.Bq Em griego , francés .
- [griego, francés].
.Dq
- “”
.Dq cadena abc .
- “cadena abc”.
.Dq ´^[A-Z]´
- “´^[A-Z]´”
.Ql man mdoc
- ‘
man mdoc
’ .Qq
- “”
.Qq cadena ) ,
- “cadena”),
.Qq cadena Ns ),
- “cadena),”
.Sq
- ‘’
.Sq cadena
- ‘cadena’
.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
[]
-I
directorio
.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.
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).
%
’ 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
’ 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
- Ioperación\ncuenta\n
.Sm off .It Cm S No / Ar anterior_patrón Xo .No / Ar nuevo_patrón .No / Op Cm g .Xc .Sm on
S
/anterior_patrón/nuevo_patrón/[]g
.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
.ifndef
[!]variable [operador variable ...]
.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:Se han usado las siguientes macros:cat
[] [-benstuv
] file ...-
.Nm cat
.Op Fl benstuv
.Op Fl
Nota: Las macros ‘.Ar
.Op
’, ‘.Fl
’, y ‘.Ar
’ reconocen el carácter de tubería ‘|
’, por lo que una línea de órdenes como:no se desmadrará. Troff normalmente interpreta | como un operador especial. Vea CADENAS PREDEFINIDAS para un carácter | usable en otras situaciones..Op Fl a | Fl b
- .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).
.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í...
.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.
Lo anterior se ha obtenido mediante:
-ldghfstru
.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.Lo anterior se ha obtenido con:% ls -ldg /usr/local/bin
.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:El tipo de visualización debe ser uno de los cuatro tipos siguientes y puede llevar un indicador de desplazamiento para sangrado:.Bd tipo-visualización [-offset valor_desplazamiento] [-compact]
-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)),
.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.La macro ‘Uso: .Li argumento ...
.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
.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:El modo de fuente debe ser uno de los siguientes tres tipos:.Bf modo-fuente
- .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 ítem uno viene aquí.
- Y el ítem dos aquí.
- El tercer y último ítem viene aquí.
.Bl -bullet -compact .It La viñeta uno viene aquí. .It La viñeta dos aquí. .El
- 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 ‘
’. La macro ‘-ohang
.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.
.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
- 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.
.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
- 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)
.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
-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
\*qint mkfifo\*q- de nuevo, establece el ancho a la anchura constante de la cadena dada.
.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 | pi |
Ne |
!= | ≠ |
Le |
<= | ≤ |
Ge |
>= | ≥ |
Lt |
< | > |
Gt |
> | < |
Pm |
+- | ± |
If |
infinity | infinity |
Na |
NaN | NaN |
Ba |
| | | |
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]
aC
’ que debería ser
‘\&aC
’ para funcionar):
.Db on .Op Fl aC Ar file ) .Db off
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
.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
\&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
-T
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 nroff no sean adecuados para obtener
una copia impresa. Existe un registro de nombre
‘cR
’ que se puede establecer a cero en
el fichero de estilo de la instalación local
/usr/src/share/tmac/doc-nroff para
restaurar el comportamiento anterior.
FICHEROS¶
- /usr/share/tmac/tmac.doc
- paquete de macros de manual
- /usr/share/misc/mdoc.template
- plantilla para escribir una página de manual
- /usr/share/examples/mdoc/*
- varias páginas de manual de ejemplo
VÉASE TAMBIÉN¶
man(1), troff(1), mdoc(7)FALLOS¶
Todavía no se han resuelto la inserción indeseada de guiones en los guiones de un argumento de opción, lo que produce contratiempos ocasionales (saltos de línea en los guiones) en la sección DESCRIPCIÓN. Las cadenas predefinidas no aparecen en la documentación. No se ha añadido la sección 3f a las rutinas de cabecera. Se debería cambiar la fuente de ‘.Nm
’ en la sección
NOMBRE.
Es necesario añadir una comprobación a
‘.Fn
’ para evitar separaciones si la
longitud de la línea es demasiado corta. Ocasionalmente separa el
último paréntesis y algunas veces produce un resultado absurdo
cuando una línea se encuentra en modo de relleno.
El método usado cuando se usa nroff para evitar los saltos de
página de cabeceras y pies de página (distintos a la cabecera y
al pie de página iniciales) inserta ocasionalmente una línea
parcialmente rellena (vacía) en lo que sería el final de la
página.
Las macros de lista y visualización no hacen ningún tipo de
agrupamiento y desde luego deberían ser capaces de ello.Diciembre 30, 1993 | Debian |