Seja bem vindo ao Projeto de Documentação do FreeBSD.(FDP). Documentação de boa qualidade é muito importante para o sucesso do FreeBSD, e nós valorizamos muito suas contribuições.
Este documento descreve como o FDP é organizado, como escrever e como submeter documentos, e como utilizar de forma efetiva as ferramentas que estão disponíveis.
Todos são bem vindos para se juntar ao FDP. A vontade de contribuir é o único requisito de adesão.
Este primer mostra como:
Identificar quais partes do FreeBSD são mantidas pelo FDP.
Instalar as ferramentas e arquivos de documentação necessários.
Realizar alterações na documentação.
Enviar de volta alterações para revisão e inclusão na documentação do FreeBSD.
Algumas etapas preparatórias devem ser seguidas antes de editar a documentação do FreeBSD. Primeiro, se registre na lista de email do projeto de documentação do FreeBSD. Alguns membros do time também interagem no IRC, canal #bsddocs
na rede EFnet. Estas pessoas podem ajudar com questões e problemas envolvendo documentação.
Instale o meta-port textproc/docproj e o Subversion. Este meta-port instala todo software necessário para editar e compilar a documentação do FreeBSD. O pacote Subversion é necessário para obter uma cópia de trabalho da documentação e para gerar patches.
#
pkg install docproj subversion
Obtenha uma cópia local da árvore de documentação do FreeBSD em ~/doc
(see Capítulo 3, A Área de Trabalho).
%
svn checkout https://svn.FreeBSD.org/doc/head
~/doc
Configure o editor de texto:
Defina a quebra de linha para 70 caracteres.
Defina a parada de tabulação para 2.
Substitua cada grupo de 8 espaços por um tab.
Configurações específicas por editor são informados em Capítulo 15, Configuração do Editor.
Atualize a árvore de trabalho local:
%
svn up
~/doc
Edite os arquivos de documentação que precisam de alterações. Se um arquivo precisar de grandes mudanças, consulte a lista de discussão para obter informações.
Referencias pra uso de tag e entidade podem ser encontradas em Capítulo 8, XHTML Markup and Capítulo 9, DocBook Markup.
Após alteração, cheque por eventuais problemas rodando:
%
igor -R filename.xml | less -RS
Revise a saída e edite o arquivo para corrigir os problemas informados e, em seguida, execute novamente o comando para verificar os problemas restantes. Repita até que todos os erros sejam resolvidos.
Sempre realize testes de compilação antes de submeter algo. Execute make
no diretório de nível superior da documentação alterada e assim será gerado a documentação no formato HTML com divisões. Por exemplo, pra compilar a versão Inglês do Handbook em HTML, execute make
no diretório en_US.ISO8859-1/books/handbook/
.
Quando as alterações estiverem completas e testadas, gere um “arquivo diff”:
%
cd ~/doc
%
svn diff >
bsdinstall
.diff.txt
Dê ao arquivo diff um nome. No exemplo acima, foram feitas alterações na parte bsdinstall
do Handbook.
Submeta o arquivo diff file pela web para o sistema de Relatórios de Problema. Se estiver usando o formulário web, insira um Sumário com [patch] descrição curta do problema
. Selecione o Componente Documentation
. No campo de Descrição, insira uma breve descrição das alterações e quaisquer detalhes importantes sobre elas. Use o botão para anexar o arquivo diff. Finalmente, pressione o botão para enviar seu diff para o sistema de relatório de problemas.
All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.