NOMBRE¶

SINOPSIS¶

groff -Tps -man fichero ...

man [sección] título

DESCRIPCIÓN¶

Dése cuenta que las páginas de manual mdoc de NET-2 BSD se pueden usar con groff simplemente especificando la opción -mdoc en vez de la opción -man. De todas formas, se recomienda utilizar la opción -mandoc porque así detecta de forma automática qué paquete de macros se está utilizando.

PREÁMBULO¶

Dése cuenta que las páginas de manual de BSD con formato mdoc comienzan con la orden Dd, no con la orden TH.

Tradicionalmente, las secciones del manual se definen como las siguientes:

SECCIONES¶

Otras secciones tradicionales poseen los siguientes contenidos:

SINOPSIS

Brevemente describe la interfaz de la orden o función. Para las órdenes, muestra la sintáxis de la orden y sus argumentos (incluyendo las opciones). La negrita se utiliza para el texto literal y la itálica para indicar los argumentos que son reemplazables. Los corchetes ([]] rodean argumentos opcionales, las barras verticales (|) separan alternativas y las elipses (...) se pueden repetir. Para las funciones, muestra cualquier declaración de datos o directivas #include necesarias, seguidas por la declaración de la función.

DESCRIPCIÓN

Explica lo que la orden, función o formato hace y cómo interactúa con ficheros o con la entrada estándar, y lo que produce en la salida estándar o en la salida de error estándar. Omite detalles internos o de implementación a menos que sean críticos para comprender la interfaz. Describe el caso usual. Para información sobre opciones, use la sección OPTIONS. Si existe algún tipo de gramática de entrada o conjunto complejo de subórdenes, considere el describirla en una sección de USO aparte (y sólo coloque un resumen en la sección DESCRIPCIÓN).

VALOR DEVUELTO

Da una lista de los valores que la rutina de biblioteca devolverá al invocador y las condiciones que hacen que se devuelvan esos valores.

ESTADO DE SALIDA

Lista los posibles valores del estado de salida de un programa y las condiciones que hacen que se devuelvan esos valores.

OPCIONES

Describe las opciones aceptadas por el programa y cómo aquellas cambian su comportamiento.

USO

Describe la gramática de cualquier sublenguaje que éste implemente.

EJEMPLOS

Muestra uno o más ejemplos describiendo como se utiliza la función, fichero u orden.

FICHEROS

Lista los ficheros que el programa o función usa, tales como ficheros de configuración, ficheros de inicio y ficheros sobre los que el programa trabaja directamente. Da las rutas completas de estos ficheros y usa el proceso de instalación para modificar la parte de directorios para concordar con las preferencias de los usuarios. Para muchos programas, el lugar de instalación por defecto es /usr/local por lo que su página de manual debería usar /usr/local como base.

ENTORNO

Lista todas las variables de entorno que afectan a su programa o función y cómo aquellas le afectan.

DIAGNÓSTICOS

Da una breve descripción de los mensajes de error más comunes y cómo hacerles frente. No necesita explicar mensajes de error del sistema o señales fatales que puedan aparecer durante la ejecución de cualquier programa a menos que sean especiales de alguna forma para su programa.

SEGURIDAD

Trata sobre problemas de seguridad y sus implicaciones. Advierte sobre configuraciones o entornos que se deben evitar, órdenes que pueden tener implicaciones para la seguridad, etc., especialmente si no son obvios. Tratar la seguridad en una sección aparte no es necesario. Si es fácil de entender, coloque la información sobre seguridad en las otras secciones (tales como DESCRIPCIÓN o USO). No obstante, por favor, ¡incluya la información sobre seguridad en algún lugar!

CONFORME A

Describe cualquier estándar o convención que ésta implemente.

NOTA

Proporciona diversas notas.

FALLOS

Lista limitaciones, defectos o inconveniencias conocidos y otras actividades cuestionables.

AUTOR

Lista los autores de la documentación o programa de tal manera que pueda enviarles un correo para informarles de cualquier fallo.

VÉASE TAMBIÉN

Lista páginas de manual relacionadas en orden alfabético, posiblemente seguidas de otras páginas o documentos relacionados. Convencionalmente, ésta es la última sección.

TIPOS DE LETRA¶

Para funciones, los argumentos siempre se especifican usando itálicas, incluso en la sección SINOPSIS, mientras que el resto de la función se escribe en negrita:

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 van en negrita (p.ej., #include <stdio.h>).

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

Cuando enumeramos una lista de códigos de error, estos van en negrita (esta lista normalmente usa la macro .TP).

Referencias a otras páginas del manual (o de algún tema dentro de la página actual) van en negrita. Si se incluye el número de sección del manual, se debe dar en tipo de letra Romana (normal), sin espacios (p.ej., man(7)).

Las órdenes para seleccionar el tipo de letra son:

.B

Negrita

.BI

Negrita alternándose con itálica (especialmente útil para la especificación de funciones)

.BR

Negrita alternándose con romana (especialmente útil para referenciar a otras páginas de manual)

.I

Itálica

.IB

Itálica alternándose con negrita

.IR

Itálica alternándose con romana

.RB

Romana alternándose con negrita

.RI

Romana alternándose con itálica

.SB

Pequeña alternándose con negrita

.SM

Pequeña (útil para acrónimos)

Tradicionalmente, cada órden puede tener seis argumentos como máximo, pero la implementación de GNU elimina esta limitación (aunque tal vez usted todavía quiera limitarse a 6 argumentos por el bien de la portabilidad). Los argumentos se delimitan por 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, la orden .BR se puede usar para especificar una palabra en negrita seguido por un signo de puntuación en romano. Si no se da ningún argumento, la orden se aplica a la siguiente línea de texto.

OTRAS MACROS Y CADENAS¶

SUBCONJUNTO SEGURO¶

También puede usar muchas secuencias de escape de troff (aquellas secuencias que comienzan por \). Cuando necesite incluir el carácter de barra invertida como texto normal, use \e. Otras secuencias que puede usar, donde x y xx son cualquier carácter y N es cualquier dígito, incluyen: \', \, \-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx y \f(xx. Evite usar secuencias de escape para dibujar gráficos.

No use el parámetro opcional de bp (break page, salto de página). Use sólo valores positivos para sp (vertical space, espacio vertical). No defina una macro (de) con el mismo nombre que una macro en éste o el paquete de macros mdoc, con un significado diferente. Es probable que tales redefiniciones se ignoren. Todo sangrado positivo (in) debería ir acompañado por el correspondiente sangrado negativo (aunque debería usar las macros RS y RE en su lugar). La condición (if,ie) sólo debería tener 't' o 'n' como condición. Sólo se deberían utilizar traducciones (tr) que se puedan ignorar. Los cambios de fuente (ft y las secuencias de escape \f) sólo debería tener los valores 1, 2, 3, 4, R, I, B, P o CW (la orden ft también puede no tener parámetros).

Si usa otras capacidades diferentes a éstas, compruebe el resultado cuidadosamente con diferentes herramientas. Una vez que haya confirmado que la capacidad adicional es segura, permita que el que mantiene este documento conozca la secuencia u orden segura que debería añadirse a esta lista.

OBSERVACIONES¶

Las herramientas que procesan estos ficheros deben abrir el fichero y examinar el primer carácter distinto de espacio. Un punto (.) o una comilla simple (') al principio de una línea indica un fichero basado en troff (tal como man o mdoc). Un menor (<) indica un fichero basado en SGML/XML (tal como HTML o Docbook). Cualquier otra cosa sugiere un simple texto ASCII (por ej., el resultado de un "catman").

Muchas páginas de manual comienzan con '\" seguido por un espacio y una lista de caracteres que indican cómo se va a procesar la página. Por el bien de la portabilidad a traductores que no se basan en troff, recomendamos que evite usar cualquier otra cosa que no sea tbl(1). Linux puede detectar eso automáticamente. Sin embargo, tal vez quiera incluir esta información de tal manera que su página man pueda ser tratada por otros sistemas (menos capaces). Aquí tiene las definiciones de los preprocesadores invocados por los siguientes caracteres:

e

eqn(1)

g

grap(1)

p

pic(1)

r

refer(1)

t

tbl(1)

v

vgrind(1)

FICHEROS¶

FALLOS¶

La macro de Sun TX no está implantada.

AUTORES¶

—

James Clark (jjc@jclark.com) escribió la implementación del paquete de macros.

—

Rickard E. Faith (faith@cs.unc.edu) escribió la versión inicial de esta página de manual.

—

Jens Schweikhardt (schweikh@noc.fdn.de) escribió el mini-COMO `Linux Man-Page' (que influyó en esta página de manual).

—

David A. Wheeler (dwheeler@ida.org) modificó en profundidad esta página de manual, añadiendo información detallada sobre secciones y macros.

VÉASE TAMBIÉN¶