Large number of updates - new structure of the HOWTO, better names, introductions, updating to 3.0

(This used to be commit dfc3d55493c40201244a9e44b89868f7128c6f85)

8 files changed, 472 insertions, 531 deletions

diff --git a/docs/docbook/projdoc/ADS-HOWTO.sgml b/docs/docbook/projdoc/ADS-HOWTO.sgml
index 0d2fda5f78c..83bb2dc85d3 100644
--- a/docs/docbook/projdoc/ADS-HOWTO.sgml
+++ b/docs/docbook/projdoc/ADS-HOWTO.sgml
@@ -7,7 +7,7 @@
 	<pubdate>2002</pubdate>
 </chapterinfo>
 
-<title>Using samba 3.0 with ActiveDirectory support</title>
+<title>Samba as a ADS domain member</title>
 
 <para>
 This is a VERY ROUGH guide to setting up the current (November 2001)
diff --git a/docs/docbook/projdoc/Browsing.sgml b/docs/docbook/projdoc/Browsing.sgml
index a463ea786b4..13d6fce9179 100644
--- a/docs/docbook/projdoc/Browsing.sgml
+++ b/docs/docbook/projdoc/Browsing.sgml
@@ -461,7 +461,7 @@ all smb.conf files :
 </para>
 
 <para>
-<command>		wins server = &gt;name or IP address&lt;</command>
+<command>wins server = &gt;name or IP address&lt;</command>
 </para>
 
 <para>
@@ -512,7 +512,7 @@ set the following option in the [global] section of the smb.conf file :
 </para>
 
 <para>
-<command>		domain master = yes</command>
+<command>domain master = yes</command>
 </para>
 
 <para>
diff --git a/docs/docbook/projdoc/DOMAIN_MEMBER.sgml b/docs/docbook/projdoc/DOMAIN_MEMBER.sgml
index 6d0b36eafcc..8bb64dbf50e 100644
--- a/docs/docbook/projdoc/DOMAIN_MEMBER.sgml
+++ b/docs/docbook/projdoc/DOMAIN_MEMBER.sgml
@@ -25,7 +25,7 @@
 </chapterinfo>
 
 
-<title>security = domain in Samba 2.x</title>
+<title>Samba as a NT4 domain member</title>
 
 <sect1>
 
diff --git a/docs/docbook/projdoc/Printing.sgml b/docs/docbook/projdoc/Printing.sgml
deleted file mode 100644
index ce9f40e88bf..00000000000
--- a/docs/docbook/projdoc/Printing.sgml
+++ /dev/null
@@ -1,398 +0,0 @@
-<chapter id="printingdebug">
-<chapterinfo>
-	<author>
-		<firstname>Patrick</firstname><surname>Powell</surname>
-		<affiliation>
-			<address><email>papowell@lprng.org</email></address>
-		</affiliation>
-	</author>
-	<pubdate>11 August 2000</pubdate>
-</chapterinfo>
-
-<title>Debugging Printing Problems</title>
-
-<sect1>
-<title>Introduction</title>
-
-<para>
-This is a short description of how to debug printing problems with
-Samba. This describes how to debug problems with printing from a SMB
-client to a Samba server, not the other way around. For the reverse
-see the examples/printing directory.
-</para>
-
-<para>
-Ok, so you want to print to a Samba server from your PC. The first
-thing you need to understand is that Samba does not actually do any
-printing itself, it just acts as a middleman between your PC client
-and your Unix printing subsystem. Samba receives the file from the PC
-then passes the file to a external "print command". What print command
-you use is up to you.
-</para>
-
-<para>
-The whole things is controlled using options in smb.conf. The most
-relevant options (which you should look up in the smb.conf man page)
-are:
-</para>
-
-<para><programlisting>
-      [global]
-        print command     - send a file to a spooler
-        lpq command       - get spool queue status
-        lprm command      - remove a job
-      [printers]
-        path = /var/spool/lpd/samba
-</programlisting></para>
-
-<para>
-The following are nice to know about:
-</para>
-
-<para><programlisting>
-        queuepause command   - stop a printer or print queue
-        queueresume command  - start a printer or print queue
-</programlisting></para>
-
-<para>
-Example:
-</para>
-
-<para><programlisting>
-        print command = /usr/bin/lpr -r -P%p %s
-        lpq command   = /usr/bin/lpq    -P%p %s
-        lprm command  = /usr/bin/lprm   -P%p %j
-        queuepause command = /usr/sbin/lpc -P%p stop
-        queuepause command = /usr/sbin/lpc -P%p start
-</programlisting></para>
-
-<para>
-Samba should set reasonable defaults for these depending on your
-system type, but it isn't clairvoyant. It is not uncommon that you
-have to tweak these for local conditions.  The commands should
-always have fully specified pathnames,  as the smdb may not have
-the correct PATH values.
-</para>
-
-<para>
-When you send a job to Samba to be printed,  it will make a temporary
-copy of it in the directory specified in the [printers] section.
-and it should be periodically cleaned out.  The lpr -r option
-requests that the temporary copy be removed after printing; If
-printing fails then you might find leftover files in this directory,
-and it should be periodically cleaned out.  Samba used the lpq
-command to determine the "job number" assigned to your print job
-by the spooler.
-</para>
-
-<para>
-The %&gt;letter&lt; are "macros" that get dynamically replaced with appropriate
-values when they are used. The %s gets replaced with the name of the spool
-file that Samba creates and the %p gets replaced with the name of the
-printer. The %j gets replaced with the "job number" which comes from
-the lpq output.
-</para>
-
-</sect1>
-
-<sect1>
-<title>Debugging printer problems</title>
-
-<para>
-One way to debug printing problems is to start by replacing these
-command with shell scripts that record the arguments and the contents
-of the print file. A simple example of this kind of things might
-be:
-</para>
-
-<para><programlisting>
-	print command = /tmp/saveprint %p %s
-
-    #!/bin/saveprint
-    # we make sure that we are the right user
-    /usr/bin/id -p >/tmp/tmp.print
-    # we run the command and save the error messages
-    # replace the command with the one appropriate for your system
-    /usr/bin/lpr -r -P$1 $2 2>>&/tmp/tmp.print
-</programlisting></para>
-
-<para>
-Then you print a file and try removing it.  You may find that the
-print queue needs to be stopped in order to see the queue status
-and remove the job:
-</para>
-
-<para><programlisting>
-
-h4: {42} % echo hi >/tmp/hi
-h4: {43} % smbclient //localhost/lw4
-added interface ip=10.0.0.4 bcast=10.0.0.255 nmask=255.255.255.0
-Password: 
-Domain=[ASTART] OS=[Unix] Server=[Samba 2.0.7]
-smb: \> print /tmp/hi
-putting file /tmp/hi as hi-17534 (0.0 kb/s) (average 0.0 kb/s)
-smb: \> queue
-1049     3            hi-17534
-smb: \> cancel 1049
-Error cancelling job 1049 : code 0
-smb: \> cancel 1049
-Job 1049 cancelled
-smb: \> queue
-smb: \> exit
-</programlisting></para>
-
-<para>
-The 'code 0' indicates that the job was removed.  The comment
-by the  smbclient is a bit misleading on this.
-You can observe the command output and then and look at the
-/tmp/tmp.print file to see what the results are.  You can quickly
-find out if the problem is with your printing system.  Often people
-have problems with their /etc/printcap file or permissions on
-various print queues.
-</para>
-</sect1>
-
-<sect1>
-<title>What printers do I have?</title>
-
-<para>
-You can use the 'testprns' program to check to see if the printer
-name you are using is recognized by Samba.  For example,  you can
-use:
-</para>
-
-<para><programlisting>
-    testprns printer /etc/printcap
-</programlisting></para>
-
-<para>
-Samba can get its printcap information from a file or from a program.
-You can try the following to see the format of the extracted
-information:
-</para>
-
-<para><programlisting>
-    testprns -a printer /etc/printcap
-
-    testprns -a printer '|/bin/cat printcap'
-</programlisting></para>
-
-</sect1>
-
-<sect1>
-<title>Setting up printcap and print servers</title>
-
-<para>
-You may need to set up some printcaps for your Samba system to use.
-It is strongly recommended that you use the facilities provided by
-the print spooler to set up queues and printcap information.
-</para>
-
-<para>
-Samba requires either a printcap or program to deliver printcap
-information.  This printcap information has the format:
-</para>
-
-<para><programlisting>
-  name|alias1|alias2...:option=value:...
-</programlisting></para>
-
-<para>
-For almost all printing systems, the printer 'name' must be composed
-only of alphanumeric or underscore '_' characters.  Some systems also
-allow hyphens ('-') as well.  An alias is an alternative name for the
-printer,  and an alias with a space in it is used as a 'comment'
-about the printer.  The printcap format optionally uses a \ at the end of lines
-to extend the printcap to multiple lines.
-</para>
-
-<para>
-Here are some examples of printcap files:
-</para>
-
-<para>
-<orderedlist>
-<listitem><para>
-pr              just printer name
-</para></listitem>
-<listitem><para>
-pr|alias        printer name and alias
-</para></listitem>
-<listitem><para>
-pr|My Printer   printer name, alias used as comment
-</para></listitem>
-<listitem><para>
-pr:sh:\        Same as pr:sh:cm= testing
-  :cm= \ 
-  testing
-</para></listitem>
-<listitem><para>
-pr:sh           Same as pr:sh:cm= testing
-  :cm= testing
-</para></listitem>
-</orderedlist>
-</para>
-
-<para>
-Samba reads the printcap information when first started.  If you make
-changes in the printcap information, then you must do the following:
-</para>
-
-<orderedlist>
-
-<listitem><para>
-make sure that the print spooler is aware of these changes.
-The LPRng system uses the 'lpc reread' command to do this.
-</para></listitem>
-
-<listitem><para>
-make sure that the spool queues, etc., exist and have the
-correct permissions.  The LPRng system uses the 'checkpc -f'
-command to do this.
-</para></listitem>
-
-<listitem><para>
-You now should send a SIGHUP signal to the smbd server to have
-it reread the printcap information.
-</para></listitem>
-</orderedlist>
-
-</sect1>
-
-<sect1>
-<title>Job sent, no output</title>
-
-<para>
-This is the most frustrating part of printing.  You may have sent the
-job,  verified that the job was forwarded,  set up a wrapper around
-the command to send the file,  but there was no output from the printer.
-</para>
-
-<para>
-First,  check to make sure that the job REALLY is getting to the
-right print queue.  If you are using a BSD or LPRng print spooler,
-you can temporarily stop the printing of jobs.  Jobs can still be
-submitted, but they will not be printed.  Use:
-</para>
-
-<para><programlisting>
-  lpc -Pprinter stop
-</programlisting></para>
-
-<para>
-Now submit a print job and then use 'lpq -Pprinter' to see if the
-job is in the print queue.  If it is not in the print queue then
-you will have to find out why it is not being accepted for printing.
-</para>
-
-<para>
-Next, you may want to check to see what the format of the job really
-was.  With the assistance of the system administrator you can view
-the submitted jobs files.  You may be surprised to find that these
-are not in what you would expect to call a printable format.
-You can use the UNIX 'file' utitily to determine what the job
-format actually is:
-</para>
-
-<para><programlisting>
-    cd /var/spool/lpd/printer   # spool directory of print jobs
-    ls                          # find job files
-    file dfA001myhost
-</programlisting></para>
-
-<para>
-You should make sure that your printer supports this format OR that
-your system administrator has installed a 'print filter' that will
-convert the file to a format appropriate for your printer.
-</para>
-
-</sect1>
-
-<sect1>
-<title>Job sent, strange output</title>
-
-<para>
-Once you have the job printing, you can then start worrying about
-making it print nicely.
-</para>
-
-<para>
-The most common problem is extra pages of output: banner pages
-OR blank pages at the end.
-</para>
-
-<para>
-If you are getting banner pages,  check and make sure that the
-printcap option or printer option is configured for no banners.
-If you have a printcap,  this is the :sh (suppress header or banner
-page) option.  You should have the following in your printer.
-</para>
-
-<para><programlisting>
-   printer: ... :sh
-</programlisting></para>
-
-<para>
-If you have this option and are still getting banner pages,  there
-is a strong chance that your printer is generating them for you
-automatically.  You should make sure that banner printing is disabled
-for the printer.  This usually requires using the printer setup software
-or procedures supplied by the printer manufacturer.
-</para>
-
-<para>
-If you get an extra page of output,  this could be due to problems
-with your job format,  or if you are generating PostScript jobs,
-incorrect setting on your printer driver on the MicroSoft client.
-For example, under Win95 there is a option:
-</para>
-
-<para><programlisting>
-  Printers|Printer Name|(Right Click)Properties|Postscript|Advanced|
-</programlisting></para>
-
-<para>
-that allows you to choose if a Ctrl-D is appended to all jobs.
-This is a very bad thing to do, as most spooling systems will
-automatically add a ^D to the end of the job if it is detected as
-PostScript.  The multiple ^D may cause an additional page of output.
-</para>
-
-</sect1>
-
-<sect1>
-<title>Raw PostScript printed</title>
-
-<para>
-This is a problem that is usually caused by either the print spooling
-system putting information at the start of the print job that makes
-the printer think the job is a text file, or your printer simply
-does not support PostScript.  You may need to enable 'Automatic
-Format Detection' on your printer.
-</para>
-
-</sect1>
-
-<sect1>
-<title>Advanced Printing</title>
-
-<para>
-Note that you can do some pretty magic things by using your
-imagination with the "print command" option and some shell scripts.
-Doing print accounting is easy by passing the %U option to a print
-command shell script. You could even make the print command detect
-the type of output and its size and send it to an appropriate
-printer.
-</para>
-
-</sect1>
-
-<sect1>
-<title>Real debugging</title>
-
-<para>
-If the above debug tips don't help, then maybe you need to bring in
-the bug guns, system tracing. See Tracing.txt in this directory.
-</para>
-</sect1>
-</chapter>
diff --git a/docs/docbook/projdoc/Samba-PDC-HOWTO.sgml b/docs/docbook/projdoc/Samba-PDC-HOWTO.sgml
index 25a9783277b..7cf3e5735c3 100644
--- a/docs/docbook/projdoc/Samba-PDC-HOWTO.sgml
+++ b/docs/docbook/projdoc/Samba-PDC-HOWTO.sgml
@@ -19,7 +19,7 @@
 </chapterinfo>
 
 <title>
-How to Configure Samba 2.2 as a Primary Domain Controller
+How to Configure Samba as a NT4 Primary Domain Controller
 </title>
 
 
diff --git a/docs/docbook/projdoc/UNIX_INSTALL.sgml b/docs/docbook/projdoc/UNIX_INSTALL.sgml
index c307636d5fa..1ff735a6568 100644
--- a/docs/docbook/projdoc/UNIX_INSTALL.sgml
+++ b/docs/docbook/projdoc/UNIX_INSTALL.sgml
@@ -3,15 +3,17 @@
 <title>How to Install and Test SAMBA</title>
 
 <sect1>
-	<title>Step 0: Read the man pages</title>
+	<title>Read the man pages</title>
 	
 	<para>The man pages distributed with SAMBA contain 
 	lots of useful info that will help to get you started. 
 	If you don't know how to read man pages then try 
 	something like:</para>
 
-	<para><prompt>$ </prompt><userinput>nroff -man smbd.8 | more
-	</userinput></para>
+	<para><prompt>$ </prompt><userinput>man smbd.8</userinput>
+	or 
+	<prompt>$ </prompt><userinput>nroff -man smbd.8 | more
+	</userinput> on older unixes.</para>
 	
 	<para>Other sources of information are pointed to 
 	by the Samba web site,<ulink url="http://www.samba.org/">
@@ -19,7 +21,7 @@
 </sect1>
 
 <sect1>
-	<title>Step 1: Building the Binaries</title>
+	<title>Building the Binaries</title>
 	
 	<para>To do this, first run the program <command>./configure
 	</command> in the source directory. This should automatically 
@@ -62,7 +64,7 @@
 </sect1>
 
 <sect1>
-	<title>Step 2: The all important step</title>
+	<title>The all important step</title>
 	
 	<para>At this stage you must fetch yourself a 
 	coffee or other drink you find stimulating. Getting the rest 
@@ -74,7 +76,7 @@
 </sect1>
 
 <sect1>
-	<title>Step 3: Create the smb configuration file. </title>
+	<title>Create the smb configuration file. </title>
 
 	<para>There are sample configuration files in the examples 
 	subdirectory in the distribution. I suggest you read them 
@@ -91,7 +93,7 @@
 	   [homes]
 	      guest ok = no
 	      read only = no
-	</programlisting</para>
+	</programlisting></para>
 	
 	<para>which would allow connections by anyone with an 
 	account on the server, using either their login name or 
@@ -111,7 +113,7 @@
 </sect1>
 
 <sect1>
-	<title>Step 4: Test your config file with 
+	<title>Test your config file with 
 	<command>testparm</command></title>
 
 	<para>It's important that you test the validity of your
@@ -122,10 +124,13 @@
 	<para>Make sure it runs OK and that the services look 
 	reasonable before proceeding. </para>
 
+	<para>Always run testparm again when you change 
+	<filename>smb.conf</filename>!</para>
+
 </sect1>
 
 <sect1>
-	<title>Step 5: Starting the smbd and nmbd</title>
+	<title>Starting the smbd and nmbd</title>
 
 	<para>You must choose to start smbd and nmbd either
 	as daemons or from <command>inetd</command>. Don't try
@@ -144,7 +149,7 @@
 	request.</para>
 
 	<sect2>
-		<title>Step 5a: Starting from inetd.conf</title>
+		<title>Starting from inetd.conf</title>
 
 		<para>NOTE; The following will be different if 
 		you use NIS or NIS+ to distributed services maps.</para>
@@ -196,7 +201,7 @@
 	</sect2>
 	
 	<sect2>
-		<title>Step 5b. Alternative: starting it as a daemon</title>
+		<title>Alternative: starting it as a daemon</title>
 
 		<para>To start the server as a daemon you should create 
 		a script something like this one, perhaps calling 
@@ -225,7 +230,7 @@
 </sect1>
 
 <sect1>
-	<title>Step 6: Try listing the shares available on your 
+	<title>Try listing the shares available on your 
 	server</title>
 
 	<para><prompt>$ </prompt><userinput>smbclient -L 
@@ -245,7 +250,7 @@
 </sect1>
 
 <sect1>
-	<title>Step 7: Try connecting with the unix client</title>
+	<title>Try connecting with the unix client</title>
 	
 	<para><prompt>$ </prompt><userinput>smbclient <replaceable>
 	//yourhostname/aservice</replaceable></userinput></para>
@@ -265,7 +270,7 @@
 </sect1>
 
 <sect1>
-	<title>Step 8: Try connecting from a DOS, WfWg, Win9x, WinNT, 
+	<title>Try connecting from a DOS, WfWg, Win9x, WinNT, 
 	Win2k, OS/2, etc... client</title>
 	
 	<para>Try mounting disks. eg:</para>
@@ -305,8 +310,8 @@
 	<sect2>
 		<title>Diagnosing Problems</title>
 
-		<para>If you have installation problems then go to 
-		<filename>DIAGNOSIS.txt</filename> to try to find the 
+		<para>If you have installation problems then go to the
+		<ulink url="Diagnosis.html">Diagnosis</ulink> chapter to try to find the 
 		problem.</para>
 	</sect2>
 	
@@ -424,6 +429,8 @@
 		its open. A client may ask for DENY_NONE, DENY_READ, DENY_WRITE 
 		or DENY_ALL. There are also special compatibility modes called 
 		DENY_FCB and  DENY_DOS.</para>
+
+		<!-- FIXME: Sync this with oplocks.sgml -->
 	</sect2>
 	
 	<sect2>
diff --git a/docs/docbook/projdoc/printer_driver2.sgml b/docs/docbook/projdoc/printer_driver2.sgml
index 85ae0713b39..7bca8dc6f57 100644
--- a/docs/docbook/projdoc/printer_driver2.sgml
+++ b/docs/docbook/projdoc/printer_driver2.sgml
@@ -11,12 +11,16 @@
 			</address>
 		</affiliation>
 	</author>
-	
-		
+	<author>
+		<firstname>Patrick</firstname><surname>Powell</surname>
+		<affiliation>
+			<address><email>papowell@lprng.org</email></address>
+		</affiliation>
+	</author>
 	<pubdate> (3 May 2001) </pubdate>
 </chapterinfo>
 
-<title>Printing Support in Samba 2.2.x</title>
+<title>Printing Support</title>
 
 <sect1>
 <title>Introduction</title>
@@ -59,12 +63,7 @@ SPOOLSS support includes:</para>
 There has been some initial confusion about what all this means
 and whether or not it is a requirement for printer drivers to be 
 installed on a Samba host in order to support printing from Windows 
-clients.  A bug existed in Samba 2.2.0 which made Windows NT/2000 clients 
-require that the Samba server possess a valid driver for the printer.  
-This is fixed in Samba 2.2.1 and once again, Windows NT/2000 clients
-can use the local APW for installing drivers to be used with a Samba 
-served printer.  This is the same behavior exhibited by Windows 9x clients.
-As a side note, Samba does not use these drivers in any way to process 
+clients. As a side note, Samba does not use these drivers in any way to process 
 spooled files.  They are utilized entirely by the clients.
 </para>
 
@@ -104,16 +103,9 @@ parameter named <parameter>printer driver</parameter> provided
 a means of defining the printer driver name to be sent to 
 the client.
 </para>
- 
-<para>
-These parameters, including <parameter>printer driver
-file</parameter> parameter, are being deprecated and should not 
-be used in new installations.  For more information on this change, 
-you should refer to the <link linkend="MIGRATION">Migration section</link>
-of this document.
-</para>
-</warning>
 
+</warning>
+ 
 <sect2>
 <title>Creating [print$]</title>	
 
@@ -243,10 +235,8 @@ that matches the printer shares defined on your Samba host.
 
 <para>The initial listing of printers in the Samba host's 
 Printers folder will have no real printer driver assigned 
-to them.  By default, in Samba 2.2.0 this driver name was set to 
-<emphasis>NO PRINTER DRIVER AVAILABLE FOR THIS PRINTER</emphasis>.
-Later versions changed this to a NULL string to allow the use
-tof the local Add Printer Wizard on NT/2000 clients.
+to them. This defaults to a NULL string to allow the use
+of the local Add Printer Wizard on NT/2000 clients.
 Attempting to view the printer properties for a printer
 which has this default driver assigned will result in 
 the error message:</para>
@@ -603,84 +593,6 @@ foreach (supported architecture for a given driver)
 	
 </sect1>
 
-
-<sect1>
-<title><anchor id="MIGRATION">Migration to from Samba 2.0.x to 2.2.x</title>
-
-<para>
-Given that printer driver management has changed (we hope improved) in 
-2.2 over prior releases, migration from an existing setup to 2.2 can 
-follow several paths. Here are the possible scenarios for 
-migration:
-</para>
-
-<itemizedlist>
-	<listitem><para>If you do not desire the new Windows NT 
-	print driver support, nothing needs to be done.  
-	All existing parameters work the same.</para></listitem>
-
-	<listitem><para>If you want to take advantage of NT printer 
-	driver support but do not want to migrate the 
-	9x drivers to the new setup, the leave the existing 
-	<filename>printers.def</filename> file.  When smbd attempts 
-	to locate a 
-	9x driver for the printer in the TDB and fails it 
-	will drop down to using the printers.def (and all 
-	associated parameters).  The <command>make_printerdef</command> 
-	tool will also remain for backwards compatibility but will 
-	be removed in the next major release.</para></listitem>
-
-	<listitem><para>If you install a Windows 9x driver for a printer 
-	on your Samba host (in the printing TDB), this information will 
-	take precedence and the three old printing parameters
-	will be ignored (including print driver location).</para></listitem>
-
-	<listitem><para>If you want to migrate an existing <filename>printers.def</filename> 
-	file into the new setup, the current only solution is to use the Windows 
-	NT APW to install the NT drivers and the 9x  drivers.  This can be scripted 
-	using <command>smbclient</command> and <command>rpcclient</command>.  See the 
-	Imprints installation client at <ulink 
-	url="http://imprints.sourceforge.net/">http://imprints.sourceforge.net/</ulink> 
-	for an example.
-	</para></listitem>
-</itemizedlist>
-
-
-<warning>
-<title>Achtung!</title>
-
-<para>
-The following <filename>smb.conf</filename> parameters are considered to 
-be deprecated and will be removed soon.  Do not use them in new 
-installations
-</para>
-		
-<itemizedlist>
-	<listitem><para><parameter>printer driver file (G)</parameter>
-	</para></listitem>
-			
-	<listitem><para><parameter>printer driver (S)</parameter>
-	</para></listitem>
-			
-	<listitem><para><parameter>printer driver location (S)</parameter>
-	</para></listitem>
-</itemizedlist>
-</warning>
-
-
-<para>
-The have been two new parameters add in Samba 2.2.2 to for 
-better support of Samba 2.0.x backwards capability (<parameter>disable
-spoolss</parameter>) and for using local printers drivers on Windows 
-NT/2000 clients (<parameter>use client driver</parameter>). Both of 
-these options are described in the smb.coinf(5) man page and are 
-disabled by default.
-</para>
-
-
-</sect1>
-
-
 <!--
 
   This comment from rpc_server/srv_spoolss_nt.c:_spoolss_open_printer_ex()
@@ -740,4 +652,393 @@ disabled by default.
                  * on the Advanced Tab of the printer properties window.
 -->
 
+<sect1>
+<title>Diagnosis</title>
+
+<sect2>
+<title>Introduction</title>
+
+<para>
+This is a short description of how to debug printing problems with
+Samba. This describes how to debug problems with printing from a SMB
+client to a Samba server, not the other way around. For the reverse
+see the examples/printing directory.
+</para>
+
+<para>
+Ok, so you want to print to a Samba server from your PC. The first
+thing you need to understand is that Samba does not actually do any
+printing itself, it just acts as a middleman between your PC client
+and your Unix printing subsystem. Samba receives the file from the PC
+then passes the file to a external "print command". What print command
+you use is up to you.
+</para>
+
+<para>
+The whole things is controlled using options in smb.conf. The most
+relevant options (which you should look up in the smb.conf man page)
+are:
+</para>
+
+<para><programlisting>
+      [global]
+        print command     - send a file to a spooler
+        lpq command       - get spool queue status
+        lprm command      - remove a job
+      [printers]
+        path = /var/spool/lpd/samba
+</programlisting></para>
+
+<para>
+The following are nice to know about:
+</para>
+
+<para><programlisting>
+        queuepause command   - stop a printer or print queue
+        queueresume command  - start a printer or print queue
+</programlisting></para>
+
+<para>
+Example:
+</para>
+
+<para><programlisting>
+        print command = /usr/bin/lpr -r -P%p %s
+        lpq command   = /usr/bin/lpq    -P%p %s
+        lprm command  = /usr/bin/lprm   -P%p %j
+        queuepause command = /usr/sbin/lpc -P%p stop
+        queuepause command = /usr/sbin/lpc -P%p start
+</programlisting></para>
+
+<para>
+Samba should set reasonable defaults for these depending on your
+system type, but it isn't clairvoyant. It is not uncommon that you
+have to tweak these for local conditions.  The commands should
+always have fully specified pathnames,  as the smdb may not have
+the correct PATH values.
+</para>
+
+<para>
+When you send a job to Samba to be printed,  it will make a temporary
+copy of it in the directory specified in the [printers] section.
+and it should be periodically cleaned out.  The lpr -r option
+requests that the temporary copy be removed after printing; If
+printing fails then you might find leftover files in this directory,
+and it should be periodically cleaned out.  Samba used the lpq
+command to determine the "job number" assigned to your print job
+by the spooler.
+</para>
+
+<para>
+The %&gt;letter&lt; are "macros" that get dynamically replaced with appropriate
+values when they are used. The %s gets replaced with the name of the spool
+file that Samba creates and the %p gets replaced with the name of the
+printer. The %j gets replaced with the "job number" which comes from
+the lpq output.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Debugging printer problems</title>
+
+<para>
+One way to debug printing problems is to start by replacing these
+command with shell scripts that record the arguments and the contents
+of the print file. A simple example of this kind of things might
+be:
+</para>
+
+<para><programlisting>
+	print command = /tmp/saveprint %p %s
+
+    #!/bin/saveprint
+    # we make sure that we are the right user
+    /usr/bin/id -p >/tmp/tmp.print
+    # we run the command and save the error messages
+    # replace the command with the one appropriate for your system
+    /usr/bin/lpr -r -P$1 $2 2>>&/tmp/tmp.print
+</programlisting></para>
+
+<para>
+Then you print a file and try removing it.  You may find that the
+print queue needs to be stopped in order to see the queue status
+and remove the job:
+</para>
+
+<para><programlisting>
+
+h4: {42} % echo hi >/tmp/hi
+h4: {43} % smbclient //localhost/lw4
+added interface ip=10.0.0.4 bcast=10.0.0.255 nmask=255.255.255.0
+Password: 
+Domain=[ASTART] OS=[Unix] Server=[Samba 2.0.7]
+smb: \> print /tmp/hi
+putting file /tmp/hi as hi-17534 (0.0 kb/s) (average 0.0 kb/s)
+smb: \> queue
+1049     3            hi-17534
+smb: \> cancel 1049
+Error cancelling job 1049 : code 0
+smb: \> cancel 1049
+Job 1049 cancelled
+smb: \> queue
+smb: \> exit
+</programlisting></para>
+
+<para>
+The 'code 0' indicates that the job was removed.  The comment
+by the  smbclient is a bit misleading on this.
+You can observe the command output and then and look at the
+/tmp/tmp.print file to see what the results are.  You can quickly
+find out if the problem is with your printing system.  Often people
+have problems with their /etc/printcap file or permissions on
+various print queues.
+</para>
+</sect2>
+
+<sect2>
+<title>What printers do I have?</title>
+
+<para>
+You can use the 'testprns' program to check to see if the printer
+name you are using is recognized by Samba.  For example,  you can
+use:
+</para>
+
+<para><programlisting>
+    testprns printer /etc/printcap
+</programlisting></para>
+
+<para>
+Samba can get its printcap information from a file or from a program.
+You can try the following to see the format of the extracted
+information:
+</para>
+
+<para><programlisting>
+    testprns -a printer /etc/printcap
+
+    testprns -a printer '|/bin/cat printcap'
+</programlisting></para>
+
+</sect2>
+
+<sect2>
+<title>Setting up printcap and print servers</title>
+
+<para>
+You may need to set up some printcaps for your Samba system to use.
+It is strongly recommended that you use the facilities provided by
+the print spooler to set up queues and printcap information.
+</para>
+
+<para>
+Samba requires either a printcap or program to deliver printcap
+information.  This printcap information has the format:
+</para>
+
+<para><programlisting>
+  name|alias1|alias2...:option=value:...
+</programlisting></para>
+
+<para>
+For almost all printing systems, the printer 'name' must be composed
+only of alphanumeric or underscore '_' characters.  Some systems also
+allow hyphens ('-') as well.  An alias is an alternative name for the
+printer,  and an alias with a space in it is used as a 'comment'
+about the printer.  The printcap format optionally uses a \ at the end of lines
+to extend the printcap to multiple lines.
+</para>
+
+<para>
+Here are some examples of printcap files:
+</para>
+
+<para>
+<orderedlist>
+<listitem><para>
+pr              just printer name
+</para></listitem>
+<listitem><para>
+pr|alias        printer name and alias
+</para></listitem>
+<listitem><para>
+pr|My Printer   printer name, alias used as comment
+</para></listitem>
+<listitem><para>
+pr:sh:\        Same as pr:sh:cm= testing
+  :cm= \ 
+  testing
+</para></listitem>
+<listitem><para>
+pr:sh           Same as pr:sh:cm= testing
+  :cm= testing
+</para></listitem>
+</orderedlist>
+</para>
+
+<para>
+Samba reads the printcap information when first started.  If you make
+changes in the printcap information, then you must do the following:
+</para>
+
+<orderedlist>
+
+<listitem><para>
+make sure that the print spooler is aware of these changes.
+The LPRng system uses the 'lpc reread' command to do this.
+</para></listitem>
+
+<listitem><para>
+make sure that the spool queues, etc., exist and have the
+correct permissions.  The LPRng system uses the 'checkpc -f'
+command to do this.
+</para></listitem>
+
+<listitem><para>
+You now should send a SIGHUP signal to the smbd server to have
+it reread the printcap information.
+</para></listitem>
+</orderedlist>
+
+</sect2>
+
+<sect2>
+<title>Job sent, no output</title>
+
+<para>
+This is the most frustrating part of printing.  You may have sent the
+job,  verified that the job was forwarded,  set up a wrapper around
+the command to send the file,  but there was no output from the printer.
+</para>
+
+<para>
+First,  check to make sure that the job REALLY is getting to the
+right print queue.  If you are using a BSD or LPRng print spooler,
+you can temporarily stop the printing of jobs.  Jobs can still be
+submitted, but they will not be printed.  Use:
+</para>
+
+<para><programlisting>
+  lpc -Pprinter stop
+</programlisting></para>
+
+<para>
+Now submit a print job and then use 'lpq -Pprinter' to see if the
+job is in the print queue.  If it is not in the print queue then
+you will have to find out why it is not being accepted for printing.
+</para>
+
+<para>
+Next, you may want to check to see what the format of the job really
+was.  With the assistance of the system administrator you can view
+the submitted jobs files.  You may be surprised to find that these
+are not in what you would expect to call a printable format.
+You can use the UNIX 'file' utitily to determine what the job
+format actually is:
+</para>
+
+<para><programlisting>
+    cd /var/spool/lpd/printer   # spool directory of print jobs
+    ls                          # find job files
+    file dfA001myhost
+</programlisting></para>
+
+<para>
+You should make sure that your printer supports this format OR that
+your system administrator has installed a 'print filter' that will
+convert the file to a format appropriate for your printer.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Job sent, strange output</title>
+
+<para>
+Once you have the job printing, you can then start worrying about
+making it print nicely.
+</para>
+
+<para>
+The most common problem is extra pages of output: banner pages
+OR blank pages at the end.
+</para>
+
+<para>
+If you are getting banner pages,  check and make sure that the
+printcap option or printer option is configured for no banners.
+If you have a printcap,  this is the :sh (suppress header or banner
+page) option.  You should have the following in your printer.
+</para>
+
+<para><programlisting>
+   printer: ... :sh
+</programlisting></para>
+
+<para>
+If you have this option and are still getting banner pages,  there
+is a strong chance that your printer is generating them for you
+automatically.  You should make sure that banner printing is disabled
+for the printer.  This usually requires using the printer setup software
+or procedures supplied by the printer manufacturer.
+</para>
+
+<para>
+If you get an extra page of output,  this could be due to problems
+with your job format,  or if you are generating PostScript jobs,
+incorrect setting on your printer driver on the MicroSoft client.
+For example, under Win95 there is a option:
+</para>
+
+<para><programlisting>
+  Printers|Printer Name|(Right Click)Properties|Postscript|Advanced|
+</programlisting></para>
+
+<para>
+that allows you to choose if a Ctrl-D is appended to all jobs.
+This is a very bad thing to do, as most spooling systems will
+automatically add a ^D to the end of the job if it is detected as
+PostScript.  The multiple ^D may cause an additional page of output.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Raw PostScript printed</title>
+
+<para>
+This is a problem that is usually caused by either the print spooling
+system putting information at the start of the print job that makes
+the printer think the job is a text file, or your printer simply
+does not support PostScript.  You may need to enable 'Automatic
+Format Detection' on your printer.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Advanced Printing</title>
+
+<para>
+Note that you can do some pretty magic things by using your
+imagination with the "print command" option and some shell scripts.
+Doing print accounting is easy by passing the %U option to a print
+command shell script. You could even make the print command detect
+the type of output and its size and send it to an appropriate
+printer.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Real debugging</title>
+
+<para>
+If the above debug tips don't help, then maybe you need to bring in
+the bug guns, system tracing. See Tracing.txt in this directory.
+</para>
+</sect2>
+</sect1>
+
 </chapter>
diff --git a/docs/docbook/projdoc/samba-doc.sgml b/docs/docbook/projdoc/samba-doc.sgml
index f20849edbfb..1a35cbd35dc 100644
--- a/docs/docbook/projdoc/samba-doc.sgml
+++ b/docs/docbook/projdoc/samba-doc.sgml
@@ -13,7 +13,6 @@
 <!ENTITY Samba-PAM SYSTEM "PAM-Authentication-And-Samba.sgml">
 <!ENTITY Samba-LDAP SYSTEM "Samba-LDAP-HOWTO.sgml">
 <!ENTITY Diagnosis SYSTEM "Diagnosis.sgml">
-<!ENTITY PRINTING SYSTEM "Printing.sgml">
 <!ENTITY BUGS SYSTEM "Bugs.sgml">
 <!ENTITY SECURITY-LEVEL SYSTEM "security_level.sgml">
 <!ENTITY SPEED SYSTEM "Speed.sgml">
@@ -23,6 +22,7 @@
 <!ENTITY Portability SYSTEM "Portability.sgml">
 <!ENTITY Other-Clients SYSTEM "Other-Clients.sgml">
 <!ENTITY ADS-HOWTO SYSTEM "ADS-HOWTO.sgml">
+<!ENTITY oplocks SYSTEM "oplocks.sgml">
 ]>
 
 <book id="Samba-HOWTO-Collection">
@@ -66,30 +66,61 @@ Cheers, jerry
 </dedication>
 
 <!-- Chapters -->
+<part>
+<title>General installation</title>
+<partintro>
+<title>Introduction</title>
+<para>This part contains general info on how to install samba 
+and how to configure the parts of samba you will most likely need.
+PLEASE read this.</para>
+</partintro>
 &UNIX-INSTALL;
+&BROWSING;
+&oplocks;
+&BROWSING-Quick;
+&ENCRYPTION;
+</part>
+
+<part>
+<title>Type of installation</title>
+<partintro>
+<title>Introduction</title>
+<para>This part contains information on using samba in a (NT 4 or ADS) domain. 
+If you wish to run samba as a domain member or DC, read the appropriate chapter in 
+this part.</para>
+</partintro>
+&Samba-PDC-HOWTO;
+&Samba-BDC-HOWTO;
+&ADS-HOWTO;
+&DOMAIN-MEMBER;
+</part>
+
+<part>
+<title>Optional configuration</title>
+<partintro>
+<title>Introduction</title>
+<para>Samba has several features that you might want or might not want to use. The chapters in this 
+part each cover one specific feature.</para>
+</partintro>
 &IntegratingWithWindows;
+&NT-Security;
 &Samba-PAM;
 &MS-Dfs-Setup;
-&NT-Security;
 &PRINTER-DRIVER2;
-&PRINTING;
 &SECURITY-LEVEL;
-&DOMAIN-MEMBER;
 &WINBIND;
-&Samba-PDC-HOWTO;
-&Samba-BDC-HOWTO;
 &Samba-LDAP;
-&ADS-HOWTO;
-&BROWSING;
-&BROWSING-Quick;
-&SPEED;
 &CVS-Access;
-&BUGS;
 &GROUP-MAPPING-HOWTO;
+&SPEED;
+</part>
 
-<!-- Appendices -->
+<part>
+<title>Appendixes</title>
 &Portability;
 &Other-Clients;
+&BUGS;
 &Diagnosis;
+</part>
 
 </book>