2.1. Métodos de trabalho DOC-BR

O DOC-BR assume o método de trabalho indicado pelo Projeto de Documentação do FreeBSD, e possui ainda características próprias de trabalho. De forma geral todo trabalho é diretamente realizado por editores de texto que podem ser dos mais simples, como vi(1) e ee(1), à editores mais completos com vim(8) e emacs(8). O FDP aconselha uso do emacs(8) em especial por ele ter suporte à modo de operação SGML -- o chamado SGML-mode. No DOC-BR temos ainda que considerar a necessidade de trabalhar com acentos em padrão de entidades XML (SGML), isso quer dizer que palavras acentuadas não podem ter os acentos literais, mas sim, deve fazer uso dessas entidades para representar os caracteres especiais típicos de nossa língua -- chamados de padrão ISO 8859-1 ou suporte à caracteres latinos.

Por exemplo, a seguinte expressão:

Este é o Projeto de Documentação do FreeBSD.

Será escrito da seguinte forma:

Este é o Projeto de Documentação do FreeBSD.

Portanto temos que decidir como trabalhar essa necessidade. Alguns (poucos é verdade) membros do projeto trabalham em editores simples como ee(1) e vi(1) e escrevem as frases diretamente com essas entidades. Contudo isso é incomum e quase não-humano (rs). Não temos esperança nem é nosso desejo que você goste de escrever e ler dessa maneira.

Por isso você pode usar outros métodos. Editores como vim(8) por exemplo tem o modo de tradução de caracteres. Quando abre um arquivo ele pode converter as entidades SGML para acentos em nosso padrão de caracteres, e ao fechar o arquivo ele converte de volta nossos caracteres para entidades SGML. Dessa forma ao ler/editar no vim(8) o indivíduo sempre terá o texto literal, e o resultado final salvo no arquivo serão as entidades. Tudo de forma transparente.

Outros membros preferem usar editores da base como vi(1) ou ee(1) e traduzir tudo com acentos. Antes de normalizar ou analisar a sintaxe do arquivo SGML contudo, transforma seus acentos em entidades SGML. Esse particularmente é o método que este que está escrevendo esse arquivo SGML adota.

Ou com emacs(8) você pode escolher como quer trabalhar. O fato é, você deve optar pelo editor de texto o qual tem mais aptidão e fica mais confortável para trabalhar. O trabalho é grande e não muito simples, então o editor de texto não precisa ser algo a mais à aprender ou adaptar-se.

O Projeto de Documentação em Português Brasileiro do FreeBSD dispõe de scripts e arquivos de configurações para auxiliar o trabalho do desenvolvedor. Portanto seja qual for sua opção editor de texto, terá ferramentas para auxiliá-lo. Complementarmente o time criou também um script em linguagem Perl que analisa o arquivo SGML e revisa algumas das principais regras do FDP. Por exemplo, você viu ao ler o Primer do Projeto de Documentação do FreeBSD que a identação das colunas deve seguir 2 caracteres de espaço. Que cada oito espaços devem ser substituídos por um \t (tab). Que o final de uma sentença deve ser denotado com dois espaços se não houver quebra de linhas ou final de parágrafo, que as linhas devem acabar no máximo na coluna 84 ou preferencialmente antes da coluna 70, etc. O script corrige todas as regras que ele for capaz e dispara um alerta para as regras que não conseguir corrigir.

A outra ferramenta que o contribuidor do DOC-BR deve conhecer, ao menos o básico é o cvs(1). Nosso projeto faz uso de um servidor cvs(1) para armazenas e possibilitar o trabalho paralelo das dezenas de membros simultâneamente. As vantagens do CVS é ter um controle rígido sobre versões, podendo restaurar um arquivo errôneamente modificado à qualquer momento, e possibilitar trabalho concorrente de diversos indivíduos. A desvantagem é que é algo mais à se aprender, caso você não tenha familiaridade com essa conhecida ferramenta.

Por último, o método de comunicação entre todos os membros do DOC-BR é através de correio eletrônico, especificamente a lista de discussão DOC disponível na $fug;. Saiba como participar da lista na seção seguinte deste documento.