Capítulo 1. Visão Geral

Índice
1.1. Quick Start
1.2. Conjunto de Documentação do FreeBSD

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:

1.1. Quick Start

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.

  1. 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
  2. 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
  3. 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.

  4. Atualize a árvore de trabalho local:

    % svn up ~/doc
  5. 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.

  6. 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.

  7. 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/.

  8. 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.

  9. 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 [ Add an attachment ] para anexar o arquivo diff. Finalmente, pressione o botão [ Submit Bug ] 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>.