doc: cleanup all of the man page documentation

The man pages have suffered from a little bitrot over time. Fix that by
updating them with references to recent changes, noting some planned
future behavioral changes (modprobe "install" commands), and improve
readability by re-ordering modprobe options to ensure everything is
documented in the current release.

Signed-off-by: Jon Masters <jcm@jonmasters.org>

11 files changed, 327 insertions, 274 deletions

diff --git a/Makefile.am b/Makefile.am
index b5249bf..4bcf598 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -36,7 +36,7 @@ depmod_LDADD = $(LDADD) libmodtools.a
 modinfo_LDADD = $(LDADD) libmodtools.a
 modindex_LDADD = $(LDADD) libmodtools.a
 
-MAN5 = modprobe.conf.5 modules.dep.5 depmod.conf.5 modprobe.d.5
+MAN5 = modprobe.conf.5 modules.dep.bin.5 modules.dep.5 depmod.conf.5 modprobe.d.5
 MAN8 = depmod.8 insmod.8 lsmod.8 rmmod.8 modprobe.8 modinfo.8
 SGML = $(addprefix doc/,  $(MAN5:%.5=%.sgml) $(MAN8:%.8=%.sgml))
 dist_man_MANS = $(MAN5) $(MAN8)
diff --git a/doc/depmod.conf.sgml b/doc/depmod.conf.sgml
index 0d1b5b7..4bc399b 100644
--- a/doc/depmod.conf.sgml
+++ b/doc/depmod.conf.sgml
@@ -18,7 +18,7 @@
       <firstname>Jon</firstname>
       <surname>Masters</surname>
     </author>
-    <date>2005-09-23</date>
+    <date>2010-03-01</date>
   </refentryinfo>
   <refmeta>
     <refentrytitle>depmod.d</refentrytitle>
@@ -88,8 +88,8 @@
 	  </para>
 	  <para>
 	    For example, it is possible to override the priority of
-	    an updated test module called <command>kmp</command> by
-	    specifying the following command: "override kmp * extra".
+	    an updated test module called <command>kmod</command> by
+	    specifying the following command: "override kmod * extra".
 	    This will ensure that any matching module name installed
 	    under the <command>extra</command> subdirectory within
 	    /lib/modules (or other module location) will take priority
@@ -102,7 +102,7 @@
   <refsect1>
     <title>COPYRIGHT</title>
     <para>
-      This manual page Copyright 2006, Jon Masters, Red Hat, Inc.
+      This manual page Copyright 2006-2010, Jon Masters, Red Hat, Inc.
     </para>
   </refsect1>
     <refsect1>
diff --git a/doc/depmod.sgml b/doc/depmod.sgml
index fcde505..ed39056 100644
--- a/doc/depmod.sgml
+++ b/doc/depmod.sgml
@@ -12,13 +12,13 @@
 <refentry>
   <refentryinfo>
     <address>
-      <email>rusty@rustcorp.com.au</email>
+      <email>jcm@jonmasters.org</email>
     </address>
     <author>
-      <firstname>Rusty</firstname>
-      <surname>Russell</surname>
+      <firstname>Jon</firstname>
+      <surname>Masters</surname>
     </author>
-    <date>2007-03-21</date>
+    <date>2010-03-01</date>
   </refentryinfo>
   <refmeta>
     <refentrytitle>depmod</refentrytitle>
@@ -52,10 +52,9 @@
     <title>DESCRIPTION</title>
     <para>
       Linux kernel modules can provide services (called "symbols") for
-      other modules to use (using EXPORT_SYMBOL in the code).  If a
-      second module uses this symbol, that second module clearly
-      depends on the first module.  These dependencies can get quite
-      complex.
+      other modules to use (using one of the EXPORT_SYMBOL variants in the
+      code).  If a second module uses this symbol, that second module clearly
+      depends on the first module.  These dependencies can get quite complex.
     </para>
     <para>
       <command>depmod</command> creates a list of module dependencies
@@ -63,10 +62,13 @@
       <filename>/lib/modules/</filename><replaceable>version</replaceable> 
       and determining what symbols it exports and what symbols it
       needs.  By default, this list is written to
-      <filename>modules.dep</filename> in the same directory.  If
+      <filename>modules.dep</filename>, and a binary hashed version named
+      <filename>modules.dep.bin</filename>, in the same directory.  If
       filenames are given on the command line, only those modules are
-      examined (which is rarely useful unless all modules are
-      listed).
+      examined (which is rarely useful unless all modules are listed).
+      <command>depmod</command> also creates a list of symbols provided
+      by modules in the file named <filename>modules.symbols</filename>
+      and its binary hashed version, <filename>modules.symbols.bin</filename>.
     </para>
     <para>
       If a <replaceable>version</replaceable> is provided, then that
@@ -74,8 +76,11 @@
       current kernel version (as returned by <command>uname -r</command>).
     </para>
     <para>
-      <command>depmod</command> will also generate various map files
-      in this directory for use by the hotplug infrastructure.
+      
+    <para>
+      <command>depmod</command> will also generate various legacy map
+      files in the output directory for use by the older hotplug
+      infrastructure. These map files are largely deprecated.
     </para>
   </refsect1>
   <refsect1>
@@ -115,7 +120,9 @@
 	      the directory name.  This
 	      <replaceable>basedir</replaceable> is stripped from the
 	      resulting <filename>modules.dep</filename> file, so it
-	      is ready to be moved into the normal location.
+	      is ready to be moved into the normal location. Use this option
+	      if you are a distribution vendor who needs to pre-generate the
+	      meta-data files rather than running depmod again later.
 	    </para>
         </listitem>
       </varlistentry>
@@ -140,7 +147,9 @@
 	      supplied by other modules or the kernel.  Normally, any
 	      symbols not provided by modules are assumed to be
 	      provided by the kernel (which should be true in a
-	      perfect world).
+	      perfect world), but this assumption can break espencially
+	      when additionally updated third party drivers are not
+	      correctly installed or were built incorrectly.
 	    </para>
 	  </listitem>
       </varlistentry>
@@ -202,7 +211,8 @@
     <title>COPYRIGHT</title>
 
     <para>
-      This manual page Copyright 2002, Rusty Russell, IBM Corporation.
+      This manual page originally Copyright 2002, Rusty Russell,
+      IBM Corporation. Maintained by Jon Masters and others.
     </para>
   </refsect1>
   <refsect1>
@@ -212,6 +222,9 @@
 	<refentrytitle>depmod.conf</refentrytitle><manvolnum>5</manvolnum>
       </citerefentry>,
       <citerefentry>
+	<refentrytitle>depmod.d</refentrytitle><manvolnum>5</manvolnum>
+      </citerefentry>,
+      <citerefentry>
 	<refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum>
       </citerefentry>,
       <citerefentry>
diff --git a/doc/insmod.sgml b/doc/insmod.sgml
index ee0b156..ab3a4e8 100644
--- a/doc/insmod.sgml
+++ b/doc/insmod.sgml
@@ -12,13 +12,13 @@
 <refentry>
   <refentryinfo>
     <address>
-      <email>rusty@rustcorp.com.au</email>
+      <email>jcm@jonmasters.org</email>
     </address>
     <author>
-      <firstname>Rusty</firstname>
-      <surname>Russell</surname>
+      <firstname>Jon</firstname>
+      <surname>Masters</surname>
     </author>
-    <date>2002-12-27</date>
+    <date>2010-03-01</date>
   </refentryinfo>
   <refmeta>
     <refentrytitle>insmod</refentrytitle>
@@ -43,7 +43,7 @@
 	taken from standard input. Most users will want to use
 	<citerefentry><refentrytitle>modprobe</refentrytitle>
 	<manvolnum>8</manvolnum> </citerefentry> instead, which is
-	more clever.</para>
+	more clever and can handle module dependencies.</para>
 
     <para>Only the most general of error messages are reported: as the
 	work of trying to link the module is now done inside the kernel,
@@ -53,7 +53,8 @@
   <refsect1>
     <title>COPYRIGHT</title>
     <para>
-      This manual page Copyright 2002, Rusty Russell, IBM Corporation.
+      This manual page originally Copyright 2002, Rusty Russell, IBM
+      Corporation. Maintained by Jon Masters and others.
     </para>
   </refsect1>
   <refsect1>
@@ -68,6 +69,9 @@
       <citerefentry>
 	<refentrytitle>lsmod</refentrytitle><manvolnum>8</manvolnum>
       </citerefentry>
+      <citerefentry>
+	<refentrytitle>modinfo</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>
     </para>
   </refsect1>
 </refentry>
diff --git a/doc/lsmod.sgml b/doc/lsmod.sgml
index 7e41a77..0267451 100644
--- a/doc/lsmod.sgml
+++ b/doc/lsmod.sgml
@@ -12,13 +12,13 @@
 <refentry>
   <refentryinfo>
     <address>
-      <email>rusty@rustcorp.com.au</email>
+      <email>jcm@jonmasters.org</email>
     </address>
     <author>
-      <firstname>Rusty</firstname>
-      <surname>Russell</surname>
+      <firstname>Jon</firstname>
+      <surname>Masters</surname>
     </author>
-    <date>2002-12-27</date>
+    <date>2010-03-01</date>
   </refentryinfo>
   <refmeta>
     <refentrytitle>lsmod</refentrytitle>
@@ -44,13 +44,18 @@
   <refsect1>
     <title>COPYRIGHT</title>
     <para>
-      This manual page Copyright 2002, Rusty Russell, IBM Corporation.
+      This manual page originally Copyright 2002, Rusty Russell, IBM
+      Corporation. Maintained by Jon Masters and others.
     </para>
   </refsect1>
   <refsect1>
     <title>SEE ALSO</title>
 
-    <para><citerefentry>
+    <para>
+      <citerefentry>
+	<refentrytitle>insmod</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citerefentry>
 	<refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum>
       </citerefentry>,
       <citerefentry>
diff --git a/doc/modinfo.sgml b/doc/modinfo.sgml
index 0975d0f..8c72eef 100644
--- a/doc/modinfo.sgml
+++ b/doc/modinfo.sgml
@@ -12,13 +12,13 @@
 <refentry>
   <refentryinfo>
     <address>
-      <email>rusty@rustcorp.com.au</email>
+      <email>jcm@jonmasters.org</email>
     </address>
     <author>
-      <firstname>Rusty</firstname>
-      <surname>Russell</surname>
+      <firstname>Jon</firstname>
+      <surname>Masters</surname>
     </author>
-    <date>2003-05-9</date>
+    <date>2010-03-01</date>
   </refentryinfo>
   <refmeta>
     <refentrytitle>modinfo</refentrytitle>
@@ -49,8 +49,8 @@
       Kernel modules given on the command line.  If the module name is
       not a filename, then the
       <filename>/lib/modules/</filename><replaceable>version</replaceable>
-      directory is searched, as done by
-      <citerefentry><refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+      directory is searched, as is also done by
+      <citerefentry><refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum></citerefentry> when loading kernel modules.
     </para>
 
     <para><command>modinfo</command> by default lists each attribute
@@ -103,7 +103,7 @@
             information from a newly installed (but not yet running) set of
             kernel modules. For example, you wish to find which firmware files
             are needed by various modules in a new kernel for which you must
-            make an initrd image prior to booting.
+            make an initrd/initramfs image prior to booting.
           </para>
         </listitem>
       </varlistentry>
@@ -137,7 +137,8 @@
   <refsect1>
     <title>COPYRIGHT</title>
     <para>
-      This manual page Copyright 2003, Rusty Russell, IBM Corporation.
+      This manual page originally Copyright 2003, Rusty Russell, IBM
+      Corporation. Maintained by Jon Masters and others.
     </para>
   </refsect1>
   <refsect1>
diff --git a/doc/modprobe.conf.sgml b/doc/modprobe.conf.sgml
index 1a2e2c6..6fab7d0 100644
--- a/doc/modprobe.conf.sgml
+++ b/doc/modprobe.conf.sgml
@@ -12,13 +12,13 @@
 <refentry>
   <refentryinfo>
     <address>
-      <email>rusty@rustcorp.com.au</email>
+      <email>jcm@jonmasters.org</email>
     </address>
     <author>
-      <firstname>Rusty</firstname>
-      <surname>Russell</surname>
+      <firstname>Jon</firstname>
+      <surname>Masters</surname>
     </author>
-    <date>2005-06-01</date>
+    <date>2010-03-01</date>
   </refentryinfo>
   <refmeta>
     <refentrytitle>modprobe.conf</refentrytitle>
@@ -31,7 +31,7 @@
     <title>DESCRIPTION</title>
 
     <para>Because the <command>modprobe</command> command can add or
-      remove more than one module, due to module dependencies,
+      remove more than one module, due to modules having dependencies,
       we need a method of specifying what options are to be used with
       those modules.  All files underneath the 
       <filename>/etc/modprobe.d</filename> directory which end with the
@@ -46,7 +46,7 @@
     <para>
       Note that module and alias names (like other module names) can
       have - or _ in them: both are interchangable throughout all the
-      module commands.
+      module commands as underscore conversion happens automatically.
     </para>
     <para>
       The format of and files under <filename>modprobe.d</filename> and
@@ -109,11 +109,10 @@
         </term>
 	<listitem>
 	  <para>
-	    This is the most powerful primitive: it tells
-	    <command>modprobe</command> to run your command instead of
-	    inserting the module in the kernel as normal.  The command
-	    can be any shell command: this allows you to do any kind
-	    of complex processing you might wish.  For example, if the
+	    This command instructs <command>modprobe</command> to run your
+	    command instead of inserting the module in the kernel as normal.
+	    The command can be any shell command: this allows you to do any
+	    kind of complex processing you might wish.  For example, if the
 	    module "fred" works better with the module "barney"
 	    already installed (but it doesn't depend on it, so
 	    <command>modprobe</command> won't automatically load it),
@@ -124,13 +123,17 @@
 	    running the same <command>install</command> command again.
 	    See also <command>remove</command> below.
 	  </para>
-	  <para>
-	    You can also use <command>install</command> to make up
-	    modules which don't otherwise exist.  For example:
-	    "install probe-ethernet /sbin/modprobe e100 ||
-	    /sbin/modprobe eepro100", which will first try to load the e100
-	    driver, and if it fails, then the eepro100 driver when you do "modprobe
-	    probe-ethernet".
+	  <para>The long term future of this command as a solution to the
+	    problem of providing additional module dependencies is not assured
+	    and it is intended to replace this command with a warning about
+	    its eventual removal or deprecation at some point in a future
+	    release. Its use complicates the automated determination of module
+	    dependencies by distribution utilities, such as mkinitrd (because
+	    these now need to somehow interpret what the
+	    <command>install</command> commands might be doing.
+	    In a perfect world, modules would provide all dependency
+	    information without the use of this command and work is underway
+	    to implement soft dependency support within the Linux kernel.
 	  </para>
 	  <para>
 	    If you use the string "$CMDLINE_OPTS" in the command, it
@@ -151,10 +154,6 @@
 	  <para>
 	    This is similar to the <command>install</command> command
 	    above, except it is invoked when "modprobe -r" is run.
-	    The removal counterparts to the two examples above would
-	    be: "remove fred /sbin/modprobe -r --ignore-remove fred &&
-	    /sbin/modprobe -r barney", and "remove probe-ethernet
-	    /sbin/modprobe -r eepro100 || /sbin/modprobe -r e100".
 	  </para>
         </listitem>
       </varlistentry>
@@ -168,7 +167,7 @@
 	    "pci:123...".  These "internal" aliases can be overridden
 	    by normal "alias" keywords, but there are cases where two
 	    or more modules both support the same devices, or a module
-	    invalidly claims to support a device: the
+	    invalidly claims to support a devicei that it does not: the
 	    <command>blacklist</command> keyword indicates that all of
 	    that particular module's internal aliases are to be ignored.
 	  </para>
@@ -177,9 +176,18 @@
     </variablelist>
   </refsect1>
   <refsect1>
+    <title>COMPATIBILITY</title>
+    <para>
+      A future version of module-init-tools will come with a strong warning
+      to avoid use of the <command>install</command> as explained above. This
+      will happen once support for soft dependencies in the kernel is complete.
+    </para>
+  </refsect1>
+  <refsect1>
     <title>COPYRIGHT</title>
     <para>
-      This manual page Copyright 2004, Rusty Russell, IBM Corporation.
+      This manual page originally Copyright 2004, Rusty Russell, IBM
+      Corporation. Maintained by Jon Masters and others.
     </para>
   </refsect1>
   <refsect1>
diff --git a/doc/modprobe.sgml b/doc/modprobe.sgml
index 9e41dde..a4a3b22 100644
--- a/doc/modprobe.sgml
+++ b/doc/modprobe.sgml
@@ -12,13 +12,13 @@
 <refentry>
   <refentryinfo>
     <address>
-      <email>rusty@rustcorp.com.au</email>
+      <email>jcm@jonmasters.org</email>
     </address>
     <author>
-      <firstname>Rusty</firstname>
-      <surname>Russell</surname>
+      <firstname>Jon</firstname>
+      <surname>Masters</surname>
     </author>
-    <date>2002-12-27</date>
+    <date>2010-03-01</date>
   </refentryinfo>
   <refmeta>
     <refentrytitle>modprobe</refentrytitle>
@@ -70,7 +70,8 @@
     <para>
       <command>modprobe</command> intelligently adds or removes a
       module from the Linux kernel: note that for convenience, there
-      is no difference between _ and - in module names.
+      is no difference between _ and - in module names (automatic
+      underscore conversion is performed).
       <command>modprobe</command> looks in the module directory
       <filename>/lib/modules/`uname -r`</filename> for all
       the modules and other files, except for the optional
@@ -83,7 +84,8 @@
       &lt;module&gt;.&lt;option&gt;.
     </para>
     <para>
-      Note that this version of <command>modprobe</command> does not
+      Note that unlike in 2.4 series Linux kernels (which are not supported
+      by this tool) this version of <command>modprobe</command> does not
       do anything to the module itself: the work of resolving symbols
       and understanding parameters is done inside the kernel.  So
       module failure is sometimes accompanied by a kernel message: see
@@ -93,15 +95,14 @@
     </para>
     <para>
       <command>modprobe</command> expects an up-to-date
-      <filename>modules.dep</filename> file, as generated by
-      <command>depmod</command> (see <citerefentry>
-      <refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum>
+      <filename>modules.dep.bin</filename> file (or fallback human
+      readable <filename>modules.dep</filename> file), as generated
+      by the corresponding <command>depmod</command> utility shipped
+      along with <command>modprobe</command> (see
+      <citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum>
       </citerefentry>).  This file lists what other modules each
       module needs (if any), and <command>modprobe</command> uses this
-      to add or remove these dependencies automatically.  See
-      <citerefentry>
-      <refentrytitle>modules.dep</refentrytitle><manvolnum>5</manvolnum>
-      </citerefentry>).
+      to add or remove these dependencies automatically.
     </para>
     <para>
       If any arguments are given after the
@@ -114,19 +115,24 @@
     <title>OPTIONS</title>
     <variablelist>
       <varlistentry>
-        <term><option>-v</option> <option>--verbose</option>
+        <term><option>-a</option> <option>--all</option>
         </term>
         <listitem>
-          <para>
-	    Print messages about what the program is doing.  Usually
-	    <command>modprobe</command> only prints messages if
-	    something goes wrong.
-	  </para>
-          <para>
-	    This option is passed through <command>install</command>
-	    or <command>remove</command> commands to other
-	    <command>modprobe</command> commands in the
-	    MODPROBE_OPTIONS environment variable.
+          <para>Insert all module names on the command line.
+	 </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>-b</option> <option>--use-blacklist</option>
+        </term>
+        <listitem>
+	  <para>
+	    This option causes <command>modprobe</command> to apply the
+	    <command>blacklist</command> commands in the configuration files
+	    (if any) to module names as well.  It is usually used by
+	    <citerefentry>
+	      <refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum>
+	    </citerefentry>.
 	  </para>
         </listitem>
       </varlistentry>
@@ -150,95 +156,46 @@
         <term><option>-c</option> <option>--showconfig</option>
         </term>
         <listitem>
-          <para>Dump out the effective configuration from the config directory and exit.
-	  </para>
-        </listitem>
-      </varlistentry>
-      <varlistentry>
-        <term><option>-n</option> <option>--dry-run</option>
-        <option>--show</option>
-        </term>
-        <listitem>
-          <para>This option does everything but actually insert or
-		delete the modules (or run the install or remove
-		commands).  Combined with <option>-v</option>, it is
-		useful for debugging problems.
-	  </para>
-        </listitem>
-      </varlistentry>
-      <varlistentry>
-        <term><option>-i</option> <option>--ignore-install</option> <option>--ignore-remove</option>
-        </term>
-        <listitem>
-          <para>This option causes <command>modprobe</command> to
-		ignore <command>install</command> and
-		<command>remove</command> commands in the
-		configuration file (if any) for the module specified on the
-		command line (any dependent modules are still subject
-		to commands set for them in the configuration file).
-		See <citerefentry>
-<refentrytitle>modprobe.conf</refentrytitle><manvolnum>5</manvolnum>
-</citerefentry>.
+          <para>Dump out the effective configuration from the config directory
+                and exit.
 	  </para>
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term><option>-q</option> <option>--quiet</option>
+        <term><option>--dump-modversions</option>
         </term>
         <listitem>
           <para>
-	    With this flag, <command>modprobe</command> won't print an error
-	    message if you try to remove or insert a module it can't find (and
-	    isn't an alias or
-	    <command>install</command>/<command>remove</command> command).
-	    However, it will still return with a non-zero exit status. The
-	    kernel uses this to opportunistically probe for modules which might
-	    exist.
-	  </para>
+            Print out a list of module versioning information required by a
+            module. This option is commonly used by distributions in order to
+            package up a Linux kernel module using module versioning deps.
+          </para>
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term><option>-r</option> <option>--remove</option>
+        <term><option>-d</option> <option>--dirname</option>
         </term>
         <listitem>
           <para>
-	    This option causes <command>modprobe</command> to remove
-	    rather than insert a module.  If the modules it depends on
-	    are also unused, <command>modprobe</command> will try to
-	    remove them too.  Unlike insertion, more than one module
-	    can be specified on the command line (it does not make
-	    sense to specify module parameters when removing modules).
-	  </para>
-	  <para>
-	    There is usually no reason to remove modules, but some
-	    buggy modules require it.  Your kernel may not support
-	    removal of modules.
-	  </para>
-        </listitem>
-      </varlistentry>
-      <varlistentry>
-        <term><option>-V</option> <option>--version</option>
-        </term>
-        <listitem>
-          <para>Show version of program and exit.</para>
+            Directory where modules can be found,
+            <filename>/lib/modules/<replaceable>RELEASE</replaceable></filename>
+            by default.
+          </para>
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term><option>-f</option> <option>--force</option>
+        <term><option>--first-time</option>
         </term>
         <listitem>
           <para>
-	    Try to strip any versioning information from the module
-	    which might otherwise stop it from loading: this is the
-	    same as using both <option>--force-vermagic</option> and
-	    <option>--force-modversion</option>.  Naturally, these
-	    checks are there for your protection, so using this option
-	    is dangerous.
-	 </para>
-	 <para>
-	    This applies to any modules inserted: both the module (or
-	    alias) on the command line and any modules it on which it depends.
-	 </para>
+	    Normally, <command>modprobe</command> will succeed (and do
+	    nothing) if told to insert a module which is already
+	    present or to remove a module which isn't present.  This is
+	    ideal for simple scripts; however, more complicated scripts often
+	    want to know whether <command>modprobe</command> really
+	    did something: this option makes modprobe fail in the
+	    case that it actually didn't do anything.
+	  </para>
         </listitem>
       </varlistentry>
       <varlistentry>
@@ -251,7 +208,8 @@
 	    a module fails to load and the kernel complains that the
 	    "version magic" doesn't match, you can use this option to
 	    remove it.  Naturally, this check is there for your
-	    protection, so this using option is dangerous.
+	    protection, so this using option is dangerous unless
+	    you know what you're doing.
 	 </para>
 	 <para>
 	    This applies to any modules inserted: both the module (or
@@ -271,7 +229,8 @@
 	    module disagrees about a version of some interface, you
 	    can use "--force-modversion" to remove the version
 	    information altogether.  Naturally, this check is there
-	    for your protection, so using this option is dangerous.
+	    for your protection, so using this option is dangerous
+	    unless you know what you're doing.
 	 </para>
 	 <para>
 	    This applies any modules inserted: both the module (or
@@ -280,12 +239,52 @@
         </listitem>
       </varlistentry>
       <varlistentry>
+        <term><option>-f</option> <option>--force</option>
+        </term>
+        <listitem>
+          <para>
+	    Try to strip any versioning information from the module
+	    which might otherwise stop it from loading: this is the
+	    same as using both <option>--force-vermagic</option> and
+	    <option>--force-modversion</option>.  Naturally, these
+	    checks are there for your protection, so using this option
+	    is dangerous unless you know what you are doing.
+	 </para>
+	 <para>
+	    This applies to any modules inserted: both the module (or
+	    alias) on the command line and any modules it on which it depends.
+	 </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>-i</option> <option>--ignore-install</option> <option>--ignore-remove</option>
+        </term>
+        <listitem>
+          <para>This option causes <command>modprobe</command> to
+		ignore <command>install</command> and
+		<command>remove</command> commands in the
+		configuration file (if any) for the module specified on the
+		command line (any dependent modules are still subject
+		to commands set for them in the configuration file). Both
+		<command>install</command> and <command>remove</command>
+		commands will currently be ignored when this option is used
+		regardless of whether the request was more specifically
+		made with only one or other (and not both) of
+		<option>--ignore-install</option> or
+		<option>--ignore-remove</option>.
+		See <citerefentry>
+<refentrytitle>modprobe.conf</refentrytitle><manvolnum>5</manvolnum>
+</citerefentry>.
+	  </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
         <term><option>-l</option> <option>--list</option>
         </term>
         <listitem>
           <para>List all modules matching the given wildcard (or "*"
 		if no wildcard is given).  This option is provided for
-		backwards compatibility: see
+		backwards compatibility and may go away in future: see
 	    <citerefentry>
 	      <refentrytitle>find</refentrytitle><manvolnum>1</manvolnum>
 	    </citerefentry> and
@@ -296,50 +295,78 @@
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term><option>-a</option> <option>--all</option>
+        <term><option>-n</option> <option>--dry-run</option>
+        <option>--show</option>
         </term>
         <listitem>
-          <para>Insert all module names on the command line.
-	 </para>
+          <para>This option does everything but actually insert or
+		delete the modules (or run the install or remove
+		commands).  Combined with <option>-v</option>, it is
+		useful for debugging problems. For historical reasons
+		both <option>--dry-run</option> and <option>--show</option>
+		actually mean the same thing and are interchangeable.
+	  </para>
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term><option>-t</option> <option>--type</option>
+        <term><option>-o</option> <option>--name</option>
         </term>
         <listitem>
-          <para>Restrict <option>-l</option> to modules
-		in directories matching the
-		<replaceable>dirname</replaceable> given.  This option
-		is provided for backwards compatibility: see
-	    <citerefentry>
-	      <refentrytitle>find</refentrytitle><manvolnum>1</manvolnum>
-	    </citerefentry>
-	    and
-	    <citerefentry>
-	      <refentrytitle>basename</refentrytitle><manvolnum>1</manvolnum>
-	    </citerefentry> for a more flexible alternative.
-	 </para>
+          <para>
+	    This option tries to rename the module which is being
+	    inserted into the kernel.  Some testing modules can
+	    usefully be inserted multiple times, but the kernel
+	    refuses to have two modules of the same name.  Normally,
+	    modules should not require multiple insertions, as that
+	    would make them useless if there were no module support.
+	  </para>
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term><option>-s</option> <option>--syslog</option>
+        <term><option>-q</option> <option>--quiet</option>
         </term>
         <listitem>
           <para>
-	    This option causes any error messages to go through the
-	    syslog mechanism (as LOG_DAEMON with level LOG_NOTICE)
-	    rather than to standard error.  This is also automatically
-	    enabled when stderr is unavailable.
+	    With this flag, <command>modprobe</command> won't print an error
+	    message if you try to remove or insert a module it can't find (and
+	    isn't an alias or
+	    <command>install</command>/<command>remove</command> command).
+	    However, it will still return with a non-zero exit status. The
+	    kernel uses this to opportunistically probe for modules which might
+	    exist using request_module.
 	  </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>-R</option> <option>--resolve-alias</option>
+        </term>
+        <listitem>
           <para>
-	    This option is passed through <command>install</command>
-	    or <command>remove</command> commands to other
-	    <command>modprobe</command> commands in the
-	    MODPROBE_OPTIONS environment variable.
+	    Print all module names matching an alias. This can be useful
+	    for debugging module alias problems.
 	  </para>
         </listitem>
       </varlistentry>
       <varlistentry>
+        <term><option>-r</option> <option>--remove</option>
+        </term>
+        <listitem>
+          <para>
+	    This option causes <command>modprobe</command> to remove
+	    rather than insert a module.  If the modules it depends on
+	    are also unused, <command>modprobe</command> will try to
+	    remove them too.  Unlike insertion, more than one module
+	    can be specified on the command line (it does not make
+	    sense to specify module parameters when removing modules).
+	  </para>
+	  <para>
+	    There is usually no reason to remove modules, but some
+	    buggy modules require it.  Your distribution kernel may not
+	    have been built to support removal of modules at all.
+	  </para>
+        </listitem>
+     </varlistentry>
+     <varlistentry>
         <term><option>-S</option> <option>--set-version</option>
         </term>
         <listitem>
@@ -358,85 +385,75 @@
 	    List the dependencies of a module (or alias), including
 	    the module itself.  This produces a (possibly empty) set
 	    of module filenames, one per line, each starting with
-	    "insmod".  Install commands which apply are shown prefixed by
+	    "insmod" and is typically used by distributions to determine
+	    which modules to include when generating initrd/initramfs images.
+	    <command>Install</commnd> commands which apply are shown prefixed by
 	    "install".  It does not run any of the install commands.  Note that
 	    <citerefentry><refentrytitle>modinfo</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 	    can be used to extract dependencies of a module from the
 	    module itself, but knows nothing of aliases or install commands.
 	  </para>
         </listitem>
-      </varlistentry>
-      <varlistentry>
-        <term><option>--resolve-alias</option>
+     </varlistentry>
+     <varlistentry>
+        <term><option>-s</option> <option>--syslog</option>
         </term>
         <listitem>
           <para>
-	    Print all module names matching an alias.
+	    This option causes any error messages to go through the
+	    syslog mechanism (as LOG_DAEMON with level LOG_NOTICE)
+	    rather than to standard error.  This is also automatically
+	    enabled when stderr is unavailable.
 	  </para>
-        </listitem>
-      </varlistentry>
-      <varlistentry>
-        <term><option>-o</option> <option>--name</option>
-        </term>
-        <listitem>
           <para>
-	    This option tries to rename the module which is being
-	    inserted into the kernel.  Some testing modules can
-	    usefully be inserted multiple times, but the kernel
-	    refuses to have two modules of the same name.  Normally,
-	    modules should not require multiple insertions, as that
-	    would make them useless if there were no module support.
+	    This option is passed through <command>install</command>
+	    or <command>remove</command> commands to other
+	    <command>modprobe</command> commands in the
+	    MODPROBE_OPTIONS environment variable.
 	  </para>
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term><option>--first-time</option>
+        <term><option>-t</option> <option>--type</option>
         </term>
         <listitem>
-          <para>
-	    Normally, <command>modprobe</command> will succeed (and do
-	    nothing) if told to insert a module which is already
-	    present or to remove a module which isn't present.  This is
-	    ideal for
-	    simple scripts; however, more complicated scripts often
-	    want to know whether <command>modprobe</command> really
-	    did something: this option makes modprobe fail for that
-	    case.
-	  </para>
+          <para>Restrict <option>-l</option> to modules
+		in directories matching the
+		<replaceable>dirname</replaceable> given.  This option
+		is provided for backwards compatibility and may go
+		away in future: see
+	    <citerefentry>
+	      <refentrytitle>find</refentrytitle><manvolnum>1</manvolnum>
+	    </citerefentry>
+	    and
+	    <citerefentry>
+	      <refentrytitle>basename</refentrytitle><manvolnum>1</manvolnum>
+	    </citerefentry> for a more flexible alternative.
+	 </para>
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term><option>--dump-modversions</option>
+        <term><option>-V</option> <option>--version</option>
         </term>
         <listitem>
-          <para>
-            Print out a list of module versioning information required by a
-            module. This option is commonly used by distributions in order to
-            package up a Linux kernel module using module versioning deps.
-          </para>
+          <para>Show version of program and exit.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term><option>-b</option> <option>--use-blacklist</option>
+        <term><option>-v</option> <option>--verbose</option>
         </term>
         <listitem>
-	  <para>
-	    This option causes <command>modprobe</command> to apply the
-	    <command>blacklist</command> commands in the configuration files (if
-	    any) to module names as well.  It is usually used by <citerefentry>
-	    <refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum>
-	    </citerefentry>.
+          <para>
+	    Print messages about what the program is doing.  Usually
+	    <command>modprobe</command> only prints messages if
+	    something goes wrong.
 	  </para>
-        </listitem>
-      </varlistentry>
-      <varlistentry>
-        <term><option>-d</option> <option>--dirname</option>
-        </term>
-        <listitem>
           <para>
-            Directory where modules can be found, <filename>/lib/modules/<replaceable>RELEASE</replaceable></filename>
-            by default.
-          </para>
+	    This option is passed through <command>install</command>
+	    or <command>remove</command> commands to other
+	    <command>modprobe</command> commands in the
+	    MODPROBE_OPTIONS environment variable.
+	  </para>
         </listitem>
       </varlistentry>
     </variablelist>
@@ -451,7 +468,8 @@
   <refsect1>
     <title>COPYRIGHT</title>
     <para>
-      This manual page Copyright 2002, Rusty Russell, IBM Corporation.
+      This manual page originally Copyright 2002, Rusty Russell, IBM
+      Corporation. Maintained by Jon Masters and others.
     </para>
   </refsect1>
   <refsect1>
@@ -461,6 +479,15 @@
 	<refentrytitle>modprobe.conf</refentrytitle><manvolnum>5</manvolnum>
       </citerefentry>,
       <citerefentry>
+	<refentrytitle>modprobe.d</refentrytitle><manvolnum>5</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+	<refentrytitle>insmod</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+	<refentrytitle>rmmod</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citerefentry>
 	<refentrytitle>lsmod</refentrytitle><manvolnum>8</manvolnum>
       </citerefentry>,
       <citerefentry>
diff --git a/doc/modules.dep.bin.sgml b/doc/modules.dep.bin.sgml
new file mode 120000
index 0000000..c780257
--- /dev/null
+++ b/doc/modules.dep.bin.sgml
@@ -0,0 +1 @@
+modules.dep.sgml
\ No newline at end of file
diff --git a/doc/modules.dep.sgml b/doc/modules.dep.sgml
index e9a77ae..fa2591f 100644
--- a/doc/modules.dep.sgml
+++ b/doc/modules.dep.sgml
@@ -12,60 +12,49 @@
 <refentry>
   <refentryinfo>
     <address>
-      <email>rusty@rustcorp.com.au</email>
+      <email>jcm@jonmasters.org</email>
     </address>
     <author>
-      <firstname>Rusty</firstname>
-      <surname>Russell</surname>
+      <firstname>Jon</firstname>
+      <surname>Masters</surname>
     </author>
-    <date>2002-12-27</date>
+    <date>2010-03-01</date>
   </refentryinfo>
   <refmeta>
     <refentrytitle>modules.dep</refentrytitle>
     <manvolnum>5</manvolnum>
   </refmeta>
   <refnamediv>
-    <refname>modules.dep</refname> <refpurpose>List of module dependencies</refpurpose>
+    <refname>modules.dep.bin</refname><refname>modules.dep</refname> <refpurpose>Module dependency information</refpurpose>
   </refnamediv>
   <refsect1>
     <title>DESCRIPTION</title>
 
     <para>
-      The <filename>modules.dep</filename> as generated by
+      The <filename>modules.dep.bin</filename> as generated by
       module-init-tools <command>depmod</command>, lists the
       dependencies for every module in the directories under
       <filename>/lib/modules/</filename><replaceable>version</replaceable>,
-      where <filename>modules.dep</filename> is.
+      where <filename>modules.dep.bin</filename> (or the human readable
+      version <filename>modules.dep</filename>) is also located. It is
+      used by utilities such as <command>modprobe</command>. The
+      binary version will be used by default, if it was generated by
+      a compatible version of <command>depmod</commnd>, with fallback
+      to the generic <filename>modules.dep</filename>.
     </para>
     <para>
-      Blank lines, and lines starting with a '#' (ignoring spaces) are
-      ignored.  Other lines are of the form "filename: [filename]*",
-      listing the complete dependencies for the first filename in
-      descending order.
-    </para>
-    <para>
-      For example, if
-      <filename>/lib/modules/2.6.29/kernel/a.ko</filename> depended on
-      <filename>b.ko</filename> and <filename>c.ko</filename> in the
-      same directory, and <filename>c.ko</filename> depended on
-      <filename>b.ko</filename> as well, the file might look like:
-    </para>
-    <screen>
-# This is a comment.
-/lib/modules/2.6.29/kernel/a.ko: /lib/modules/2.6.29/kernel/c.ko /lib/modules/2.6.29/kernel/b.ko
-/lib/modules/2.6.29/kernel/b.ko:
-/lib/modules/2.6.29/kernel/c.ko: /lib/modules/2.6.29/kernel/b.ko
-    </screen>
-    <para>
-      This file is used by <command>modprobe</command> to know the
-      order in which to load modules (they are loaded right to left, and
-      removed left to right).
+      These files are not intended for editing or use by any additional
+      utilities as their format is subject to change in the future. You
+      should use the
+      <citerefentry><refentrytitle>modinfo</refentrytitle><manvolnum>8</manvolnum></citerefentry> command to obtain information about modules in a future
+      proof and compatible fashion rather than touching these files.
     </para>
   </refsect1>
   <refsect1>
     <title>COPYRIGHT</title>
     <para>
-      This manual page Copyright 2002, Rusty Russell, IBM Corporation.
+      This manual page originally Copyright 2002, Rusty Russell, IBM
+      Corporation. Maintained by Jon Masters and others.
     </para>
   </refsect1>
   <refsect1>
diff --git a/doc/rmmod.sgml b/doc/rmmod.sgml
index 1d975b2..bd009b7 100644
--- a/doc/rmmod.sgml
+++ b/doc/rmmod.sgml
@@ -12,13 +12,13 @@
 <refentry>
   <refentryinfo>
     <address>
-      <email>rusty@rustcorp.com.au</email>
+      <email>jcm@jonmasters.org</email>
     </address>
     <author>
-      <firstname>Rusty</firstname>
-      <surname>Russell</surname>
+      <firstname>Jon</firstname>
+      <surname>Masters</surname>
     </author>
-    <date>2002-12-27</date>
+    <date>2010-03-01</date>
   </refentryinfo>
   <refmeta>
     <refentrytitle>rmmod</refentrytitle>
@@ -41,7 +41,8 @@
     <title>DESCRIPTION</title>
 
     <para><command>rmmod</command> is a trivial program to remove a
-      module from the kernel.  Most users will want to use
+      module (when module unloading support is provided) from the kernel.
+      Most users will want to use
       <citerefentry>
 	<refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum>
       </citerefentry> with the <option>-r</option> option instead.
@@ -116,7 +117,8 @@
   <refsect1>
     <title>COPYRIGHT</title>
     <para>
-      This manual page Copyright 2002, Rusty Russell, IBM Corporation.
+      This manual page originally Copyright 2002, Rusty Russell, IBM
+      Corporation. Maintained by Jon Masters and others.
     </para>
   </refsect1>
   <refsect1>
@@ -132,6 +134,9 @@
       <citerefentry>
 	<refentrytitle>lsmod</refentrytitle><manvolnum>8</manvolnum>
       </citerefentry>
+      <citerefentry>
+	<refentrytitle>modinfo</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>
     </para>
   </refsect1>
 </refentry>