- Patch from John to update PDC-HOWTO, add ServerType and CUPS (not finished yet)

- Regenerate docs
- Update docs-status
(This used to be commit adbb714ade8ab6f4e9b5d80f0f85041746c0edf1)

7 files changed, 1495 insertions, 82 deletions

diff --git a/docs/docbook/projdoc/CUPS-printing.sgml b/docs/docbook/projdoc/CUPS-printing.sgml
new file mode 100644
index 0000000000..bfd23e3c6c
--- /dev/null
+++ b/docs/docbook/projdoc/CUPS-printing.sgml
@@ -0,0 +1,1184 @@
+<chapter id="CUPS-printing">
+
+
+<chapterinfo>
+	<author>
+		<firstname>John H</firstname><surname>Terpstra</surname>
+		<affiliation>
+			<orgname>Samba Team</orgname>
+			<address>
+				<email>jht@samba.org</email>
+			</address>
+		</affiliation>
+	</author>
+	<author>
+		<firstname>Kurt</firstname><surname>Pfeifle</surname>
+		<affiliation>
+			<address><email>kpfeifle@danka.de</email></address>
+		</affiliation>
+	</author>
+	<pubdate> (25 March 2003) </pubdate>
+</chapterinfo>
+
+<title>CUPS Printing Support</title>
+
+<sect1>
+<title>Introduction</title>
+	
+<para>
+The Common Unix Print System (CUPS) has become very popular, but to many it is
+a very mystical tool. There is a great deal of uncertainty regarding CUPS and how
+it works. The result is seen in a large number of posting on the samba mailing lists
+expressing frustration when MS Windows printers appear not to work with a CUPS
+backr-end.
+/para>
+
+<para>
+This is a good time to point out how CUPS can be used and what it does. CUPS is more
+than just a print spooling system - it is a complete printer management system that
+complies with HTTP and IPP protocols. It can be managed remotely via a web browser
+and it can print using http and ipp protocols.
+</para>
+
+<para>
+CUPS allows to creation of RAW printers (ie: NO file format translation) as well as
+SMART printers (ie: CUPS does file format conversion as required for the printer). In
+many ways this gives CUPS similar capabilities to the MS Windows print monitoring
+system. Of course, if you are a CUPS advocate, you would agrue that CUPS is better!
+In any case, let us now move on to explore how one may configure CUPS for interfacing
+with MS Windows print clients via Samba.
+</para>
+
+</sect1>
+
+<sect1>
+<title>CUPS - RAW Print Through  Mode</title>
+
+<para>
+When CUPS printers are configured for RAW print-through mode operation it is the
+responsibility of the Samba client to fully render the print job (file) in a format
+that is suitable for direct delivery to the printer. In this case CUPS will NOT
+do any print file format conversion work.
+</para>
+
+<para>
+The CUPS files that need to be correctly set for RAW mode printers to work are:
+
+<itemlist>
+	<listitem><para><filename>/etc/cups/mime.types</filename><para></listitem)
+
+	<listitem><para><filename>/etc/cups/mime.convs</filename><para></listitem>
+</itemlist>
+
+Both contain entries that must be uncommented to allow <empasis>RAW</emphasis> mode
+operation.
+</para>
+
+<para>
+Firstly, to enable CUPS based printing from Samba the following options must be
+enabled in your smb.conf file [globals] section:
+
+<itemlist>
+	<listitem><para>printing = CUPS</para></listitem>
+
+	<listitem><para>printcap = CUPS</para></listitem>
+</itemlist>
+
+When these parameters are specified the print directives in smb.conf (as well as in
+samba itself) will be ignored because samba will directly interface with CUPS through
+it's application program interface (API) - so long as Samba has been compiled with
+CUPS library (libcups) support. If samba has NOT been compiled with CUPS support then
+printing will use the System V AT&T command set with the <emphasis>-oraw</emphasis> 
+option automatically passing through.
+</para>
+
+<para>
+Cupsomatic (an enhanced printing utility that is part of some CUPS implementations) 
+on the Samba/CUPS server does *not* add any features if a file is really
+printed "raw".  However, if you have loaded the driver for the Windows client from
+the CUPS server, using the "cupsaddsmb" utility, and if this driver is one using
+a "Foomatic" PPD, the PJL header in question is already added on the Windows client,
+at the time when the driver initially generated the PostScript data and CUPS in true
+"-oraw" manner doesn't remove this PJL header and passes the file "as is" to its
+printer communication backend.
+</para>
+
+<para>
+<note>NOTE: editing in the "mime.convs" and the "mime.types" file does not *enforce*
+"raw" printing, it only *allows* it.</note>
+</para>
+
+<para>
+Print files that arrive from MS Windows printing are "auto-typed" by CUPS. This aids
+the process of determining proper treatment while in the print queue system.
+
+<itemlist>
+	<listitem><para>
+	Files generated by PCL drivers and directed at PCK printers get auto-typed as
+	<filename>application/octet-stream</filename>. Unknown file format types also
+	get auto-typed with this tag.
+	</para></listitem>
+
+	<listitem><para>
+	Files generated by a Postscript driver and directed at a Postscript printer
+	are auto-typed depending on the auto-detected most suitable MIME type as:
+
+	<itemlist>
+		<listitem><para>* application/postscript</para></listitem>
+		<listitem><para>* application/vnd.cups-postscript</para></listitem>
+	</itemlist>
+	</para>
+</itemlist>
+</para>
+
+
+<para>
+"application/postscript" first goes thru the "pstops" filter (where the page counting
+and accounting takes place). The outcome will be of MIME type
+"application/vnd.cups-postscript". The pstopsfilter reads and uses information from
+the PPD and inserts user-provided options into the PostScript file. As a consequence,
+the filtered file could possibly have an unwanted PJL header.
+</para>
+
+<para>
+"application/postscript" will be all files with a ".ps", ".ai", ".eps" suffix or which
+have as their first character string one of "%!" or "<04>%".
+</para>
+
+<para>
+"application/vnd.cups-postscript" will files which contain the string
+"LANGUAGE=POSTSCRIPT" (or similar variations with different capitalization) in the
+first 512 bytes, and also contain the "PJL super escape code" in the first 128 bytes
+("<1B>%-12345X"). Very likely, most PostScript files generated on Windows using a CUPS
+or other PPD, will have to be auto-typed as "vnd.cups-postscript".  A file produced
+with a "Generic PostScript driver" will just be tagged "application/postscript".
+</para>
+
+<para>
+Once the file is in "application/vnd.cups-postscript" format, either "pstoraster"
+or "cupsomatic" will take over (depending on the printer configuration, as
+determined by the PPD in use).
+</para>
+
+<para><note>
+A printer queue with *no* PPD associated to it is a "raw" printer and all files
+will go directly there as received by the spooler. The exeptions are file types
+"application/octet-stream" which need "passthrough feature" enabled.
+"Raw" queues don't do any filtering at all, they hand the file directly to the
+CUPS backend. This backend is responsible for the sending of the data to the device
+(as in the "device URI" notation as lpd://, socket://, smb://, ipp://, http://,
+parallel:/, serial:/, usb:/ etc.)
+</note></para>
+
+<para><note>
+"cupsomatic"/Foomatic are *not* native CUPS drivers and they don't ship with CUPS.
+They are a Third Party add-on, developed at Linuxprinting.org.  As such, they are
+a brilliant hack to make all models (driven by Ghostscript drivers/filters in
+traditional spoolers) also work via CUPS, with the same (good or bad!) quality
+as in these other spoolers. "cupsomatic" is only a vehicle to execute a ghostscript
+commandline at that stage in the CUPS filtering chain, where "normally" the native
+CUPS "pstoraster" filter would kick in.  cupsomatic by-passes pstoraster, "kidnaps"
+the printfile from CUPS away and re-directs it to go through Ghostscipt. CUPS accepts this,
+because the associated CUPS-O-Matic-/Foomatic-PPD specifies:
+</para>
+
+<programlisting>
+   *cupsFilter:  "application/vnd.cups-postscript 0 cupsomatic"
+</programlisting>
+
+<para>
+This line persuades CUPS to hand the file to cupsomatic, once it has successfully
+converted it to the MIME type "application/vnd.cups-postscript". This conversion will not
+happen for Jobs arriving from Windows which are auto-typed "application/octet-stream",
+with the according changes in "/etc/cups/mime.types" in place.
+</para>
+
+<para>
+CUPS is widely configurable and flexible, even regarding its filtering mechanism.
+Another workaround in some situations would be to have
+in "/etc/cups/mime.types" entries as follows:
+</para>
+
+<programlisting>
+   application/postscript           application/vnd.cups-raw  0  -
+   application/vnd.cups-postscript  application/vnd.cups-raw  0  -
+</programlisting>
+
+<para>
+This would prevent all Postscript files from being filtered (rather, they will go
+thru the virtual "nullfilter" denoted with "-"). This could only be useful for
+PS printers. If you want to print PS code on non-PS printers an entry as follows
+could be useful:
+</para>
+
+<programlisting>
+   */*           application/vnd.cups-raw  0  -
+</programlisting>
+
+<para>
+and would effectively send *all* files to the backend without further processing.
+</para>
+
+<para>
+Lastly, you could have the following entry:
+</para>
+
+<programlisting>
+   application/vnd.cups-postscript  application/vnd.cups-raw  0  my_PJL_stripping_filter
+</programlisting>
+
+<para>
+You will need to write a "my_PJL_stripping_filter" (could be a shellscript) that
+parses the PostScript and removes the unwanted PJL. This would need to conform to
+CUPS filter design (mainly, receive and pass the parameters printername, job-id,
+username, jobtitle, copies, print options and possibly the filename). It would
+be installed as world executable into "/usr/lib/cups/filters/" and will be called
+by CUPS if it encounters a MIME type "application/vnd.cups-postscript".
+</para>
+
+<para>
+CUPS can handle "-o job-hold-until=indefinite". This keeps the job in the queue
+"on hold". It will only be printed upon manual release by the printer operator.
+This is a requirement in many "central reproduction departments", where a few
+operators manage the jobs of hundreds of users on some big machine, where no
+user is allowed to have direct access. (The operators often need to load the
+proper paper type before running the 10.000 page job requested by marketing
+for the mailing, etc.).
+</para>
+
+</sect1>
+
+<sect1>
+<title>The CUPS Filter Chains</title>
+
+<para>
+The following diagrams reveal how CUPS handles print jobs.
+</para>
+
+<programlisting>
+#########################################################################
+#
+# CUPS in and of itself has this (general) filter chain (CAPITAL
+# letters are FILE-FORMATS or MIME types, other are filters (this is
+# true for pre-1.1.15 of pre-4.3 versions of CUPS and ESP PrintPro):
+#
+# <SOMETHNG>-FILEFORMAT
+#      |
+#      |
+#      V
+#     <something>tops
+#      |
+#      |
+#      V
+# APPLICATION/POSTSCRIPT
+#      |
+#      |
+#      V
+#     pstops
+#      |
+#      |
+#      V
+# APPLICATION/VND.CUPS-POSTSCRIPT
+#      |
+#      |
+#      V
+#     pstoraster   # as shipped with CUPS, independent from any Ghostscipt
+#      |           # installation on the system
+#      |  (= "postscipt interpreter")
+#      |
+#      V
+# APPLICATION/VND.CUPS-RASTER
+#      |
+#      |
+#      V
+#     rasterto<something>  (f.e. Gimp-Print filters may be plugged in here)
+#      |   (= "raster driver")
+#      |
+#      V
+# SOMETHING-DEVICE-SPECIFIC
+#      |
+#      |
+#      V
+#     backend
+#
+#
+# ESP PrintPro has some enhanced "rasterto<something>" filters as compared to
+# CUPS, and also a somewhat improved "pstoraster" filter.
+#
+# NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to
+#       CUPS and ESP PrintPro plug-in where rasterto<something> is noted.
+#
+#########################################################################
+</programlisting>
+
+<programlisting>
+#########################################################################
+#
+# This is how "cupsomatic" comes into play:
+# =========================================
+#
+# <SOMETHNG>-FILEFORMAT
+#      |
+#      |
+#      V
+#    <something>tops
+#      |
+#      |
+#      V
+# APPLICATION/POSTSCRIPT
+#      |
+#      |
+#      V
+#    pstops
+#      |
+#      |
+#      V
+# APPLICATION/VND.CUPS-POSTSCRIPT ----------------+
+#      |                                          |
+#      |                                          V
+#      V                                         cupsomatic
+#    pstoraster                                  (constructs complicated
+#      |  (= "postscipt interpreter")            Ghostscript commandline
+#      |                                         to let the file be
+#      V                                         processed by a
+# APPLICATION/VND.CUPS-RASTER                    "-sDEVICE=<s.th.>"
+#      |                                         call...)
+#      |                                          |
+#      V                                          |
+#    rasterto<something>                          V
+#      |    (= "raster driver")     +-------------------------+
+#      |                            | Ghostscript at work.... |
+#      V                            |                         |
+# SOMETHING-DEVICE-SPECIFIC         *-------------------------+
+#      |                                          |
+#      |                                          |
+#      V                                          |
+#    backend <------------------------------------+
+#      |
+#      |
+#      V
+#    THE PRINTER
+#
+#
+# Note, that cupsomatic "kidnaps" the printfile after the
+# "APPLICATION/VND.CUPS-POSTSCRPT" stage and deviates it through
+# the CUPS-external, systemwide Ghostscript installation, bypassing the
+# "pstoraster" filter (therefor also bypassing the CUPS-raster-drivers
+# "rasterto<something>", and hands the rasterized file directly to the CUPS
+# backend...
+#
+# cupsomatic is not made by the CUPS developers. It is an independent
+# contribution to printing development, made by people from
+# Linuxprinting.org. (see also http://www.cups.org/cups-help.html)
+#
+# NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to
+#       CUPS and ESP PrintPro plug-in where rasterto<something> is noted.
+#
+#########################################################################
+</programlisting>
+
+<programlisting>
+#########################################################################
+#
+# And this is how it works for ESP PrintPro from 4.3:
+# ===================================================
+#
+# <SOMETHNG>-FILEFORMAT
+#      |
+#      |
+#      V
+#     <something>tops
+#      |
+#      |
+#      V
+# APPLICATION/POSTSCRIPT
+#      |
+#      |
+#      V
+#     pstops
+#      |
+#      |
+#      V
+# APPLICATION/VND.CUPS-POSTSCRIPT
+#      |
+#      |
+#      V
+#     gsrip
+#      |  (= "postscipt interpreter")
+#      |
+#      V
+# APPLICATION/VND.CUPS-RASTER
+#      |
+#      |
+#      V
+#     rasterto<something>  (f.e. Gimp-Print filters may be plugged in here)
+#      |   (= "raster driver")
+#      |
+#      V
+# SOMETHING-DEVICE-SPECIFIC
+#      |
+#      |
+#      V
+#     backend
+#
+# NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to
+#       CUPS and ESP PrintPro plug-in where rasterto<something> is noted.
+#
+#########################################################################
+</programlisting>
+
+<programlisting>
+#########################################################################
+#
+# This is how "cupsomatic" would come into play with ESP PrintPro:
+# ================================================================
+#
+#
+# <SOMETHNG>-FILEFORMAT
+#      |
+#      |
+#      V
+#    <something>tops
+#      |
+#      |
+#      V
+# APPLICATION/POSTSCRIPT
+#      |
+#      |
+#      V
+#    pstops
+#      |
+#      |
+#      V
+# APPLICATION/VND.CUPS-POSTSCRIPT ----------------+
+#      |                                          |
+#      |                                          V
+#      V                                         cupsomatic
+#    gsrip                                       (constructs complicated
+#      |  (= "postscipt interpreter")            Ghostscript commandline
+#      |                                         to let the file be
+#      V                                         processed by a
+# APPLICATION/VND.CUPS-RASTER                    "-sDEVICE=<s.th.>"
+#      |                                         call...)
+#      |                                          |
+#      V                                          |
+#    rasterto<something>                          V
+#      |   (= "raster driver")      +-------------------------+
+#      |                            | Ghostscript at work.... |
+#      V                            |                         |
+# SOMETHING-DEVICE-SPECIFIC         *-------------------------+
+#      |                                          |
+#      |                                          |
+#      V                                          |
+#    backend <------------------------------------+
+#      |
+#      |
+#      V
+#    THE PRINTER
+#
+# NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to
+#       CUPS and ESP PrintPro plug-in where rasterto<something> is noted.
+#
+#########################################################################
+</programlisting>
+
+<programlisting>
+#########################################################################
+#
+# And this is how it works for CUPS from 1.1.15:
+# ==============================================
+#
+# <SOMETHNG>-FILEFORMAT
+#      |
+#      |
+#      V
+#     <something>tops
+#      |
+#      |
+#      V
+# APPLICATION/POSTSCRIPT
+#      |
+#      |
+#      V
+#     pstops
+#      |
+#      |
+#      V
+# APPLICATION/VND.CUPS-POSTSCRIPT-----+
+#                                     |
+#                  +------------------v------------------------------+
+#                  | Ghostscript                                     |
+#                  | at work...                                      |
+#                  | (with                                           |
+#                  | "-sDEVICE=cups")                                |
+#                  |                                                 |
+#                  |         (= "postscipt interpreter")             |
+#                  |                                                 |
+#                  +------------------v------------------------------+
+#                                     |
+#                                     |
+# APPLICATION/VND.CUPS-RASTER <-------+
+#      |
+#      |
+#      V
+#     rasterto<something>
+#      |   (= "raster driver")
+#      |
+#      V
+# SOMETHING-DEVICE-SPECIFIC
+#      |
+#      |
+#      V
+#     backend
+#
+#
+# NOTE: since version 1.1.15 CUPS "outsourced" the pstoraster process to
+#       Ghostscript. GNU Ghostscript needs to be patched to handle the
+#       CUPS requirement; ESP Ghostscript has this builtin. In any case,
+#       "gs -h" needs to show up a "cups" device. pstoraster is now a
+#       calling an appropriate "gs -sDEVICE=cups..." commandline to do
+#       the job. It will output "application/vnd.cup-raster", which will
+#       be finally processed by a CUPS raster driver "rasterto<something>"
+#       Note the difference to "cupsomatic", which will *not* output
+#       CUPS-raster, but a final version of the printfile, ready to be
+#       sent to the printer. cupsomatic also doesn't use the "cups"
+#       devicemode in Ghostscript, but one of the classical devicemodes....
+#
+# NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to
+#       CUPS and ESP PrintPro plug-in where rasterto<something> is noted.
+#
+#########################################################################
+</programlisting>
+
+<programlisting>
+#########################################################################
+#
+# And this is how it works for CUPS from 1.1.15, with cupsomatic included:
+# ========================================================================
+#
+# <SOMETHNG>-FILEFORMAT
+#      |
+#      |
+#      V
+#     <something>tops
+#      |
+#      |
+#      V
+# APPLICATION/POSTSCRIPT
+#      |
+#      |
+#      V
+#     pstops
+#      |
+#      |
+#      V
+# APPLICATION/VND.CUPS-POSTSCRIPT-----+
+#                                     |
+#                  +------------------v------------------------------+
+#                  | Ghostscript        . Ghostscript at work....    |
+#                  | at work...         . (with "-sDEVICE=           |
+#                  | (with              .            <s.th.>"        |
+#                  | "-sDEVICE=cups")   .                            |
+#                  |                    .                            |
+#                  | (CUPS standard)    .      (cupsomatic)          |
+#                  |                    .                            |
+#                  |          (= "postscript interpreter")           |
+#                  |                    .                            |
+#                  +------------------v--------------v---------------+
+#                                     |              |
+#                                     |              |
+# APPLICATION/VND.CUPS-RASTER <-------+              |
+#      |                                             |
+#      |                                             |
+#      V                                             |
+#     rasterto<something>                            |
+#      |   (= "raster driver")                       |
+#      |                                             |
+#      V                                             |
+# SOMETHING-DEVICE-SPECIFIC <------------------------+
+#      |
+#      |
+#      V
+#     backend
+#
+#
+# NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to
+#       CUPS and ESP PrintPro plug-in where rasterto<something> is noted.
+#
+##########################################################################
+</programlisting>
+
+</sect1>
+
+
+<sect1>
+<title>CUPS Print Drivers and Devices</title>
+
+<para>
+CUPS ships with good support for HP LaserJet type printers. You can install
+the driver as follows:
+
+<itemlist>
+	<listitem><para>
+	lpadmin -p laserjet4plus -v parallel:/dev/lp0 -E -m laserjet.ppd
+	</para></listitem>
+</itemlist>
+
+(The "-m" switch will retrieve the "laserjet.ppd" from the standard repository
+for not-yet-installed-PPDs, which CUPS typically stores in 
+filename>/usr/share/cups/model</filename>. Alternatively, you may use
+"-P /absolute/filesystem/path/to/where/there/is/PPD/your.ppd").
+</para>
+
+<para>
+<programlisting>
+Windows printing involves some more steps....
+
+But let me first point out some more general things about printer "drivers"
+for Linux/Unix (yes, and for Mac OS X now!), be it you use CUPS or one of
+the venerable (I'd even call them "ancient" and "rusty" now...) printing
+systems.
+
+You  -- and everybody else, for that matter --  should always also consult the
+database on linuxprinting.org for all recommendations about "which driver
+is best used for which printer":
+
+   http://www.linuxprinting.org/printer_list.cgi
+
+There select your model and click on "Show". You'll arrive at a page listing
+all drivers working with your model. There will always be *one* "recommended"
+one. Try this one first. In your case ("HP LaserJet 4 Plus"), you'll arrive
+here:
+
+   http://www.linuxprinting.org/show_printer.cgi?recnum=75104
+
+The recommended driver is "ljet4". It has a link to the page for the ljet4
+driver too:
+
+   http://www.linuxprinting.org/show_driver.cgi?driver=ljet4
+
+On the driver's page, you'll find various important and detailed infos about
+how to use that driver within various spoolers. You can generate a PPD for
+CUPS. The PPD contains all the info about how to use your model and the driver;
+this is, once installed, working transparently for the user -- you'll only
+need to choose resolution, paper size etc. from the web-based menu or from
+the print dialog GUI or from the commandline...
+
+On the driver's page, choose to use the "PPD-O-Matic" online PPD generator
+program. Select your model and click "Generate PPD file". When you safe the
+appearing ASCII text file, don't use "cut'n'past" (as it will possible corrupt
+line endings and tabs), but use "Save as..." in your browser's menu. Save it
+at "/some/path/on/your/filesystem/somewhere/my-name-for-my-printer.ppd"
+
+Then install the printer:
+
+    "lpadmin -p laserjet4plus -v parallel:/dev/lp0 -E -P /some/path/on/your/filesystem/somewhere/my-name-for-my-printer.ppd"
+
+Note, that for all the "Foomatic-PPDs" from Linuxprinting.org, you also need
+a special "CUPS filter" named "cupsomatic". Get the latest version of
+"cupsomatic" from
+
+     http://www.linuxprinting.org/cupsomatic
+
+This needs to be copied to "/usr/lib/cups/filter/cupsomatic" and be made world
+executable. This filter is needed to read and act upon the specially encoded
+Foomatic comments, embedded in the printfile, which in turn are used to
+construct (transparently for you, the user) the complicated ghostscript command
+line needed for your printer/driver combo.
+
+You can have a look at all the options for the Ghostscript commandline supported
+by your printer and the ljet4 driver by going to the section "Execution details",
+selecting your model (Laserjet 4 Plus) and clicking on "Show execution details".
+This will bring up this web page:
+
+    http://www.linuxprinting.org/execution.cgi?driver=ljet4&printer=75104&.submit=Show+execution+details
+
+The ingenious thing is this: the database is kept very current. If there
+is a bug fix and an improvement somewhere in the database, you will
+always get the most current and stable and feature-rich driver by following
+the steps described above... Till Kamppeter from MandrakeSoft is doing an
+excellent job here, and too few people still know about it. (So if you use
+it often, please send him a note of your appreciation sometime...)
+
+(The latest and greatest improvement now is support for "custom page sizes"
+for all those printers which support it...)
+
+"cupsomatic" is documented here:
+
+    http://www.linuxprinting.org/cups-doc.html
+
+More printing tutorial info may be found here:
+
+    http://www.linuxprinting.org/kpfeifle/LinuxKongress2002/Tutorial/
+
+Note, that *all* the Foomatic drivers listed on Linuxprinting.org (now
+approaching the "all-time high" number of 1.000 for the supported models)
+are using a special filtering chain involving Ghostscript, as described
+in great detail in the Samba CVS sources (for 2.2.x) in
+
+    docs/textdocs/CUPS-PrintingInfo.txt
+
+To sum it up:
+
+* having a "foomatic+<something>" PPD is not enough to print with CUPS
+   (but it is *one* important component)
+* you also need the "cupsomatic" filter script (Perl) in "/usr/lib/cups/filters/"
+* you need Perl to make cupsomatic run
+* you also need Ghostscript (because it is called and controlled by the
+   PPD/cupsomatic combo in a way to fit your printermodel/driver combo...)
+* your Ghostscript *must*, depending on the driver/model, contain support
+   for a certain "device" (as shown by "gs -h")
+
+In the case of the "hpijs" driver, you need a Ghostscript version, which
+is showing a "ijs" amongst its supported devices in "gs -h". In the case of
+"hpijs+foomatic", a valid ghostscript commandline would be reading like this:
+
+       gs -q -dBATCH -dPARANOIDSAFER -dQUIET -dNOPAUSE -sDEVICE=ijs       \
+             -sIjsServer=hpijs<PageSize> -dDuplex=<Duplex> <Model>        \
+             -r<Resolution>,PS:MediaPosition=<InputSlot> -dIjsUseOutputFD \
+             -sOutputFile=- -
+
+Note, that with CUPS and the "hpijs+foomatic" PPD (plus Perl and cupsomatic)
+you don't need to remember this. You can choose the available print options
+thru a GUI print command (like "glp" from ESP's commercially supported
+PrintPro software, or KDE's "kprinter", or GNOME's "gtklp" or the independent
+"xpp") or the CUPS web interface via human-readable drop-down selection
+menus.....
+
+If you use "ESP Ghostscript" (also under the GPL, provided by Easy Software
+Products, the makers of CUPS, downloadable from http://www.cups.org/software.html,
+co-maintained by the developers of linuxprinting.org), you are guaranteed to
+have in use the most uptodate, bug-fixed, enhanced and stable version of a Free
+Ghostscript. It contains support for ~300 devices, whereas plain vanilla
+GNU Ghostscript 7.05 only has ~200....
+
+>>/ However, I can only print a Cups test page, from the web interface. when I
+/>>/ try to print a windows test page, it acts like the job was never sent.
+/
+  * Can you print "standard" jobs from the CUPS machine?
+
+  * Are the jobs from Windows visible in the Web interface on CUPS
+    (http://localhost:631/)?
+
+*Most important:* What kind of printer driver are you using on the Windows clients???
+
+You can try to get a more detailed debugging info by setting "LogLevel debug" in
+"/etc/cups/cupsd.conf", re-start cupsd and investigate "/var/log/cups/error_log"
+for the whereabouts of your Windows-originating printjobs:
+
+   * what does the "auto-typing" line say? which is the "MIME type" CUPS thinks
+     is arriving from the Windows clients?
+   * are there "filter" available for this MIME type?
+   * are there "filter rules" defined in "/etc/cups/mime.convs" for this MIME type?
+</programlisting>
+</para>
+
+</sect1>
+
+
+<sect1>
+<title>Limiting the number of pages users can print</title>
+
+<para>
+The feature you want is dependent on the real print subsystem
+you're using. Samba's part is always to receive the job files
+from the clients (filtered *or* unfiltered) and hand it over
+to this printing subsystem.
+
+Of course one could "hack" things with one's own scripts.
+
+But there is CUPS (Common Unix Printing System). CUPS supports "quotas".
+Quotas can be based on sizes of jobs or on the number of pages or both,
+and are spanning any time period you want.
+
+This is an example command how root would set a print quota in CUPS,
+assuming an existing printer named "quotaprinter":
+</para>
+
+<programlisting>
+  lpadmin -p quotaprinter -o job-quota-period=604800 -o job-k-limit=1024 -o job-page-limit=100
+</programlisting>
+
+<para>
+This would limit every single user to print 100 pages or 1024 KB of
+data (whichever comes first) within the last 604.800 seconds ( = 1 week).
+
+For CUPS to count correctly, the printfile needs to pass the CUPS
+"pstops" filter, otherwise it uses a "dummy" count of "1". (Some
+printfiles don't pass it -- f.e. image files -- but then those are
+mostly 1 page jobs anyway). This also means, proprietary drivers for
+the target printer running on the client computers and CUPS/Samba
+then spooling these files as "raw" (i.e. leaving them untouched, not
+filtering them), will be counted as "1-pagers" too!
+
+You need to send PostScript from the clients (i.e. run a PostScript
+driver there) for having the chance to get accounting done. If the
+printer is a non-PostScript model, you need to let CUPS do the job to
+convert the file to a print-ready format for the target printer. This
+will be working for currently ~1.000 different printer models, see
+</para>
+
+<programlisting>
+     http://www.linuxprinting.org/printer_list.cgi
+</programlisting>
+
+<para>
+Before CUPS-1.1.16 your only option was to use the Adobe PostScript
+Driver on the Windows clients. The output of this driver was not always
+passed thru the "pstops" filter on the CUPS/Samba side, and therefor was
+not counted correctly (the reason is that it often --- depending on the
+"PPD" being used --- did write a "PJL"-header in front of the real
+PostScript which made CUPS to skip the pstops and go directy to
+the "pstoraster" stage).
+
+ From CUPS-1.1.16 onward you can use the "CUPS PostScript Driver
+for Windows NT/2K/XP clients" (it is tagged in the download area of
+http://www.cups.org/ as the "cups-samba-1.1.16.tar.gz" package).
+It is *not* working for Win9x/ME clients. But it....
+
+   ...it guarantees to not write an PJL-header;
+   ...it guarantees to still read and support all PJL-options named
+      in the driver PPD with its own means;
+   ...it guarantees the file going thru the "pstops" filter on the
+      CUPS/Samba server;
+   ...it guarantees to page-count correctly the printfile...
+
+You can read more about the setup of this combination in the
+manpage for "cupsaddsmb" (only present with CUPS installed, only
+current with CUPS 1.1.16).
+
+These are the items CUPS logs in the "page_log" for every single
+*page* of a job:
+
+* Printer name
+* User name
+* Job ID
+* Time of printing
+* the page number
+* the number of copies
+* a billing info string (optional)
+
+Here is an extract of my CUPS server's page_log file to illustrate
+the format and included items:
+
+infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 1 2  #marketing
+infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 2 2  #marketing
+infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 3 2  #marketing
+infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 4 2  #marketing
+infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 5 2  #marketing
+infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 6 2  #marketing
+
+This was Job ID "40", printed on "infotec_IS2027" by user "kurt",
+a 6-page job printed in 2 copies and billed to "#marketing"...
+
+Which flaws or shortcomings are there?
+
+  * the ones named above;
+  * CUPS really counts the job pages being *processsed in software*
+    (going thru the "RIP") rather than the physical sheets successfully
+    leaving the printing device -- if there is a jam while printing
+    the 5th sheet out of 1000 and the job is aborted by the printer,
+    the "page count" will still show the figure of 1000 for that
+    job;
+  * all quotas are the same for all users (no flexibility to
+    give the boss a higher quota than the clerk)
+  * no support for groups;
+  * no means to read out the current balance or "used-up"
+    number of current quota;
+  * a user having used up 99 sheets of 100 quota will still be
+    able to send and print a 1.000 sheet job;
+  * a user being denied a job because of a filled-up quota
+    doesn't get a meaningful error message from CUPS other than
+    "client-error-not-possible".
+
+But this is the best system out there currently. And there are
+huge improvements under development:
+
+--> page counting will go into the "backends" (these talk directly
+     to the printer and will increase the count in sync with the
+     actual printing process  -- a jam at the 5th sheet will lead
+     to a stop in the counting...)
+
+--> quotas will be handled more flexibly;
+
+--> probably there will be support for users to inquire their
+     "accounts" in advance;
+
+--> probably there will be support for some other tools around
+     this topic...
+
+Other than the current stage of the CUPS development, I don't
+know any other ready-to-use tool which you could consider.
+</para>
+
+<para>
+You can download the driver files from http://www.cups.org/software.html. It
+is a separate package from the CUPS base software files, tagged as "CUPS 1.1.16
+Windows NT/2k/XP Printer Driver for SAMBA (tar.gz, 192k)". The filename to
+download is "cups-samba-1.1.16.tar.gz". Upon untar-/unzip-ping it will reveal
+the files
+
+   cups-samba.install
+   cups-samba.license
+   cups-samba.readme
+   cups-samba.remove
+   cups-samba.ss
+
+These have been packaged with the ESP meta packager software "EPM". The
+*.install and *.remove files are simple shell script, which untars the
+*.ss (which is nothing else than a tar-archive) and puts its contents
+into "/usr/share/cups/drivers/". Its contents are 3 files:
+
+   cupsdrvr.dll
+   cupsui.dll
+   cups.hlp
+
+[ ATTENTION: due to a bug the current release puts the "cups.hlp" into
+   "/usr/share/drivers/" instead of "/usr/share/cups/drivers/". To work
+   around this, copy/move the file after running the "./cups-samba.install"
+   script manually to the right place:
+
+      "cp /usr/share/drivers/cups.hlp /usr/share/cups/drivers/" ]
+
+This new CUPS PostScript driver is currently binary-only, but free (as in
+free beer); no source code is provided (yet). The reason is this: it has
+been developed with the help of the Microsoft Driver Developer Kit (DDK)
+and compiled with Microsoft Visual Studio 6. It is not clear to the driver
+developers if they are allowed to distribute the whole of the source code
+as Free Software. However, they will likely release the "diff" in source
+code under the GPL, so anybody with a license of Visual Studio and a DDK
+will be able to compile for him/herself.
+
+Once you have run the install script (and possibly manually moved the
+"cups.hlp" file to "/usr/share/cups/drivers/"), the driver is ready to be
+put into Samba's [print$] share (which often maps to "/etc/samba/drivers/"
+and contains a subdir tree with WIN40 and W32X86 branches), by running
+"cupsaddsmb" (see also "man cupsaddsmb" for CUPS 1.1.16). [Don't forget to
+put root into the smbpasswd file by running "smbpasswd" should you run
+this whole procedure for the first time.] Once the driver files are in the
+[print$] share, they are ready to be downloaded and installed by the
+Win NT/2k/XP clients.
+
+NOTE 1: Win 9x/ME clients won't work with this driver. For these you'd
+         still need to use the ADOBE*.* drivers as previously.
+
+NOTE 2: It is not harming if you've still the ADOBE*.* driver files from
+         previous installations in the "/usr/share/cups/drivers/" directory.
+         The new cupsaddsmb (from 1.1.16) will automatically use the
+         "newest" installed driver (which here then is the CUPS drivers).
+
+NOTE 3: Should your Win clients have had the old ADOBE*.* files and the
+         Adobe PostScript drivers installed, the download and installation
+         of the new CUPS PostScript driver for Windows NT/2k/XP will fail
+         at first.
+         It is not enough to "delete" the printer (as the driver files
+         will still be kept by the clients and re-used if you try to
+         re-install the printer). To really get rid of the Adobe driver
+         files on the clients, open the "Printers" folder (possibly via
+         "Start --> Settings --> Control Panel --> Printers"), right-click
+         onto the folder background and select "Server Properties". A
+         new dialog opens; select the "Drivers" tab; on the list select
+         the driver you want to delete and click on the "Delete" button.
+         (This will only work if there is no single printer left which
+         uses that particular driver -- you need to "delete" all printers
+         using this driver in the "Printers" folder first...)
+
+NOTE 4: Once you have successfully downloaded the CUPS PostScript driver
+         to a client, you can easily switch all printers to this one
+         by proceeding as described elsewhere in the "Samba HOWTO
+         Collection" to change a driver for an existing printer....
+
+
+What are the benefits with the "CUPS PostScript driver for Windows NT/2k/XP"
+as compared to the Adobe drivers?
+                                                                                            9
+* no hassle with the Adobe EULA; no hassle with the question "where do I
+   get the ADOBE*.* driver files from?"
+
+* the Adobe drivers (depending on the printer PPD associated with them)
+   often put a PJL header in front of the core PostScript part of the print
+   file (thus the file starts with "<1B>%-12345X" or "<escape>%-12345X"
+   instead of "%!PS"). This leads to the CUPS daemon autotyping the
+   arriving file as a print-ready file, not requiring a pass thru the
+   "pstops" filter (to speak more technical, it is not regarded as the
+   generic MIME type "application/postscript", but as the more special
+   MIME type "application/cups.vnd-postscript"), which therefore also
+   leads to the page accounting in "/var/log/cups/page_log" not receiving
+   the exact mumber of pages; instead the dummy page number of "1" is
+   logged in a standard setup...)
+
+* the Adobe driver has more options to "mis-configure" the PostScript
+   generated by it (like setting it inadvertedly to "Optimize for Speed",
+   instead of "Optimize for Portability", which could lead to CUPS being
+   unable to process it....)
+
+* the CUPS PostScript driver output sent by Windows clients to the CUPS
+   server will be guaranteed to be auto-typed as generic MIME type
+   "application/postscript", thusly passing thru the CUPS "pstops" filter
+   and logging the correct number of pages in the page_log for accounting
+   and quota purposes...
+
+* the CUPS PostScript driver supports the sending of additional print
+   options by the Win NT/2k/XP clients, such as naming the CUPS standard
+   banner pages (or the custom ones, should they be installed at the time
+   of driver download), using the CUPS "page-label" option, setting a
+   job-priority and setting the scheduled time of printing (with the option
+   to support additional useful IPP job attributes in the future).
+
+* the CUPS PostScript driver supports the inclusion of the new
+   "*cupsJobTicket" comments at the beginnig of the PostScript file (which
+   could be used in the future for all sort of beneficial extensions on
+   the CUPS side, but which will not disturb any other application as those
+   will regard it as a comment and simply ignore it).
+
+* the CUPS PostScript driver will be the heart of the fully fledged CUPS
+   IPP client for Windows NT/2k/XP to be released soon (probably alongside
+   the first Beta release for CUPS 1.2).
+</para>
+
+</sect1>
+
+<sect1>
+<title>Advanced Postscript Printing from MS Windows</title>
+
+<para>
+* Let the Windows Clients use a PostScript driver, to produce
+   PostScript as their print output sent towards the Samba print
+   server (just like any Linux or Unix Client would also use
+   PostScript to send to the server...)
+
+* make the Unix printing subsystem which is underneath Samba
+   convert the incoming PostScript files to the native print
+   format of the target printers (would likely be PCL?
+   I understand you have mainly HP models?)
+
+* You're afraid, that this would just mean a *Generic* PostScript
+   driver for the clients? With no Simplex/Duplex selection,
+   no paper tray choice? But you need them to be able to set up
+   their jobs, ringing all the bells and whistles of the printers?
+
+   --> Not possible with traditional spooling systems!
+
+   --> But perfectly supported by CUPS (which uses "PPD" files to
+       describe how to control the print options for PostScript and
+       non-PostScript devices alike...
+
+   CUPS PPDs are working perfectly on Windows
+   clients who use Adobe PostScript drivers (or the new CUPS
+   PostScript driver for Windows NT/2K/XP). Clients can use
+   them to setup the job to their liking and CUPS will use
+   the received job options to make the (PCL-, ESC/P- or
+   PostScript-) printer behave as required.
+
+* You want to have the additional benefit of page count logging
+   and accounting? In this case the CUPS PostScript driver
+   is the best choice (better than the Adobe one).
+
+* You want to make the drivers downloadable for the clients?
+   "cupsaddsmb" is your friend. It will setup the [print$]
+   share on the Samba host to be ready to serve the clients
+   for a "point and print" driver installation...
+
+"What strings are attached?", I hear you asking...
+
+You are right, there are some. But, given the sheer CPU power
+you can buy nowadays in German supermarkets, these can be
+overcome easily.
+
+The strings: Well, if the
+CUPS/Samba side will have to print a *lot* onto 40 printers
+serving 500 users, you probably will need to set up a second
+server (which can do automatic load balancing with the first
+one, plus a degree of fail-over mechanism). Converting the
+incoming PostScript jobs, "interpreting" them for
+non-PostScript printers, amounts to the work of a "RIP"
+(Raster Image Processor) done in software. This requires
+more CPU and RAM than for the mere "raw spooling" task
+your current setup is solving... It all depends on the
+avarage and peak printing load the server should be
+able to handle....
+</para>
+
+</sect1>
+
+<sect1>
+<title>Auto-Deletion of CUPS spool files</title>
+
+<para>
+Samba print files pass thru 2
+different "spool" directories. Once the incoming directory
+managed by Samba, (set f.e. in the "path = /var/spool/samba"
+directive in the [printers] section of "smb.conf"). Second is
+the spool directory of your UNIX print subsystem. For CUPS it is
+normally "/var/spool/cups/", as set by the cupsd.conf directive
+"RequestRoot /var/spool/cups".
+
+I am not sure, which one of your directories keeps the files.
+ From what you say, it is most likely the Samba part.
+
+For the CUPS part, you may want to consult:
+
+   http://localhost:631/sam.html#PreserveJobFiles and
+   http://localhost:631/sam.html#PreserveJobHistory and
+   http://localhost:631/sam.html#MaxJobs
+
+There are the settings described for your CUPS daemon, which
+could lead to completed job files not being deleted.
+
+"PreserveJobHistory Yes" -- keeps some details of jobs in
+cupsd's mind (well it keeps the "c12345", "c12346" etc. files
+in the CUPS spool directory, which do a similar job as the
+old-fashioned BSD-LPD control files). This is set to "Yes"
+as a default.
+
+"PreserveJobFiles Yes" -- keeps the job files themselves in
+cupsd's mind (well it keeps the "d12345", "d12346" etc. files
+in the CUPS spool directory...). This is set to "No" as the
+CUPS default.
+
+"MaxJobs 500" -- this directive controls the maximum number
+of jobs that are kept in memory. Once the number of jobs
+reaches the limit, the oldest completed job is automatically
+purged from the system to make room for the new one. If all
+of the known jobs are still pending or active then the new
+job will be rejected. Setting the maximum to 0 disables this
+functionality. The default setting is 0.
+
+(There are also additional settings for "MaxJobsPerUser" and
+"MaxJobsPerPrinter"...)
+
+For everything to work as announced, you need to have three
+things:
+
+   * a Samba-smbd which is compiled against "libcups" (Check
+     on Linux by running "ldd `which smbd`")
+
+   * a Samba-smb.conf setting of "printing = cups"
+
+   * another Samba-smb.conf setting of "printcap = cups"
+
+Note, that in this case all other manually set printing-related
+commands (like "print command", "lpq command", "lprm command",
+"lppause command" or "lpresume command") are ignored and they
+should normally have no influence what-so-ever on your printing.
+
+If you want to do things manually, replace the "printing = cups"
+by "printing = bsd". Then your manually set commands may work
+(haven't tested this), and a "print command = lp -d %P %s; rm %s"
+may do what you need.
+
+You forgot to mention the CUPS version you're using. If you did
+set things up as described in the man pages, then the Samba
+spool files should be deleted. Otherwise it may be a bug. On
+the CUPS side, you can control the behaviour as described
+above.
+If you have more problems, post the output of these commands:
+
+   grep -v ^# /etc/cups/cupsd.conf | grep -v ^$
+   grep -v ^# /etc/samba/smb.conf | grep -v ^$ | grep -v "^;"
+
+(adapt paths as needed). These commands sanitize the files
+and cut out the empty lines and lines with comments, providing
+the "naked settings" in a compact way.
+</para>
+</sect1>
diff --git a/docs/docbook/projdoc/Samba-PDC-HOWTO.sgml b/docs/docbook/projdoc/Samba-PDC-HOWTO.sgml
index c0be81d989..53dae21775 100644
--- a/docs/docbook/projdoc/Samba-PDC-HOWTO.sgml
+++ b/docs/docbook/projdoc/Samba-PDC-HOWTO.sgml
@@ -13,13 +13,18 @@
 			<orgname>Samba Team</orgname>
 			<address><email>dbannon@samba.org</email></address>
 		</affiliation>
+		<firstname>John H</firstname><surname>Terpstra</surname>
+		<affiliation>
+			<orgname>Samba Team</orgname>
+			<address><email>jht@samba.org</email></address>
+		</affiliation>
 		
 	</author>
 	<pubdate> (26 Apr 2001) </pubdate>
 </chapterinfo>
 
 <title>
-Samba as a NT4 or Win2k Primary Domain Controller
+Samba as an NT4 or Win2k Primary Domain Controller
 </title>
 
 
@@ -37,8 +42,7 @@ that you are comfortable with configuring basic files services
 in smb.conf and how to enable and administer password 
 encryption in Samba.  Theses two topics are covered in the
 <ulink url="smb.conf.5.html"><filename>smb.conf(5)</filename></ulink> 
-manpage and the <ulink url="ENCRYPTION.html">Encryption chapter</ulink> 
-of this HOWTO Collection.
+manpage.
 </para>
 
 
@@ -56,46 +60,28 @@ of this HOWTO Collection.
 Background
 </title>
 
-<note>
 <para>
-<emphasis>Author's Note:</emphasis> This document is a combination 
-of David Bannon's "Samba 2.2 PDC HOWTO" and "Samba NT Domain FAQ". 
-Both documents are superseded by this one.
-</para>
-</note>
-
-<para>
-Versions of Samba prior to release 2.2 had marginal capabilities to act
-as a Windows NT 4.0 Primary Domain Controller
-<indexterm><primary>Primary Domain Controller</primary></indexterm>
-(PDC).  With Samba 2.2.0, we are proud to announce official support for
-Windows NT 4.0-style domain logons from Windows NT 4.0 and Windows 
-2000 clients.  This article outlines the steps
-necessary for configuring Samba as a PDC.  It is necessary to have a
-working Samba server prior to implementing the PDC functionality.  If
-you have not followed the steps outlined in <ulink
-url="UNIX_INSTALL.html"> UNIX_INSTALL.html</ulink>, please make sure
-that your server is configured correctly before proceeding.  Another
-good resource in the <ulink url="smb.conf.5.html">smb.conf(5) man
-page</ulink>. The following functionality should work in 2.2:
+This article outlines the steps necessary for configuring Samba as a PDC.
+It is necessary to have a working Samba server prior to implementing the
+PDC functionality.
 </para>
 
 <itemizedlist>
 	<listitem><para>
-	domain logons for Windows NT 4.0/2000 clients.
+	domain logons for Windows NT 4.0 / 200x / XP Professional clients.
 	</para></listitem>
 	
 	<listitem><para>
-	placing a Windows 9x client in user level security
+	placing Windows 9x / Me clients in user level security
 	</para></listitem>
 	
 	<listitem><para>
 	retrieving a list of users and groups from a Samba PDC to
-	Windows 9x/NT/2000 clients
+	Windows 9x / Me / NT / 200x / XP Professional clients
 	</para></listitem>
 	
 	<listitem><para>
-	roving (roaming) user profiles
+	roaming user profiles
 	</para></listitem>
 	
 	<listitem><para>
@@ -105,7 +91,7 @@ page</ulink>. The following functionality should work in 2.2:
 
 
 <para>
-The following pieces of functionality are not included in the 2.2 release:
+The following functionalities are new to the Samba 3.0 release:
 </para>
 
 <itemizedlist>
@@ -114,31 +100,42 @@ The following pieces of functionality are not included in the 2.2 release:
 	</para></listitem>
 	
 	<listitem><para>
+	Adding users via the User Manager for Domains
+	</para></listitem>
+</itemizedlist>
+
+<para>
+The following functionalities are NOT provided by Samba 3.0:
+</para>
+
+<itemizedlist>
+	<listitem><para>
 	SAM replication with Windows NT 4.0 Domain Controllers
 	(i.e. a Samba PDC and a Windows NT BDC or vice versa) 
 	</para></listitem>
 	
 	<listitem><para>
-	Adding users via the User Manager for Domains
-	</para></listitem>
-
-	<listitem><para>
 	Acting as a Windows 2000 Domain Controller (i.e. Kerberos and 
 	Active Directory)
 	</para></listitem>
 </itemizedlist>
 
 <para>
-Please note that Windows 9x clients are not true members of a domain
+Please note that Windows 9x / Me / XP Home clients are not true members of a domain
 for reasons outlined in this article.  Therefore the protocol for
 support Windows 9x-style domain logons is completely different
-from NT4 domain logons and has been officially supported for some 
+from NT4 / Win2k type domain logons and has been officially supported for some 
 time.
 </para>
 
+<para><emphasis>
+MS Windows XP Home edition is NOT able to join a domain and does not permit
+the use of domain logons.</emphasis>
+</para>
+
 
 <para>
-Implementing a Samba PDC can basically be divided into 2 broad
+Implementing a Samba PDC can basically be divided into 3 broad
 steps.
 </para>
 
@@ -148,8 +145,11 @@ steps.
 	</para></listitem>
 	
 	<listitem><para>
-	Creating machine trust accounts	and joining clients 
-	to the domain
+	Creating machine trust accounts	and joining clients to the domain
+	</para></listitem>
+
+	<listitem><para>
+	Adding and managing domain user accounts
 	</para></listitem>
 </orderedlist>
 
@@ -157,7 +157,7 @@ steps.
 There are other minor details such as user profiles, system
 policies, etc...  However, these are not necessarily specific
 to a Samba PDC as much as they are related to Windows NT networking
-concepts.  They will be mentioned only briefly here.
+concepts.
 </para>
 
 </sect1>
@@ -174,11 +174,10 @@ concepts.  They will be mentioned only briefly here.
 
 <para>
 The first step in creating a working Samba PDC is to 
-understand the parameters necessary in smb.conf.  I will not
-attempt to re-explain the parameters here as they are more that
-adequately covered in <ulink url="smb.conf.5.html"> the smb.conf
-man page</ulink>.  For convenience, the parameters have been
-linked with the actual smb.conf description.
+understand the parameters necessary in smb.conf. Here we
+attempt to explain the parameters that are covered in
+<ulink url="smb.conf.5.html"> the smb.conf
+man page</ulink>.
 </para>
 
 <para>
@@ -209,8 +208,7 @@ Here is an example <filename>smb.conf</filename> for acting as a PDC:
     ; where to store user profiles?
     <ulink url="smb.conf.5.html#LOGONPATH">logon path</ulink> = \\%N\profiles\%u
     
-    ; where is a user's home directory and where should it
-    ; be mounted at?
+    ; where is a user's home directory and where should it be mounted at?
     <ulink url="smb.conf.5.html#LOGONDRIVE">logon drive</ulink> = H:
     <ulink url="smb.conf.5.html#LOGONHOME">logon home</ulink> = \\homeserver\%u
     
@@ -256,20 +254,16 @@ There are a couple of points to emphasize in the above configuration.
 </itemizedlist>    
 
 <para>
-As Samba 2.2 does not offer a complete implementation of group mapping
+Samba 3.0 offers a complete implementation of group mapping
 between Windows NT groups and Unix groups (this is really quite
-complicated to explain in a short space), you should refer to the
-<ulink url="smb.conf.5.html#DOMAINADMINGROUP">domain admin
-group</ulink> smb.conf parameter for information of creating "Domain
-Admins" style accounts.
+complicated to explain in a short space).
 </para>
 
 </sect1>
 
 
 <sect1>
-<title>Creating Machine Trust Accounts and Joining Clients to the
-Domain</title>
+<title>Creating Machine Trust Accounts and Joining Clients to the Domain</title>
 
 <para>
 A machine trust account is a Samba account that is used to
@@ -282,15 +276,65 @@ The password of a machine trust account acts as the shared secret for
 secure communication with the Domain Controller.  This is a security
 feature to prevent an unauthorized machine with the same NetBIOS name
 from joining the domain and gaining access to domain user/group
-accounts.  Windows NT and 2000 clients use machine trust accounts, but
-Windows 9x clients do not.  Hence, a Windows 9x client is never a true
-member of a domain because it does not possess a machine trust
-account, and thus has no shared secret with the domain controller.
+accounts.  Windows NT, 200x, XP Professional clients use machine trust
+accounts, but Windows 9x / Me / XP Home clients do not.  Hence, a
+Windows 9x / Me / XP Home  client is never a true member of a domain
+because it does not possess a machine trust account, and thus has no
+shared secret with the domain controller.
 </para>
 
 <para>A Windows PDC stores each machine trust account in the Windows
-Registry.  A Samba PDC, however, stores each machine trust account 
-in two parts, as follows:
+Registry. A Samba-3 PDC also has to stoe machine trust account information
+in a suitable back-end data store. With Samba-3 there can be multiple back-ends
+for this including:
+</para>
+
+<itemizedlist>
+	<listitem><para>
+	<emphasis>smbpaswd</emphasis> - the plain ascii file stored used by
+	earlier versions of Samba. This file configuration option requires
+	a Unix/Linux system account for EVERY entry (ie: both for user and for
+	machine accounts). This file will be located in the <emphasis>private</emphasis>
+	directory (default is /usr/local/samba/lib/private or on linux /etc/samba).
+	</para></listitem>
+
+	<listitem><para>
+	<emphasis>smbpasswd_nua</emphasis> - This file is independant of the
+	system wide user accounts. The use of this back-end option requires
+	specification of the "non unix account range" option also. It is called
+	smbpasswd and will be located in the <filename>private</filename> directory.
+	</para></listitem>
+
+	<listitem><para>
+	<emphasis>tdbsam</emphasis> - a binary database backend that will be
+	stored in the <emphasis>private</emphasis> directory in a file called
+	<emphasis>passwd.tdb</emphasis>. The key benefit of this binary format
+	file is that it can store binary objects that can not be accomodated
+	in the traditional plain text smbpasswd file.
+	</para></listitem>
+
+	<listitem><para>
+	<emphasis>tdbsam_nua</emphasis> like the smbpasswd_nua option above, this
+	file allows the creation of arbitrary user and machine accounts without
+	requiring that account to be added to the system (/etc/passwd) file. It
+	too requires the specification of the "non unix account range" option
+	in the [globals] section of the smb.conf file.
+	</para></listitem>
+
+	<listitem><para>
+	<emphasis>ldapsam</emphasis> - An LDAP based back-end. Permits the
+	LDAP server to be specified. eg: ldap://localhost or ldap://frodo.murphy.com
+	</para></listitem>
+
+	<listitem><para>
+	<emphasis>ldapsam_nua</emphasis> - LDAP based back-end with no unix
+	account requirement, like smbpasswd_nua and tdbsam_nua above.
+	</para></listitem>
+</itemizedlist>
+
+<para>
+A Samba PDC, however, stores each machine trust account in two parts,
+as follows:
 
 <itemizedlist>
     <listitem><para>A Samba account, stored in the same location as user
diff --git a/docs/docbook/projdoc/ServerType.sgml b/docs/docbook/projdoc/ServerType.sgml
new file mode 100644
index 0000000000..65544572b7
--- /dev/null
+++ b/docs/docbook/projdoc/ServerType.sgml
@@ -0,0 +1,140 @@
+<chapter id="ServerType">
+<chapterinfo>
+        <author>
+                <firstname>John H</firstname><surname>Terpstra</surname>
+                <affiliation>
+                        <orgname>Samba Team</orgname>
+                        <address><email>jht@samba.org</email></address>
+                </affiliation>
+        </author>
+</chapterinfo>
+
+<title>Nomenclature of Server Types</title>
+
+<para>Adminstrators of Microsoft networks often refer to there being three
+different type of servers:</para>
+
+<itemizedlist>
+	<listitem><para>Stand Alone Server</para></listitem>
+	<listitem><para>Domain Member Server</para></listitem>
+	<listitem><para>Domain Controller</para>
+		<itemizedlist>
+			<listitem><para>Primary Domain Controller</para></listitem>
+			<listitem><para>Backup Domain Controller</para></listitem>
+		</itemizedlist>
+	</listitem>
+</itemizedlist>
+
+<para>A network administrator who is familiar with these terms and who
+wishes to migrate to or use Samba will want to know what these terms mean
+within a Samba context.</para>
+
+<sect1>
+<title>Stand Alone Server</title>
+
+<para>
+The term <emphasis>stand alone server</emphasis> means that the server
+will provide local authentication and access control for all resources
+that are available from it. In general this means that there will be a
+local user database. In more technical terms, it means that resources
+on the machine will either be made available in either SHARE mode or in
+USER mode. SHARE mode and USER mode security are documented under
+discussions regarding "security mode". The smb.conf configuration parameters
+that control security mode are: "security = user" and "security = share".
+</para>
+
+<para>
+Samba tends to blur the distinction a little in respect of what is
+a stand alone server. This is because the authentication database may be
+local or on a remote server, even if from the samba protocol perspective
+the samba server is NOT a member of a domain security context.
+</para>
+
+<para>
+Through the use of PAM (Pluggable Authentication Modules) and nsswitch
+(the name service switcher) the source of authentication may reside on 
+another server. We would be inclined to call this the authentication server.
+This means that the samba server may use the local Unix/Linux system
+password database (/etc/passwd or /etc/shadow), may use a local smbpasswd
+file (/etc/samba/smbpasswd or /usr/local/samba/lib/private/smbpasswd), or
+may use an LDAP back end, or even via PAM and Winbind another CIFS/SMB
+server for authentication.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Domain Member Server</title>
+
+<para>
+This mode of server operation involves the samba machine being made a member
+of a domain security context. This means by definition that all user authentication
+will be done from a centrally defined authentication regime. The authentication
+regime may come from an NT3/4 style (old domain technology) server, or it may be
+provided from an Active Directory server (ADS) running on MS Windows 2000 or later.
+>/para>
+
+<para><emphasis>
+Of course it should be clear that the authentication back end itself could be from any
+distributed directory architecture server that is supported by Samba. This can be
+LDAP (from OpenLDAP), or Sun's iPlanet, of NetWare Directory Server, etc.
+</emphasis></para>
+
+<para>
+Please refer to the section on Howto configure Samba as a Primary Domain Controller
+and for more information regarding how to create a domain machine account for a
+domain member server as well as for information regading how to enable the samba
+domain member machine to join the domain and to be fully trusted by it.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Domain Controller</title>
+
+<para>
+Over the years public perceptions of what Domain Control really is has taken on an
+almost mystical nature. Before we branch into a brief overview of what Domain Control
+is the following types of controller are known:
+</para>
+
+<sect2>
+<title>Domain Controller Types</title>
+
+<simplelist>
+	<member>Primary Domain Controller</member>
+	<member>Backup Domain Controller</member>
+	<member>ADS Domain Controller</member>
+</simplelist>
+
+<para>
+The <emphasis>Primary Domain Controller</emphasis> or PDC plays an important role in the MS 
+Windows NT3 and NT4 Domain Control architecture, but not in the manner that so many
+expect. The PDC seeds the Domain Control database (a part of the Windows registry) and
+it plays a key part in synchronisation of the domain authentication database. 
+</para>
+
+<para>
+New to Samba-3.0.0 is the ability to use a back-end file that holds the same type of data as
+the NT4 style SAM (Security Account Manager) database (one of the registry files).
+The samba-3.0.0 SAM can be specified via the smb.conf file parameter "passwd backend" and
+valid options include <emphasis> smbpasswd tdbsam ldapsam nisplussam plugin unixsam</emphasis>.
+The smbpasswd, tdbsam and ldapsam options can have a "_nua" suffix to indicate that No Unix
+Accounts need to be created. In other words, the Samba SAM will be independant of Unix/Linux
+system accounts, provided a uid range is defined from which SAM accounts can be created.
+</para>
+
+<para>
+The <emphasis>Backup Domain Controller</emphasis> or BDC plays a key role in servicing network
+authentication requests. The BDC is biased to answer logon requests so that on a network segment
+that has a BDC and a PDC the BDC will be most likely to service network logon requests. The PDC will
+answer network logon requests when the BDC is too busy (high load). A BDC can be promoted to
+a PDC. If the PDC is on line at the time that the BDC is promoted to PDC the previous PDC is
+automatically demoted to a BDC.
+</para>
+
+<para>
+At this time Samba is NOT capable of acting as an <emphasis>ADS Domain Controller</emphasis>.
+
+</sect2>
+</sect1>
diff --git a/docs/docbook/projdoc/passdb.sgml b/docs/docbook/projdoc/passdb.sgml
index 222b4010ab..fa2d75bd34 100644
--- a/docs/docbook/projdoc/passdb.sgml
+++ b/docs/docbook/projdoc/passdb.sgml
@@ -30,6 +30,16 @@
 			</address>
 		</affiliation>
 	</author>
+	<author>
+		<firstname>John H</firstname><surname>Terpstra</surname>
+		<affiliation>
+			<orgname>Samba Team</orgname>
+			<address>
+				<email>jht@samba.org</email>
+			</address>
+		</affiliation>
+	</author>
+	
 	<pubdate>February 2003</pubdate>
 </chapterinfo>
 
@@ -104,6 +114,10 @@
 		<para>Other Microsoft operating systems which also exhibit 
 		this behavior includes</para>
 		
+		<para> These versions of MS Windows do not support full domain
+		security protocols, although they may log onto a domain environment.
+		Of these Only MS Windows XP Home does NOT support domain logons.</para>
+
 		<simplelist>
 			<member>MS DOS Network client 3.0 with 
 			the basic network redirector installed</member>
@@ -112,8 +126,25 @@
 			update installed</member>
 			
 			<member>Windows 98 [se]</member>
+
+			<member>Windows Me</member>
+
+			<member>Windows XP Home</member>
+		</simplelist>
+
+		<para> The following versions of MS Windows fully support domain
+		security protocols.</para>
+
+		<simplelist>
+			<member>Windows NT 3.5x</member>
+
+			<member>Windows NT 4.0</member>
 			
-			<member>Windows 2000</member>
+			<member>Windows 2000 Professional</member>
+
+			<member>Windows 200x Server/Advanced Server</member>
+
+			<member>Windows XP Professional</member>
 		</simplelist>
 		
 		<para><emphasis>Note :</emphasis>All current release of 
@@ -121,23 +152,36 @@
 		SMB Challenge/Response mechanism described here.  Enabling
 		clear text authentication does not disable the ability
 		of the client to participate in encrypted authentication.</para>
+
+
+		<para>MS Windows clients will cache the encrypted password alone.
+		Even when plain text passwords are re-enabled, through the appropriate
+		registry change, the plain text password is NEVER cached. This means that
+		in the event that a network connections should become disconnected (broken)
+		only the cached (encrypted) password will be sent to the resource server
+		to affect a auto-reconnect. If the resource server does not support encrypted
+		passwords the auto-reconnect will fail. <emphasis>USE OF ENCRYPTED PASSWORDS
+		IS STRONGLY ADVISED.</emphasis></para>
 	</warning>
 
 	<sect2>
 		<title>Advantages of SMB Encryption</title>
 
 		<simplelist>
-			<member>plain text passwords are not passed across 
+			<member>Plain text passwords are not passed across 
 			the network. Someone using a network sniffer cannot just 
 			record passwords going to the SMB server.</member>
 		 
 			<member>WinNT doesn't like talking to a server 
-			that isn't using SMB encrypted passwords. It will refuse 
+			that SM not support encrypted passwords. It will refuse 
 			to browse the server if the server is also in user level 
 			security mode. It will insist on prompting the user for the 
 			password on each connection, which is very annoying. The
 			only things you can do to stop this is to use SMB encryption.
 			</member>
+
+			<member>Encrypted password support allows auto-matic share
+			(resource) reconnects.</member>
 		</simplelist>
 	</sect2>
 
@@ -146,16 +190,15 @@
 		<title>Advantages of non-encrypted passwords</title>
 
 		<simplelist>
-			<member>plain text passwords are not kept 
-			on disk. </member>
+			<member>Plain text passwords are not kept 
+			on disk, and are NOT cached in memory. </member>
 			
-			<member>uses same password file as other unix 
+			<member>Uses same password file as other unix 
 			services such as login and ftp</member>
 			
-			<member>you are probably already using other 
-			services (such as telnet and ftp) which send plain text 
-			passwords over the net, so sending them for SMB isn't 
-			such a big deal.</member>
+			<member>Use of other services (such as telnet and ftp) which
+			send plain text passwords over the net, so sending them for SMB
+			isn't such a big deal.</member>
 		</simplelist>
 	</sect2>
 </sect1>
@@ -166,8 +209,7 @@
 	
 	<para>The smbpasswd utility is a utility similar to the 
 	<command>passwd</command> or <command>yppasswd</command> programs.
-	It maintains the two 32 byte password fields 
-	in the passdb backend. </para>
+	It maintains the two 32 byte password fields in the passdb backend. </para>
 
 	<para><command>smbpasswd</command> works in a client-server mode 
 	where it contacts the local smbd to change the user's password on its 
@@ -352,11 +394,12 @@ the details of configuring these packages are beyond the scope of this document.
 <title>Supported LDAP Servers</title>
 
 <para>
-The LDAP samdb code in 2.2.3 has been developed and tested using the OpenLDAP
-2.0 server and client libraries.  The same code should be able to work with
-Netscape's Directory Server and client SDK. However, due to lack of testing
-so far, there are bound to be compile errors and bugs.  These should not be
-hard to fix. If you are so inclined, please be sure to forward all patches to
+The LDAP samdb code in 2.2.3 (and later) has been developed and tested
+using the OpenLDAP 2.0 server and client libraries. 
+The same code should be able to work with Netscape's Directory Server
+and client SDK. However, due to lack of testing so far, there are bound
+to be compile errors and bugs.  These should not be hard to fix.
+If you are so inclined, please be sure to forward all patches to
 <ulink url="samba-patches@samba.org">samba-patches@samba.org</ulink> and
 <ulink url="jerry@samba.org">jerry@samba.org</ulink>.
 </para>
diff --git a/docs/docbook/projdoc/samba-doc.sgml b/docs/docbook/projdoc/samba-doc.sgml
index c1662ee3bf..d06d86337d 100644
--- a/docs/docbook/projdoc/samba-doc.sgml
+++ b/docs/docbook/projdoc/samba-doc.sgml
@@ -5,6 +5,7 @@
 <!ENTITY DOMAIN-MEMBER SYSTEM "DOMAIN_MEMBER.sgml">
 <!ENTITY WINBIND SYSTEM "winbind.sgml">
 <!ENTITY NT-Security SYSTEM "NT_Security.sgml">
+<!ENTITY ServerType SYSTEM "ServerType.sgml">
 <!ENTITY Samba-PDC-HOWTO SYSTEM "Samba-PDC-HOWTO.sgml">
 <!ENTITY Samba-BDC-HOWTO SYSTEM "Samba-BDC-HOWTO.sgml">
 <!ENTITY IntegratingWithWindows SYSTEM "Integrating-with-Windows.sgml">
@@ -91,6 +92,7 @@ Samba can operate in various SMB networks. This part contains information on con
 for various environments.
 </para>
 </partintro>
+&ServerType;
 &SECURITY-LEVEL;
 &Samba-PDC-HOWTO;
 &Samba-BDC-HOWTO;
diff --git a/docs/docbook/projdoc/security_level.sgml b/docs/docbook/projdoc/security_level.sgml
index e2d9cfbbaa..00dcc6e83b 100644
--- a/docs/docbook/projdoc/security_level.sgml
+++ b/docs/docbook/projdoc/security_level.sgml
@@ -9,7 +9,7 @@
 	</author>
 </chapterinfo>
 
-<title>User and Share security level (for servers not in a domain)</title>
+<title>Samba as Stand-Alone server (User and Share security level)</title>
 
 <para>
 A SMB server tells the client at startup what "security level" it is
diff --git a/docs/docbook/projdoc/unicode.sgml b/docs/docbook/projdoc/unicode.sgml
index a467a0d4e7..7d8f0a03be 100644
--- a/docs/docbook/projdoc/unicode.sgml
+++ b/docs/docbook/projdoc/unicode.sgml
@@ -2,10 +2,10 @@
 <chapterinfo>
 	<author>
 		<firstname>Jelmer</firstname><surname>Vernooij</surname>
-		<affiliate>
+		<affiliation>
 			<orgname>Samba Team</orgname>
 			<address><email>jelmer@samba.org</email></address>
-		</affiliate>
+		</affiliation>
 	</author>
 	<pubdate>25 March 2003</pubdate>
 </chapterinfo>
@@ -18,8 +18,8 @@
 <para>
 Computers communicate in numbers. In texts, each number will be 
 translated to a corresponding letter. The meaning that will be assigned 
-to a certain number depends on the <emphasize>character set(charset)
-</emphasize> that is used. 
+to a certain number depends on the <emphasis>character set(charset)
+</emphasis> that is used. 
 A charset can be seen as a table that is used to translate numbers to 
 letters. Not all computers use the same charset (there are charsets 
 with German umlauts, Japanese characters, etc). Usually a charset contains 
@@ -64,7 +64,7 @@ samba knows of three kinds of character sets:
 		<term>unix charset</term>
 		<listitem><para>
 		This is the charset used internally by your operating system. 
-		The default is <emphasize>ASCII</emphasize>, which is fine for most 
+		The default is <emphasis>ASCII</emphasis>, which is fine for most 
 		systems.
 		</para></listitem>
 	</varlistentry>