Las páginas de referencia deben seguir una estructura estándar. Esto permite a los usuarios encontrar la información deseada más rápidamente y también anima a los redactores a documentar todos los aspectos relevantes de un comando. Se busca la consistencia no solo entre las páginas de referencia de PostgreSQL, sino también con las páginas de referencia proporcionadas por el sistema operativo y otros paquetes. Por lo tanto, se han desarrollado las siguientes pautas, las cuales son en su mayor parte consistentes con directrices similares establecidas por varios sistemas operativos.
Las páginas de referencia que describen comandos ejecutables deben contener las siguientes secciones, en este orden. Las secciones que no correspondan pueden omitirse. Solo se deben usar secciones adicionales de nivel superior en circunstancias especiales; a menudo, esa información pertenece a la sección “Uso”.
Esta sección se genera automáticamente. Contiene el nombre del comando y un resumen de media frase sobre su funcionalidad.
Esta sección contiene el diagrama de sintaxis del comando. Por lo general, la sinopsis no debe enumerar cada opción de la línea de comandos; eso se hace más abajo. En su lugar, enumera los componentes principales de la línea de comandos, como el destino de los archivos de entrada y salida.
Varios párrafos que explican lo que hace el comando.
Una lista que describe cada opción de la línea de comandos. Si hay muchas opciones, se pueden utilizar subsecciones.
Si el programa utiliza 0 para indicar éxito y un valor distinto de cero para fallos, entonces no es necesario documentarlo. Si hay un significado específico detrás de los diferentes códigos de salida distintos de cero, enuméralos aquí.
Describe cualquier sublenguaje o interfaz de tiempo de ejecución del programa. Si el programa no es interactivo, esta sección generalmente se puede omitir. De lo contrario, esta sección sirve para describir características del tiempo de ejecución. Utiliza subsecciones si es adecuado.
Enumera todas las variables de entorno que el programa podría utilizar.
Intenta ser exhaustivo; incluso variables aparentemente triviales como
SHELL pueden ser de interés para el usuario.
Enumera cualquier archivo al que el programa pueda acceder implícitamente. Es decir, no enumeres los archivos de entrada y salida que se especificaron en la línea de comandos, sino los archivos de configuración, etc.
Explica cualquier salida inusual que el programa pueda generar. Evita enumerar cada mensaje de error posible. Esto requiere mucho trabajo y tiene poca utilidad práctica. Pero si, por ejemplo, los mensajes de error tienen un formato estándar que el usuario puede analizar, este sería el lugar adecuado para explicarlo.
Cualquier cosa que no encaje en otra sección, en particular errores (bugs), fallos de implementación, consideraciones de seguridad y problemas de compatibilidad.
Ejemplos
Si hubo hitos importantes en la historia del programa, se pueden enumerar aquí. Por lo general, esta sección se puede omitir.
Autor (solo se usa en la sección contrib)
Referencias cruzadas, enumeradas en el siguiente orden: otras páginas de referencia de comandos de PostgreSQL, páginas de referencia de comandos SQL de PostgreSQL, citas de manuales de PostgreSQL, otras páginas de referencia (por ejemplo, del sistema operativo, otros paquetes) y otra documentación. Los elementos del mismo grupo se enumeran alfabéticamente.
Las páginas de referencia que describen comandos SQL deben contener las siguientes secciones: Nombre, Sinopsis, Descripción, Parámetros, Salidas, Notas, Ejemplos, Compatibilidad, Historial, Ver también. La sección Parámetros es similar a la sección Opciones, pero hay más libertad sobre qué cláusulas del comando se pueden enumerar. La sección Salidas solo es necesaria si el comando devuelve algo distinto de una etiqueta estándar de finalización del comando. La sección Compatibilidad debe explicar en qué medida este comando se ajusta a los estándares SQL, o con qué otro sistema de base de datos es compatible. La sección Ver también de los comandos SQL debe enumerar los comandos SQL antes de las referencias cruzadas a programas.