Documentação do PostgreSQL 7.4.1
Anterior Início Apêndice G. Documentação Fim Próxima

G.3. Geração da documentação

Após estar tudo instalado, o diretório doc/src/sgml deve ser tornado o diretório corrente, e um dos comandos descritos nas subseções abaixo deve ser executado para gerar a documentação (Lembre-se de utilizar o make do GNU).

G.3.1. HTML

Para gerar a versão HTML da documentação:

doc/src/sgml$ gmake html

Esta também é a versão gerada por padrão.

Quando a documentação HTML é gerada, o processamento também gera as informações de vínculo com as entradas do índice. Portanto, se for desejado que a documentação possua um índice no final, é necessário gerar a documentação HTML primeiro, e depois gerar a documentação novamente no formato desejado.

Para permitir o tratamento mais fácil da distribuição final, os arquivos que compõem a documentação HTML são armazenados em um arquivo tar que é desempacotado durante a instalação. Para criar o pacote de documentação HTML, devem ser utilizados os comandos

cd doc/src
gmake postgres.tar.gz

Na distribuição, estes arquivos se encontram no diretório doc, sendo instalados por padrão pelo gmake install.

G.3.2. Páginas do manual Unix

É utilizado o utilitário docbook2man para converter as páginas refentry do DocBook em saída *roff adequada para as páginas do manual. As páginas do manual também são distribuídas como um arquivo tar, semelhante à versão HTML. Para gerar o pacote de páginas do manual devem ser utilizados os comandos

cd doc/src
gmake man.tar.gz

que produz um arquivo tar gerado no diretório doc/src.

Para gerar páginas do manual com qualidade, pode ser necessário utilizar uma versão "hackeada" do utilitário de conversão, ou fazer algum pós-processamento manual. Todas as páginas do manual devem ser inspecionadas manualmente antes de serem distribuídas.

G.3.3. Imprimir a saída usando JadeTex

Se for desejado utilizar o JadeTex para gerar uma versão da documentação que possa ser impressa, pode ser utilizado um dos seguintes comandos:

G.3.4. Imprimir a saída através do RTF

Também é possível criar uma versão imprimível da documentação do PostgreSQL convertendo-a em RTF, e depois aplicando pequenas correções de formatação utilizando um pacote de automação de escritórios. Dependendo das funcionalidades do pacote de automação de escritórios utilizado, a documentação pode ser convertida para Postscript a partir do PDF. O procedimento abaixo mostra este processo utilizando o Applixware.

Nota: Parece que a versão corrente da documentação do PostgreSQL dispara algum erro ou excede o limite de tamanho do OpenJade. Se o processo de geração da versão RTF demorar muito tempo, e o tamanho do arquivo de saída permanecer igual a 0, então você esbarrou no problema mas tenha em mente que a geração normal leva de 5 a 10 minutos, portanto não interrompa muito rapidamente.

Limpeza do RTF usando o Applixware

O OpenJade omite a especificação do estilo padrão para o corpo do texto. No passado, este problema não diagnosticado levava a um longo processo para geração do sumário. Entretanto, com grande ajuda das pessoas da Applixware, o sintoma foi diagnosticado e uma correção está disponível.

  1. Gerar a versão RTF digitando: 
    doc/src/sgml$ gmake postgres.rtf
  2. Reparar o arquivo RTF para especificar corretamente todos os estilos, em particular o estilo padrão. Se o documento contém seções refentry, também devem ser substituídas as dicas de formatação que ligam o parágrafo precedente ao parágrafo corrente e, em seu lugar, ligar o parágrafo corrente ao parágrafo seguinte. O utilitário fixrtf está disponível em doc/src/sgml para efetuar estes reparos: 
    doc/src/sgml$ ./fixrtf --refentry postgres.rtf
    Este script adiciona {\s0 Normal;} como sendo o zero-ésimo estilo no documento. De acordo com a Applixware, o padrão RTF proíbe adicionar um zero-ésimo estilo implícito, embora o Word da Microsoft trate este caso. Para reparar as seções refentry, o script substitui as marcas \keepn por \keep.
  3. Abra um novo documento no Applixware Words e depois importe o arquivo RTF.
  4. Gere o novo Sumário (ToC) utilizando o Applixware.
    1. Selecione as linhas existentes no Sumário, do início do primeiro caractere da primeira linha ao último caractere da última linha.
    2. Construa um novo Sumário utilizando Tools->Book Building->Create Table of Contents. Selecione os três primeiros níveis de cabeçalho para serem incluídos no Sumário. Este procedimento substitui as linhas existentes importadas no RTF por um Sumário nativo do Applixware.
    3. Ajuste a formatação do Sumário utilizando Format->Style, selecione cada um dos três estilos de Sumário, e ajuste o recuo para First e Left. Use os seguintes valores:
      Style First Indent (inches) Left Indent (inches)
      TOC-Heading 1 0.4 0.4
      TOC-Heading 2 0.8 0.8
      TOC-Heading 3 1.2 1.2
  5. Percorra o documento para:
    • Ajustar as quebras de página.
    • Ajustar as larguras das colunas das tabelas.

  6. Substitua os números das páginas alinhados à direita na parte de Exemplos e de Figuras do Sumário pelos valores corretos. Esta atividade só toma alguns minutos.
  7. Apague a seção de índice do documento caso esteja vazia.
  8. Gere novamente e ajuste o Sumário.
    1. Selecione o campo Sumário.
    2. Selecione Tools->Book Building->Create Table of Contents.
    3. Desvincule o Sumário selecionando Tools->Field Editing->Unprotect.
    4. Apague a primeira linha do Sumário, que é uma entrada para o próprio Sumário.
  9. Salve o documento no formato nativo do Applixware Words para facilitar uma edição posterior, caso seja necessário.
  10. Imprima ("Print") o documento em um arquivo no formato Postscript.

G.3.5. Arquivos texto puro

Diversos arquivos são distribuídos como texto puro, para serem lidos durante o processo de instalação. O arquivo INSTALL corresponde ao Capítulo 14 , com pequenas alterações para levar em conta a diferença de contexto. Para recriar este arquivo, o diretório doc/src/sgml deve ser tornado o diretório corrente, e deve ser executado gmake INSTALL. Isto cria o arquivo INSTALL.html que pode ser salvo como texto utilizando o Netscape Navigator e colocado no lugar do arquivo existente. O Netscape parece oferecer a melhor qualidade na conversão de HTML em texto (melhor que o lynx e o w3m).

O arquivo HISTORY pode ser criado de forma semelhante, utilizando o comando gmake HISTORY. Para criar o arquivo src/test/regress/README o comando é gmake regress_README.

G.3.6. Verificação da sintaxe

A geração da documentação pode ser demorada. Entretanto, existe um método para verificar apenas se a sintaxe dos arquivos de documentação está correta que só leva alguns segundos:

doc/src/sgml$ gmake check

Anterior Principal Próxima
Conjunto de ferramentas Acima Criação da documentação
SourceForge.net Logo