Documentação FirebirdPara escritores de documentação FirebirdObter e gerar as manuais → Gerando os Documentos
Firebird home Firebird home Anterior: Obtendo o módulo do SFPrincipal: Documentação FirebirdAcima: Obter e gerar as manuaisPróxima: Mantendo o módulo atualizado

Gerando os Documentos do Firebird

Onde obter o Java 2
Como configurar o ambiente para a geração dos documentos
Gerando os documentos em HTML e PDF

Este módulo de manuais vem acompanhado de uma ferramenta de geração chamada Ant para produzir HTML e PDF a partir de um fonte em DocBook XML. Ant é uma ferramenta Java; a qual necessita uma versão recente do Java 2 instalado no seu computador.

Nas próximas subseções, mostraremos:

  1. Onde obter o Java 2

  2. Como configurar o ambiente para o processo de geração de documentos

  3. Como gerar os documentos em HTML e PDF

Se você já possui o Java 2 instalado, pode pular este passo.

Onde obter o Java 2

Baixe e instale apenas uma das seguintes opções:

  • Java 2 Runtime Environment, Standard Edition - geralmente abreviada como J2RE SE.

    Vá a http://www.java.com/ e siga os links para as páginas de download. Obtenha a versão para o seu SO. Clicando em um link “Download” ou “Get it now” pode levar a janelas pipocando, perguntando se está tudo OK que a Sun Microsystems instale coisas no seu computaos. Se você concordar, praticamente tudo é instalado automaticamente. Se isso não o agrada, você pode baixar o instalador manualmente e executá-lo você mesmo.

  • Java 2 Software Development Kit, Standard Edition - ou J2SDK SE.

    Este é um pacote muito maior, que também contém a J2RE SE. Se você deseja o SDK, vá em http://java.sun.com/j2se/ e pegue a última versão estável. Quando você tiver que escolher entre o SDK e a JRE, escolha o SDK. (Sim, você pode baixar a J2RE aqui também, mas é bem mais fácil usando o link da primeira opção). Baixe o programa de instalação e execute-o.

Se você não entende a diferença entre ambos, vá para a primeira opção: a Java 2 Runtime Environment. Você não precisa do SDK para gerar os documentos do Firebird.

Como configurar o ambiente para a geração dos documentos

O script de geração necessita de uma variável de ambiente chamada JAVA_HOME, a qual deve apontar para a pasta de instalação do Java 2.

  • No Windows, isto é algo do tipo C:\Program Files\Java\j2re1.4.2_01.

  • No Linux, pode ser algo como /usr/lib/java/jre ou /usr/java/j2sdk ou... bem, pode ser um monte coisa diferente.

Nota

Para ter certeza de que é a pasta correta, verifique se existe dentro dela uma pasta chamada bin, e se esta pasta contém o arquivo java.exe

Se você for sortudo, a variável JAVA_HOME já está presente e correta. Senão, você deve configurar isso você mesmo, por exemplo:

  • Em Windows, use set JAVA_HOME=C:\Program Files\Java\j2re1.4.2_01

  • No Linux, use export JAVA_HOME=/usr/lib/java/jre

Nota

Esses caminhos são apenas exemplos, os quais podem (ou não) coincidir com os caminhos no seu sistema.

Dica: faça a variável JAVA_HOME permanente de modo que não tenha mais que configurá-la novamente. Consulte a documentação do seu SO para saber como realizar isso.

Gerando os documentos em HTML e PDF

Se você chegou até aqui inteiro, então está finalmente pronto para gerar os documentos Firebird. Aqui está o que deve ser feito:

  1. Se não o fez ainda, este é o momento de ler o arquivo Readme que está na pasta manual. O mesmo contém informações importantes que ainda não foram incluídas neste documento

  2. Se está num ambiente, abra uma janela de linha de comando

  3. A não ser que o Readme instrua em contrário, vá para a pasta manual\src\build e dispare o comando:

    build (em Windows), ou

    ./build.sh (no Linux)

  4. Agora você irá gerar algo mais substancial, por exemplo:

    build html ou

    build pdf ou

    build docs

    O que você gerar irá ser armazenado na estrutura de pastas abaixo de manual\dist

    Nota

    • Se for gerada a documentação em PDF, durante o processo você receberá muitas mensagens de erros. Ignore-as sem se preocupar caso as últimas linhas sejam BUILD SUCCESSFUL.

    • Devido à limitações no software de geração, grande parte dos arquivos PDF necessitarão de um – tedioso – pós-processamento manual antes que estejam apresentáveis. Para o seu próprio uso estão OK, no sentido de que “tudo está ali”.

    Para gerar a documentação em outras línguas (assim que as mesmas estiverem disponíveis) use o argumento -Dsfx e inclua o sufixo do código da linguagem, por exemplo:

    build pdf -Dsfx=es

    build html -Dsfx=fr

    Se o parâmetro -Dsfx não for especificado, a documentação em Inglês será gerada.

    Atenção

    Nem todos os conjuntos de documentação contém todo o montante de documentação. Isto depende da atividade dos escritores de documentação e dos tradutores. Na maioria das vezes, o conjunto em inglês será o mais completo.

    Os exemplos acima produzem toda o conjunto de documentação para uma dada linguagem. Se o que você deseja gerar apenas parte disso - por exemplo, um livro ou artigo - use o parâmetro -Drootid. Isto é particularmente útil na geração dos documentos em PDF, porque do contrário será gerado um arquivo monstruosamente grande.

    Com o parâmetro -Drootid, é necessário suprir o ID do elemento que se deseja gerar, por exemplo:

    build pdf -Drootid=fbutils

    build pdf -Dsfx=fr -Drootid=qsg15-fr

    Como você pode ver, parãmetros em linha de comandos podem ser combinados.

    Como saber o ID? Ache-o nos fontes em DocBook XML. Mas isto é algo a ser discutido no Firebird Docwriting Howto. Usar o parâmetro -Drootid é tipicamente algo feito por escritores de documentação, não por pessoas gerando casualmente os documentos.

É isso aí, agora você um gerador de documentação do Firebird certificado. Parabéns!!!!

Se você deseja escrever ou traduzir documentos para o Projeto Firebird por si mesmo, também leia o Guia de escrita de documentação Firebird

Anterior: Obtendo o módulo do SFPrincipal: Documentação FirebirdAcima: Obter e gerar as manuaisPróxima: Mantendo o módulo atualizado
Documentação FirebirdPara escritores de documentação FirebirdObter e gerar as manuais → Gerando os Documentos