--- description: 'Visão geral sobre o Processo de Documentação do FreeBSD' next: books/fdp-primer/tools params: path: "/books/fdp-primer/overview/" prev: books/fdp-primer/preface showBookMenu: 'true' tags: ["overview", "FreeBSD Documentation Project", "quick start"] title: 'Capítulo 1. Visão Geral' weight: 2 --- [[overview]] = Visão geral :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 1 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] 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: * Compreender o papel da documentação e seu lugar no ecossistema. * 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. [[overview-documentation-ecosystem]] == Documentação no Ecossistema FreeBSD Todos os documentos são para o benefício de seus leitores, não de seus escritores ou zeladores. Eles devem se adaptar ao leitor e não esperar que o leitor se adapte a eles. Nunca culpe o leitor por: * ser incapaz de fazer uso de um documento facilmente ou de tudo * achar o documento confuso * não entender o documento ou como utilizá-lo * não encontrar uma resposta explícita ou preencher lacunas com sucesso (ou conectando pontos) para raciocinar em direção a uma Em vez disso, reconheça que o documento é: * inacessível * confuso * difícil de entender ou utilizar * incompleto Em seguida, faça o documento: * mais acessível * menos confuso * mais claro * mais completo Use os seguintes métodos: * aplique as link:https://webaim.org/intro/#principles[melhores práticas de acessibilidade] para corrigir o problema relatado e quaisquer outros semelhantes que você encontrar * refazer ou esclarecer a estrutura ou linguagem confusa * adicionar exemplos relevantes para a parte que é difícil de entender ou aplicar * preencha as lacunas ou adicione os degraus que faltam [[overview-quick-start]] == Introdução Algumas etapas preparatórias devem ser seguidas antes de editar a documentação do FreeBSD. Primeiro, se registre na {freebsd-doc}. Alguns membros do time também interagem no IRC, canal `#bsddocs` na rede http://www.efnet.org/[EFnet]. Estas pessoas podem ajudar com questões e problemas envolvendo documentação. [[freebsd-installation-process]] === Processo de instalação do FreeBSD [.procedure] ==== . Instale esses pacotes. O _meta-port_ `docproj` instala todos os aplicativos necessários para editar e compilar a documentação do FreeBSD. + [source, shell] .... # pkg install docproj .... + . Obtenha uma cópia local da árvore de documentação do FreeBSD em [.filename]#~/doc# (ver crossref:working-copy[working-copy,A Área de Trabalho]). + [source, shell] .... % git clone https://git.FreeBSD.org/doc.git ~/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. + 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 e revise as alterações antes de submeter algo. Execute `make` no diretório `documentation` ou `website` para gerar a documentação no formato HTML. + [source, shell] .... % make .... + Para reduzir o tempo de compilação, apenas um idioma pode ser compilado: + [source, shell] .... % make DOC_LANG=en .... + A saída da compilação é armazenada em [.filename]#~/doc/documentation/public/en/articles/# e [.filename]#~/doc/documentation/public/en/books/#. + . Revise a saída da compilação e certifique-se de que as edições não contenham erros de digitação, problemas de layout ou erros. Se algum erro for encontrado durante o processo de compilação, edite os arquivos com erro para corrigir quaisquer problemas que apareçam e, em seguida, execute o comando de compilação novamente até que todos os erros sejam resolvidos. + . Adicione todos os arquivos com `git add .`, então revise o diff com `git diff`. Por exemplo: + [source, shell] .... % git add . % git diff --staged .... + Certifique-se de que todos os arquivos necessários estejam incluídos, então confirme a mudança em seu branch local e gere um patch com `git format-patch` + [source, shell] .... % git commit % git format-patch origin/main .... + Patch gerado com `git format-patch` incluirá a identidade do autor e endereços de e-mail, tornando mais fácil para os desenvolvedores aplicarem (com `git am`) e dar os devidos créditos. + [IMPORTANT] ====== Para tornar mais fácil para os committers aplicarem o patch em sua cópia de trabalho da árvore de documentação, por favor, gere o [.filename]#.diff# da base de sua árvore de documentação. ====== + No exemplo acima, foram feitas alterações na parte [.filename]#bsdinstall# do Handbook. + . Submeta o patch or arquivo diff pela web para o sistema de https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[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 btn:[Add an attachment] para anexar o patch ou arquivo diff. Finalmente, pressione o botão btn:[Submit Bug] para enviar seu diff para o sistema de relatório de problemas. ==== [[gnu-linux-installation-process]] === Processo de instalação GNU/Linux [.procedure] ==== . Instale esses pacotes em sistemas baseados em apt como Debian ou Ubuntu. Em outras distribuições GNU/Linux os nomes dos pacotes podem mudar. Consulte o gerenciador de pacotes da sua distribuição em caso de dúvida. + [source, shell] .... # apt install hugo ruby-asciidoctor ruby-asciidoctor-pdf ruby-rouge git bmake .... + . Obtenha uma cópia local da árvore de documentação do FreeBSD em [.filename]#~/doc# (ver crossref:working-copy[working-copy,A Área de Trabalho]). + [source, shell] .... % git clone https://git.FreeBSD.org/doc.git ~/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. + Revise a saída e edite os arquivos 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 compile e teste as alterações antes de enviá-las. A execução de `bmake` nos subdiretórios `documentation` ou `website` irá gerar a documentação em formato HTML. + [source, shell] .... % bmake run LOCALBASE=/usr .... + . Adicione todos os arquivos com `git add .`, então revise o diff com `git diff`. Por exemplo: + [source, shell] .... % git add . % git diff --staged .... + Certifique-se de que todos os arquivos necessários estejam incluídos, então confirme a mudança em seu branch local e gere um patch com `git format-patch` + [source, shell] .... % git commit % git format-patch origin/main .... + Patch gerado com `git format-patch` incluirá a identidade do autor e endereços de e-mail, tornando mais fácil para os desenvolvedores aplicarem (com `git am`) e dar os devidos créditos. + [IMPORTANT] ====== Para tornar mais fácil para os committers aplicarem o patch em sua cópia de trabalho da árvore de documentação, por favor, gere o [.filename]#.diff# da base de sua árvore de documentação. ====== + . Submeta o patch ou arquivo diff file pela web para o sistema de https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Relatórios de Problema]. Se estiver usando o formulário web, insira um Sumário com uma _breve descrição 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 e adicione _patch_ no campo _Keywords_. Use o botão btn:[Add an attachment] para anexar o patch ou arquivo diff. Finalmente, pressione o botão btn:[Submit Bug] para enviar seu diff para o sistema de relatório de problemas. ==== [[mac-os-installation-process]] === Processo de instalação do macOS(R) [.procedure] ==== . Instale esses pacotes usando o link:https://brew.sh/[Homebrew] e o link:https://rubygems.org/[RubyGem]. + [source, shell] .... $ brew install hugo ruby git bmake .... + . Adicione o Ruby ao Path. + [source, shell] .... $ echo 'export GEM_PATH="/usr/local/lib/ruby/gems/3.1.0"' >> ~/.zshrc $ echo 'export PATH="$(brew --prefix ruby)/bin:$PATH"' >> ~/.zshrc $ source ~/.zshrc .... + . Adicione o alias do git ao Homebrew, pois `git format-patch` do git fornecido pela Apple não funcionará com o Phabricator. + [source, shell] .... $ echo 'alias git=/usr/local/bin/git' >> ~/.zshrc $ source ~/.zshrc .... . Instale o pacote rouge usando RubyGem. + [source, shell] .... $ sudo gem install rouge asciidoctor asciidoctor-pdf asciidoctor-epub3 .... + . Obtenha uma cópia local da árvore de documentação do FreeBSD em [.filename]#~/doc# (ver crossref:working-copy[working-copy,A Área de Trabalho]). + [source, shell] .... $ git clone https://git.FreeBSD.org/doc.git ~/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. + Revise a saída e edite os arquivos 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 compile e teste as alterações antes de enviá-las. A execução de `bmake` nos subdiretórios `documentation` ou `website` irá gerar a documentação em formato HTML. + [source, shell] .... $ bmake run USE_RUBYGEMS=YES RUBY_CMD=$(brew --prefix ruby)/bin/ruby .... . Adicione todos os arquivos com `git add .`, então revise o diff com `git diff`. Por exemplo: + [source, shell] .... % git add . % git diff --staged .... + Certifique-se de que todos os arquivos necessários estejam incluídos, então confirme a mudança em seu branch local e gere um patch com `git format-patch` + [source, shell] .... % git commit % git format-patch origin/main .... + Patch gerado com `git format-patch` incluirá a identidade do autor e endereços de e-mail, tornando mais fácil para os desenvolvedores aplicarem (com `git am`) e dar os devidos créditos. + [IMPORTANT] ====== Para tornar mais fácil para os committers aplicarem o patch em sua cópia de trabalho da árvore de documentação, por favor, gere o [.filename]#.diff# da base de sua árvore de documentação. ====== + . Submeta o patch ou arquivo diff file pela web para o sistema de https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Relatórios de Problema]. Se estiver usando o formulário web, insira um Sumário com uma _breve descrição 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 e adicione _patch_ no campo _Keywords_. Use o botão btn:[Add an attachment] para anexar o patch ou arquivo diff. Finalmente, pressione o botão btn:[Submit Bug] para enviar seu diff para o sistema de relatório de problemas. ==== [[overview-doc]] == Conjunto de Documentação do FreeBSD O FDP é responsável por quatro categorias de documentação do FreeBSD. * _Handbook_: O Handbook almeja ser um compreensivo recurso de referência online para os usuários do FreeBSD. * _FAQ_: O FAQ utiliza um formato curto de pergunta e resposta para abordar dúvidas que são frequentemente realizadas nas listas de discussão e fóruns dedicados ao FreeBSD. Este formato não permite respostas longas e detalhadas. * _Páginas de Manual_: As páginas de manual do sistema de língua inglesa geralmente não são escritas pelo FDP, pois fazem parte do sistema base. Contudo, o FDP pode reformular partes das páginas de manual existentes para torná-las mais claras ou para corrigir imprecisões. * _Web site_: Esta é a presença principal do FreeBSD na web, visite https://www.freebsd.org/[https://www.FreeBSD.org/] e muitos mirrors ao redor do mundo. O site é tipicamente o primeiro contato de um usuário novo com o FreeBSD. As equipes de tradução são responsáveis por traduzir o manual e o site para diferentes idiomas. As páginas do manual não são traduzidas no momento. Código fonte do site do FreeBSD, Handbook, e FAQ estão disponíveis no repositório de documentação em `https://cgit.freebsd.org/doc/`. Código fonte das páginas de manual estão disponíveis em um repositório diferente localizado em `https://cgit.freebsd.org/src/`. As mensagens de commit de documentação podem ser visualizadas com `git log`. As mensagens de commit também são arquivadas em link:{dev-commits-doc-all}. Endereço web para ambos os repositórios disponíveis em https://cgit.freebsd.org/doc/[] e https://cgit.freebsd.org/src/[]. Muitas pessoas tem escrito tutoriais e artigos how-to sobre FreeBSD. Alguns são armazenados como parte dos arquivos FDP. Em outros casos, o autor decidiu manter a documentação separada. O FDP esforça-se para fornecer links para o máximo possível dessas documentações externas.