aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
blob: 6a9458063b054ed06760ca6cdf5714941308643e (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
<?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>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 a
	  mirror of the &os; repository in
	  <filename>~/doc</filename> (see
	  <xref linkend="working-copy"/>).</para>

	<screen>&prompt.user; <userinput>svn checkout https://svn0.us-west.FreeBSD.org/doc/head ~/doc</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 ~/doc</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 /usr/doc</userinput>
&prompt.user; <userinput>svn diff &gt; bsdinstall.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 or with &man.send-pr.1;.  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>[&nbsp;Browse...&nbsp;]</guibutton> button to
	  attach the diff file.</para>
      </step>
    </procedure>
  </sect1>
</chapter>