| Documentação Firebird → Para escritores de documentação Firebird → Obter e gerar as manuais → Gerando os Documentos |
|
|
|
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:
Onde obter o Java 2
Como configurar o ambiente para o processo de geração de documentos
Como gerar os documentos em HTML e PDF
Se você já possui o Java 2 instalado, pode pular este passo.
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.
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.
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
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.
Se você chegou até aqui inteiro, então está finalmente pronto para gerar os documentos Firebird. Aqui está o que deve ser feito:
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
Se está num ambiente, abra uma janela de linha de comando
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)
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
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.
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
|
| Documentação Firebird → Para escritores de documentação Firebird → Obter e gerar as manuais → Gerando os Documentos |