diff options
Diffstat (limited to 'nl_NL.ISO8859-1/books/fdp-primer/overview/chapter.xml')
| -rw-r--r-- | nl_NL.ISO8859-1/books/fdp-primer/overview/chapter.xml | 255 |
1 files changed, 0 insertions, 255 deletions
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/overview/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/overview/chapter.xml deleted file mode 100644 index 0deb064ee2..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/overview/chapter.xml +++ /dev/null @@ -1,255 +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. - - $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>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> - - <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 - 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 > <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="&url.base;/support.html#gnats">Problem - Report</link> system. 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>[ Browse... ]</guibutton> button to - attach the diff file.</para> - </step> - </procedure> - </sect1> -</chapter> |