| Projeto de Documentação do FreeBSD em Português Brasileiro | ||
|---|---|---|
| Anterior | Capítulo 2. Projeto DOC-BR internamente | Próxima |
Como parte de um exercício muito simples, faça checkout de todos os módulos relevantes do CVS do Projeto DOC-BR. Depois entre no diretório tools/sandbox/exercicios:
% cd ~/CVS_ROOT/doc-br % cvs co tools % cvs co pt_BR.ISO8859-1 % cvs co glossario % cd ~/CVS_ROOT/doc-br/tools/sandbox/exercicios
Neste diretório, observe uma série de arquivos SGML. Você pode utiliza-los da forma como achar conveniente, fique a vontade para modificá-los todos. Mas a primeira atividade proposta é com o arquivo exercicio-novo-membro.sgml.
Edite-o e modifique as entidades versao e author. Incremente “versao” em 0.1 (por exemplo, se ela é 1.2, coloque como 1.3) e modifique seu nome em author.
Com nsgmls verifique a integridade desse arquivo SGML:
% nsgmls -s exercicio-novo-membro.sgml
Se houver erro, corrija-os. Em seguida faça a normalização desse arquivo SGML para HTML com a aplicação sgmlnorm mantendo o DOCTYPE no resultado normalizado.
% sgmlnorm -d exercicio-novo-membro.sgml > exercicio-novo-membro.html
Analise então o conteúdo do arquivo e veja se as frases que mencionam a versão e autor do arquivo estão apresentando essa informação de maneira correta.
AtençãoNenhum desses dois passos são relacionados ao trabalho diário do DOC-BR, mas são etapas que o membro deve em teoria ter uma noção mínima de como funcionam, pois é isso que acontece quando compilamos nossos SGML tornando-os arquivos em formatos finais (PDF, doc, HTML, etc). Se no seu sistema não tem essas aplicações, então você não instalou o meta-port textproc/docproj, sendo assim provavelmente não leu o Primer do Projeto de Documentação do FreeBSD atenciosamente. Nesse caso você não precisa continuar lendo esse texto, pois estará desperdiçando seu tempo, e potencialmente o nosso. Usuários sem a sensibilidade para entender a relevância do Primer do Projeto de Documentação do FreeBSD e dos exercícios nele propostos não estão áptos à prover ajuda apreciada pela DOC-BR -- a não ser em casos muito especiais (já ter participado de um projeto desse tipo ou ter familiaridade com DocBook, por exemplo). Se não é o seu caso desconsidere esse parágrafo. Se é, por gentileza leia o Primer do Projeto de Documentação do FreeBSD atentamente.
Agora sim, finalmente vamos exercitar tarefas diárias do projeto. Ao acabar de editar o SGML, use o fdp.pl para verificar se houveram correções no arquivo:
% cp exercicio-novo-membro.sgml exercicio-novo-membro.sgml.bkp % ~/CVS_ROOT/DOC-BR/tools/scripts/fdp.pl exercicio-novo-membro.sgml > exercicio-novo-membro.sgml.novo Total de 2 linha(s) alterada(s) no arquivo exercicio-novo-membro.sgml
Caso hajam correções você verá uma linha de sumário similar à esta, dizendo o número de linhas alteradas. Não é possível saber quais alterações foram feitas e em quais linhas através do próprio fdpl.pl. De qualquer maneira no dia-a-dia não será necessário analisar o que foi modificado pela ferramenta, mas se desejar fazê-lo em alguma sitação particular, pode usar o diff(1), por exemplo:
Exemplo 2-8. Exemplo de uso do diff(1) para verificar modificações locais
% diff -u exercicio-novo-membro.sgml exercicio-novo-membro.sgml.novo
Ao terminar a correção com fdp.pl, renomeie o novo arquivo para o arquivo original:
% mv exercicio-novo-membro.sgml.novo exercicio-novo-membro.sgml
Agora é a vez de usar o sed(1) para transformar acentos em entidades SGML:
% sed -f ~/CVS_ROOT/DOC-BR/tools/scripts/acentos.sed exercicio-novo-membro.sgml > exercicio-novo-membro.sgml.novo % mv exercicio-novo-membro.sgml.novo exercicio-novo-membro.sgml
Em ambos os casos, nesse primeiro exercício você pode usar fdp.pl e o sed(1) sem apontar o novo arquivo, e analisar apenas a saída padrão. Nesse caso a alteração não terá sido feita, mas como o arquivo de exercício é pequeno você terá uma visão clara das modificações, em especial no caso do sed(1) com acentos.sed. No dia-a-dia esta prática não é muito viável pois o arquivo sendo trabalhado será grande.
Agora é hora de finalmente efetivar sua modificação, com um commit:
% cvs commit exercicio-novo-membro.sgml Password:
Ao término do commit você terá enviado seu arquivo para o CVS, portanto agora a versão disponível remotamente é a mesma que você tem localmente. Você notará que ao enviar o commit, o cvs(1) abrirá uma tela no seu editor de texto padrão (conteúdo da variável de ambiente EDITOR). Nele você deve escrever o log do motivo de seu commit. Você pode evitar este editor de textos e enviar a mensagem de log já na linha de comando, para tal use a opção -m do cvs(1):
% cvs commit -m 'atualizacao para versao 1.2, modificacao do author para meu nome' exercicio-novo-membro.sgml
Não faça commit sem logs!. Os logs não precisam ser detalhados, mas ao menos mencione o que foi feito. Por exemplo, logs ruins seriam:
Exemplo 2-9. Exemplos de maus logs de commit
“corrigindo ultimo problema”
“atualizando”
“continuando traducao, mais um pouco”
Nesses casos os logs mínimos deveriam conter:
Exemplo 2-10. Exemplos bons e curtos de logs de commit
“corrigindo problema por falta de entidade e erro de digitacao”
“atualizando capitulo 3, adicao de novo paragrafo, conformidade com rev 1.445”
“continuando traducao, agora 45% esta pronto; traduzido ate capitulo 4”
Dessa forma apenas lendo a mensagem de log do commit os companheiros de equipe saberão exatamente o que está acontecendo.
Para exercitar, tire diffs remotos desse arquivo com cvs diff, e se desejar modifique outros arquivos desse diretório e faça commit deles. Consulte também os logs dos arquivos com "cvs log".
Você notou que o método de autenticação CVS usado no DOC-BR é o SSH. Notou também que no commit o servidor CVS solicitou senha. De fato não só para cada commit, mas para cada ação como update ou checkout o servidor CVS sempre solicitará senha. Isso garante que o usuário que está fazendo o acesso CVS é mesmo quem ele diz ser.
Contudo alguns membros do time consideram ter que enviar a senha a todo momento incômodo demais. A solução nesse caso é configurar o ssh(1) para trabalhar com autenticação por chave pública ao fazer qualquer acesso no servidor CVS do Projeto DOC-BR.
Se você já tem uma chave privada, copie o par público dela (a chave pública) para o arquivo ~/.ssh/authorized_keys no servidor shell.berlios.de.
Se ainda não tem, é um bom momento para criá-la. Crie sua chave com o ssh-keygen(1). No caso do BerliOS especificamente a chave deve ser do tipo rsa. Use o parâmetro -t rsa do ssh-keygen(1). Note que a aplicação solicitará algumas informações, em especial onde armazenar suas chaves públicas e privadas (que em geral tem o nome id_rsa e id_rsa.pub no caso de chaves rsa. Solicitará também uma passphrase, que será a contra-chave para sua chave privada. Acompanhe o exemplo:
Exemplo 2-11. Exemplo de criação de chave pública e privada
% ssh-keygen -t rsa Generating public/private rsa key pair. Enter file in which to save the key (/usr/home/usuario/.ssh/id_rsa): Created directory '/usr/home/usuario/.ssh'. Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /usr/home/usuario/.ssh/id_rsa. Your public key has been saved in /usr/home/usuario/.ssh/id_rsa.pub. The key fingerprint is: c1:b4:83:97:bb:6e:a7:08:58:76:e5:b1:ba:3e:1a:40 usuario@seu.hostname.domainname
Em seguida copie sua chave pública para o servidor BerliOS:
% cat ~/.ssh/id_rsa.pub | ssh usuario_no_berlios@shell.berlios.de "cat - >>.ssh/authorized_keys"
Agora sempre que necessário, inicie o ssh-agent(1) apenas uma vez durante sua sessão de trabalho. Ele cuidará de enviar seu passphrase sempre que necessário, quando já estiver configurado. Para saber mais sobre o ssh-agent(1) e como configurá-lo, consulte a documentação do OpenSSH em http://openssh.org/.
Se desejar você pode ainda criar uma chave privada sem passphrase. Enquanto isso diminuirá drásticamente a segurança em potencial do ambiente, aumentará também a simplicidade. Se o passphrase não for usado, a autenticação remota se dará apenas com a chave privada, não sendo necessário jamais entrar a passphrase e como consequência, não sendo necessário o uso do ssh-agent(1).
Para gerar uma chave privada sem passphrase basta repetir o procedimento citado acima, mas quando o ssh-keygen(1) solicitar a passphrase dê apenas um ENTER. Quando solicitar confirmação do passphrase dê apenas um ENTER novamente.
AtençãoNote que se você criar uma chave privada sem passphrase, a autenticação acontecerá apenas com o uso de sua chave privada. Portanto multiplique seus cuidados com o arquivo ~/.ssh/id_rsa mil vezes. Qualquer pessoa que puder obter uma cópia desse arquivo poderá acessar o servidor com a chave pública correspondente à esta chave privada. No caso da DOC-BR, se alguém copiar o seu ~/.ssh/id_rsa poderá acessar o repositório CVS com seu usuário, mesmo não sabendo sua senha.
Salvo esta consideração, se você cuidar bem de sua chave privada pode criá-la sem passphrase para uso no CVS.
Agora ao acessar o servidor CVS do Projeto DOC-BR basta antes iniciar o ssh-agent(1). Ou se a chave privada não tem passphrase, nem isso é necessário, a autenticação das suas ações se fará por meio de chave privada, não sendo mais necessário entrar a senha de seu usuário cada vez que fizer acesso ao servidor cvs(1).
Este, e outros documentos, podem ser obtidos em ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.
Para perguntas sobre FreeBSD, leia a documentação antes de contatar <questions@FreeBSD.org>.
Para perguntas sobre esta documentação, envie e-mail para <doc@FreeBSD.org>.