<?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 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 the reader 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 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>Documentation commit messages are visible with
<application>svn</application>. Commit messages are also
archived at <ulink url="&a.svn-doc-all.url;"></ulink>.</para>
<para>In addition, 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 id="overview-quick-start">
<title>Quick Start</title>
<para>Here we describe the steps contributors must take before
making changes to the <acronym>FDP</acronym>. New
contributors will interact with other members of the &os;
Documentation Team, which can assist in learning to use
<acronym>XML</acronym> and the suggestions in
<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
class="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>Locate the file to edit. Run
<command>svn up</command> within the local working copy to
make sure that it is up to date. Before making major
changes to a file, discuss the proposed changes 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.
References to the commonly used tags and entities can be
found in <xref linkend="xhtml-markup"/> and
<xref linkend="docbook-markup"/>.</para>
</step>
<step>
<para>After edits are complete, 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 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
<command>make</command> 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>[ Browse... ]</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 around 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>