Firebird Docbuilding Howto Brazilian Portuguese

Como obter e gerar o módulo de manuais do Firebird Paul Vinkenoog 13 Mar 2005 – Documento versão 1.1-pt_br Tradução para o Português do Brasil: Fabrício Araújo 2 Índice Introdução: Propósito e Público – alvo deste documento .......................................................................... 3 O que é esse “módulo de manuais” mesmo? ................................................................................... 3 Existe mais documentação além daquela que é fornecida pelo módulo de manuais? ............................ 3 É necessário eu mesmo gerar os documentos? Não existe uma forma mais simples? ........................... 3 Obtendo o módulo de manuais do repositório do SourceForge .................................................................. 4 O que é o CVS? ............................................................................................................................ 4 Clientes de CVS ............................................................................................................................ 4 Fazendo Check out do módulo de manuais ...................................................................................... 5 Gerando os Documentos do Firebird ....................................................................................................... 8 Onde obter o Java 2 ....................................................................................................................... 8 Como configurar o ambiente para a geração dos documentos ........................................................... 9 Gerando os documentos em HTML e PDF ...................................................................................... 9 Mantendo o seu módulo atualizado ....................................................................................................... 11 Se as coisas derem errado .................................................................................................................... 11 Apêndice A: História do Documento ..................................................................................................... 12 Apêndice B: Aviso de Licensa .............................................................................................................. 13 3 Introdução: Propósito e Público – alvo deste documento Este documento explica, passo-a-passo, como você baixa e gera o módulo de manuais do Projeto Firebird no site SourceForge. O que é esse “módulo de manuais” mesmo? O módulo de manuais é parte do Projeto Firebird no SourceForge. É um esforço, direcionado em produzir docu- mentação acurada e abrangente no RDBMS Firebird (Sistema de Gerenciamento de Banco de Dados Relacional). É importante entender que o módulo de manuais contém documentação em formato fonte – para ser mais preciso: no formato DocBook. Esses fontes precisam ser processados (gerados) para se obter documentos legíveis, os quais podem ser publicados na Internet. Existe mais documentação além daquela que é fornecida pelo módulo de manuais? Claro! Na época que este documento foi escrito, a maior parte da documentação útil do Firebird foi feita fora do módulo. Ainda temos uma longa estrada a percorrer antes que a documentação gerada por nós esteja próxima de estar completa. Aliás, facilitar a vida dos novos escritores de documentação e ajudá-los a vencer mais facilmente as dificuldades iniciais é um dos objetivos deste documento. Se o que você busca é documentação pronta e abundante, atualmente os melhores lugares para iniciar a busca são: • http://www.ibphoenix.com – site da IBPhoenix Siga os links Downloads -> Main Downloads e Development -> General Documentation • http://www.firebirdsql.org/index.php?op=doc – página de documentação do Projeto Firebird. É necessário eu mesmo gerar os documentos? Não existe uma forma mais simples? Claro que existe! Assim que alguma parte da documentação atinge um certo nível de maturidade, assim como atualizações significativas, esta é publicada – em HTML e PDF – no site do Firebird. Você pode achar todos os documentos que nós publicamos através das páginas índice de HTML e PDF http://www.firebirdsql.org/manual/ http://www.firebirdsql.org/pdfmanual/ Ou então visite a página do Subprojeto de Documentação: Obter e gerar as manuais 4 http://www.firebird.org/index.php?op=devel&sub=doc Só é necessário baixar o módulo de manuais e gerá-los por si mesmo se (e somente se) você deseja: • obter a versão mais atualizada possível (Esteja avisado que uma das razões de um documento não ter sido publicado é este possuir erros); • ajudar a escrever a documentação; • aprender como essa coisa de gerar documentos funciona, e / ou pensa que fazer as coisas por si mesmo é mais divertido que simplesmente baixar a coisa pronta. Se uma destas situações se aplica a você, este documento foi feito para você. Obtendo o módulo de manuais do repositório do SourceForge O módulo de manuais é parte do repositório CVS no SourceForge. Para baixá-lo, é necessário um tipo de software chamado cliente CVS. Esta seção descreve os passos necessários para obter o software e o módulo de manual. A geração de manuais será discutida na seção Gerando os doc Firebird O que é o CVS? CVS significa Sistema de Versões Concorrentes. É uma ferramenta para gerenciamento de software, útil tanto para desenvolvedores como para o trabalho em equipe. Praticamente todos os projetos no SourceForge usam o CVS para armazenar e desenvolver suas bases de código. A árvore do Firebird no CVS é dividida em diversos módulos, o módulo de manuais sendo um desses. Clientes de CVS Baixar um módulo de um repositório CVS é chamado de checking out na linguagem do CVS. Nota do Tradutor: não encontrei uma tradução satisfatória para check out. A expressão será utilizada no original. Para se fazer isso, é necessário um cliente CVS, os quais existem em praticamente todos sistemas operacionais. Aqui temos uma lista desses clientes para alguns SOs populares: • Linux, BSD e outros *nix - CVS em linha de comando é freqüentemente pré-instalado. Senão, use as ferramentas de administração para instalar isso - você tipicamente achará isso na categoria de desenvolvimento. Se isso não funcionar para você, obtenha-o em http://www.cvshome.org - gCVS - uma interface gráfica para o CVS, em http://cvsgui.sourceforge.net/download.html • Windows Obter e gerar as manuais 5 - CVS em linha de comando em http://www.cvshome.org - WinCVS: Bastante poderoso, porém bastante complicado para o novato. Baixar em: http://cvsgui.source- forge.net - TortoiseCVS: plugin para o Windows Explorer. Brilhante, fácil de usar, intuitivo - embora não tenha as funcionalidades avançadas do WinCVS, mas nada básico foi deixado de fora. Baixar em http://tortoisecvs. sourceforge.net/download.shtml • Macintosh OS X (OSX) & Macintosh Classic (Classic) - (OSX) Já vem instalado o CVS em linha de comando - (OSX) Fink (ferramentas Unix para OS X) contém uma versão mais atualizada do CVS. Baixar em http:// fink.sourceforge.net/download.html - (Ambos) MacCvsX em http://cvsgui.sourceforge.net/download.html. É do mesmo projeto do gCVS e WinCVS. Esse porte para OS X ainda está em beta. - (Ambos) MacCvs Pro em http://sourceforge.net/projects/maccvspro/ • Outras plataformas - Tente sua sorte em http://www.cvshome.org - Faça uma busca no Google - Ou então pergunte no newsgroup gnu.cvs.help ou na lista de mensagens firebird-docs Baixe e instale (pelo menos) um dos clientes de CVS acima mencionados e instale de acordo com as instruções que vêm com o mesmo. Depois disso, você está pronto para fazer check out do módulo de manuais. Fazendo Check out do módulo de manuais Existem duas maneiras de fazer check out do módulo de manuais: como usuário anônimo ou com seu apelido no SourceForge. O segundo método é chamado geralmente de SSH check out (porque usa uma Interface Segura) ou então EXT check out (por causa de usar o SSH como protocolo EXTerno). Todos podem fazer o check out anonimamente. Membros do projeto Firebird também podem fazer check out com o seu apelido do SourceForge. Nota Mesmo que você tenha a conta no SourceForge,