Minha Casa

Convenções

Aqui estão as nossas convenções, isto é, decisões tomadas pelo grupo quanto a determinados assuntos e algumas decisões do grupo do original. Também contém algumas dicas. É muito importante acompanha-las:

Não se altera de nenhuma forma as tags do xml, por exemplo você não traduz, e de preferência tente não fazer alterações que adicionem ou retirem tags.

Não se utiliza tabs para a indentação, isso é feito apenas com espaços. O motivo para isso é que o seu editor pode mostrar a tabulação com uma quantidade de espaços e o editor de outra pessoa mostrar com outra quantidade. Com isso acaba acontecendo de outra pessoa "consertar" esta formatação. Quanto esse arquivo for enviado para o CVS irá aparecer que a linha foi modificada, enquanto que na realidade foi modificada apenas a formatação e não o conteúdo. Isso torna difícil para os outros membros do grupo acompanharem quais modificações foram realizadas.

Os caracteres acentuados são escritos normalmente, como áéãõ sem problema nenhum. Isso foi fruto de muitas discussões e foi decidido assim, por tornar o manual mais simples para se ler(os fontes) e simplificar o nosso trabalho sendo que todas as ferramentas de geração do manual funcionam sem nenhum problema com a nossa acentuação. Você DEVE escrever como entidade HTML apenas os caracteres <, > e & que são, respectivamente, &lt;, &gt; e &amp;. Isso é regra para o xml mas é necessário para que o manual compile corretamente. Existe uma excessão, que é quando estiver escrevendo exemplos, onde todos os caracteres devem ser escritos normalmente.

Ainda sobre este assunto. Cuidado com o conjunto de caracteres usados. O windows, por padrão, sempre trabalha com iso-8859-1. Versões mais recentes do Linux tem trabalhado com uft-8(como o Ububtu 6.06 que eu usei no passado) e não mais com iso-8859-1. Para o manual do PHP, Smarty e PEAR deve ser usado o iso-8859-1, para o manual do PHP-GTK 2, deve ser usado utf-8. No linux isso não é problema porque vários editor suportam codificações diferentes, mas não conheço editor com suporte a utf-8 no windows.

Tenha cuidado para colocar a revisão correta. Uma explicação de como utilizar o sistema de revisões pode ser encontrada aqui.

Windows, Linux e Mac utilizam estilos de fim-de-linha diferentes. O padrão utilizado é o do Linux, então quando estiver em outro sistema operacional, escolha um editor que possa salvar com o fim-de-linha do Linux("\n"). O motivo para isso também é relacionado com o CVS. Quando o arquivo é gravado com um estilo de fim-de-linha diferente, o CVS mostra que todo o arquivo foi modificado. Existem vários editores que podem fazer isso no Windows. Você não deve usar o bloco de notas ou o Wordpad.

Isto não chega a ser uma convensão entre nós, mas uma prática comum. Quando você encontrar pequenos erros de ortografia ou gramatica em qualquer um dos arquivos traduzidos você pode altera-lo sem problema. Se for fazer uma alteração maior, é sempre bom entrar em contato com a pessoa que seja responsável por ele antes.

Adicionando exemplos: muitas funções do manual não tem exemplos. Se você quiser adicionar um pode faze-lo sem problemas. Tenha certeza de que ele esta correto. Você pode também adiciona-lo no manual em inglês se quiser, mas tanto o exemplo quanto algum comentário/explicação que ele contenha deverão estar em inglês neste caso.

Atualizando arquivos de outras pessoas: quando você quiser atualizar arquivos que sejam mantidos por outra pessoa sempre mande uma mensagem para a lista pedindo para o responsável atual se ele permite. Somente altere os arquivos se ele permitir ou se após um prazo(por exemplo, umas duas semanas) ele não responder.

Quando você for enviar arquivos para o cvs tenha cuidado para não enviar arquivos que contenham algum erro de xml que impeça a compilação do manual. Para isso, você precisa fazer o make test, ele vai indicar se existe algum erro no manual. Se for mandar arquivos para outra pessoa, também faça o make test.

A politica do pessoal da documentação original é que quando você faz algo de errado, você mesmo deve corrigir, mas nós adotamos algo diferente, assim, se tiver qualquer problema, basta pedir ajuda na nossa lista de discussão que os colegas do grupo vão lhe ajudar!