syncing up docs, examples, & packaging from 3.0

(This used to be commit dd1348c566b4700ea01bd89639e2d3330c878167)

1 files changed, 54 insertions, 58 deletions

diff --git a/docs/docbook/projdoc/Bugs.xml b/docs/docbook/projdoc/Bugs.xml
index 0688e23cf3..15bd14ac1a 100644
--- a/docs/docbook/projdoc/Bugs.xml
+++ b/docs/docbook/projdoc/Bugs.xml
@@ -1,8 +1,9 @@
 <chapter id="bugreport">
 
 <chapterinfo>
+	&author.jht;
 	&author.jelmer;
-	&author.tridge; <!-- This is mostly a guess -->
+	&author.tridge;
 	<pubdate> 27 June 1997 </pubdate>
 </chapterinfo>
 
@@ -11,79 +12,76 @@
 <sect1>
 <title>Introduction</title>
 
-<para>Please report bugs using
-	<ulink url="https://bugzilla.samba.org/">bugzilla</ulink>.</para>
-
-<para>
-Please take the time to read this file before you submit a bug
-report. Also, please see if it has changed between releases, as we
-may be changing the bug reporting mechanism at some time.
+<para>Please report bugs using Samba's
+<ulink url="https://bugzilla.samba.org/">Bugzilla</ulink> facilities and
+take the time to read this file before you submit a bug
+report. Also, check to see if it has changed between releases, as we
+may be changing the bug reporting mechanism at some point.
 </para>
 
 <para>
-Please also do as much as you can yourself to help track down the
+Please do as much as you can yourself to help track down the
 bug. Samba is maintained by a dedicated group of people who volunteer
-their time, skills and efforts. We receive far more mail about it than
-we can possibly answer, so you have a much higher chance of an answer
-and a fix if you send us a "developer friendly" bug report that lets
+their time, skills and efforts. We receive far more mail than
+we can possibly answer, so you have a much higher chance of a response
+and a fix if you send us a <quote>developer friendly</quote> bug report that lets
 us fix it fast. 
 </para>
 
 <para>
 Do not assume that if you post the bug to the comp.protocols.smb
 newsgroup or the mailing list that we will read it. If you suspect that your 
-problem is not a bug but a configuration problem then it is better to send 
-it to the Samba mailing list, as there are (at last count) 5000 other users on
-that list that may be able to help you.
+problem is not a bug but a configuration problem, it is better to send 
+it to the Samba mailing list, as there are thousands of other users on
+that list who may be able to help you.
 </para>
 
 <para>
 You may also like to look though the recent mailing list archives,
-which are conveniently accessible on the Samba web pages
+which are conveniently accessible on the Samba Web pages
 at <ulink noescape="1" url="http://samba.org/samba/">http://samba.org/samba/</ulink>.
 </para>
 
 </sect1>
 
 <sect1>
-<title>General info</title>
+<title>General Information</title>
 
 <para>
-Before submitting a bug report check your config for silly
-errors. Look in your log files for obvious messages that tell you that
-you've misconfigured something and run testparm to test your config
+Before submitting a bug report, check your config for silly
+errors. Look in your log files for obvious messages that tell
+you've misconfigured something. Run testparm to check your config
 file for correct syntax.
 </para>
 
 <para>
-Have you run through the <link linkend="diagnosis">diagnosis</link>? 
-This is very important.
+Have you looked through <link linkend="diagnosis"/>? This is extremely important.
 </para>
 
 <para>
-If you include part of a log file with your bug report then be sure to
+If you include part of a log file with your bug report, then be sure to
 annotate it with exactly what you were doing on the client at the
-time, and exactly what the results were.
+time and exactly what the results were.
 </para>
 
 </sect1>
 
 <sect1>
-<title>Debug levels</title>
+<title>Debug Levels</title>
 
 <para>
 If the bug has anything to do with Samba behaving incorrectly as a
-server (like refusing to open a file) then the log files will probably
-be very useful. Depending on the problem a log level of between 3 and
+server (like refusing to open a file), then the log files will probably
+be quite useful. Depending on the problem, a log level of between 3 and
 10 showing the problem may be appropriate. A higher level gives more
 detail, but may use too much disk space.
 </para>
 
 <para>
-To set the debug level use the <smbconfoption><name>log level</name></smbconfoption> in your 
+To set the debug level, use the <smbconfoption><name>log level</name></smbconfoption> in your 
 &smb.conf;. You may also find it useful to set the log 
 level higher for just one machine and keep separate logs for each machine. 
-To do this add the following lines to your main &smb.conf; file:
+To do this, add the following lines to your main &smb.conf; file:
 </para>
 
 <para><smbconfblock>
@@ -93,47 +91,46 @@ To do this add the following lines to your main &smb.conf; file:
 </smbconfblock></para>
 
 <para>
-then create a file 
-<filename>/usr/local/samba/lib/smb.conf.<replaceable>machine</replaceable></filename> where
+and create a file <filename>/usr/local/samba/lib/smb.conf.<replaceable>machine</replaceable></filename> where
 <replaceable>machine</replaceable> is the name of the client you wish to debug. In that file
 put any &smb.conf; commands you want, for example 
 <smbconfoption><name>log level</name></smbconfoption> may be useful. This also allows you to 
-experiment with different security systems, protocol levels etc on just 
+experiment with different security systems, protocol levels and so on, on just 
 one machine.
 </para>
 
 <para>
 The &smb.conf; entry <smbconfoption><name>log level</name></smbconfoption> 
 is synonymous with the parameter <smbconfoption><name>debuglevel</name></smbconfoption> that has
-been used in older versions of Samba and is being retained for backwards 
+been used in older versions of Samba and is being retained for backward 
 compatibility of &smb.conf; files.
 </para>
 
 <para>
-As the <smbconfoption><name>log level</name></smbconfoption> value is increased you will record 
-a significantly increasing level of debugging information. For most 
-debugging operations you may not need a setting higher than 
+As the <smbconfoption><name>log level</name></smbconfoption> value is increased, you will record 
+a significantly greater level of debugging information. For most 
+debugging operations, you may not need a setting higher than 
 <constant>3</constant>. Nearly 
 all bugs can be tracked at a setting of <constant>10</constant>, but be 
-prepared for a VERY large volume of log data.
+prepared for a large volume of log data.
 </para>
 
 </sect1>
 
 <sect1>
-<title>Internal errors</title>
+<title>Internal Errors</title>
 
 <para>
-If you get a <errorname>INTERNAL ERROR</errorname> message in your log files 
+If you get the message <quote><errorname>INTERNAL ERROR</errorname></quote> in your log files, 
 it means that Samba got an unexpected signal while running. It is probably a
 segmentation fault and almost certainly means a bug in Samba (unless
 you have faulty hardware or system software).
 </para>
 
 <para>
-If the message came from smbd then it will probably be accompanied by
-a message which details the last SMB message received by smbd. This
-info is often very useful in tracking down the problem so please
+If the message came from smbd, it will probably be accompanied by
+a message that details the last SMB message received by smbd. This
+information is often useful in tracking down the problem so please
 include it in your bug report.
 </para>
 
@@ -142,17 +139,17 @@ You should also detail how to reproduce the problem, if
 possible. Please make this reasonably detailed.
 </para>
 
-<indexterm><primary>core files</primary></indexterm>
 
 <para>
+<indexterm><primary>core files</primary></indexterm>
 You may also find that a core file appeared in a <filename>corefiles</filename>
-subdirectory of the directory where you keep your samba log
+subdirectory of the directory where you keep your Samba log
 files. This file is the most useful tool for tracking down the bug. To
-use it you do this:
-</para>
-
+use it, you do this:
 <indexterm><primary>gdb</primary></indexterm>
 <indexterm><primary>debug</primary></indexterm>
+</para>
+
 
 <screen>
 &prompt;<userinput>gdb smbd core</userinput>
@@ -160,29 +157,28 @@ use it you do this:
 
 <para>
 adding appropriate paths to smbd and core so gdb can find them. If you
-don't have gdb then try <userinput>dbx</userinput>. Then within the debugger
+do not have gdb, try <userinput>dbx</userinput>. Then within the debugger,
 use the command <command>where</command> to give a stack trace of where the
 problem occurred. Include this in your report.
 </para>
 
 <para>
-If you know any assembly language then do a 
-<command>disass</command> of the routine
-where the problem occurred (if its in a library routine then
+If you know any assembly language, do a <command>disass</command> of the routine
+where the problem occurred (if its in a library routine, then
 disassemble the routine that called it) and try to work out exactly
 where the problem is by looking at the surrounding code. Even if you
-don't know assembly, including this info in the bug report can be
+do not know assembly, including this information in the bug report can be
 useful. 
 </para>
 </sect1>
 
 <sect1>
-<title>Attaching to a running process</title>
+<title>Attaching to a Running Process</title>
 
 <para>
-Unfortunately some unixes (in particular some recent linux kernels)
+Unfortunately, some UNIXes (in particular some recent Linux kernels)
 refuse to dump a core file if the task has changed uid (which smbd
-does often). To debug with this sort of system you could try to attach
+does often). To debug with this sort of system, you could try to attach
 to the running process using
 <userinput>gdb smbd <replaceable>PID</replaceable></userinput> where you get
 <replaceable>PID</replaceable> from <application>smbstatus</application>.
@@ -196,12 +192,12 @@ where it occurred.
 <sect1>
 <title>Patches</title>
 
-<indexterm><primary>diff</primary></indexterm>
-<indexterm><primary>patch</primary></indexterm>
 
 <para>
+<indexterm><primary>diff</primary></indexterm>
+<indexterm><primary>patch</primary></indexterm>
 The best sort of bug report is one that includes a fix! If you send us
-patches please use <userinput>diff -u</userinput> format if your version of 
+patches, please use <userinput>diff -u</userinput> format if your version of 
 diff supports it, otherwise use <userinput>diff -c4</userinput>. Make sure 
 you do the diff against a clean version of the source and let me know 
 exactly what version you used.