MAN(7)

NOMBRE
man - macros para formatear páginas del manual

SINOPSIS
groff -Tacsii -man fichero ...

groff -Tps -man fichero ...

man [sección] título

DESCRIPCION
Esta página del manual describe el paquete de macros groff tmac.an. El programador debe usar este paquete de macros cuando escriba o porte páginas del manual para Linux. Al ser bastante compatible con otras versiones, portar páginas del manual no debería dar problemas (con excepción de la distribución BSD del NET-2, que utiliza un paquete de macros totalmente distinto). Para usar las páginas del manual del NET-2 BSD con groff simplemente se utiliza la opción -mdoc en vez de la opción -man. De todas formas, se recomienda utilizar la opción -mandoc porque así se detecta en forma automática que paquete de macros utilizar.

PREÁMBULO
El primer comando en una página de manual debería ser

    .TH título sección fecha fuente manual,

donde:

    título
        Es el título de la página del manual (p.ej., MAN).

    sección
        Es el número de sección donde debería ir la página (p.ej., 7).

    fecha
        Esta es la fecha de la última revisión — la fecha debería cambiarse cada vez que se modifica la página, ya que ésta es la forma mas genérica de hacer control de versión.

    fuente
        Indica cual es la fuente del comando.

        Para ficheros binarios, se utilizan nombres como: GNU, NET-2, Distribución SLS, Distribución MCC.

        Para llamadas al sistema, se especifca la versión actual del kernel: Linux 0.99.11.

        Para llamadas a biblioteca, se especifica la fuente de la función: GNU, BSD 4.3, Linux DLL 4.4.1.

    manual
        Indica el título del manual (p.ej., Manual del Programador).

Tradicionalmente, las secciones del manual son las siguientes:

    1 Comandos
        Comandos que el usuario puede ejecutar desde el intérprete de comandos.

    2 Llamadas al sistema
        Funciones que el kernel debe ejecutar.

    3 Llamadas a biblioteca
        La mayoría de las funciones en libc, (tales como sort(3))

    4 Ficheros especiales
        Ficheros en el directorio /dev

    5 Formatos de ficheros y convenciones
        El formato de /etc/passwd y otros ficheros de texto.

    6 Juegos

    7 Paquetes de macros y convenciones
        Describe la organización estándard del sistema de ficheros, ésta pagina del manual y otras cosas.

    8 Commandos para la administración del sistema
        Comandos como mount(8), que sólo pueden ser ejecutados por el usuario root.

    9 Rutinas del kernel
        Esta sección del manual no es estándar y está incluída porque el código fuente del kernel de Linux está libremente disponible bajo la Licencia Pública GNU y hay mucha gente modificando el kernel.

TIPOS DE LETRA
Aunque el mundo UNIX tiene muchas convenciones arbitrarias para las páginas del manual, los cientos de páginas del manual Linux definen nuestros estándares:

    Para funciones, los argumentos siempre se especifican usando itálicas, incluso en la sección SINOPSIS,mientrasque el resto de la función se escribe en negrita:
    int mifuncion(int argc, char **argv);

    Los nombres de ficheros van siempre en letra itálica (p.ej., /usr/include/stdio.h), excepto en la sección SINOPSIS, donde los ficheros de cabecera van en negrita (p.ej., #include <stdio.h>).

    Macros especiales, que suelen ir en mayúsculas, van en negrita (p.ej., MAXINT).

    Los códigos de una lista de códigos de errores van en negrita (para generar esta lista se suele usar el macro .TP).

    Referencias a otras páginas del manual (o dentro de la página actual) van en negrita. Si la referencia incluye el número de sección del manual, se debe dar en tipo de letra romana, sin espacios (p.ej., man(7)). Los comandos usados para seleccionar distintos tipos de letra son los siguientes:

.B  Negrita

.BI Negrita alternando con itálica

.BR Negrita alternando con romana

.I  Itálica

.IB Itálica alternando con negrita

.IR Itálica alternando con romana

.RB Romana alternando con negrita

.RI Romana alternando con itálica

.SB Pequeña alternando con negrita

.SM Pequeña

Tradicionalmente, cada comando puede tener seis argumentos como máximo, pero la versión de GNU no tiene esa limitación. Los argumentos se delimitan con espacios. Si el argumento contiene espacios, se deben usar comillas dobles. Todos los argumentos se imprimen uno al lado del otro sin espacios entre medio. De esta forma, el comando .BR se puede usar para especificar una palabra en negrita seguido de un signo de puntuación en romano.

SECCIONES
Las secciones se empiezan con .SH seguido del encabezamiento. Si el éste contiene espacios y aparece en la misma linea que el .SH, entonces se debe poner el encabezamiento dentro de comillas dobles. Los siguientes son los encabezamientos tradicionales: NOMBRE, SINOPSIS, DESCRIPCIÓN, OPCIONES, FICHEROS, VÉASE TAMBIÉN, DIAGNÓSTICOS, ERRORES, y AUTOR. El único encabezamiento obligatorio es NOMBRE, que debe incluír una descripción breve del programa en el renglón de abajo:

    .SH NOMBRE
    ajedrez \- el juego de ajedrez

Es muy importante respetar este formato, nótese que después del nombre del comando hay una barra invertida antes del guión. Esta sintaxis la utiliza el programa makewhatis(8) para crear una base de datos de descripciones breves para los comandos whatis(1) y apropos(1).

OTROS MACROS
Otros macros que se pueden utilizar:

.DT Tabuladores por omisión

.HP Comenzar sangrado francés

.IP Comenzar un párrafo con "hanging tag". Tiene el mismo efecto que .TP, con la excepción que el "tag" está en el mismo renglón.

.LP Lo mismo que .PP

.PD Establece la distancia entre párrafos al valor dado por el argumento

.PP Comienza un nuevo párrafo

.RE Finaliza indentado relativo (párrafo indentado)

.RS Comienza indentado relativo (párrafo indentado)

.SS Subencabezamiento (igual que .SH, pero usado para subsecciones)

.TP Comienza un párrafo con "hanging tag". El "tag" está en el siguiente renglón. Este comando es parecido a .IP

FICHEROS
/usr/local/lib/groff/tmac/tmac.an
/usr/man/whatis

VÉASE TAMBIÉN
groff(1), man(1), whatis(1), apropos(1), makewhatis(8)