NOMBRE¶
mdoc —
Guía de referencia
rápida para el paquete de macros -mdoc
SINOPSIS¶
groff -mdoc
ficheros ...
DESCRIPCIÓN¶
El paquete
-mdoc es un conjunto de macros basadas en contenido
y basadas en dominio que se utilizan para formatear las páginas de manual
de
BSD. Los nombres de las macros y sus significados
están listados más abajo para una referencia rápida; para una
explicación más detallada sobre cómo utilizar el paquete,
véase el tutorial
mdoc.samples(7).
Nótese que éste no es el paquete de macros habitual para la
documentación de Linux, aunque se utiliza para la documentación de
bastantes programas de uso extendido; véase
man(7).
Las macros se describen en dos grupos, el primero incluye las macros del
diseño estructural y físico de la página. El segundo contiene
las macros de manual y de dominio de texto general que diferencian al paquete
-mdoc de otros paquetes de formateo en
troff.
DOMINIO DE ESTRUCTURA
DE PÁGINA¶
Macros de Título¶
Para crear una página de manual válida, se requieren estas tres
macros, en este orden:
.Dd
Mes dia, año
- Fecha del documento.
.Dt
TITULO_DEL_DOCUMENTO [sección]
[volúmen]
- Título, en mayúsculas.
.Os
SISTEMA_OPERATIVO [versión/revisión]
- Sistema Operativo (BSD).
Macros de Diseño
de Página¶
Cabeceras de sección, saltos de párrafo, listas y visualizaciones.
.Sh
- Cabeceras de Sección. Cabeceras válidas, en orden
de presentación:
- NOMBRE
- Sección de nombre, debe incluir las macros
‘
.Nm
’ o
‘.Fn
’, y
‘.Nd
’
- SINOPSIS
- Utilización.
- DESCRIPCIÓN
- Descripción general, debe incluir opciones y
parámetros.
- VALOR
DEVUELTO
- Llamadas a funciones de las secciones dos y tres.
- ENTORNO
- Describe las variables de entorno.
- FICHEROS
- Ficheros asociados al tema.
- EJEMPLOS
- Ejemplos y sugerencias.
- DIAGNÓSTICOS
- Normalmente utilizada para los diagnósticos del
interfaz de dispositivo de la sección cuatro.
- ERRORES
- Manejo de errores y señales de las secciones dos y
tres.
- VÉASE
TAMBIÉN
- Referencias cruzadas y citas.
- CONFORME
A
- Conformidad a estándares, si viniera al caso.
- HISTORIA
- Si no se puede aplicar un estándar, se debe
mostrar la historia del asunto.
- FALLOS
- Defectos y advertencias.
- otros
- Cabeceras personalizadas que se pueden añadir a la
discreción de autor.
.Ss
- Cabeceras de subsección.
.Pp
- Salto de Párrafo. Espacio vertical (una linea).
.D1
- (D-one) Display-one. Sangrar y visualizar una línea de
texto.
.Dl
- (D-ell) Display-one literal. Sangrar y visualizar una
línea de texto literal.
.Bd
- Begin-display block. Comenzar un bloque de
visualización. Opciones de visualización:
- -ragged
- Sin justificado (bordes desiguales).
- -filled
- Justificado.
- -literal
- Texto o código literal.
- -file
nombre
- Leer el fichero nombrado y
visualizar.
- -offset
cadena
- Desplazamiento de visualización. Valores de
cadena aceptables:
- left
- Alinear el bloque a la izquierda (por
defecto).
- center
- Aproximar al margen central.
- indent
- Seis espacios de anchura constante (una
tabulación).
- indent-two
- Dos tabulaciones.
- right
- Alinea el bloque a la izquierda a 2 pulgadas de la
derecha.
- xxn
- Donde xx es un número
entre 4n y
99n.
- Aa
- Donde Aa es un nombre de
macro invocable.
- cadena
- Se usa la anchura de
cadena.
.Ed
- End-display. Finalizar visualización (se corresponde
con .Bd).
.Bl
- Begin-list. Crear listas o columnas. Opciones:
- Tipos de
lista
-
-bullet |
Lista de
puntos |
-item |
Lista sin
etiquetar |
-enum |
Lista
enumerada |
-tag |
Lista
etiquetada |
-diag |
Lista de
diagnóstico |
-hang |
Lista con
etiquetas colgantes |
-ohang |
Lista con
etiquetas sobresalientes |
-inset |
Lista con
etiquetas insertadas o seguidas |
- Parámetros de
lista
-
- -offset
- (Todas las listas.) Véase
‘
.Bd begin-display
’ más
arriba.
- -width
- (Sólo listas -tag y
-hang.) Véase
‘
.Bd
’.
- -compact
- (Todas las listas.) Suprime las líneas en
blanco.
.El
- End-list. Final de lista.
.It
- List item. Elemento de lista.
MACROS DE
MANUAL Y DE DOMINIO DE TEXTO GENERAL¶
Las macros de manual y de dominio de texto general son especiales en el sentido
de que la mayoría de ellas se analizan o interpretan (`parse') en
búsqueda de macros invocables, por ejemplo:
.Op Fl s Ar
fichero
- Produce [-s
fichero]
En este ejemplo, la macro de cierre de opción
‘
.Op
’ se analiza y llama a la macro de
contenido invocable ‘
Fl
’ que opera en el
argumento ‘
s
’ y luego llama a la macro de
contenido invocable ‘
Ar
’ que opera en el
argumento ‘
fichero
’. Algunas macros pueden
ser invocables pero no interpretadas y viceversa. Estas macros se indican en
las columnas
interpretadas e
invocables
que aparecen más abajo.
Si no se indica lo contrario, las macros de dominio de manual comparten una
sintaxis común.
.Va argumento
[ . , ; : ( ) [ ] argumento
... ]
Nota: Los caracteres de puntuación de apertura y cierre
sólo se reconocen como tales cuando aparecen uno a uno. La cadena
‘
),
’ no se reconoce como una
puntuación y se mostrará con un espacio en blanco al principio y con
cualquiera que sea la fuente usada por la macro invocadora. La lista de
argumentos ‘
] ) ,
’ se reconoce como tres
caracteres de puntuación secuenciales y no se muestra un espacio en
blanco entre los caracteres y el argumento previo (si hay alguno). El
significado especial de un caracter de puntuación puede eliminarse con la
cadena ‘
\&
’. Por ejemplo, la siguiente
cadena,
.Ar
fichero1 , fichero2 , fichero3 ) .
- produce fichero1,
fichero2, fichero3).
Macros de Dominio de Manual¶
Nombre |
Analizada |
Llamable |
Descripción |
Ad |
Si |
Si |
Dirección. (Esta
macro puede quedar obsoleta.) |
An |
Si |
Si |
Nombre del Autor. |
Ar |
Si |
Si |
Argumento en línea de
órdenes. |
Cd |
No |
No |
Declaración de
configuración (sólo para la sección cuatro). |
Cm |
Si |
Si |
Modificador de argumento
en línea de órdenes. |
Dv |
Si |
Si |
Variable definida
(código fuente). |
Er |
Si |
Si |
Número de error
(código fuente). |
Ev |
Si |
Si |
Variable de entorno. |
Fa |
Si |
Si |
Argumento de
función. |
Fd |
Si |
Si |
Declaración de
función. |
Fn |
Si |
Si |
Llamada a función
(También .Fo y .Fc). |
Ic |
Si |
Si |
Orden interactiva. |
Li |
Si |
Si |
Texto literal. |
Nm |
Si |
Si |
Nombre de orden. |
Op |
Si |
Si |
Opción (también
.Oo y .Oc). |
Ot |
Si |
Si |
Tipo de función en
estilo antiguo (sólo Fortran). |
Pa |
Si |
Si |
Ruta o nombre de
fichero. |
St |
Si |
Si |
Estándares (-p1003.2,
-p1003.1 o -ansiC) |
Va |
Si |
Si |
Nobre de variable. |
Vt |
Si |
Si |
Tipo de variable
(sólo Fortran). |
Xr |
Si |
Si |
Referencia cruzada a
página de manual. |
Macros de Dominio de
Texto General¶
Nombre |
Analizada |
Llamable |
Descripción |
%A |
Si |
No |
Referencia al autor. |
%B |
Si |
Si |
Referencia al título
del libro. |
%C |
No |
No |
Referencia al lugar de
publicación (ciudad). |
%D |
No |
No |
Referencia a la
fecha. |
%J |
Si |
Si |
Referencia al título
de la revista. |
%N |
No |
No |
Referencia al número
del artículo. |
%O |
No |
No |
Referencia a
información opcional. |
%P |
No |
No |
Referencia al(los)
número(s) de página. |
%R |
No |
No |
Referencia al nombre del
informe. |
%T |
Si |
Si |
Referencia al título
del artículo. |
%V |
No |
No |
Referencia al
volumen. |
Ac |
Si |
Si |
Cierre de comillas de
ángulo. |
Ao |
Si |
Si |
Apertura de comillas de
ángulo. |
Ap |
Si |
Si |
Apóstrofo. |
Aq |
Si |
Si |
Comillas de
ángulo |
At |
No |
No |
AT&T UNIX |
Bc |
Si |
Si |
Cierre de corchete. |
Bf |
No |
No |
Comienzo de modo de
fuente. |
Bo |
Si |
Si |
Apertura de corchete. |
Bq |
Si |
Si |
Corchetes. |
Bx |
Si |
Si |
BSD. |
|
Li Db |
No |
No |
Depurar (la opción
por defecto es \*qoff\*q) |
Dc |
Si |
Si |
Cierre de comillas
dobles. |
Do |
Si |
Si |
Apertura de comillas
dobles. |
Dq |
Si |
Si |
Comillas dobles. |
Ec |
Si |
Si |
Cierre de la cadena de
entrecomillado. |
Ef |
No |
No |
Fin de modo de
fuente. |
Em |
Si |
Si |
Acento (inglés
tradicional). |
Eo |
Si |
Si |
Apertura de la cadena de
entrecomillado. |
Fx |
No |
No |
Sistema operativo
FreeBSD |
No |
Si |
Si |
Texto normal (no-op). |
Ns |
Si |
Si |
Sin espacio. |
Pc |
Si |
Si |
Cierre de
paréntesis. |
Pf |
Si |
No |
Cadena prefijo. |
Po |
Si |
Si |
Apertura de
paréntesis. |
Pq |
Si |
Si |
Paréntesis. |
Qc |
Si |
Si |
Cierre de dobles comillas
rectas. |
Ql |
Si |
Si |
Literal
entrecomillado. |
Qo |
Si |
Si |
Apertura de dobles
comillas rectas. |
Qq |
Si |
Si |
Dobles comillas
rectas. |
Re |
No |
No |
Fin de referencia. |
Rs |
No |
No |
Comienzo de
referencia. |
Rv |
No |
No |
Valores devueltos
(sólo secciones dos y tres). |
Sc |
Si |
Si |
Cierre de comillas
simples. |
So |
Si |
Si |
Apertura de comillas
simples. |
Sq |
Si |
Si |
Comillas simples. |
Sm |
No |
No |
Modo de espacio (la
opción por defecto es \*qon\*q) |
Sx |
Si |
Si |
Referencia cruzada a
sección. |
Sy |
Si |
Si |
Simbólico
(inglés tradicional). |
Tn |
Si |
Si |
Nombre de tipo o marca
(mayúsculas pequeñas). |
Ux |
Si |
Si |
UNIX |
Xc |
Si |
Si |
Cierre de lista de
argumentos extendida. |
Xo |
Yes |
Yes |
Apertura de lista de
argumentos extendida. |
Los nombres de macro que acaban en ‘
q
’
entrecomillan los elementos restantes de la lista de argumentos. Los nombres
de macro que acaban en ‘
o
’ comienzan un
entrecomillado que puede ocupar más de una línea de entrada y se
cierra con el nombre de macro correspondiente acabado en
‘
c
’. Las macros de cierre pueden estar
anidadas y están limitadas a ocho argumentos.
Nota: las macros para las listas de argumentos extendidas
(‘
.Xo
’,
‘
.Xc
’) y las macros de cierre de
función (‘
.Fo
’,
‘
.Fc
’) son irregulares. Las macros para
las listas extendidas se usan cuando el número de argumentos de la macro
excederían la limitación de
troff de nueve
argumentos.
Las macros UR (comenzar una referencia a hipertexto URI/URL), UE (terminar la
referencia), y UN (identificar un destino para una referencia) también
están disponibles. Véase
man(7) para más
información sobre estas macros.
CONFIGURACIÓN¶
Para la configuración específica del paquete de macros, véase el
archivo
/usr/src/share/tmac/README.
FICHEROS¶
- tmac.doc
- Macros de dominio de manual y de texto general.
- tmac.doc-common
- Macros estructurales comunes y definiciones.
- tmac.doc-nroff
- Fichero de estilo nroff dependiente de la
instalación local.
- tmac.doc-ditroff
- Fichero de estilo troff dependiente de la
instalación local.
- tmac.doc-syms
- Definiciones especiales (como la macro de
estándares).
VÉASE TAMBIÉN¶
mdoc.samples(7),
man(7)