aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml
blob: 4ca7dfa1edf3a5db651e90994a1c595647cf36cb (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
296
297
298
299
300
<!-- 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 FreeBSD Documentation Project.  Good quality
    documentation is very important to the success of FreeBSD, and the
    FreeBSD Documentation Project (FDP) is how a lot of that documentation
    is produced.  Your contributions are very valuable.</para>
  
  <para>This document's main purpose is to clearly explain <emphasis>how
    the FDP is organized</emphasis>, <emphasis>how to write and submit
    documentation to the FDP</emphasis>, and <emphasis>how to
    effectively use the tools available to you when writing
    documentation</emphasis>.</para>
  
  <para><indexterm>
      <primary>Membership</primary>
    </indexterm>
    Everyone is welcome to join the FDP.  There is no minimum
    membership requirement, no quota of documentation you need to
    produce per month.  All you need to do is subscribe to the
    &a.doc;.</para>

  <para>After you have finished reading this document you should:</para>
  
  <itemizedlist>
    <listitem> 
      <para>Know which documentation is maintained by the FDP.</para>
    </listitem>
    
    <listitem>
      <para>Be able to read and understand the SGML source code for the
	documentation maintained by the FDP.</para>
    </listitem>
    
    <listitem> 
      <para>Be able to make changes to the documentation.</para>
    </listitem>
    
    <listitem>
      <para>Be able to submit your changes back for review and eventual
	inclusion in the FreeBSD documentation.</para>
    </listitem> 
  </itemizedlist>

  <sect1 id="overview-doc">
    <title>The FreeBSD Documentation Set</title>

    <para>The FDP is responsible for four categories of FreeBSD
      documentation.</para>
    
    <variablelist>
      <varlistentry>
        <term>Manual pages</term>

        <listitem>
          <para>The English language system manual pages are not written by
	    the FDP, as they are part of the base system. However, the FDP can
	    (and has) re-worded parts of existing manual pages to make them
	    clearer, or to correct inaccuracies.</para>

          <para>The translation teams are responsible for translating the
	    system manual pages into different languages.  These translations
	    are kept within the FDP.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>FAQ</term>
	
        <listitem>
          <para>The FAQ aims to address (in short question and answer format)
	    questions that are asked, or should be asked, on the various
	    mailing lists and newsgroups devoted to FreeBSD.  The format does
	    not permit long and comprehensive answers.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Handbook</term>

        <listitem>
          <para>The Handbook aims to be the comprehensive on-line resource and
	    reference for FreeBSD users.</para>
        </listitem>
      </varlistentry>
 
      <varlistentry>
         <term>Web site</term>
	
         <listitem>
           <para>This is the main FreeBSD presence on the World Wide Web,
	    visible at <ulink
	      url="../../../../index.html">http://www.FreeBSD.org/</ulink>
	    and many mirrors around the world.  The web site is many people's
	    first exposure to FreeBSD.</para>
	</listitem>
      </varlistentry>
    </variablelist>
    
    <para>These four groups of documentation are all available in the
      FreeBSD CVS tree.  This means that the logs of changes to these
      files are visible to anyone, and anyone can use a program such as
      <application>CVSup</application> or
      <application>CTM</application> to keep local copies of
      this documentation.</para>
    
    <para>In addition, many people have written tutorials or other web
      sites relating to FreeBSD.  Some of these are stored in the CVS
      repository as well (where the author has agreed to this).  In
      other cases the author has decided to keep his documentation
      separate from the main FreeBSD repository.  The FDP endeavours to
      provide links to as much of this documentation as
      possible.</para>
  </sect1>                                                                     
  
  <sect1 id="overview-before">
    <title>Before you start</title>                                            
    
    <para>This document assumes that you already know:</para>                  
    
    <itemizedlist>                                                             
      <listitem>                                                               
	<para>How to maintain an up-to-date local copy of the FreeBSD
	  documentation by maintaining a local copy of the
	  FreeBSD CVS repository (using <application>CVS</application>
	  and either <application>CVSup</application> or
	  <application>CTM</application>) or by using
	  <application>CVSup</application> to download just a
	  <emphasis>checked-out</emphasis> copy.</para>
      </listitem>
      
      <listitem>                                                               
	<para>How to download and install new software using either the
	  FreeBSD Ports system or &man.pkg.add.1;.</para>
      </listitem>                                                              
    </itemizedlist>                                                            
  </sect1>

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

    <para>If you just want to get going, and feel confident you can pick
      things up as you go along, follow these instructions.</para>

    <procedure>
      <step>
	<para>Install the <filename role="package">textproc/docproj</filename>
	  meta-port.</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput>
&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
      </step>

      <step>
	<para>Get a local copy of the FreeBSD <filename>doc</filename> tree.
	  Either use CVSup in <literal>checkout</literal> mode to do this, or
	  get a full copy of the CVS repository locally.</para>

	<para>If you have the CVS repository locally then as a minimum you
	  will need to checkout the <filename>doc/share</filename>, and
	  <filename>doc/en_US.ISO8859-1/share</filename>
	  directories.</para>

	<screen>&prompt.user; <userinput>cvs checkout doc/share</userinput>
&prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/share</userinput></screen>

	<para>If you have plenty of disk space then you could check out
	  everything.</para>

	<screen>&prompt.user; <userinput>cvs checkout doc</userinput></screen>
      </step>

      <step>
	<para>If you are preparing a change to an existing book or article,
	  check it out of the repository as necessary.  If you are planning on
	  contributing a new book or article then use an existing one as a
	  guide.</para>

	<para>For example, if you want to contribute a new article about
	  setting up a VPN between FreeBSD and Windows 2000 you might do the
	  following.</para>

	<procedure>
	  <step>
	    <para>Check out the <filename>articles</filename>
	      directory.</para>

	    <screen>&prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/articles</userinput></screen>
	  </step>

	  <step>
	    <para>Copy an existing article to use as a template.  In this
	      case, you have decided that your new article belongs in a
	      directory called <filename>vpn-w2k</filename>.</para>

	    <screen>&prompt.user; <userinput>cd doc/en_US.ISO8859-1/articles</userinput>
&prompt.user; <userinput>cp -r committers-guide vpn-w2k</userinput></screen>
	  </step>
	</procedure>

	<para>If you wanted to edit an existing document, such as the FAQ,
	  which is in <filename>doc/en_US.ISO8859-1/books/faq</filename> you
	  would check it out of the repository like this.</para>

	<screen>&prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/books/faq</userinput></screen>
      </step>

      <step>
	<para>Edit the <filename>.sgml</filename> files using your editor of
	  choice.</para>
      </step>

      <step>
	<para>Test the markup using the <maketarget>lint</maketarget>
	  target.  This will quickly find any errors in the document
	  without actually performing the time-consuming
	  transformation.</para>

	<screen>&prompt.user; <userinput>make lint</userinput></screen>

	<para>When you are ready to actually build the document, you
  	  may specify a single format or a list of formats in the
  	  <varname>FORMATS</varname> variable.  Currently,
  	  <literal>html</literal>, <literal>html-split</literal>,
  	  <literal>txt</literal>, <literal>ps</literal>,
  	  <literal>pdf</literal>, and <literal>rtf</literal> are
  	  supported.  The most up to date list of supported formats is
  	  listed at the top of the
  	  <filename>doc/share/mk/doc.docbook.mk</filename> file.  Make
  	  sure to use quotes around the list of formats when you build
  	  more than one format with a single command.</para>

        <para>For example, to convert the document to
          <literal>html</literal> only, you would use:</para>

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

        <para>But when you want to convert the document to both
          <literal>html</literal> and <literal>txt</literal> format,
          you could use either two separate &man.make.1; runs,
          with:</para>

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

        <para>or, you can do it in one command:</para>

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

      <step>
	<para>Submit your changes using &man.send-pr.1;.</para>
      </step>
    </procedure>
  </sect1>
</chapter>

<!--
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "part" "chapter")
     End:
-->