aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml273
1 files changed, 0 insertions, 273 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
deleted file mode 100644
index 1d806b1e60..0000000000
--- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
+++ /dev/null
@@ -1,273 +0,0 @@
-<?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.
-
--->
-<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-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> meta-package
- and <application>Subversion</application>.
- This meta-package installs all of the software needed to
- edit and build &os; documentation. The
- <application>Subversion</application> package is needed to
- obtain a working copy of the documentation and generate
- patches with.</para>
-
- <screen>&prompt.root; <userinput>pkg install docproj subversion</userinput></screen>
- </step>
-
- <step>
- <para>Optional: to generate PDF documentation, install the
- <package>textproc/fop</package> package as it is not
- installed by default by <package>textproc/docproj</package>.
- </para>
-
- <screen>&prompt.root; <userinput>pkg install fop</userinput></screen>
- </step>
-
- <step>
- <para>Install a local working copy of the documentation from
- the &os; repository in
- <filename>~/doc</filename> (see
- <xref linkend="working-copy"/>).</para>
-
- <screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></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 <replaceable>~/doc</replaceable></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 ~/doc</userinput>
-&prompt.user; <userinput>svn diff &gt; <replaceable>bsdinstall</replaceable>.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="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation">Problem
- Report</link> system. If using the web form, enter a
- Summary of <emphasis>[patch] <replaceable>short description
- of problem</replaceable></emphasis>. Select the
- Component <literal>Documentation</literal>. In the
- Description field, enter a short description of the changes
- and any important details about them. Use the
- <guibutton>[&nbsp;Add an attachment&nbsp;]</guibutton>
- button to attach the diff file. Finally, use the
- <guibutton>[&nbsp;Submit Bug&nbsp;]</guibutton> button to
- submit your diff to the problem report system.</para>
- </step>
- </procedure>
- </sect1>
-
- <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="https://www.freebsd.org/index.html">
- https://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>Web frontends to both of these repositories are available
- at <link xlink:href="https://svnweb.FreeBSD.org/doc/"></link>
- and <link
- xlink:href="https://svnweb.FreeBSD.org/base/"></link>.</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>
-</chapter>