| Firebird Documentation Index → 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
|
| Firebird Documentation Index → Obter e gerar as manuais → Gerando os Documentos |