aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
blob: 5ead068fd910942f2434ea265a2b600b91ac5cba (plain) (blame)
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
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
<?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 id="overview">
  <title>Overview</title>

  <para>Welcome to the &os; Documentation Project
    (<acronym>FDP</acronym>).  Quality documentation is very important
    to the success of &os;.  Your contributions are very
    valuable.</para>

  <para>This document's main purpose is to explain 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>.  There is no membership requirement or
    minimum quota of documentation that needs to be produced.</para>

  <para>After you have finished reading this document you will be
    able to:</para>

  <itemizedlist>
    <listitem>
      <para>Identify which parts of &os; are maintained by the
	<acronym>FDP</acronym>.</para>
    </listitem>

    <listitem>
      <para>Install the required tools and files.</para>
    </listitem>

    <listitem>
      <para>Make changes to the documentation.</para>
    </listitem>

    <listitem>
      <para>Submit changes back for review and eventual inclusion in
	the &os; documentation.</para>
    </listitem>
  </itemizedlist>

  <sect1 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 <ulink
	    url="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</ulink>
	  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.</para>

    <para>Documentation source for the &os; web site, Handbook, and
      <acronym>FAQ</acronym> is available in the Subversion
      repository at
      <literal>https://svn.FreeBSD.org/doc/</literal>.</para>

    <para>Source for manual pages is available in a separate
      Subversion repository located at
      <literal>https://svn.FreeBSD.org/base/</literal>.</para>

    <para>The commit messages to the <acronym>FDP</acronym>
      are visible to anyone usingv<application>svn</application>.
      They are also archived at &a.svn-doc-all.url;.</para>

    <para>In addition, many people have written tutorials or how-to
      articles about &os;.  Some are stored in the
      <acronym>FDP</acronym>.  In other cases, the author has decided
      to keep the documentation separate from the
      <acronym>FDP</acronym>.  The <acronym>FDP</acronym> endeavors to
      provide links to as much of this documentation as
      possible.</para>
  </sect1>

  <sect1 id="overview-quick-start">
    <title>Quick Start</title>

    <para>This section outlines the steps which new contributors need
      to follow before they can make changes to the
      <acronym>FDP</acronym>.  New contributors will interact with
      other members of the &os; Documentation Team which can assist in
      learning how to use <acronym>XML</acronym> and the <xref
	linkend="writing-style-guide"/>.  If a new user contributes
      regularly, a Documentation Team member may be assigned as a
      mentor to guide the user through the process from contributor
      to documentation committer.</para>

    <procedure>
      <step>
	<para>Subscribe to the &a.doc;.  Some members of the mailing
	  list also interact on the <literal>#bsddocs</literal>
	  <acronym>IRC</acronym> channel on <ulink
	    url="http://www.efnet.org/">EFnet</ulink>.</para>
      </step>

      <step>
	<para>Install the
	  <filename role="package">textproc/docproj</filename>
	  package or port.  This meta-port installs all of the
	  utilities needed by the <acronym>FDP</acronym>.</para>
      </step>

      <step>
	<para>Install a local working copy of the documentation
	  from a mirror of the &os; repository.  For the fastest
	  download, pick the nearest mirror from the list of <ulink
	    url="&url.books.handbook;/subversion-mirrors.html">Subversion
	    mirror sites</ulink>.  If <filename
	    role="directory">/usr/doc</filename> already exists, move
	  or delete it first to prevent file conflicts.</para>

	<screen>&prompt.user; <userinput>svn checkout https://<replaceable>svn0.us-west.FreeBSD.org</replaceable>/doc/head <replaceable>/usr/doc</replaceable></userinput></screen>
	</step>

	<step>
	  <para>Before making any documentation edits, configure your
	    editor to conform to <acronym>FDP</acronym> standards.
	    How to do so varies by editor.  Some editor configurations
	    are listed in <xref linkend="writing-style"/>. The editor
	    should be configured as follows:</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>
	</step>

	<step>
	  <para>Determine which file to edit.  Run
	    <command>svn up</command> within the local working copy
	    to make sure that it is current.  Before making major
	    changes to a file, discuss the proposed changes first with
	    the &a.doc;.</para>

	  <para>When making edits, determine which tags and entities
	    are needed to achieve the desired formatting.  One way to
	    learn is to compare some text in the
	    <acronym>HTML</acronym> formatted version of the document
	    to the tags which surround the text or the entities that
	    represent that text in the <acronym>XML</acronym> file.
	    A reference to the commonly used tags and entities can be
	    found in <xref linkend="xhtml-markup"/> and
	    <xref linkend="docbook-markup"/>.</para>
	</step>

	<step>
	  <para>Once the edits are complete, check for problems by
	    running:</para>

	  <screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen>

	  <para>While reviewing the output, edit the file to fix the
	    listed tab errors, spelling mistakes, and improper
	    grammar.  Save the changes and rerun this command to find
	    any remaining problems.  Repeat until all of the errors
	    that you deem fixable are resolved.  If you get stuck
	    trying to fix errors, ask for assistance on the
	    &a.doc;.</para>
	</step>

	<step>
	  <para><emphasis>Always</emphasis> build-test changes before
	    submitting them.  By default, typing
	    <userinput>make</userinput> in the top-level directory of
	    the type of documentation being edited will generate that
	    documentation in split HTML format.  For example, to build
	    the English version of the Handbook, type
	    <userinput>make</userinput> in the
	    <filename>en_US.ISO8859-1/books/handbook/</filename>
	    directory.  This step is necessary to make sure that the
	    edits do not break the build.</para>
	</step>

	<step>
	  <para>In order to build the output in other formats, other
	    <application>make</application> targets are defined in
	    <filename>head/share/mk/doc.docbook.mk</filename>.  Use
	    quotes around the list of formats when building more than
	    one format with a single command.</para>

	  <para>For example, to convert the document to both
	    <literal>.html</literal> and <literal>.txt</literal>, use
	    this command:</para>

	  <screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen>

	<para>Once these steps are successfully completed, generate a
	  <quote>diff file</quote> of the changes.  While in <filename
	    class="directory">/usr/doc</filename>, run this command,
	  replacing <replaceable>bsdinstall</replaceable> with the
	  name of the directory containing the edits:</para>

	<screen>&prompt.user; <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen>
	</step>

	<step>
	  <para>Submit the diff file using the web-based <ulink
	      url="&url.base;/support.html#gnats">Problem
	      Report</ulink> system or with &man.send-pr.1;.  If using
	    the web form, input 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>.  The body of the message
	    should contain a short description of the edits and any
	    important discussion points.  Use the
	    <guibutton>[&nbsp;Browse...&nbsp;]</guibutton> button to
	    attach the <literal>.diff.txt</literal> file and enter
	    the captcha phrase.</para>

	  <para>It is important to remember that the
	    <acronym>FDP</acronym> is comprised of volunteers who
	    review edits in their spare time and who live in different
	    time zones across the globe.  It takes time to review
	    edits and to either commit them or respond if additional
	    edits are required.  If you do not receive a response in a
	    reasonable amount of time, send a follow-up email to the
	    &a.doc; and ask if anyone has had a chance to review the
	    patch or if additional information is required.</para>
	</step>
      </procedure>
    </sect1>
  </chapter>