[ALSA] writing-an-alsa-driver.tmpl: English style improvements

This patch brings some English style improvements throughout the
document, as well as 1 or 2 extra technical details.

Signed-off-by: Michael Opdenacker <michael@free-electrons.com>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

1 files changed, 458 insertions, 462 deletions

diff --git a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
index 2c3fc3cb3b6b..48e4053eda12 100644
--- a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
+++ b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
@@ -18,7 +18,7 @@
       </affiliation>
      </author>
 
-     <date>September 10, 2007</date>
+     <date>Oct 15, 2007</date>
      <edition>0.3.7</edition>
 
     <abstract>
@@ -67,7 +67,7 @@
       This document describes how to write an
       <ulink url="http://www.alsa-project.org/"><citetitle>
       ALSA (Advanced Linux Sound Architecture)</citetitle></ulink>
-      driver. The document focuses mainly on the PCI soundcard.
+      driver. The document focuses mainly on PCI soundcards.
       In the case of other device types, the API might
       be different, too. However, at least the ALSA kernel API is
       consistent, and therefore it would be still a bit help for
@@ -75,23 +75,23 @@
     </para>
 
     <para>
-    The target of this document is ones who already have enough
-    skill of C language and have the basic knowledge of linux
-    kernel programming.  This document doesn't explain the general
-    topics of linux kernel codes and doesn't cover the detail of
-    implementation of each low-level driver.  It describes only how is
+    This document targets people who already have enough
+    C language skills and have basic linux kernel programming
+    knowledge.  This document doesn't explain the general
+    topic of linux kernel coding and doesn't cover low-level
+    driver implementation details. It only describes
     the standard way to write a PCI sound driver on ALSA.
     </para>
 
     <para>
-      If you are already familiar with the older ALSA ver.0.5.x, you
-    can check the drivers such as <filename>es1938.c</filename> or
-    <filename>maestro3.c</filename> which have also almost the same
+      If you are already familiar with the older ALSA ver.0.5.x API, you
+    can check the drivers such as <filename>sound/pci/es1938.c</filename> or
+    <filename>sound/pci/maestro3.c</filename> which have also almost the same
     code-base in the ALSA 0.5.x tree, so you can compare the differences.
     </para>
 
     <para>
-      This document is still a draft version. Any feedbacks and
+      This document is still a draft version. Any feedback and
     corrections, please!!
     </para>
   </preface>
@@ -106,7 +106,7 @@
     <section id="file-tree-general">
       <title>General</title>
       <para>
-        The ALSA drivers are provided in the two ways.
+        The ALSA drivers are provided in two ways.
       </para>
 
       <para>
@@ -114,15 +114,14 @@
       ALSA's ftp site, and another is the 2.6 (or later) Linux kernel
       tree. To synchronize both, the ALSA driver tree is split into
       two different trees: alsa-kernel and alsa-driver. The former
-      contains purely the source codes for the Linux 2.6 (or later)
+      contains purely the source code for the Linux 2.6 (or later)
       tree. This tree is designed only for compilation on 2.6 or
       later environment. The latter, alsa-driver, contains many subtle
-      files for compiling the ALSA driver on the outside of Linux
-      kernel like configure script, the wrapper functions for older,
-      2.2 and 2.4 kernels, to adapt the latest kernel API,
+      files for compiling ALSA drivers outside of the Linux kernel tree,
+      wrapper functions for older 2.2 and 2.4 kernels, to adapt the latest kernel API,
       and additional drivers which are still in development or in
       tests.  The drivers in alsa-driver tree will be moved to
-      alsa-kernel (eventually 2.6 kernel tree) once when they are
+      alsa-kernel (and eventually to the 2.6 kernel tree) when they are
       finished and confirmed to work fine.
       </para>
 
@@ -168,7 +167,7 @@
     <section id="file-tree-core-directory">
       <title>core directory</title>
       <para>
-        This directory contains the middle layer, that is, the heart
+        This directory contains the middle layer which is the heart
       of ALSA drivers. In this directory, the native ALSA modules are
       stored. The sub-directories contain different modules and are
       dependent upon the kernel config. 
@@ -181,7 +180,7 @@
           The codes for PCM and mixer OSS emulation modules are stored
         in this directory. The rawmidi OSS emulation is included in
         the ALSA rawmidi code since it's quite small. The sequencer
-        code is stored in core/seq/oss directory (see
+        code is stored in <filename>core/seq/oss</filename> directory (see
         <link linkend="file-tree-core-directory-seq-oss"><citetitle>
         below</citetitle></link>).
         </para>
@@ -200,7 +199,7 @@
       <section id="file-tree-core-directory-seq">
         <title>core/seq</title>
         <para>
-          This and its sub-directories are for the ALSA
+          This directory and its sub-directories are for the ALSA
         sequencer. This directory contains the sequencer core and
         primary sequencer modules such like snd-seq-midi,
         snd-seq-virmidi, etc. They are compiled only when
@@ -229,22 +228,22 @@
       <title>include directory</title>
       <para>
         This is the place for the public header files of ALSA drivers,
-      which are to be exported to the user-space, or included by
+      which are to be exported to user-space, or included by
       several files at different directories. Basically, the private
       header files should not be placed in this directory, but you may
-      still find files there, due to historical reason :) 
+      still find files there, due to historical reasons :) 
       </para>
     </section>
 
     <section id="file-tree-drivers-directory">
       <title>drivers directory</title>
       <para>
-        This directory contains the codes shared among different drivers
-      on the different architectures.  They are hence supposed not to be
+        This directory contains code shared among different drivers
+      on different architectures.  They are hence supposed not to be
       architecture-specific.
       For example, the dummy pcm driver and the serial MIDI
       driver are found in this directory. In the sub-directories,
-      there are the codes for components which are independent from
+      there is code for components which are independent from
       bus and cpu architectures. 
       </para>
 
@@ -271,7 +270,7 @@
 
       <para>
         Although there is a standard i2c layer on Linux, ALSA has its
-      own i2c codes for some cards, because the soundcard needs only a
+      own i2c code for some cards, because the soundcard needs only a
       simple operation and the standard i2c API is too complicated for
       such a purpose. 
       </para>
@@ -292,28 +291,28 @@
 
         <para>
           So far, there is only Emu8000/Emu10k1 synth driver under
-        synth/emux sub-directory. 
+        the <filename>synth/emux</filename> sub-directory. 
         </para>
     </section>
 
     <section id="file-tree-pci-directory">
       <title>pci directory</title>
       <para>
-        This and its sub-directories hold the top-level card modules
-      for PCI soundcards and the codes specific to the PCI BUS.
+        This directory and its sub-directories hold the top-level card modules
+      for PCI soundcards and the code specific to the PCI BUS.
       </para>
 
       <para>
-        The drivers compiled from a single file is stored directly on
-      pci directory, while the drivers with several source files are
-      stored on its own sub-directory (e.g. emu10k1, ice1712). 
+        The drivers compiled from a single file are stored directly
+      in the pci directory, while the drivers with several source files are
+      stored on their own sub-directory (e.g. emu10k1, ice1712). 
       </para>
     </section>
 
     <section id="file-tree-isa-directory">
       <title>isa directory</title>
       <para>
-        This and its sub-directories hold the top-level card modules
+        This directory and its sub-directories hold the top-level card modules
       for ISA soundcards. 
       </para>
     </section>
@@ -321,16 +320,16 @@
     <section id="file-tree-arm-ppc-sparc-directories">
       <title>arm, ppc, and sparc directories</title>
       <para>
-        These are for the top-level card modules which are
-      specific to each given architecture. 
+        They are used for top-level card modules which are
+      specific to one of these architectures. 
       </para>
     </section>
 
     <section id="file-tree-usb-directory">
       <title>usb directory</title>
       <para>
-        This contains the USB-audio driver. On the latest version, the
-      USB MIDI driver is integrated together with usb-audio driver. 
+        This directory contains the USB-audio driver. In the latest version, the
+      USB MIDI driver is integrated in the usb-audio driver. 
       </para>
     </section>
 
@@ -338,16 +337,17 @@
       <title>pcmcia directory</title>
       <para>
         The PCMCIA, especially PCCard drivers will go here. CardBus
-      drivers will be on pci directory, because its API is identical
-      with the standard PCI cards. 
+      drivers will be in the pci directory, because their API is identical
+      to that of standard PCI cards. 
       </para>
     </section>
 
     <section id="file-tree-oss-directory">
       <title>oss directory</title>
       <para>
-        The OSS/Lite source files are stored here on Linux 2.6 (or
-      later) tree. (In the ALSA driver tarball, it's empty, of course :) 
+        The OSS/Lite source files are stored here in Linux 2.6 (or
+      later) tree. In the ALSA driver tarball, this directory is empty,
+      of course :) 
       </para>
     </section>
   </chapter>
@@ -362,7 +362,7 @@
     <section id="basic-flow-outline">
       <title>Outline</title>
       <para>
-        The minimum flow of PCI soundcard is like the following:
+        The minimum flow for PCI soundcards is as follows:
 
         <itemizedlist>
           <listitem><para>define the PCI ID table (see the section
@@ -370,9 +370,13 @@
           </citetitle></link>).</para></listitem> 
           <listitem><para>create <function>probe()</function> callback.</para></listitem>
           <listitem><para>create <function>remove()</function> callback.</para></listitem>
-          <listitem><para>create pci_driver table which contains the three pointers above.</para></listitem>
-          <listitem><para>create <function>init()</function> function just calling <function>pci_register_driver()</function> to register the pci_driver table defined above.</para></listitem>
-          <listitem><para>create <function>exit()</function> function to call <function>pci_unregister_driver()</function> function.</para></listitem>
+          <listitem><para>create a <structname>pci_driver</structname> structure
+	  containing the three pointers above.</para></listitem>
+          <listitem><para>create an <function>init()</function> function just calling
+	  the <function>pci_register_driver()</function> to register the pci_driver table
+	  defined above.</para></listitem>
+          <listitem><para>create an <function>exit()</function> function to call
+	  the <function>pci_unregister_driver()</function> function.</para></listitem>
         </itemizedlist>
       </para>
     </section>
@@ -382,12 +386,12 @@
       <para>
         The code example is shown below. Some parts are kept
       unimplemented at this moment but will be filled in the
-      succeeding sections. The numbers in comment lines of
-      <function>snd_mychip_probe()</function> function are the
-      markers. 
+      next sections. The numbers in the comment lines of the
+      <function>snd_mychip_probe()</function> function
+      refer to details explained in the following section. 
 
         <example>
-          <title>Basic Flow for PCI Drivers Example</title>
+          <title>Basic Flow for PCI Drivers - Example</title>
           <programlisting>
 <![CDATA[
   #include <sound/driver.h>
@@ -398,6 +402,7 @@
   #include <sound/initval.h>
 
   /* module parameters (see "Module Parameters") */
+  /* SNDRV_CARDS: maximum number of cards supported by this module */
   static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
   static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
   static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
@@ -405,13 +410,13 @@
   /* definition of the chip-specific record */
   struct mychip {
           struct snd_card *card;
-          /* rest of implementation will be in the section
-           * "PCI Resource Managements"
+          /* the rest of the implementation will be in section
+           * "PCI Resource Management"
            */
   };
 
   /* chip-specific destructor
-   * (see "PCI Resource Managements")
+   * (see "PCI Resource Management")
    */
   static int snd_mychip_free(struct mychip *chip)
   {
@@ -442,7 +447,7 @@
           *rchip = NULL;
 
           /* check PCI availability here
-           * (see "PCI Resource Managements")
+           * (see "PCI Resource Management")
            */
           ....
 
@@ -454,7 +459,7 @@
           chip->card = card;
 
           /* rest of initialization here; will be implemented
-           * later, see "PCI Resource Managements"
+           * later, see "PCI Resource Management"
            */
           ....
 
@@ -521,7 +526,7 @@
           return 0;
   }
 
-  /* destructor -- see "Destructor" sub-section */
+  /* destructor -- see the "Destructor" sub-section */
   static void __devexit snd_mychip_remove(struct pci_dev *pci)
   {
           snd_card_free(pci_get_drvdata(pci));
@@ -536,16 +541,16 @@
     <section id="basic-flow-constructor">
       <title>Constructor</title>
       <para>
-        The real constructor of PCI drivers is probe callback. The
-      probe callback and other component-constructors which are called
-      from probe callback should be defined with
-      <parameter>__devinit</parameter> prefix. You 
-      cannot use <parameter>__init</parameter> prefix for them,
+        The real constructor of PCI drivers is the <function>probe</function> callback.
+      The <function>probe</function> callback and other component-constructors which are called
+      from the <function>probe</function> callback should be defined with
+      the <parameter>__devinit</parameter> prefix. You 
+      cannot use the <parameter>__init</parameter> prefix for them,
       because any PCI device could be a hotplug device. 
       </para>
 
       <para>
-        In the probe callback, the following scheme is often used.
+        In the <function>probe</function> callback, the following scheme is often used.
       </para>
 
       <section id="basic-flow-constructor-device-index">
@@ -570,7 +575,7 @@
         </para>
 
         <para>
-          At each time probe callback is called, check the
+          Each time the <function>probe</function> callback is called, check the
         availability of the device. If not available, simply increment
         the device index and returns. dev will be incremented also
         later (<link
@@ -594,7 +599,7 @@
         </para>
 
         <para>
-          The detail will be explained in the section
+          The details will be explained in the section
           <link linkend="card-management-card-instance"><citetitle>
           Management of Cards and Components</citetitle></link>.
         </para>
@@ -619,9 +624,9 @@
             </programlisting>
           </informalexample>
 
-          The detail will be explained in the section <link
+          The details will be explained in the section <link
         linkend="pci-resource"><citetitle>PCI Resource
-        Managements</citetitle></link>.
+        Management</citetitle></link>.
         </para>
       </section>
 
@@ -640,7 +645,7 @@
           </informalexample>
 
           The driver field holds the minimal ID string of the
-        chip. This is referred by alsa-lib's configurator, so keep it
+        chip. This is used by alsa-lib's configurator, so keep it
         simple but unique. 
           Even the same driver can have different driver IDs to
         distinguish the functionality of each chip type. 
@@ -648,7 +653,7 @@
 
         <para>
           The shortname field is a string shown as more verbose
-        name. The longname field contains the information which is
+        name. The longname field contains the information
         shown in <filename>/proc/asound/cards</filename>. 
         </para>
       </section>
@@ -703,7 +708,7 @@
           </informalexample>
 
           In the above, the card record is stored. This pointer is
-        referred in the remove callback and power-management
+        used in the remove callback and power-management
         callbacks, too. 
         </para>
       </section>
@@ -757,22 +762,22 @@
         </informalexample>
 
 	where the last one is necessary only when module options are
-      defined in the source file.  If the codes are split to several
-      files, the file without module options don't need them.
+      defined in the source file.  If the code is split into several
+      files, the files without module options don't need them.
       </para>
 
       <para>
-        In addition to them, you'll need
-      <filename>&lt;linux/interrupt.h&gt;</filename> for the interrupt
-      handling, and <filename>&lt;asm/io.h&gt;</filename> for the i/o
-      access. If you use <function>mdelay()</function> or
+        In addition to these headers, you'll need
+      <filename>&lt;linux/interrupt.h&gt;</filename> for interrupt
+      handling, and <filename>&lt;asm/io.h&gt;</filename> for I/O
+      access. If you use the <function>mdelay()</function> or
       <function>udelay()</function> functions, you'll need to include
-      <filename>&lt;linux/delay.h&gt;</filename>, too. 
+      <filename>&lt;linux/delay.h&gt;</filename> too. 
       </para>
 
       <para>
-      The ALSA interfaces like PCM or control API are defined in other
-      header files as <filename>&lt;sound/xxx.h&gt;</filename>.
+      The ALSA interfaces like the PCM and control APIs are defined in other
+      <filename>&lt;sound/xxx.h&gt;</filename> header files.
       They have to be included after
       <filename>&lt;sound/core.h&gt;</filename>.
       </para>
@@ -795,12 +800,12 @@
 
       <para>
       A card record is the headquarters of the soundcard.  It manages
-      the list of whole devices (components) on the soundcard, such as
+      the whole list of devices (components) on the soundcard, such as
       PCM, mixers, MIDI, synthesizer, and so on.  Also, the card
       record holds the ID and the name strings of the card, manages
       the root of proc files, and controls the power-management states
       and hotplug disconnections.  The component list on the card
-      record is used to manage the proper releases of resources at
+      record is used to manage the correct release of resources at
       destruction. 
       </para>
 
@@ -824,9 +829,8 @@
         <constant>THIS_MODULE</constant>),
         and the size of extra-data space.  The last argument is used to
         allocate card-&gt;private_data for the
-        chip-specific data.  Note that this data
-        <emphasis>is</emphasis> allocated by
-        <function>snd_card_new()</function>.
+        chip-specific data.  Note that these data
+        are allocated by <function>snd_card_new()</function>.
       </para>
     </section>
 
@@ -834,10 +838,10 @@
       <title>Components</title>
       <para>
         After the card is created, you can attach the components
-      (devices) to the card instance. On ALSA driver, a component is
+      (devices) to the card instance. In an ALSA driver, a component is
       represented as a struct <structname>snd_device</structname> object.
       A component can be a PCM instance, a control interface, a raw
-      MIDI interface, etc.  Each of such instances has one component
+      MIDI interface, etc.  Each such instance has one component
       entry.
       </para>
 
@@ -859,7 +863,7 @@
       (<constant>SNDRV_DEV_XXX</constant>), the data pointer, and the
       callback pointers (<parameter>&amp;ops</parameter>). The
       device-level defines the type of components and the order of
-      registration and de-registration.  For most of components, the
+      registration and de-registration.  For most components, the
       device-level is already defined.  For a user-defined component,
       you can use <constant>SNDRV_DEV_LOWLEVEL</constant>.
       </para>
@@ -867,13 +871,13 @@
       <para>
       This function itself doesn't allocate the data space. The data
       must be allocated manually beforehand, and its pointer is passed
-      as the argument. This pointer is used as the identifier
-      (<parameter>chip</parameter> in the above example) for the
-      instance. 
+      as the argument. This pointer is used as the
+      (<parameter>chip</parameter> identifier in the above example)
+      for the instance. 
       </para>
 
       <para>
-        Each ALSA pre-defined component such as ac97 or pcm calls
+        Each pre-defined ALSA component such as ac97 and pcm calls
       <function>snd_device_new()</function> inside its
       constructor. The destructor for each component is defined in the
       callback pointers.  Hence, you don't need to take care of
@@ -881,19 +885,19 @@
       </para>
 
       <para>
-        If you would like to create your own component, you need to
-      set the destructor function to dev_free callback in
-      <parameter>ops</parameter>, so that it can be released
-      automatically via <function>snd_card_free()</function>. The
-      example will be shown later as an implementation of a
-      chip-specific data. 
+        If you wish to create your own component, you need to
+      set the destructor function to the dev_free callback in
+      the <parameter>ops</parameter>, so that it can be released
+      automatically via <function>snd_card_free()</function>.
+      The next example will show an implementation of chip-specific
+      data.
       </para>
     </section>
 
     <section id="card-management-chip-specific">
       <title>Chip-Specific Data</title>
       <para>
-      The chip-specific information, e.g. the i/o port address, its
+      Chip-specific information, e.g. the I/O port address, its
       resource pointer, or the irq number, is stored in the
       chip-specific record.
 
@@ -909,13 +913,14 @@
       </para>
 
       <para>
-        In general, there are two ways to allocate the chip record.
+        In general, there are two ways of allocating the chip record.
       </para>
 
       <section id="card-management-chip-specific-snd-card-new">
         <title>1. Allocating via <function>snd_card_new()</function>.</title>
         <para>
-          As mentioned above, you can pass the extra-data-length to the 4th argument of <function>snd_card_new()</function>, i.e.
+          As mentioned above, you can pass the extra-data-length
+	  to the 4th argument of <function>snd_card_new()</function>, i.e.
 
           <informalexample>
             <programlisting>
@@ -925,7 +930,7 @@
             </programlisting>
           </informalexample>
 
-          whether struct <structname>mychip</structname> is the type of the chip record.
+          struct <structname>mychip</structname> is the type of the chip record.
         </para>
 
         <para>
@@ -1037,8 +1042,8 @@
       <title>Registration and Release</title>
       <para>
         After all components are assigned, register the card instance
-      by calling <function>snd_card_register()</function>. The access
-      to the device files are enabled at this point. That is, before
+      by calling <function>snd_card_register()</function>. Access
+      to the device files is enabled at this point. That is, before
       <function>snd_card_register()</function> is called, the
       components are safely inaccessible from external side. If this
       call fails, exit the probe function after releasing the card via
@@ -1047,7 +1052,7 @@
 
       <para>
         For releasing the card instance, you can call simply
-      <function>snd_card_free()</function>. As already mentioned, all
+      <function>snd_card_free()</function>. As mentioned earlier, all
       components are released automatically by this call. 
       </para>
 
@@ -1055,7 +1060,7 @@
         As further notes, the destructors (both
       <function>snd_mychip_dev_free</function> and
       <function>snd_mychip_free</function>) cannot be defined with
-      <parameter>__devexit</parameter> prefix, because they may be
+      the <parameter>__devexit</parameter> prefix, because they may be
       called from the constructor, too, at the false path. 
       </para>
 
@@ -1071,20 +1076,20 @@
 
 
 <!-- ****************************************************** -->
-<!-- PCI Resource Managements  -->
+<!-- PCI Resource Management  -->
 <!-- ****************************************************** -->
   <chapter id="pci-resource">
-    <title>PCI Resource Managements</title>
+    <title>PCI Resource Management</title>
 
     <section id="pci-resource-example">
       <title>Full Code Example</title>
       <para>
-        In this section, we'll finish the chip-specific constructor,
-      destructor and PCI entries. The example code is shown first,
+        In this section, we'll complete the chip-specific constructor,
+      destructor and PCI entries. Example code is shown first,
       below. 
 
         <example>
-          <title>PCI Resource Managements Example</title>
+          <title>PCI Resource Management Example</title>
           <programlisting>
 <![CDATA[
   struct mychip {
@@ -1103,7 +1108,7 @@
           /* release the irq */
           if (chip->irq >= 0)
                   free_irq(chip->irq, chip);
-          /* release the i/o ports & memory */
+          /* release the I/O ports & memory */
           pci_release_regions(chip->pci);
           /* disable the PCI entry */
           pci_disable_device(chip->pci);
@@ -1196,13 +1201,13 @@
           .remove = __devexit_p(snd_mychip_remove),
   };
 
-  /* initialization of the module */
+  /* module initialization */
   static int __init alsa_card_mychip_init(void)
   {
           return pci_register_driver(&driver);
   }
 
-  /* clean up the module */
+  /* module clean up */
   static void __exit alsa_card_mychip_exit(void)
   {
           pci_unregister_driver(&driver);
@@ -1228,10 +1233,10 @@
       </para>
 
       <para>
-        In the case of PCI devices, you have to call at first
-      <function>pci_enable_device()</function> function before
+        In the case of PCI devices, you first have to call
+      the <function>pci_enable_device()</function> function before
       allocating resources. Also, you need to set the proper PCI DMA
-      mask to limit the accessed i/o range. In some cases, you might
+      mask to limit the accessed I/O range. In some cases, you might
       need to call <function>pci_set_master()</function> function,
       too.
       </para>
@@ -1261,15 +1266,15 @@
     <section id="pci-resource-resource-allocation">
       <title>Resource Allocation</title>
       <para>
-        The allocation of I/O ports and irqs are done via standard kernel
+        The allocation of I/O ports and irqs is done via standard kernel
       functions. Unlike ALSA ver.0.5.x., there are no helpers for
       that. And these resources must be released in the destructor
       function (see below). Also, on ALSA 0.9.x, you don't need to
-      allocate (pseudo-)DMA for PCI like ALSA 0.5.x.
+      allocate (pseudo-)DMA for PCI like in ALSA 0.5.x.
       </para>
 
       <para>
-        Now assume that this PCI device has an I/O port with 8 bytes
+        Now assume that the PCI device has an I/O port with 8 bytes
         and an interrupt. Then struct <structname>mychip</structname> will have the
         following fields:
 
@@ -1288,7 +1293,7 @@
       </para>
 
       <para>
-        For an i/o port (and also a memory region), you need to have
+        For an I/O port (and also a memory region), you need to have
       the resource pointer for the standard resource management. For
       an irq, you have to keep only the irq number (integer). But you
       need to initialize this number as -1 before actual allocation,
@@ -1299,7 +1304,7 @@
       </para>
 
       <para>
-        The allocation of an i/o port is done like this:
+        The allocation of an I/O port is done like this:
 
         <informalexample>
           <programlisting>
@@ -1318,12 +1323,12 @@
 
       <para>
         <!-- obsolete -->
-        It will reserve the i/o port region of 8 bytes of the given
+        It will reserve the I/O port region of 8 bytes of the given
       PCI device. The returned value, chip-&gt;res_port, is allocated
       via <function>kmalloc()</function> by
       <function>request_region()</function>. The pointer must be
-      released via <function>kfree()</function>, but there is some
-      problem regarding this. This issue will be explained more below.
+      released via <function>kfree()</function>, but there is a
+      problem with this. This issue will be explained later.
       </para>
 
       <para>
@@ -1351,8 +1356,8 @@
       </para>
 
       <para>
-      On the PCI bus, the interrupts can be shared. Thus,
-      <constant>IRQF_SHARED</constant> is given as the interrupt flag of
+      On the PCI bus, interrupts can be shared. Thus,
+      <constant>IRQF_SHARED</constant> is used as the interrupt flag of
       <function>request_irq()</function>. 
       </para>
 
@@ -1364,7 +1369,7 @@
       </para>
 
       <para>
-        I won't define the detail of the interrupt handler at this
+        I won't give details about the interrupt handler at this
         point, but at least its appearance can be explained now. The
         interrupt handler looks usually like the following: 
 
@@ -1386,11 +1391,11 @@
         Now let's write the corresponding destructor for the resources
       above. The role of destructor is simple: disable the hardware
       (if already activated) and release the resources. So far, we
-      have no hardware part, so the disabling is not written here. 
+      have no hardware part, so the disabling code is not written here. 
       </para>
 
       <para>
-        For releasing the resources, <quote>check-and-release</quote>
+        To release the resources, the <quote>check-and-release</quote>
         method is a safer way. For the interrupt, do like this: 
 
         <informalexample>
@@ -1410,7 +1415,7 @@
       <para>
         When you requested I/O ports or memory regions via
 	<function>pci_request_region()</function> or
-	<function>pci_request_regions()</function> like this example,
+	<function>pci_request_regions()</function> like in this example,
 	release the resource(s) using the corresponding function,
 	<function>pci_release_region()</function> or
 	<function>pci_release_regions()</function>.
@@ -1429,7 +1434,7 @@
 	or <function>request_mem_region</function>, you can release it via
 	<function>release_resource()</function>.  Suppose that you keep
 	the resource pointer returned from <function>request_region()</function>
-	in chip-&gt;res_port, the release procedure looks like below:
+	in chip-&gt;res_port, the release procedure looks like:
 
         <informalexample>
           <programlisting>
@@ -1442,7 +1447,7 @@
 
       <para>
       Don't forget to call <function>pci_disable_device()</function>
-      before all finished.
+      before the end.
       </para>
 
       <para>
@@ -1459,14 +1464,14 @@
 
       <para>
       Again, remember that you cannot
-      set <parameter>__devexit</parameter> prefix for this destructor. 
+      use the <parameter>__devexit</parameter> prefix for this destructor. 
       </para>
 
       <para>
-      We didn't implement the hardware-disabling part in the above.
+      We didn't implement the hardware disabling part in the above.
       If you need to do this, please note that the destructor may be
       called even before the initialization of the chip is completed.
-      It would be better to have a flag to skip the hardware-disabling
+      It would be better to have a flag to skip hardware disabling
       if the hardware was not initialized yet.
       </para>
 
@@ -1475,14 +1480,14 @@
       <function>snd_device_new()</function> with
       <constant>SNDRV_DEV_LOWLELVEL</constant> , its destructor is 
       called at the last.  That is, it is assured that all other
-      components like PCMs and controls have been already released.
-      You don't have to call stopping PCMs, etc. explicitly, but just
-      stop the hardware in the low-level.
+      components like PCMs and controls have already been released.
+      You don't have to stop PCMs, etc. explicitly, but just
+      call low-level hardware stopping.
       </para>
 
       <para>
         The management of a memory-mapped region is almost as same as
-        the management of an i/o port. You'll need three fields like
+        the management of an I/O port. You'll need three fields like
         the following: 
 
         <informalexample>
@@ -1561,8 +1566,8 @@
     <section id="pci-resource-entries">
       <title>PCI Entries</title>
       <para>
-        So far, so good. Let's finish the rest of missing PCI
-      stuffs. At first, we need a
+        So far, so good. Let's finish the missing PCI
+      stuff. At first, we need a
       <structname>pci_device_id</structname> table for this
       chipset. It's a table of PCI vendor/device ID number, and some
       masks. 
@@ -1588,13 +1593,13 @@
 
       <para>
         The first and second fields of
-      <structname>pci_device_id</structname> struct are the vendor and
-      device IDs. If you have nothing special to filter the matching
-      devices, you can use the rest of fields like above. The last
-      field of <structname>pci_device_id</structname> struct is a
+      the <structname>pci_device_id</structname> structure are the vendor and
+      device IDs. If you have no reason to filter the matching
+      devices, you can leave the remaining fields as above. The last
+      field of the <structname>pci_device_id</structname> struct contains
       private data for this entry. You can specify any value here, for
-      example, to tell the type of different operations per each
-      device IDs. Such an example is found in intel8x0 driver. 
+      example, to define specific operations for supported device IDs.
+      Such an example is found in the intel8x0 driver. 
       </para>
 
       <para>
@@ -1621,10 +1626,10 @@
 
       <para>
         The <structfield>probe</structfield> and
-      <structfield>remove</structfield> functions are what we already
-      defined in 
-      the previous sections. The <structfield>remove</structfield> should
-      be defined with 
+      <structfield>remove</structfield> functions have already
+      been defined in the previous sections.
+      The <structfield>remove</structfield> function should
+      be defined with the 
       <function>__devexit_p()</function> macro, so that it's not
       defined for built-in (and non-hot-pluggable) case. The
       <structfield>name</structfield> 
@@ -1665,8 +1670,7 @@
 
       <para>
         Oh, one thing was forgotten. If you have no exported symbols,
-        you need to declare it on 2.2 or 2.4 kernels (on 2.6 kernels
-        it's not necessary, though).
+        you need to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels).
 
         <informalexample>
           <programlisting>
@@ -1698,7 +1702,7 @@
 
       <para>
         For accessing to the PCM layer, you need to include
-      <filename>&lt;sound/pcm.h&gt;</filename> above all. In addition,
+      <filename>&lt;sound/pcm.h&gt;</filename> first. In addition,
       <filename>&lt;sound/pcm_params.h&gt;</filename> migh