[fspm_howto] / FreeSoftwareDevelopmentHOWTO.sgml

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

<article>

<!-- Header -->

 <artheader>
  <title>Free Software Development HOWTO</title>

  <author>
     <firstname>Benjamin</firstname>
     <othername>Mako</othername>
     <surnamen>Hill</surname>
     <affiliation>
        <address>
           <email>mako@debian.org</email>

        </address>
     </affiliation>
  </author>

   <revhistory>
      <revision>
         <revnumber>v0.01</revnumber>
         <date>1 January 2001</date>
         <authorinitials>bch</authorinitials>
          <revremark>
          Initial Release
         </revremark>
      </revision>
   </revhistory>

  <abstract>
    <indexterm>
      <primary>fswd</primary>
    </indexterm>

    <para>
     This HOWTO is designed for people with experience in programming
     and some skills in managing a software project but who are new to
     the world of Free Software. This document is meant to act as a
     guide to the non-technical aspects of programming and was written
     to act as a crash course in the people skills that aren't taught
     to commercial coders but that can make or break a free software
     project.
    </para>
  </abstract>

 </artheader>

<!-- Section1: intro -->

 <sect1 id="intro">
   <title>Introduction</title>

   <indexterm>
    <primary>fswd!introduction</primary>
   </indexterm>

  <para>
   For various reasons, this realease has been codenamed the
   <emphasis>homade yogurt</emphasis> release.
  </para>

  <para>
   New code names will appear as per industry standard
   guidelines to emphasize the state-of-the-art-ness of this
   document.
  </para>

  <para>
   Skimming through Freshmeat provides mountains of reasons for this
   HOWTO's existence--the Internet is littered with excellently
   written and useful programs that have faded away into the Universe
   of Free Software Forgottenness. This dismal scene made me ask
   myself, "Why?"
  </para>

  <para>
   This HOWTO tries to do a lot of thing (probably too many), but it
   can't answer that question and won't attempt it. What this HOWTO
   will attempt to do is give your Free Software project a fighting
   chance-an edge. If you write a piece of crap that no one is
   interested in, you can read this HOWTO until you recite it in your
   sleep and your project will probably fail. Then again, you can
   write a beautiful, relevent piece of software and follow every
   instruction in this HOWTO and your software may still not make
   it. Sometimes life is like that. However, I'll go out a limb and
   say that if you write a great, relevant pieces of software and
   ignore the advise in this HOWTO, you'll probably fail <emphasis>
   more often</emphasis>.
  </para>

  <para>
   A lot of the information in this HOWTO is best called common
   sense. Of course, as any debate on interfaces will prove, what is
   common sense to some programmers proves totally unintuitive to
   others. After explaining bites and pieces of this HOWTO to Free
   Software developers on several occasions, I realized that that
   writing this HOWTO might provide a useful resource and a forum for
   programmers to share ideas about what has and has not worked for
   them. 
  </para>

  <para>

  </para>

  <para>
   As anyone involved in any of what seems like an unending parade of
   ridiculous intellectual property clashes will attest to, a little
   bit of legalese proves important.
  </para>

<!-- Section2: copyright -->

  <sect2 id="copyright">
   <title>Copyright Information</title>

   <para>
    This document is copyrighted (c) 2000 Stein Gjoen and is
    distributed under the terms of the Linux Documentation Project
    (LDP) license, stated below.  <emphasis>Replace with your name,
    or supply a new license, when you use this skeleton for a new
    HOWTO.</emphasis>
   </para>

   <para>
    Unless otherwise stated, Linux HOWTO documents are
    copyrighted by their respective authors. Linux HOWTO documents may
    be reproduced and distributed in whole or in part, in any medium
    physical or electronic, as long as this copyright notice is
    retained on all copies. Commercial redistribution is allowed and
    encouraged; however, the author would like to be notified of any
    such distributions.
   </para>

   <para>
    All translations, derivative works, or aggregate works
    incorporating any Linux HOWTO documents must be covered under this
    copyright notice. That is, you may not produce a derivative work
    from a HOWTO and impose additional restrictions on its
    distribution. Exceptions to these rules may be granted under
    certain conditions; please contact the Linux HOWTO coordinator at
    the address given below.
   </para>

   <para>
    In short, we wish to promote dissemination of this
    information through as many channels as possible. However, we do
    wish to retain copyright on the HOWTO documents, and would like to
    be notified of any plans to redistribute the HOWTOs.
   </para>

   <para>
    If you have any questions, please contact 
    <email>linux-howto@metalab.unc.edu</email>
   </para>
  </sect2>

<!-- Section2: disclaimer -->

  <sect2 id="disclaimer">
   <title>Disclaimer</title>

   <para>
    No liability for the contents of this documents can be accepted.
    Use the concepts, examples and other content at your own risk.
    As this is a new edition of this document, there may be errors
    and inaccuracies, that may of course be damaging to your system.
    Proceed with caution, and although this is highly unlikely,
    the author(s) do not take any responsibility for that.
   </para>

   <para>
    All copyrights are held by their by their respective owners, unless
    specifically noted otherwise.  Use of a term in this document
    should not be regarded as affecting the validity of any trademark
    or service mark.
   </para>

   <para>
    Naming of particular products or brands should not be seen 
    as endorsements.
   </para>

   <para>
    You are strongly recommended to take a backup of your system 
    before major installation and backups at regular intervals.
   </para>
  </sect2>

<!-- Section2: newversions-->

  <sect2 id="newversions">
   <title>New Versions</title>

    <indexterm>
     <primary>(your index root)!news on</primary>
    </indexterm>

   <para>
    This is the initial release. It is written to be released to
    developers for critique and brainstorming and submitted to
    Hampshire College for academic credit. Please keep in mind that
    this version of the HOWTO is still in an infant stage and will be
    revised extensively before it hits the LDP.
   </para>

   <para>
    The latest version number of this document should always be listed 
    at my webpage at<ulink url="http://people.debian.org/~mako/">
    http://people.debian.org/~mako/</unlink> Debian.
   </para>

   <para>
    The newest version of this HOWTO will always be made available at
    the same website, in a variety of formats:
   </para>

   <para>
   <itemizedlist>
    <listitem>
     <para>
      <ulink url="http://people.debian.org/fswd-howto.html">HTML</ulink>.
     </para>
    </listitem>

    <listitem>
     <para>
       <ulink URL="http://people.debian.org/fswd-howto.txt">plain text</ulink>.
     </para>
    </listitem>

    <listitem>
     <para>
      <ulink url="http://people.debian.org/fswd-howto.US.ps.gz">compressed 
       postscript (US letter format)</ulink>.
     </para>
    </listitem>

    <listitem>
     <para>
      <ulink url="http://people.debian.org/fswd-howto.UF.ps.gz">compressed 
       postscript (Universal format / 8.27x11in; 210x279mm)</ulink>.
     </para>
    </listitem>

    <listitem>
     <para>
      <ulink url="http://people.debian.org/fswd-howto.sgml">SGML source</ulink>.
     </para>
    </listitem>
   </itemizedlist>
   </para>

<!-- Section2: credits -->

  <sect2 id="credits">
   <title>Credits</title>

   <para>
    <emphasis>It is always nice to acknowledge people who help you
    with input; it is also regarded by many as important in the
    Linux world new economy.</emphasis>
   </para>

   <para>
    In this version I have the pleasure of acknowledging:
   </para>

   <para>
    <email>name (at) site.org</email>
   </para>

   <para>
    <emphasis>Please scramble the addresses so email harvesters
    cannot get addresses from your HOWTO and then spam people. That
    has happened in the past.</emphasis>
   </para>

   <para>
    <emphasis>Somecompany</emphasis> is acknowledged for sending me
    documentation on their gizmos as well as permission to quote from
    the material.  These quotes have been approved before appearing
    here and will be clearly labeled.
   </para>
  </sect2>

<!-- Section2: feedback -->

  <sect2 id="feedback">
   <title>Feedback</title>

   <para>
    Feedback is most certainly welcome for this document. Without
    your submissions and input, this document wouldn't exist. Please
    send your additions, comments and criticisms to the following
    email address : <email>sgjoen@nyx.net</email>.
   </para>
   </sect2>

<!-- Section2: translations -->

  <sect2 id="translations">
   <title>Translations</title>

   <para>
    Not everyone speaks English, pointers to translations are nice.
    Also your translators tend to give very important inputs.
   </para>

   <para>
    <itemizedlist>

     <listitem>
      <para>
        <ulink url="http://linuxdoc.org/">German Translation</ulink>
        by <email>someone (at) somewhere.de</email>
      </para>
     </listitem>

     <listitem>
      <para>
        <ulink url="http://linuxdoc.org/">French Translation</ulink>
        by <email>someone (at) somewhere.fr</email>
      </para>
     </listitem>

     <listitem>
      <para>
        <ulink url="http://linuxdoc.org/">Italian Translation</ulink>
        by <email>someone (at) somewhere.it</email>
      </para>
     </listitem>
    </itemizedlist>
   </para>
   </sect2>

 </sect1>

<!-- Section1: intro: END -->

<!-- Section1: starting -->

 <sect1 id="starting">
  <title>Starting a Project</title>

<!-- Section2: chooseproject-->

  <sect2 id="chooseproject">
   <title>Choosing a Project</title>
  </sect2>

<!-- Section2: chooselicense-->

  <sect2 id="chooselicense">
   <title>Deciding on a License</title>
  </sect2>

<!-- Section2: chooseversioning-->

  <sect2 id="chooseversioning">
   <title>Choosing a Method of Version Numbering</title>
  </sect2>

<!-- Section2: documentation-->

  <sect2 id="documentation">
   <title>Documentation</title>
  </sect2>

<!-- Section2: presentation -->

  <sect2 id="presentation">
   <title>Other Presentation Issues</title>
  </sect2>

<!-- Section2: futuredev -->

  <sect2 id="futuredev">
   <title>Nuturing Future Development</title>
  </sect2>

 </sect1>

<!-- Section1: starting: END -->

<!-- Section1: developers -->

 <sect1 id="developers">
  <title>Maintaining a Project: Interacting with Developers</title>

<!-- Section2: delegation  -->

  <sect2 id="delegation">
   <title>Delegating Work</title>
  </sect2>

<!-- Section2: branches  -->

  <sect2 id="branches">
   <title>Stable and Development Branches</title>
  </sect2>

<!-- Section2: freezing -->

  <sect2 id="freezing">
   <title>Freezing</title>
  </sect2>

<!-- Section2: codecram -->

  <sect2 id="codecram">
   <title>Avoiding the Code Cram Effect</title>
  </sect2>

<!-- Section2: patching -->

  <sect2 id="patching">
   <title>Accepting and Rejecting Patches</title>
  </sect2>
 </sect1>

<!-- Section1: users -->

 <sect1 id="users">
  <title>Maintaining a Project: Interacting with Users</title>

<!-- Section2: announcing  -->

  <sect2 id="announcing">
   <title>Announcing Your Project</title>
  </sect2>

<!-- Section2: testing -->

  <sect2 id="testing">
   <title>Testing and Testers</title>
  </sect2>
</sect1>

<!-- Section1: samples  -->

 <sect1 id="samples">
  <title>Samples</title>

  <para>
   <emphasis>This section gives some simple SGML examples you could
   use. Read the SGML source to see how it was done.</emphasis>
  </para>

  <para>
   Further information and examples can be obtained from the publication
   <ulink url="http://docbook.org/tdg/html/">DocBook: The Definitive 
   Guide</ulink>. Written by <emphasis>Norman Walsh</emphasis>
   and <emphasis>Leonard Muellner</emphasis>; 1st Edition, October 1999.
  </para>
  
<!-- Section2: lists -->

  <sect2 id="lists">
   <title>Lists</title>

   <para>
    <emphasis>Lists are used frequently, and are available in a number
    of formats shown below.</emphasis>
   </para>

   <para>
    A list in which each entry is marked with a bullet or other dingbat:
   </para>

   <para>
    <itemizedlist>

     <listitem>
      <para>Apples</para>
     </listitem>

     <listitem>
      <para>Oranges</para>
     </listitem>

     <listitem>
      <para>Bananas</para>
     </listitem>

    </itemizedlist>
   </para>

   <para>
    A list in which each entry is composed of a set of one or more
    terms and an associated description:
   </para>

   <para>
    <variablelist>

     <varlistentry>
      <term>Fruits</term>
      <listitem>
       <para>such as apples, oranges, and more.</para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Nuts</term>
      <listitem>
       <para>Don't eat too many; you are what you eat.</para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Vegetables</term>
      <listitem>
       <para>Potatos are spelled with care.</para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>

   <para>
    A list in which each entry is marked with a sequentially 
    incremented label:
   </para>

   <para>
     <orderedlist>

      <listitem>
       <para>Step one</para>
      </listitem>

      <listitem>
       <para>Step two</para>
      </listitem>

     </orderedlist>
   </para>
  </sect2>

<!-- Section2: links -->

  <sect2 id="links">
   <title>Links</title>

   <para>
    <emphasis>Links can be used within your documents to refer to
    different sections and chapters or to refer to documents external
    to yours.</emphasis>
   </para>

   <sect3 id="int-links">
    <title>Internal links</title>

    <para>
     Click on the <xref LinkEnd="samples"> link to jump to the top of
     this chapter. Note the anchor at the section tag.
    </para>
   </sect3>

   <sect3 id="ext-links">
    <title>External links</title>

    <para>
     Click on <ulink url="http://www.linuxdoc.org/">this</ulink> link
     to jump to the LDP site. Note you can use http, ftp, news and
     other protocols in the locator if required.
    </para>
   </sect3>

  </sect2>

<!-- Section2: images -->

  <sect2 id="images">
   <title>Images</title>

   <para>
    <emphasis>Avoid diagrams if possible as this cannot be rendered
    in the ASCII outputs which are still needed by many around the
    world.</emphasis>
   </para>

   <para>
     <figure>
      <title>Graphics Test Image</title>
      <graphic FileRef="red.gif"></graphic>
     </figure>
   </para>

   <para>
    Here is another variation which allows for ALT text:
   </para>

   <para>
     <mediaobject>

      <imageobject>
       <imagedata fileref="green.gif" format="gif">
      </imageobject>

      <textobject>
       <phrase>
        ALT text to be used: Green Ball
       </phrase>
      </textobject>

      <caption>
       <para>
        Caption for the graphic goes here: This is a Green Ball.
       </para>
      </caption>
     </mediaobject>
   </para>
  </sect2>

 </sect1>

<!-- Section1: samples: END -->


<!-- Section1: structure -->

 <sect1 id="structure">
  <title>Structure</title>

  <para>
   <emphasis>A quick overview on how all parts fit together in the overall
   structure. An example from the Multi Disk HOWTO is used.</emphasis>
 </para>

  <para>
   As this type of document is supposed to be as much for learning as
   a technical reference document I have rearranged the structure to
   this end. For the designer of a system it is more useful to have
   the information presented in terms of the goals of this exercise
   than from the point of view of the logical layer structure of the
   devices themselves. Nevertheless this document would not be
   complete without such a layer structure the computer field is so
   full of, so I will include it here as an introduction to how it
   works.
  </para>

<!-- Section2: logical-struct -->

  <sect2 id="logical-struct">
   <title>Logical structure</title>

    <indexterm>
     <primary>disk!structure, I/O subsystem</primary>
    </indexterm>

   <para>
    This is based on how each layer access each other, traditionally
    with the application on top and the physical layer on the bottom.
    It is quite useful to show the interrelationship between each of
    the layers used in controlling drives.

    <screen>
        ___________________________________________________________
        |__     File structure          ( /usr /tmp etc)        __|
        |__     File system             (ext2fs, vfat etc)      __|
        |__     Volume management       (AFS)                   __|
        |__     RAID, concatenation     (md)                    __|
        |__     Device driver           (SCSI, IDE etc)         __|
        |__     Controller              (chip, card)            __|
        |__     Connection              (cable, network)        __|
        |__     Drive                   (magnetic, optical etc) __|
        -----------------------------------------------------------
    </screen>
   </para>

   <para>
    In the above diagram both volume management and RAID and
    concatenation are optional layers. The 3 lower layers are in
    hardware. All parts are discussed at length later on in this
    document.
   </para>
  </sect2>

<!-- Section2: doc-struct -->

  <sect2 id="doc-struct">
   <title>Document structure</title>

   <para>
    Most users start out with a given set of hardware and some plans
    on what they wish to achieve and how big the system should be.
    This is the point of view I will adopt in this document in
    presenting the material, starting out with hardware, continuing
    with design constraints before detailing the design strategy that
    I have found to work well. I have used this both for my own
    personal computer at home, a multi purpose server at work and
    found it worked quite well. In addition my Japanese co-worker in
    this project have applied the same strategy on a server in an
    academic setting with similar success.
   </para>

   <para>
    Finally at the end I have detailed some configuration tables for
    use in your own design. If you have any comments regarding this
    or notes from your own design work I would like to hear from you
    so this document can be upgraded.
   </para>
  </sect2>

<!-- Section2: reading-plan -->

  <sect2 id="reading-plan">
   <title>Reading plan</title>

   <para>
    <emphasis>As you go beyond 50 pages or so there will be a lot of
    text that experts and even the experienced do not need to read.
    Keeping in mind that we wish to care for all kinds of people in
    the Linux world we might have to make a reading plan. Again,
    an example follows from the Multi Disk HOWTO.</emphasis>
   </para>

   <para>
    Although not the biggest HOWTO it is nevertheless rather big
    already and I have been requested to make a reading plan to make
    it possible to cut down on the volume.
   </para>

   <para>
    <variablelist>

     <varlistentry>
      <term>Expert</term>
      <listitem>
       <para>
        (aka the elite). If you are familiar with Linux as well as
        disk drive technologies you will find most of what you need in
        the appendices. Additionally you are recommended to read the
        FAQ and the <XRef LinkEnd="bits-n-pieces">chapter.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Experienced</term>
      <listitem>
       <para>
        (aka Competent). If you are familiar with computers in
        general you can go straight to the chapters on 
        <XRef LinkEnd="technologies"> and continue from there on.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Newbie</term>
      <listitem>
       <para>
        (mostly harmless). You just have to read the whole thing.
        Sorry. In addition you are also recommended to read all the
        other disk related HOWTOs.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>
  </sect2>

 </sect1>

<!-- Section1: structure: END -->


<!-- Section1: technologies -->

 <sect1 id="technologies">
  <title>Technologies</title>

   <indexterm>
    <primary>(your index root)!technologies</primary>
   </indexterm>

  <para>
   <emphasis>Introduction of technology for the newbie with a few
   references to detailed works. Remember that not everyone has
   Internet access so you have to explain in sufficient details so
   even the newbie can get by.</emphasis>
  </para>

 </sect1>

<!-- Section1: technologies: END -->


<!-- Section1: implement -->

 <sect1 id="implement">
  <title>Implementation</title>

   <indexterm>
    <primary>(your index root)!implementation</primary>
   </indexterm>

  <para>
   <emphasis>Now your readers should have a sufficient knowledge of
   what this is about and now we come to the hands on of implementing
   your clever scheme.</emphasis>
  </para>

 </sect1>

<!-- Section1: implement: END -->


<!-- Section1: maint -->

 <sect1 id="maint">
  <title>Maintenance</title>

   <indexterm>
    <primary>(your index root)!maintenance</primary>
   </indexterm>

  <para>
   <emphasis>Few systems and designs are maintenance free, here you
   explain how to keep the system running.</emphasis>
  </para>

 </sect1>

<!-- Section1: maint: END -->


<!-- Section1: adv-issues -->

 <sect1 id="adv-issues">
  <title>Advanced Issues</title>

   <indexterm>
    <primary>(your index root)!advanced topics</primary>
   </indexterm>

  <para>
   <emphasis>You can get most things up and running in a quick and
   dirty fashion, useful for testing and getting used to how things
   work. For more serious use you would need to be a little more
   advanced. This is the place to explain it all, if applicable.</emphasis>
  </para>

 </sect1>

<!-- Section1: adv-issues: END -->


<!-- Section1: moreinfo -->

 <sect1 id="moreinfo">
  <title>Further Information</title>

   <indexterm>
    <primary>(your index root)!information resources</primary>
   </indexterm>

  <para>
   <emphasis>A HOWTO cannot describe everything, some times the user
   has to venture out on th enet to get more information or just
   updates. Here is the place to tell where and how. Again examples
   from the Multi Disk HOWTO, replace as needed.</emphasis> There is wealth
   of information one should go through when setting up a major system,
   for instance for a news or general Internet service provider.  The
   FAQs in the following groups are useful:
  </para>

<!-- Section2: newsgroups -->

  <sect2 id="newsgroups">
   <title>News groups</title>

    <indexterm>
     <primary>disk!information resources!news groups</primary>
    </indexterm>

   <para>Some of the most interesting news groups are:

    <itemizedlist>

     <listitem>
      <para>
       <ulink url="news:comp.arch.storage">Storage</ulink>.
      </para>
     </listitem>

     <listitem>
      <para>
       <ulink url="news:comp.sys.ibm.pc.hardware.storage">PC storage</ulink>.
      </para>
     </listitem>

     <listitem>
      <para>
       <ulink url="news:alt.filesystems.afs">AFS</ulink>.
      </para>
     </listitem>

     <listitem>
      <para>
       <ulink url="news:comp.periphs.scsi">SCSI</ulink>.
      </para>
     </listitem>

     <listitem>
      <para>
       <ulink url="news:comp.os.linux.setup">Linux setup</ulink>.
      </para>
     </listitem>

    </itemizedlist>
   </para>

   <para>
    Most newsgroups have their own FAQ that are designed to answer most
    of your questions, as the name Frequently Asked Questions indicate.
    Fresh versions should be posted regularly to the relevant newsgroups.
    If you cannot find it in your news spool you could go directly to the
    <ulink url="ftp://rtfm.mit.edu/">FAQ main archive FTP site</ulink>.
    The WWW versions can be browsed at the 
    <ulink url="http://www.cis.ohio-state.edu/hypertext/faq/usenet/FAQ-List.html">FAQ
    main archive WWW site</ulink>.
   </para>

   <para>
    Some FAQs have their own home site, of particular interest:

    <itemizedlist>

     <listitem>
      <para>
       <ulink url="http://www.paranoia.com/~filipg/HTML/LINK/F_SCSI.html">SCSI FAQ</ulink> 
       and
      </para>
     </listitem>

     <listitem>
      <para>
       <ulink url="http://alumni.caltech.edu/~rdv/comp_arch_storage/FAQ-1.html">comp.arch.storage FAQ</ulink>.
      </para>
     </listitem>

    </itemizedlist>
   </para>
  </sect2>

<!-- Section2: maillists -->

  <sect2 id="maillists">
   <title>Mailing Lists</title>

    <indexterm>
     <primary>disk!information resources!mailing lists</primary>
    </indexterm>

   <para>
    These are low-noise channels mainly for developers. Think twice
    before asking questions there as noise delays the development.
    Some relevant lists are <email>linux-raid</email>,
    <email>linux-scsi</email> and <email>linux-ext2fs</email>.  Many
    of the most useful mailing lists run on the <Literal
    remap="tt">vger.rutgers.edu</Literal> server but this is
    notoriously overloaded, so try to find a mirror. There are some
    lists mirrored at <ulink url="http://www.redhat.com">The Redhat
    Home Page</ulink>. Many lists are also accessible at <ulink
    url="http://www.linuxhq.com/lnxlists">linuxhq</ulink>, and the
    rest of the web site contains useful information as well.
   </para>

   <para>
    If you want to find out more about the lists available you can send
    a message with the line <command>lists</command> to the list server
    at <email>majordomo@vger.rutgers.edu</email>.
    If you need help on how to use the mail server just send the line
    <command>help</command> to the same address.  Due to the
    popularity of this server it is likely it takes a bit to time before
    you get a reply or even get messages after you send a
    <command>subscribe</command> command.
   </para>

   <para>
    There is also a number of other majordomo list servers that can
    be of interest such as the EATA driver list
    (<email>linux-eata@mail.uni-mainz.de</email>)
    and the Intelligent IO list <email>linux-i2o@dpt.com</email>.
   </para>

   <para>
    Mailing lists are in a state of flux but you can find links to a
    number of interesting lists from the 
    <ulink url="http://www.linuxdoc.org/">Linux Documentation
    Homepage</ulink>.
   </para>
  </sect2>

<!-- Section2: howto -->

  <sect2 id="howto">
   <title>HOWTO</title>

    <indexterm>
     <primary>disk!information resources!HOWTOs</primary>
    </indexterm>

   <para>
    These are intended as the primary starting points to get the
    background information as well as show you how to solve a
    specific problem. Some relevant HOWTOs are
    <Literal remap="tt">Bootdisk</Literal>, 
    <Literal remap="tt">Installation</Literal>,
    <Literal remap="tt">SCSI</Literal> and 
    <Literal remap="tt">UMSDOS</Literal>.  The main site for these is the
    <ulink url="http://www.linuxdoc.org/">LDP archive</ulink>at
    Metalab (formerly known as Sunsite).
   </para>

   <para>
    There is a a new HOWTO out that deals with setting up a DPT RAID
    system, check out the
    <ulink url="http://www.ram.org/computing/linux/dpt_raid.html">DPT RAID
    HOWTO homepage</ulink>.
   </para>
  </sect2>

<!-- Section2: local-res -->

  <sect2 id="local-res">
   <title>Local Resources</title>

    <indexterm>
     <primary>disk!information resources!local</primary>
    </indexterm>

   <para>
    In most distributions of Linux there is a document directory
    installed, have a look in the <filename>/usr/doc</filename>
    directory. where most packages store their main documentation and
    README files etc.  Also you will here find the HOWTO archive 
    (<filename>/usr/doc/HOWTO</filename>) of ready formatted HOWTOs
    and also the mini-HOWTO archive 
    (<filename>/usr/doc/HOWTO/mini</filename>) of plain text
    documents.
   </para>

   <para>
    Many of the configuration files mentioned earlier can be found in
    the <filename>/etc</filename> directory. In particular you will
    want to work with the <filename>/etc/fstab</filename> file that
    sets up the mounting of partitions and possibly also
    <filename>/etc/raidtab</filename> file that is used for the
    <Literal remap="tt">md</Literal> system to set up RAID.
   </para>

   <para>
    The kernel source in <filename>/usr/src/linux</filename> is, of
    course, the ultimate documentation. In other words, <quote>use
    the source, Luke</quote>. It should also be pointed out that the
    kernel comes not only with source code which is even commented
    (well, partially at least) but also an informative
    <filename>/usr/src/linux/Documentation</filename>. If you are
    about to ask any questions about the kernel you should read this
    first, it will save you and many others a lot of time and
    possibly embarrassment.
   </para>

   <para>
    Also have a look in your system log file
    (<filename>/var/log/messages</filename>) to see what is going on
    and in particular how the booting went if too much scrolled off
    your screen. Using <command>tail -f /var/log/messages</command>
    in a separate window or screen will give you a continuous update
    of what is going on in your system.
   </para>

   <para>
    You can also take advantage of the  <filename>/proc</filename>
    file system that is a window into the inner workings of your
    system. Use <command>cat</command> rather than
    <command>more</command> to view the files as they are reported as
    being zero length. Reports are that <command>less</command> works
    well here.
   </para>
  </sect2>

<!-- Section2: web -->

  <sect2 id="web">
   <title>Web Sites</title>

    <indexterm>
     <primary>disk!information resources!WWW</primary>
    </indexterm>
    <indexterm>
     <primary>disk!information resources!web pages</primary>
    </indexterm>

   <para>
    There are a huge number of informative web sites available. By
    their very nature they change quickly so do not be surprised
    if these links become quickly outdated.
   </para>

   <para>
    A good starting point is of course the 
    <ulink url="http://www.linuxdoc.org/">Linux Documentation
    Project</ulink> home page, an information central for
    documentation, project pages and much more.
   </para>

   <para>
    Please let me know if you have any other leads that can be 
    of interest.
   </para>
  </sect2>

 </sect1>

<!-- Section1: moreinfo: END -->


<!-- Section1: help -->

 <sect1 id="help">
  <title>Getting Help</title>

   <indexterm>
    <primary>(your index root)!assistance, obtaining</primary>
   </indexterm>

  <para>
   In the end you might find yourself unable to solve your problems
   and need help from someone else. The most efficient way is either
   to ask someone local or in your nearest Linux user group, search
   the web for the nearest one.
  </para>

  <para>
   Another possibility is to ask on Usenet News in one of the many,
   many newsgroups available. The problem is that these have such a
   high volume and noise (called low signal-to-noise ratio) that your
   question can easily fall through unanswered.
  </para>

  <para>
   No matter where you ask it is important to ask well or you will
   not be taken seriously. Saying just <emphasis remap="it">my disk
   does not work</emphasis> is not going to help you and instead the
   noise level is increased even further and if you are lucky someone
   will ask you to clarify.
  </para>

  <para>
   Instead describe your problems in some detail that will enable
   people to help you. The problem could lie somewhere you did not
   expect. Therefore you are advised to list the following information
   about your system:
  </para>

  <para>
   <variablelist>

    <varlistentry>
     <term>Hardware</Term>
     <listitem>
      <para>
       <itemizedlist>
        <listitem>
         <para>Processor</para>
        </listitem>

        <listitem>
         <para>DMA</para>
        </listitem>

        <listitem>
         <para>IRQ</para>
        </listitem>

        <listitem>
         <para>Chip set (LX, BX etc)</para>
        </listitem>

        <listitem>
         <para>Bus (ISA, VESA, PCI etc)</para>
        </listitem>

        <listitem>
         <para>
          Expansion cards used (Disk controllers, video, IO 
          etc.)
         </para>
        </listitem>

       </itemizedlist>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>Software</term>
     <listitem>
      <para>
       <itemizedlist>

        <listitem>
         <para>BIOS (On motherboard and possibly SCSI host adapters)</para>
        </listitem>

        <listitem>
         <para>LILO, if used</para>
        </listitem>

        <listitem>
         <para>
          Linux kernel version as well as possible modifications 
          and patches
         </para>
        </listitem>

        <listitem>
         <para>Kernel parameters, if any</para>
        </listitem>

        <listitem>
         <para>
          Software that shows the error (with version number 
          or date)
         </para>
        </listitem>

       </itemizedlist>
      </para>

     </listitem>
    </varlistentry>

    <varlistentry>
     <term>Peripherals</term>
     <listitem>
      <para>
       <itemizedlist>

        <listitem>
         <para>
          Type of disk drives with manufacturer name, version and type
         </para>
        </listitem>

        <listitem>
         <para>Other relevant peripherals</para>
        </listitem>

       </itemizedlist>
      </para>
     </listitem>
    </varlistentry>

   </variablelist>
  </para>

  <para>
   Remember that booting text is logged to
   <filename>/var/log/messages</filename> which can answer most of
   the questions above. Obviously if the drives fail you might not be
   able to get  the log saved to disk but you can at least scroll
   back up the screen using the <keycap>SHIFT</keycap> and
   <keycap>PAGE UP</keycap> keys. It may also be useful to include
   part of this in your request for help but do not go overboard,
   keep it <emphasis>brief</emphasis> as a complete log file dumped
   to Usenet News is more than a little annoying.
  </para>

 </sect1>

<!-- Section1: help: END -->


<!-- Section1: remarks -->

 <sect1 id="remarks">
  <title>Concluding Remarks</title>

   <indexterm>
    <primary>(your index root)!conclusion</primary>
   </indexterm>

  <para>
   <emphasis>Just summing up... Also a place for general
   recommendations.</emphasis>
  </para>

 </sect1>

<!-- Section1: remarks: END -->


<!-- Section1: faq -->

 <sect1 id="faq">
  <title>Questions and Answers</title>

   <indexterm>
    <primary>(your index root)!FAQ</primary>
   </indexterm>
   <indexterm>
    <primary>(your index root)!frequently asked questions</primary>
   </indexterm>

  <para>
   <emphasis>Check the newsgroups and try to determine some frequent
   problems and cover them here. Again an example from the Multi Disk
   HOWTO.</emphasis>
  </para>

  <para>
   This is just a collection of what I believe are the most common
   questions people might have. Give me more feedback and I will turn
   this section into a proper FAQ.
  </para>

  <para>
   <itemizedlist>
    <listitem>
     <para>
      Q:How many physical disk drives (spindles) does a Linux system need?
     </para>

     <para>
      A: Linux can run just fine on one drive (spindle).  Having
      enough  RAM (around 32 MB, and up to 64 MB) to support swapping
      is a  better price/performance choice than getting a second
      disk. (E)IDE disk is usually cheaper (but a little slower) than
      SCSI.
     </para>
    </listitem>

    <listitem>
     <para>
      Q: Are there any disadvantages in this scheme?
     </para>

     <para>
      A: There is only a minor snag: if even a single partition
      overflows the system might stop working properly. The severity
      depends of course on what partition is affected. Still this is
      not hard to monitor, the command <command>df</command> gives
      you a good overview of the situation. Also check the swap
      partition(s) using <command>free</command> to make sure you are
      not about to run out of virtual memory.
     </para>
    </listitem>

    <listitem>
     <para>
      Q: OK, so should I split the system into as many partitions as 
      possible for a single drive?
     </para>

     <para>
      A: No, there are several disadvantages to that. First of all
      maintenance becomes needlessly complex and you gain very little
      in this. In fact if your partitions are too big you will seek
      across larger areas than needed. This is a balance and
      dependent on the number of physical drives you have.
     </para>
    </listitem>

   </itemizedlist>

   <comment>
    Greg Leblanc:  Depending on how big this FAQ gets, perhaps it
    would be worthwhile to have, say, the 5 most FAQ, and put the
    rest into an external FAQ.  Dunno.  Comments?
   </comment>

   <emphasis>(rest deleted.)</emphasis>
  </para>

 </sect1>

<!-- Section1: faq: END -->


<!-- Section1: bits-n-pieces -->

 <sect1 id="bits-n-pieces">
  <title>Bits and Pieces </title>

   <indexterm>
    <primary>disk!miscellaneous</primary>
   </indexterm>

  <para>
   This is basically a section where I stuff all the bits I have not
   yet decided where should go, yet that I feel is worth knowing
   about. It is a kind of transient area.
  </para>

 </sect1>

<!-- Section1: bits-n-pieces: END -->


<!-- Section1: examples -->

 <sect1 id="examples">
  <title>Examples</title>

   <indexterm>
    <primary>(your index root)!examples</primary>
   </indexterm>

  <para>
   <emphasis>Example designs and sample configuration files and other
   relevant details is always handy</emphasis>
  </para>

 </sect1>

<!-- Section1: examples: END -->

</article>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-namecase-general:t
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:nil
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->