.\" Copyright (c) 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)mdoc.7	8.2 (Berkeley) 12/30/93
.\"	$Id: mdoc.7,v 1.5 2005/05/30 07:34:03 juan.piernas Exp $
.\"
.\" The December 30, 1993 version
.\" Modified by David A. Wheeler (dwheeler@ida.org) on 1999-07-11
.\" to conform to Linux.
.\"
.\" Translated on Wed 2004-07-28 by Jorge Rodriguez Garcia (A.K.A. Tiriel) <tiriel@users.sourceforge.net>
.\"
.Dd 11 julio 1999
.Dt MDOC 7
.Os Linux
.Sh NOMBRE
.Nm mdoc
.Nd Guía de referencia rápida para el paquete de macros
.Nm \-mdoc
.Sh SINOPSIS
.Nm groff
.Fl m Ns Ar doc
.Ar ficheros ...
.Sh DESCRIPCIÓN
El paquete
.Nm \-mdoc
es un conjunto de macros basadas en contenido y basadas en dominio
que se utilizan para formatear las páginas de manual de
.Bx .
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
.Xr mdoc.samples 7 .
.Pp
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
.Xr man 7 .
.Pp
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
.Nm \-mdoc
de otros paquetes de formateo en
.Xr troff.
.Sh DOMINIO DE ESTRUCTURA DE PÁGINA
.Ss Macros de Título
Para crear una página de manual válida, se requieren estas
tres macros, en este orden:
.Bl -tag -width "xxxx.Os OPERATINGxSYSTEM [version/release]" -compact
.It Li "\&.Dd  " Ar "Mes dia, año"
Fecha del documento.
.It Li "\&.Dt  " Ar "TITULO_DEL_DOCUMENTO [sección] [volúmen]"
Título, en mayúsculas.
.It Li "\&.Os  " Ar "SISTEMA_OPERATIVO [versión/revisión]"
Sistema Operativo
.Pq Tn BSD .
.El
.Ss Macros de Diseño de Página
Cabeceras de sección, saltos de párrafo, listas y visualizaciones.
.Bl -tag -width flag -compact
.It Li \&.Sh
Cabeceras de Sección.
Cabeceras válidas, en orden de presentación:
.Bl -tag -width "VALOR DEVUELTO" -compact
.It Ar NOMBRE
Sección de nombre, debe incluir las macros
.Ql \&.Nm
o
.Ql \&.Fn ,
y
.Ql \&.Nd
.It Ar SINOPSIS
Utilización.
.It Ar DESCRIPCIÓN
Descripción general, debe incluir
opciones y parámetros.
.It Ar VALOR DEVUELTO
Llamadas a funciones de las secciones dos y tres.
.It Ar ENTORNO
Describe las variables de entorno.
.It Ar FICHEROS
Ficheros asociados al tema.
.It Ar EJEMPLOS
Ejemplos y sugerencias.
.It Ar DIAGNÓSTICOS
Normalmente utilizada para los diagnósticos del interfaz
de dispositivo de la sección cuatro.
.It Ar ERRORES
Manejo de errores y señales de las secciones dos y tres.
.It Ar VÉASE TAMBIÉN
Referencias cruzadas y citas.
.It Ar CONFORME A
Conformidad a estándares, si viniera al caso.
.It Ar HISTORIA
Si no se puede aplicar un estándar, se debe
mostrar la historia del asunto.
.It Ar FALLOS
Defectos y advertencias.
.It Ar otros
Cabeceras personalizadas que se
pueden añadir a la discreción de autor.
.El
.It Li \&.Ss
Cabeceras de subsección.
.It Li \&.Pp
Salto de Párrafo.
Espacio vertical (una linea).
.It Li \&.D1
(D-one) Display-one.
Sangrar y visualizar una línea de texto.
.It Li \&.Dl
(D-ell) Display-one literal.
Sangrar y visualizar una línea de texto literal.
.It Li \&.Bd
Begin-display block.
Comenzar un bloque de visualización.
Opciones de visualización:
.Bl -tag -width "xoffset string " -compact
.It Fl ragged
Sin justificado (bordes desiguales).
.It Fl filled
Justificado.
.It Fl literal
Texto o código literal.
.It Fl file Ar nombre
Leer el
.Ar fichero
nombrado y visualizar.
.It Fl offset Ar cadena
Desplazamiento de visualización.
Valores de
.Ar cadena
aceptables:
.Bl -tag -width indent-two -compact
.It Ar left
Alinear el bloque a la izquierda (por defecto).
.It Ar center
Aproximar al margen central.
.It Ar indent
Seis espacios de anchura constante (una tabulación).
.It Ar indent-two
Dos tabulaciones.
.It Ar right
Alinea el bloque a la izquierda
a 2 pulgadas de la derecha.
.It Ar xx Ns Cm n
Donde
.Ar xx
es un número entre
.No \&4 Ns Cm n
y
.No \&9\&9 Ns Cm n .
.It Ar Aa
Donde
.Ar Aa
es un nombre de macro invocable.
.It Ar cadena
Se usa la anchura de
.Ar cadena.
.El
.El
.It Li \&.Ed
End-display. Finalizar visualización (se corresponde con \&.Bd).
.It Li \&.Bl
Begin-list.
Crear listas o columnas. Opciones:
.Bl -tag -width flag -compact
.It Ar Tipos de lista
.Bl -column xbullet -compact
.It Fl bullet Ta "Lista de puntos"
.It Fl item Ta "Lista sin etiquetar"
.It Fl enum Ta "Lista enumerada"
.It Fl tag Ta "Lista etiquetada"
.It Fl diag Ta "Lista de diagnóstico"
.It Fl hang Ta "Lista con etiquetas colgantes"
.It Fl ohang Ta "Lista con etiquetas sobresalientes"
.It Fl inset Ta "Lista con etiquetas insertadas o seguidas"
.El
.It Parámetros de lista
.Bl -tag -width "xcompact " -compact
.It Fl offset
(Todas las listas.) Véase
.Ql \&.Bd begin-display
más arriba.
.It Fl width
(Sólo listas
.Fl tag
y
.Fl hang.)
Véase
.Ql \&.Bd .
.It Fl compact
(Todas las listas.)
Suprime las líneas en blanco.
.El
.El
.It Li \&.El
End-list.
Final de lista.
.It Li \&.It
List item.
Elemento de lista.
.El
.Sh 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:
.Bl -tag -width ".Op Fl s Ar filex" -offset indent
.It Li "\&.Op Fl s Ar fichero"
Produce
.Op Fl s Ar fichero
.El
.Pp
En este ejemplo, la macro de cierre de opción
.Ql \&.Op
se analiza y llama a la macro de contenido invocable
.Ql \&Fl
que opera en el argumento
.Ql s
y luego llama a la macro de contenido invocable
.Ql \&Ar
que opera en el argumento
.Ql fichero .
Algunas macros pueden ser invocables pero no interpretadas y viceversa.
Estas macros se indican en las columnas
.Em interpretadas
e
.Em invocables
que aparecen más abajo.
.Pp
Si no se indica lo contrario, las macros de dominio de manual
comparten una sintaxis común.
.Pp
.Dl \&.Va argumento [\ .\ ,\ ;\ :\ (\ )\ [\ ]\ argumento \...\ ]
.Pp
.Sy Nota :
Los caracteres de puntuación de apertura y cierre sólo se reconocen
como tales cuando aparecen uno a uno.
La cadena
.Ql "),"
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
.Ql "] ) ,"
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
.Ql \e& .
Por ejemplo, la siguiente cadena,
.Bl -tag -width "&.Ar fichero1\ , fichero2\ , fichero3\ )\ ." -offset indent
.It Li "\&.Ar fichero1\ , fichero2\ , fichero3\ )\ ."
produce
.Ar fichero1 , fichero2 , fichero3 ) .
.El
.ne 1i
.Ss Macros de Dominio de Manual
.Bl -column "Name" "Parsed" Callable" -compact
.It Em Nombre	Analizada	Llamable	Descripción
.It Li \&Ad Ta Si Ta Si Ta "Dirección. (Esta macro puede quedar obsoleta.)"
.It Li \&An Ta Si Ta Si Ta "Nombre del Autor."
.It Li \&Ar Ta Si Ta Si Ta "Argumento en línea de órdenes."
.It Li \&Cd Ta \&No Ta \&No Ta "Declaración de configuración (sólo para la sección cuatro)."
.It Li \&Cm Ta Si Ta Si Ta "Modificador de argumento en línea de órdenes."
.It Li \&Dv Ta Si Ta Si Ta "Variable definida (código fuente)."
.It Li \&Er Ta Si Ta Si Ta "Número de error (código fuente)."
.It Li \&Ev Ta Si Ta Si Ta "Variable de entorno."
.It Li \&Fa Ta Si Ta Si Ta "Argumento de función."
.It Li \&Fd Ta Si Ta Si Ta "Declaración de función."
.It Li \&Fn Ta Si Ta Si Ta "Llamada a función (También .Fo y .Fc)."
.It Li \&Ic Ta Si Ta Si Ta "Orden interactiva."
.It Li \&Li Ta Si Ta Si Ta "Texto literal."
.It Li \&Nm Ta Si Ta Si Ta "Nombre de orden."
.It Li \&Op Ta Si Ta Si Ta "Opción (también .Oo y .Oc)."
.It Li \&Ot Ta Si Ta Si Ta "Tipo de función en estilo antiguo (sólo Fortran)."
.It Li \&Pa Ta Si Ta Si Ta "Ruta o nombre de fichero."
.It Li \&St Ta Si Ta Si Ta "Estándares (-p1003.2, -p1003.1 o -ansiC)"
.It Li \&Va Ta Si Ta Si Ta "Nobre de variable."
.It Li \&Vt Ta Si Ta Si Ta "Tipo de variable (sólo Fortran)."
.It Li \&Xr Ta Si Ta Si Ta "Referencia cruzada a página de manual."
.El
.Ss Macros de Dominio de Texto General
.Bl -column "Name" "Parsed" Callable" -compact
.It Em "Nombre	Analizada	Llamable	Descripción"
.It Li \&%A Ta Si Ta \&No Ta "Referencia al autor."
.It Li \&%B Ta Si Ta Si Ta "Referencia al título del libro."
.It Li \&%\&C Ta \&No Ta \&No Ta "Referencia al lugar de publicación (ciudad)."
.It Li \&%\&D Ta \&No Ta \&No Ta "Referencia a la fecha."
.It Li \&%J Ta Si Ta Si Ta "Referencia al título de la revista."
.It Li \&%N Ta \&No Ta \&No Ta "Referencia al número del artículo."
.It Li \&%\&O Ta \&No Ta \&No Ta "Referencia a información opcional."
.It Li \&%P Ta \&No Ta \&No Ta "Referencia al(los) número(s) de página."
.It Li \&%R Ta \&No Ta \&No Ta "Referencia al nombre del informe."
.It Li \&%T Ta Si Ta Si Ta "Referencia al título del artículo."
.It Li \&%V Ta \&No Ta \&No Ta "Referencia al volumen."
.It Li \&Ac Ta Si Ta Si Ta "Cierre de comillas de ángulo."
.It Li \&Ao Ta Si Ta Si Ta "Apertura de comillas de ángulo."
.It Li \&Ap Ta Si Ta Si Ta "Apóstrofo."
.It Li \&Aq Ta Si Ta Si Ta "Comillas de ángulo"
.It Li \&At Ta \&No Ta \&No Ta Tn "AT&T UNIX"
.It Li \&Bc Ta Si Ta Si Ta "Cierre de corchete."
.It Li \&Bf Ta \&No Ta \&No Ta "Comienzo de modo de fuente."
.It Li \&Bo Ta Si Ta Si Ta "Apertura de corchete."
.It Li \&Bq Ta Si Ta Si Ta "Corchetes."
.It Li \&Bx Ta Si Ta Si Ta Bx .
.It Li \&Db Ta \&No Ta \&No Ta "Depurar (la opción por defecto es \\*qoff\\*q)"
.It Li \&Dc Ta Si Ta Si Ta "Cierre de comillas dobles."
.It Li \&Do Ta Si Ta Si Ta "Apertura de comillas dobles."
.It Li \&Dq Ta Si Ta Si Ta "Comillas dobles."
.It Li \&Ec Ta Si Ta Si Ta "Cierre de la cadena de entrecomillado."
.It Li \&Ef Ta \&No Ta \&No Ta "Fin de modo de fuente."
.It Li \&Em Ta Si Ta Si Ta "Acento (inglés tradicional)."
.It Li \&Eo Ta Si Ta Si Ta "Apertura de la cadena de entrecomillado."
.It Li \&Fx Ta \&No Ta \&No Ta Tn "Sistema operativo FreeBSD"
.It Li \&No Ta Si Ta Si Ta "Texto normal (no-op)."
.It Li \&Ns Ta Si Ta Si Ta "Sin espacio."
.It Li \&Pc Ta Si Ta Si Ta "Cierre de paréntesis."
.It Li \&Pf Ta Si Ta \&No Ta "Cadena prefijo."
.It Li \&Po Ta Si Ta Si Ta "Apertura de paréntesis."
.It Li \&Pq Ta Si Ta Si Ta "Paréntesis."
.It Li \&Qc Ta Si Ta Si Ta "Cierre de dobles comillas rectas."
.It Li \&Ql Ta Si Ta Si Ta "Literal entrecomillado."
.It Li \&Qo Ta Si Ta Si Ta "Apertura de dobles comillas rectas."
.It Li \&Qq Ta Si Ta Si Ta "Dobles comillas rectas."
.It Li \&Re Ta \&No Ta \&No Ta "Fin de referencia."
.It Li \&Rs Ta \&No Ta \&No Ta "Comienzo de referencia."
.It Li \&Rv Ta \&No Ta \&No Ta "Valores devueltos (sólo secciones dos y tres)."
.It Li \&Sc Ta Si Ta Si Ta "Cierre de comillas simples."
.It Li \&So Ta Si Ta Si Ta "Apertura de comillas simples."
.It Li \&Sq Ta Si Ta Si Ta "Comillas simples."
.It Li \&Sm Ta \&No Ta \&No Ta "Modo de espacio (la opción por defecto es \\*qon\\*q)"
.It Li \&Sx Ta Si Ta Si Ta "Referencia cruzada a sección."
.It Li \&Sy Ta Si Ta Si Ta "Simbólico (inglés tradicional)."
.It Li \&Tn Ta Si Ta Si Ta "Nombre de tipo o marca (mayúsculas pequeñas)."
.It Li \&Ux Ta Si Ta Si Ta Ux
.It Li \&Xc Ta Si Ta Si Ta "Cierre de lista de argumentos extendida."
.It Li \&Xo Ta Yes Ta Yes Ta "Apertura de lista de argumentos extendida."
.El
.\" .It Sy \&Hf Ta \&No Ta \&No Ta "Include file with header"
.Pp
Los nombres de macro que acaban en
.Ql q
entrecomillan los elementos restantes de la lista de argumentos.
Los nombres de macro que acaban en
.Ql 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
.Ql c .
Las macros de cierre pueden estar anidadas y
están limitadas a ocho argumentos.
.Pp
Nota: las macros para las listas de argumentos extendidas
.Pf ( Ql \&.Xo ,
.Ql \&.Xc )
y las macros de cierre de función
.Pf ( Ql \&.Fo ,
.Ql \&.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
.Xr troff
de nueve argumentos.
.Pp
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
.Xr man 7
para más información sobre estas macros.
.Sh CONFIGURACIÓN
Para la configuración específica del paquete de macros,
véase el archivo
.Pa /usr/src/share/tmac/README .
.Sh FICHEROS
.Bl -tag -width "tmac.doc-ditroff" -compact
.It Pa tmac.doc
Macros de dominio de manual y de texto general.
.It Pa tmac.doc-common
Macros estructurales comunes y definiciones.
.It Pa tmac.doc-nroff
Fichero de estilo
.Xr nroff
dependiente de la instalación local.
.It Pa tmac.doc-ditroff
Fichero de estilo
.Xr troff
dependiente de la instalación local.
.It Pa tmac.doc-syms
Definiciones especiales (como la macro de estándares).
.El
.Sh "VÉASE TAMBIÉN"
.Xr mdoc.samples 7 ,
.Xr man 7