Tradução da Documentação do PostgreSQL
Este texto é um guia para os novos colaboradores com o projeto de tradução da documentação do PostgreSQL para Português do Brasil. Aqui está descrito as convenções e ferramentas utilizadas para a tradução e revisão da documentação.
Introdução
Este artigo é um guia para os novos colaboradores do projeto de tradução da documentação do PostgreSQL para o Português do Brasil. O domínio da língua portuguesa é essencial para este trabalho voluntário. O conhecimento da linguagem DocBook é desejável mas não essencial. Serão utilizadas algumas ferramentas com editores de texto, dicionários e verificadores de ortografia bem como alguns programas para manipulação do DocBook. Nas seções seguintes entraremos em maiores detalhes sobre estas ferramentas.
Como colaborar
Para colaborar são necessários alguns requisitos:
- domínio do idioma inglês;
- domínio do idioma português do Brasil;
- algum tempo para se dedicar ao projeto;
Simples, né? Neste trabalho voluntário você aprenderá muito sobre documentação, dicionários, linguagem DocBook e algumas outras ferramentas interessantes.
A primeira coisa a fazer é assinar a nossa lista de discussão. Nós discutimos tudo relacionado ao projeto de documentação nela. Envie um e-mail expressando o seu interesse em participar do projeto de tradução da documentação que guiaremos para que começe desde já.
O segundo passo é escolher algum arquivo ou seção para traduzir ou revisar. Verifique o status da tradução. Cada status tem um significado. Veja:
- NOVO - arquivo não foi traduzido ainda.
- EM TRADUÇÃO - arquivo sendo traduzido.
- TRADUZIDO - arquivo já foi traduzido mas não revisado.
- REVISADO - arquivo já foi traduzido e revisado.
- NÃO UTILIZADO - arquivo não é incluído na documentação, portanto não precisa de tradução.
- SEM TRADUÇÃO - arquivo não contém texto a ser traduzido.
Trabalhamos com os arquivos que contém os três primeiros status (NOVO, TRADUZIDO e REVISADO).
Aos novos colaboradores, é aconselhável que começem pelos arquivos com status NOVO. É importante que estes novos colaboradores leiam uma parte da documentação já traduzida para assimilar o estilo de tradução.
Os colaboradores com um pouco mais de experiência vão revisar as traduções novas.
Informe o arquivo a ser traduzido ou revisado ao coordenador do projeto (atualmente Euler Taveira de Oliveira) via lista de discussão para que não haja conflito entre traduções e revisões.
Caso encontre alguma erro ortográfico, gramatical ou mesmo léxico (do DocBook), por favor deixe-nos saber. Prepare um patch com a correção e envie para nossa lista de discussão.
Documentação
A documentação do PostgreSQL é distribuída em quatro formatos:
- Texto puro, para informação de pré-instalação.
- HTML, para navegação on-line e referência.
- PDF ou Postscript, para impressão.
- man pages, para referência rápida no interpretador de comandos.
Estes quatro formatos são produzidos a partir de arquivos escritos na linguagem DocBook.
Os fontes da documentação estão escritos em DocBook, que é uma linguagem de marcação semelhante, superficialmente, ao HTML. Estas duas linguagens são aplicações da Standard Generalized Markup Language, SGML, que é essencialmente uma linguagem para descrever outras linguagens. No que se segue, os dois termos DocBook e SGML são empregados, mas tecnicamente não podem ser trocados.
O DocBook permite ao autor especificar a estrutura e o conteúdo de um documento técnico sem se preocupar com relação aos detalhes da apresentação. O estilo do documento define como o conteúdo é apresentado em uma dentre várias formas finais. O DocBook é mantido pelo grupo OASIS. O Site oficial do DocBook possui uma boa documentação introdutória e de referência e um livro O'Reilly completo que pode ser lido on-line. O FreeBSD Documentation Project também usa o DocBook e possui boas informações, incluindo vários guias para estilo que valem a pena serem levados em consideração.
Ferramentas
As seguintes ferramentas são utilizadas para processar, revisar e traduzir a documentação. Algumas podem ser opcionais, conforme indicado.
Esta é a definição do próprio DocBook. Atualmente é utilizada a versão 4.2; não utilize uma versão diferente desta. Observe que também existe uma versão XML do DocBook -- não utilize esta versão.
Entidades de caractere ISO 8879
Estas entidades são requeridas pelo DocBook, mas são distribuídas em separado porque são mantidas pela ISO.
- Este é o pacote básico para processar o SGML. Contém um analisador SGML, um processador DSSSL (ou seja, um programa para converter o SGML em outros formatos utilizando as folhas de estilo DSSSL), bem como várias ferramentas relacionadas.
Folhas de estilo DSSSL do DocBook
Contém instruções de processamento para converter os fontes em DocBook para outros formatos, tal como HTML.
- Este pacote opcional é utilizado para criar as man pages, e contém vários pacotes pré-requisitos próprios.
- Se for desejado, podem ser instalados também JadeTeX para utilizar o TeX como formatador para o Jade. O JadeTeX pode criar arquivos Postscript ou PDF.
- É um editor de textos muito poderoso. É quase compatível com o editor vi do UNIX. Pode ser utilizado para os processos de tradução e revisão da documentação.
- Editor de texto muito utilizado para trabalhar com SGML. Utilizado para os processos de tradução e revisão da documentação.
- É um verificador ortográfico muito útil. Pode ser usado em conjunto com os editores ViM e Emacs para visualizar as palavras que não estão presentes no dicionário.
A versão do dicionário em Português do Brasil está disponível em http://www.ime.usp.br/~ueda/br.ispell. Muitas distribuições já contém um pacote com o dicionário em Português falado no Brasil.
- Este arquivo contém um glossário dos termos mais utilizados no jargão do PostgreSQL. É essencial que se utilize estes termos na documentação para que a tradução fique uniforme.
- Este é o vocabulário padrão utilizado pelo grupo de tradução de documentação no Brasil. É essencial que utilize estes termos para que a tradução fique uniforme. Sempre consulte o Glossário do PostgreSQL antes deste pois ele não é tão específico quanto o outro.
- CVS é o sistema de controle de versões utilizado pelo PostgreSQL, que permite a manutenção das versões anteriores dos arquivos e registra quem, quando e porquê as mudanças ocurreram. Ele pode gerenciar vários desenvolvedores, diretórios e controlar várias operações e, também pode trabalhar em rede. No nosso caso, utilizaremos apenas o cliente para copiarmos a documentação do PostgreSQL.
- Subversion é o sistema de controle de versões utilizado pelo PostgreSQL Brasil para versionamento das traduções.
A instalação da ferramentas de processamento do DocBook (as 6 primeiras) está explicada na documentação do PostgreSQL. As outras estão disponíveis em quase todas as distribuições Linux e BSD. Consulte a documentação de cada distribuição para obter detalhes sobre a instalação de cada programa listado acima.
Como proceder
Esta seção explica como utilizar as ferramentas para processar, traduzir e revisar a documentação do PostgreSQL.
Supomos que você tenha instalado todos os programas requeridos e listados na seção anterior.
Atualmente temos no nosso repositório uma mistura entre versões. O objetivo é uniformizar todos os arquivos para a versão atual (8.3). Quando finalizarmos a tradução e revisão, atualizaremos a documentação para última versão da série 8.3 (atualmente a 8.3.1). Utilize como base para a tradução a versão 8.3.1 (depois atualizaremos para as versões subsequentes).
As versões que vamos manter não incluem versões que mudam apenas o patch level (terceiro dígito na versão), ou seja, não manteremos documentações para 8.2.1, 8.2.2, 8.2.3 e assim por diante. Ao invés disso, manteremos a documentação da versão estável de cada branch (ramificação), ou seja, 8.0, 8.1, 8.2 e assim por diante. A razão de fazermos isso é a dificuldade de manutenção de tantas versões da documentação e porque as mudanças entre cada patch level são mínimas.
O primeiro passo é copiar a documentação traduzida que está disponível no repositório SVN. Para saber mais sobre Sistemas de Controle de versão clique aqui.
svn co svn://svn.postgresql.org.br/pgbr/doc/trunk
O próximo passo é verificar o status da tradução e escolher o arquivo que será traduzido ou revisado. É uma boa prática perguntar (via lista de discussão) se alguém não já está trabalhando naquele arquivo; evitando assim duplicidade de trabalho.
É no status que estará presente qual a versão relativa aquela tradução. De posse dessa versão você pode verificar as modificações que ocorreram desde aquela versão até a versão de trabalho (8.3.1). Abaixo será exemplificado como fazer pela linha de comando, existem outras maneiras, inclusive pela interface Web, que podem ser vistas neste Tutorial.
Utilizando o comando cvs diff. Será necessário que você copie o código-fonte do PostgreSQL ou pelo menos o diretório doc/src/sgml. Para instruções de como fazer isso verifique a documentação.
$ cd /path/to/codigo/do/pg
$ export CVSROOT=:pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot
$ cvs login
Logging in to :pserver:anoncvs@anoncvs.postgresql.org:2401/projects/cvsroot
CVS password: (qualquer uma menos vazio)
$ cvs diff -u -rREL8_0_8 -rREL8_3_1 doc/src/sgml/arch-dev.sgml
.
.
.
$ cvs logout
Logging out of :pserver:anoncvs@anoncvs.postgresql.org:2401/projects/cvsroot
Ao terminar o trabalho, envie o arquivo compactado para a lista de discussão. Se a modificação for um revisão ou pequena correção, opte por enviar apenas um diff (-c ou -u). Ele será colocado juntamente com os arquivos já traduzidos e o status da tradução será atualizado.
Por enquanto, a revisão está sendo feita por apenas uma pessoa (Euler Taveira de Oliveira).
Durante a tradução não se esqueça de utilizar o Glossário do PostgreSQL e o Vocabulário Padrão do LDP-BR para que a tradução esteja uniforme com o que já existe. Aconselha-se aos novos colaboradores ler a parte traduzida para que o estilo de tradução também seja preservado.
Os créditos da tradução serão mantidos em nosso site. A documentação traduzida será mantida sob licença BSD e o direito autoral será delegado a Comunidade PostgreSQL Brasileira.
Nota
Esta seção está incompleta.