Grammar, word, and phrasing updates as well as a few extra notes/tips here

and there regarding using a dumpdev/dumpdir to obtain crash information.

en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml

@@ -12,27 +12,28 @@
   <sect1 id="kerneldebug-obtain">
     <title>Obtaining a Kernel Crash Dump</title>
 
-    <para>When running a development kernel (eg: &os.current;), a
+    <para>When running a development kernel (eg: &os.current;), such as a
       kernel under extreme conditions (eg: very high load averages,
       tens of thousands of connections, exceedingly high number of
       concurrent users, hundreds of &man.jail.8;s, etc.), or using a
       new feature or device driver on &os.stable; (eg:
       <acronym>PAE</acronym>), sometimes a kernel will panic.  In the
-      event that it does, this chapter includes basic instructions for
+      event that it does, this chapter will demonstrate how to extract
-      extracting useful information out of a crash.</para>
+      useful information out of a crash.</para>
 
     <para>A system reboot is inevitable once a kernel panics.  Once a
       system is rebooted, the contents of a system's physical memory
       (<acronym>RAM</acronym>) is lost, as well as any bits that are
       on the swap device before the panic.  To preserve the bits in
       physical memory, the kernel makes use of the swap device as a
-      place to store the bits that are in physical memory that way
+      temporary place to store the bits that are in RAM across a
-      when the system reboots, a kernel image can be extracted and
+      reboot after a crash.  In doing this, when &os; boots after a
-      debugging can take place.</para>
+      crash, a kernel image can now be extracted and debugging can
+      take place.</para>
 
     <note><para>A swap device that has been configured as a dump
-      device still acts as a swap device.  Dumps to non-swap devices,
+      device still acts as a swap device.  Dumps to non-swap devices
-      tapes for example, are not supported at this time.  A
+      (such as tapes or CDRWs, for example) are not supported at this time.  A
       <quote>swap device</quote> is synonymous with a <quote>swap
       partition.</quote></para></note>
 
@@ -42,8 +43,7 @@
       reboots, the kernel is smart enough to check to see if a swap
       device has been configured as a dump device.  If there is a
       valid dump device, the kernel dumps the contents of what is in
-      physical memory to the swap device (assuming the swap device is
+      physical memory to the swap device.</para>
-      configured as a dump device).</para>
 
     <sect2 id="config-dumpdev">
       <title>Configuring the Dump Device</title>
@@ -55,13 +55,13 @@
 	&man.dumpon.8; program must be called after the swap partition
 	has been configured with &man.swapon.8;.  This is normally
 	handled by setting the <varname>dumpdev</varname> variable in
-	&man.rc.conf.5; to the path of the swap device.</para>
+	&man.rc.conf.5; to the path of the swap device (the
+	recommended way to extract a kernel dump).</para>
 
-      <para>Alternatively, you can hard-code the dump device via the
+      <para>Alternatively, the dump device can be hard-coded via the
-	<literal>dump</literal> clause in the <literal>config</literal> line of
+	<literal>dump</literal> clause in the &man.config.5; line of
-	your kernel configuration file.  This approach is deprecated and should
+	a kernel configuration file.  This approach is deprecated and should
-	be used only if you want a crash dump from a kernel that crashes during
+	be used only if a kernel is crashing before &man.dumpon.8; can be executed.</para>
-	booting.</para>
 
       <tip><para>Check <filename>/etc/fstab</filename> or
 	&man.swapinfo.8; for a list of swap devices.</para></tip>
@@ -70,7 +70,12 @@
         specified in &man.rc.conf.5; exists before a kernel
         crash!</para>
 
-        <screen>&prompt.root; <userinput>mkdir /var/crash</userinput></screen>
+        <screen>&prompt.root; <userinput>mkdir /var/crash</userinput>
+&prompt.root; <userinput>chmod 700 /var/crash</userinput></screen>
+
+        <para>Also, remember that the contents of
+	  <filename>/var/crash</filename> is sensitive and very likely
+	  contains confidential information such as passwords.</para>
       </important>
     </sect2>
 
@@ -78,15 +83,28 @@
       <title>Extracting a Kernel Dump</title>
 
         <para>Once a dump has been written to a dump device, the dump
-	  must be extracted before the swap device is mounted,
+	  must be extracted before the swap device is mounted.
-	  otherwise the dump will be corrupted.  To extract a dump
+	  To extract a dump
 	  from a dump device, use the &man.savecore.8; program.  If
 	  <varname>dumpdev</varname> has been set in &man.rc.conf.5;,
 	  &man.savecore.8; will be called automatically on the first
 	  multi-user boot after the crash and before the swap device
 	  is mounted.  The location of the extracted core is placed in
 	  the &man.rc.conf.5; value <varname>dumpdir</varname>, by
-	  default <filename>/var/crash</filename>.</para>
+	  default <filename>/var/crash</filename> and will be named
+	  <filename>vmcore.0</filename>.</para>
+
+        <para>In the event that there is already a file called
+          <filename>vmcore.0</filename> in
+          <filename>/var/crash</filename> (or whatever
+          <varname>dumpdev</varname> is set to), the kernel will
+          increment the trailing number for every crash to avoid
+          overwriting an existing <filename>vmcore</filename> (eg:
+          <filename>vmcore.1</filename>).  While debugging, it is
+          highly likely that you will want to use the highest version
+          <filename>vmcore</filename> in
+          <filename>/var/crash</filename> when searching for the right
+          <filename>vmcore</filename>.</para>
 
     <tip>
       <para>If you are testing a new kernel but need to boot a different one in
@@ -103,14 +121,13 @@
       from <filename>/dev/ad0s1b</filename> and place the contents in
       <filename>/var/crash</filename>.  Don't forget to make sure the
       destination directory <filename>/var/crash</filename> has enough
-      space for the dump or to specify the correct path to your swap
+      space for the dump.  Also, don't forget to specify the correct path to your swap
       device as it is likely different than
       <filename>/dev/ad0s1b</filename>!</para></tip>
 
-      <para>The recommended and certainly easiest way to automate
+      <para>The recommended, and certainly the easiest way to automate
         obtaining crash dumps is to use the <varname>dumpdev</varname>
         variable in &man.rc.conf.5;.</para>
-
     </sect2>
   </sect1>
 
@@ -123,8 +140,10 @@
       the crash dump, locate the debug version of your kernel
       (normally called <filename>kernel.debug</filename>) and the path
       to the source files used to build your kernel (normally
-      <filename>/usr/obj/usr/src/sys/KERNCONF</filename>).  With those
+      <filename>/usr/obj/usr/src/sys/KERNCONF</filename>, where
-      two pieces of info, let the debugging commence!
+      <filename>KERNCONF</filename> is the <varname>ident</varname>
+      specified in a kernel &man.config.5;).  With those two pieces of
+      info, let the debugging commence!
 
       <screen>&prompt.root; <userinput>cd /usr/obj/usr/src/sys/KERNCONF</userinput>
 &prompt.root; <userinput>gdb -k /boot/kernel/kernel.debug /var/crash/vmcore.0</userinput></screen>
@@ -277,6 +296,11 @@
 	</listitem>
       </varlistentry>
     </variablelist>
+
+    <tip><para>If your system is crashing regularly and you're running
+      out of disk space, deleting old <filename>vmcore</filename>
+      files in <filename>/var/crash</filename> could save a
+      considerable amount of disk space!</para></tip>
   </sect1>
 
   <sect1 id="kerneldebug-ddd">