NOMBRE¶
mdoc
—
Guía de referencia rápida para el
paquete de macros -mdoc
SINOPSIS¶
groff
-m
doc
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.
- xx
n
- Donde xx es un número
entre
4
n
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:
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,
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)