294 lines
12 KiB
XML
294 lines
12 KiB
XML
<?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>
|