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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="overview">
<title>Overview</title>
<para>Welcome to the &os; Documentation Project
(<acronym>FDP</acronym>). Quality documentation is crucial
to the success of &os;, and we value your contributions very
highly.</para>
<para>This document describes how the <acronym>FDP</acronym> is
organized, how to write and submit documentation, and how to
effectively use the available tools.</para>
<para>Everyone is welcome to contribute to the
<acronym>FDP</acronym>. Willingness to contribute is the only
membership requirement.</para>
<para>This primer shows how to:</para>
<itemizedlist>
<listitem>
<para>Identify which parts of &os; are maintained by the
<acronym>FDP</acronym>.</para>
</listitem>
<listitem>
<para>Install the required documentation tools and files.</para>
</listitem>
<listitem>
<para>Make changes to the documentation.</para>
</listitem>
<listitem>
<para>Submit changes back for review and inclusion in the &os;
documentation.</para>
</listitem>
</itemizedlist>
<sect1 xml:id="overview-doc">
<title>The &os; Documentation Set</title>
<para>The <acronym>FDP</acronym> is responsible for four
categories of &os; documentation.</para>
<itemizedlist>
<listitem>
<para><emphasis>Handbook</emphasis>: The Handbook is the
comprehensive online resource and reference for &os;
users.</para>
</listitem>
<listitem>
<para><emphasis>FAQ</emphasis>: The <acronym>FAQ</acronym>
uses a short question and answer format to address questions
that are frequently asked on the various mailing lists and
forums devoted to &os;. This format does not permit long
and comprehensive answers.</para>
</listitem>
<listitem>
<para><emphasis>Manual pages</emphasis>: The English language
system manual pages are usually not written by the
<acronym>FDP</acronym>, as they are part of the base system.
However, the <acronym>FDP</acronym> can reword parts of
existing manual pages to make them clearer or to correct
inaccuracies.</para>
</listitem>
<listitem>
<para><emphasis>Web site</emphasis>: This is the main &os;
presence on the web, visible at <link xlink:href="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</link>
and many mirrors around the world. The web site is
typically a new user's first exposure to &os;.</para>
</listitem>
</itemizedlist>
<para>Translation teams are responsible for translating the
Handbook and web site into different languages. Manual pages
are not translated at present.</para>
<para>Documentation source for the &os; web site, Handbook, and
<acronym>FAQ</acronym> is available in the documentation
repository at
<literal>https://svn.FreeBSD.org/doc/</literal>.</para>
<para>Source for manual pages is available in a separate
source repository located at
<literal>https://svn.FreeBSD.org/base/</literal>.</para>
<para>Documentation commit messages are visible with
<command>svn log</command>. Commit messages are also
archived at <uri xlink:href="&a.svn-doc-all.url;">&a.svn-doc-all.url;</uri>.</para>
<para>Web frontends to both of these repositories are available at <link
xlink:href="https://svnweb.FreeBSD.org/doc/"></link> and <link
xlink:href="https://svnweb.FreeBSD.org/base/"></link>.</para>
<para>Many people have written tutorials or how-to articles about
&os;. Some are stored as part of the <acronym>FDP</acronym>
files. In other cases, the author has decided to keep the
documentation separate. The <acronym>FDP</acronym> endeavors to
provide links to as much of this external documentation as
possible.</para>
</sect1>
<sect1 xml:id="overview-quick-start">
<title>Quick Start</title>
<para>Some preparatory steps must be taken before editing the &os;
documentation. First, subscribe to the &a.doc;. Some team
members also interact on the <literal>#bsddocs</literal>
<acronym>IRC</acronym> channel on
<link xlink:href="http://www.efnet.org/">EFnet</link>. These people
can help with questions or problems involving the
documentation.</para>
<procedure>
<step>
<para>Install the
<package>textproc/docproj</package>
package or port. This meta-port installs all of the
software needed to edit and build &os; documentation.</para>
</step>
<step>
<para>Install a local working copy of the documentation from
the &os; repository in
<filename>~/doc</filename> (see
<xref linkend="working-copy"/>).</para>
<screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>
</step>
<step>
<para>Configure the text editor:</para>
<itemizedlist>
<listitem>
<para>Word wrap set to 70 characters.</para>
</listitem>
<listitem>
<para>Tab stops set to 2.</para>
</listitem>
<listitem>
<para>Replace each group of 8 leading spaces with a
single tab.</para>
</listitem>
</itemizedlist>
<para>Specific editor configurations are listed in
<xref linkend="editor-config"/>.</para>
</step>
<step>
<para>Update the local working copy:</para>
<screen>&prompt.user; <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen>
</step>
<step>
<para>Edit the documentation files that require changes. If a
file needs major changes, consult the mailing list for
input.</para>
<para>References to tag and entity usage can be found in
<xref linkend="xhtml-markup"/> and
<xref linkend="docbook-markup"/>.</para>
</step>
<step>
<para>After editing, check for problems by running:</para>
<screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen>
<para>Review the output and edit the file to fix any problems
shown, then rerun the command to find any remaining
problems. Repeat until all of the errors are
resolved.</para>
</step>
<step>
<para><emphasis>Always</emphasis> build-test changes before
submitting them. Running <userinput>make</userinput> in the
top-level directory of the documentation being edited will
generate that documentation in split HTML format. For
example, to build the English version of the Handbook in
<acronym>HTML</acronym>, run <command>make</command> in the
<filename>en_US.ISO8859-1/books/handbook/</filename>
directory.</para>
</step>
<step>
<para>When changes are complete and tested, generate a
<quote>diff file</quote>:</para>
<screen>&prompt.user; <userinput>cd ~/doc</userinput>
&prompt.user; <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen>
<para>Give the diff file a descriptive name. In the example
above, changes have been made to the
<filename>bsdinstall</filename> portion of
the Handbook.</para>
</step>
<step>
<para>Submit the diff file using the web-based
<link xlink:href="&url.base;/support.html#gnats">Problem
Report</link> system. If using
the web form, enter a synopsis of
<emphasis>[patch] <replaceable>short description of
problem</replaceable></emphasis>. Select the category
<literal>docs</literal> and the class
<literal>doc-bug</literal>. In the body of the message,
enter a short description of the changes and any important
details about them. Use the
<guibutton>[ Browse... ]</guibutton> button to
attach the diff file.</para>
</step>
</procedure>
</sect1>
</chapter>
|
