1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
---
description: 'Visão geral sobre o Processo de Documentação do FreeBSD'
next: books/fdp-primer/tools
prev: books/fdp-primer/preface
tags: ["overview", "FreeBSD Documentation Project", "quick start"]
title: 'Capítulo 1. Visão Geral'
---
[[overview]]
= Visão geral
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:source-highlighter: rouge
:experimental:
:skip-front-matter:
:xrefstyle: basic
:relfileprefix: ../
:outfilesuffix:
:sectnumoffset: 1
include::shared/releases.adoc[]
include::shared/pt-br/mailing-lists.adoc[]
toc::[]
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.
[[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.
[.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 python3
....
+
. 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 antes de submeter algo. Execute `make` no diretório de nível superior da documentação e assim será gerado a documentação no formato HTML.
+
[source, shell]
....
% make
....
+
. Quando as alterações estiverem completas e testadas, gere um "arquivo diff":
+
[source, shell]
....
% cd ~/doc
% git diff > bsdinstall.diff.txt
....
+
Dê ao arquivo diff um nome. No exemplo acima, foram feitas alterações na parte [.filename]#bsdinstall# do Handbook.
. Submeta o 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 _[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 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:{git-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.
|
