As páginas de referência devem seguir uma organização padrão. Isto permite aos usuários encontrarem as informações desejadas mais rapidamente e, também, encoraja os autores a documentar todos os aspectos relevantes do comando. A consistência não é desejada apenas entre as páginas de referência do PostgreSQL, mas também com as páginas de referência disponibilizadas pelo sistema operacional e por outros pacotes. As diretrizes descritas a seguir foram desenvolvidas para esta finalidade. Em sua maior parte estas diretrizes são consistentes com as diretrizes semelhantes estabelecidas por vários sistemas operacionais.
As páginas de referência que descrevem comandos executáveis devem conter as seguintes seções, nesta ordem. As seções que não se aplicam podem ser omitidas. Seções adicionais de nível mais alto devem ser utilizadas apenas em circunstâncias especiais; geralmente esta informação pertence à seção "Utilização".
Esta seção é gerada automaticamente. Contém o nome do comando e um breve resumo de sua funcionalidade.
Esta seção contém o diagrama da sintaxe do comando. Normalmente a sinopse não deve relacionar todas as opções de linha de comando; isto é feito abaixo. Em vez disto, devem ser relacionados os principais componentes da linha de comando, tal como o local dos arquivos de entrada e de saída.
Vários parágrafos explicando o que o comando faz.
Uma lista descrevendo cada opção de linha de comando. Havendo muitas opções, podem ser usadas subseções.
Se o programa utilizar zero para execução bem-sucedida, e diferente de zero para mal-sucedida, então isto não precisa ser documentado. Havendo um significado por trás dos códigos de retorno diferentes de zero, estes devem ser descritos aqui.
Descreve todas as sub-linguagens ou interfaces em tempo de execução do programa. Normalmente esta seção pode ser omitida quando o programa não é interativo. Caso contrário, esta seção engloba a descrição de todas as funcionalidades em tempo de execução. Devem ser utilizadas subseções quando for apropriado.
Relaciona todas as variáveis de ambiente que o programa pode utilizar. Deve ser completa; mesmo variáveis que parecem triviais, como SHELL, podem ser de interesse do usuário.
Relaciona todos os arquivos que o programa pode acessar implicitamente, ou seja, não relaciona os arquivos de entrada e de saída especificados na linha de comando, mas relaciona os arquivos de configuração, etc.
Explica qualquer saída não usual que o programa pode produzir. Deve-se evitar relacionar todas as mensagens de erro possíveis; isto dá muito trabalho e possui pouca utilidade prática. Mas se, por exemplo, as mensagens de erro possuem um formato padrão que o usuário pode analisar, este é o lugar para que isto seja explicado.
Tudo que não é adequado em outro lugar, mas em particular erros, problemas na implementação, considerações sobre segurança, e questões de compatibilidade.
Exemplos
Havendo marcos relevantes na história do programa, estes devem ser descritos aqui. Normalmente esta seção pode ser omitida.
Referências cruzadas, relacionadas na seguinte ordem: outras páginas de referência de comandos do PostgreSQL, páginas de referência de comandos SQL do PostgreSQL, citação dos manuais do PostgreSQL, outras páginas de referência (por exemplo, sistema operacional, outros pacotes), outra documentação. Os itens do mesmo grupo devem estar em ordem alfabética.
As páginas de referência contendo comandos SQL devem possuir as seguintes seções: Nome, Sinopse, Descrição, Parâmetros, Saídas, Notas, Exemplos, Compatibilidade, Histórico e Consulte Também. A seção sobre Parâmetros é como a seção Opções, mas há maior liberdade sobre que cláusulas do comando podem ser relacionadas. A seção Saídas somente é necessária quando o comando retorna algo diferente da marca padrão de comando terminado. A seção Compatibilidade deve explicar a extensão da conformidade [1] do comando com o padrão SQL, ou informar com que outro sistema de banco de dados é compatível. A seção Consulte Também dos comandos SQL deve relacionar os comandos SQL antes da referência cruzada com os programas.
| [1] |
conformidade — atributos do software que o tornam consonante com padrões ou convenções relacionadas à portabilidade. NBR 13596/1996, Tecnologia da Informação - Avaliação de produto de software - Características de qualidade e diretrizes para o seu uso, ABNT, Rio de Janeiro. (N. do T.) |
