* working on Makefile

* converting printing internal doc to SGML

3 files changed, 250 insertions, 118 deletions

diff --git a/docs/docbook/Makefile.in b/docs/docbook/Makefile.in
index 492aa85ba44..c79c9008ffa 100644
--- a/docs/docbook/Makefile.in
+++ b/docs/docbook/Makefile.in
@@ -61,7 +61,7 @@ pdf: ../Samba-HOWTO-Collection.pdf ../Samba-Developers-Guide.pdf
 ps: ../Samba-HOWTO-Collection.ps ../Samba-Developers-Guide.ps
 txt: ../textdocs/Samba-HOWTO-Collection.txt ../textdocs/Samba-Developers-Guide.txt
 htmlman:  $(MANPAGES_HTML)
-html-single: ../htmldocs/Samba-HOWTO-Collection.html  ../htmldocs/Samba-Developers-Guide.html
+html-single: ../$(HTMLDIR)/Samba-HOWTO-Collection.html  ../$(HTMLDIR)/Samba-Developers-Guide.html
 html:
 	$(DOCBOOK2HTML) -d samba.dsl -o $(HTMLDIR) projdoc/samba-doc.sgml
 
@@ -81,17 +81,17 @@ html:
 	$(DOCBOOK2PS) -o .. $<
 	mv ../samba-doc.ps $@
 
-../Samba-HOWTO-Collection.pdf: ../htmldocs/Samba-HOWTO-Collection.html
+../Samba-HOWTO-Collection.pdf: ../$(HTMLDIR)/Samba-HOWTO-Collection.html
 	$(HTMLDOC) --book --color --links -f $@ $<
 
-../Samba-Developers-Guide.pdf: ../htmldocs/Samba-Developers-Guide.html
+../Samba-Developers-Guide.pdf: ../$(HTMLDIR)/Samba-Developers-Guide.html
 	$(HTMLDOC) --book --color --links -f $@ $<
 
-../htmldocs/Samba-HOWTO-Collection.html: $(SGMLDIR)/samba-doc.sgml
+../$(HTMLDIR)/Samba-HOWTO-Collection.html: $(SGMLDIR)/samba-doc.sgml
 	$(DOCBOOK2HTML) -u -o .. $<
 	mv ../samba-doc.html $@
 
-../htmldocs/Samba-Developers-Guide.html: devdoc/dev-doc.sgml
+../$(HTMLDIR)/Samba-Developers-Guide.html: devdoc/dev-doc.sgml
 	$(DOCBOOK2HTML) -u -o .. $<
 	mv ../dev-doc.html $@
 
@@ -106,4 +106,4 @@ $(MANDIR)/%: $(MANSGMLDIR)/%.sgml
 	mv $@.temp $@
 
 clean: 
-	rm -f $(MANPAGES) $(MANPAGES_HTML) ../htmldocs/*.html ../Samba-HOWTO-Collection.p* ../Samba-Developers-Guide.p*
+	rm -f $(MANPAGES) $(MANPAGES_HTML) ../$(HTMLDIR)/*.html ../Samba-HOWTO-Collection.p* ../Samba-Developers-Guide.p*
diff --git a/docs/docbook/devdoc/dev-doc.sgml b/docs/docbook/devdoc/dev-doc.sgml
index c1ffb735bad..965d7a1ea88 100644
--- a/docs/docbook/devdoc/dev-doc.sgml
+++ b/docs/docbook/devdoc/dev-doc.sgml
@@ -8,6 +8,7 @@
 <!ENTITY CodingSuggestions SYSTEM "CodingSuggestions.sgml">
 <!ENTITY Tracing SYSTEM "Tracing.sgml">
 <!ENTITY cifsntdomain SYSTEM "cifsntdomain.sgml">
+<!ENTITY printing SYSTEM "printing.sgml">
 ]>
 
 <book id="Samba-Developer-Documentation">
@@ -25,7 +26,7 @@
 <title>Abstract</title>
 
 <para>
-<emphasis>Last Update</emphasis> : Mon aug 26 12:41:19 CEST 2002
+<emphasis>Last Update</emphasis> : Mon Sep 30 15:23:53 CDT 2002
 </para>
 
 <para>
@@ -58,5 +59,6 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt</u
 &unix-smb;
 &Tracing;
 &cifsntdomain;
+&printing;
 
 </book>
diff --git a/docs/docbook/devdoc/printing.sgml b/docs/docbook/devdoc/printing.sgml
index 2e9d429439e..c95d5460b7c 100644
--- a/docs/docbook/devdoc/printing.sgml
+++ b/docs/docbook/devdoc/printing.sgml
@@ -1,49 +1,80 @@
-!=
-!= Samba Printing Internals
-!=
-!= Author : Gerald Carter <jerry@samba.org>
-!=
-!===================================================================
+<chapter id="printing">
+<chapterinfo>
+	<author>
+		<firstname>Gerald</firstname><surname>Carter</surname>
+	</author>
+	<pubdate>October 2002</pubdate>
+</chapterinfo>
 
+
+<title>Samba Printing Internals</title>
+
+
+<sect1>
+<title>Abstract</title>
+<para>
 The purpose of this document is to provide some insight into
 Samba's printing functionality and also to describe the semantics
 of certain features of Windows client printing.
+</para>
+</sect1>
 
 
+
+<sect1>
+<title>
 Printing Interface to Various Backends
---------------------------------------
+</title>
 
+<para>
 Samba uses a table of function pointers to seven functions.  The
-function prototypes are defined in the printif structure declared
-in printing.h.
-
-  * retrieve the contents of a print queue
-  * pause the print queue
-  * resume a paused print queue
-  * delete a job from the queue
-  * pause a job in the print queue
-  * result a paused print job in the queue
-  * submit a jobn to the print queue
-
+function prototypes are defined in the <VarName>printif</VarName> structure declared
+in <filename>printing.h</filename>.
+</para>
+
+<itemizedlist>
+	<listitem><para>retrieve the contents of a print queue</para></listitem>
+	<listitem><para>pause the print queue</para></listitem>
+	<listitem><para>resume a paused print queue</para></listitem>
+	<listitem><para>delete a job from the queue</para></listitem>
+	<listitem><para>pause a job in the print queue</para></listitem>
+	<listitem><para>result a paused print job in the queue</para></listitem>
+	<listitem><para>submit a jobn to the print queue</para></listitem>
+</itemizedlist>
+
+<para>
 Currently there are only two printing backend implementations
 defined.
+</para>
+
+<itemizedlist>
+	<listitem><para>a generic set of functions for working with standard UNIX
+	printing subsystems</para></listitem>
+
+	<listitem><para>a set of CUPS specific functions (this is only enabled if
+	the CUPS libraries were located at compile time).</para></listitem>
+</itemizedlist>
+
+</sect1>
 
-  * a generic set of functions for working with standard UNIX
-    printing subsystems
-  * a set of CUPS specific functions (this is only enabled if
-    the CUPS libraries were located at compile time).
 
 
 
+<sect1>
+<title>
 Print Queue TDB's
-------------------
+</title>
 
+
+<para>
 Samba provides periodic caching of the output from the "lpq command"
 for performance reasons.  This cache time is configurable in seconds.
 Obviously the longer the cache time the less often smbd will be
 required to exec a copy of lpq.  However, the accuracy of the print
 queue contents displayed to clients will be diminished as well.
+</para>
 
+<para>
 The list of currently opened print queue TDB's can eb found
 be examining the list of tdb_print_db structures ( see print_db_head
 in printing.c ). A queue TDB is opened using the wrapper function
@@ -53,13 +84,17 @@ a large print server from exhausting all available file descriptors.
 If the number of open queue TDB's exceeds the MAX_PRINT_DBS_OPEN
 limit, smbd falls back to a most recently used algorithm for maintaining
 a list of open TDB's.
+</para>
 
+<para>
 There are two ways in which a a print job can be entered into
 a print queue's TDB.  The first is to submit the job from a Windows
 client which will insert the job information directly into the TDB.
 The second method is to have the print job picked up by executing the
 "lpq command".
+</para>
 
+<para><programlisting>
 /* included from printing.h */
 struct printjob {
 	pid_t pid; /* which process launched the job */
@@ -77,187 +112,282 @@ struct printjob {
 	fstring queuename; /* service number of printer for this job */
 	NT_DEVICEMODE *nt_devmode;
 };
+</programlisting></para>
 
+<para>
 The current manifestation of the printjob structure contains a field
 for the UNIX job id returned from the "lpq command" and a Windows job
 ID (32-bit bounded by PRINT_MAX_JOBID).  When a print job is returned
 by the "lpq command" that does not match an existing job in th queue's
 TDB, a 32-bit job ID above the is generating by adding UNIX_JOB_START to
 the id reported by lpq.
+</para>
 
+<para>
 In order to match a 32-bit Windows jobid onto a 16-bit lanman print job
 id, smbd uses an in memory TDB to match the former to a number approriate
 for old lanman clients.
+</para>
 
+<para>
 When updating a print queue, smbd will performs the following
-steps ( refer to print.c:print_queue_update() ):
-
-  1) Check to see if another sbmd is currently in the process of
-     updating the queue contents by checking the pid stored in
-     "LOCK/<printer_name>".  If so, then do not update the TDB.
-  2) Lock the mutex entry in the TDB and store our own pid.
-     Check that this succeeded, else fail.
-  3) Store the updated time stamp for the new cache listing
-  4) Retrieve the queue listing via "lpq command"
-  5) foreach job in the queue
-     {
-         if the job is a UNIX job, create a new entry;
-	 if the job has a Windows based jobid, then
-	 {
-	     Lookup the record by the jobid;
-             if the lookup failed, then
-	         treat it as a UNIX job;
-	     else
-	         update the job status only
-	 }
-     }
-  6) Delete any jobs in the TDB that are not in the in the lpq
-     listing
-  7) Store the print queue status in the TDB
-  8) update the cache time stamp again
-
+steps ( refer to <filename>print.c:print_queue_update()</filename> ):
+</para>
+
+<orderedlist>
+	<listitem><para>Check to see if another sbmd is currently in 
+	the process of updating the queue contents by checking the pid 
+	stored in <constant>LOCK/<replaceable>printer_name</replaceable></constant>.  
+	If so, then do not update the TDB.</para></listitem>
+	
+	<listitem><para>Lock the mutex entry in the TDB and store our own pid.
+	Check that this succeeded, else fail.</para></listitem>
+
+	<listitem><para>Store the updated time stamp for the new cache
+	listing</para></listitem>
+
+	<listitem><para>Retrieve the queue listing via "lpq command"</para></listitem>
+
+	<listitem><para><programlisting>
+	foreach job in the queue
+     	{
+		if the job is a UNIX job, create a new entry;
+		if the job has a Windows based jobid, then
+		{
+			Lookup the record by the jobid;
+			if the lookup failed, then
+				treat it as a UNIX job;
+			else
+				update the job status only
+		}
+	}</programlisting></para></listitem>
+
+	<listitem><para>Delete any jobs in the TDB that are not
+	in the in the lpq listing</para></listitem>
+
+	<listitem><para>Store the print queue status in the TDB</para></listitem>
+	
+	<listitem><para>update the cache time stamp again</para></listitem>
+	
+</orderedlist>
+
+<para>
 Note that it is the contents of this TDB that is returned to Windows
 clients and not the actual listing from the "lpq command".
+</para>
 
-The NT_DEVICEMODE stored as part of the printjob structure is used to 
-store a pointer to a non-default DeviceMode associated with the print 
+<para>
+The NT_DEVICEMODE stored as part of the printjob structure is used to
+store a pointer to a non-default DeviceMode associated with the print
 job.  The pointer will be non-null when the client included a Device
-Mode in the OpePrinterEx() call and subsequently submitted a job for 
+Mode in the OpePrinterEx() call and subsequently submitted a job for
 printing on that sam handle.  If the client did not include a Device
 Mode in the OpenPrinterEx() request, the nt_devmode field is NULL
 and the job has the printer's device mode associated with it by default.
+</para>
 
+<para>
 Only non-default Device Mode are stored with print jobs in the print
 queue TDB.  Otherwise, the Device Mode is obtained from the printer
 object when the client issues a GetJob(level == 2) request.
+</para>
 
+</sect1>
 
 
 
 
-
+<sect1>
+<title>
 ChangeID & Client Caching of Printer Information
-------------------------------------------------
+</title>
+
+<para>
+[To be filled in later]
+</para>
+</sect1>
 
-	[To be filled in later]
 
 
+<sect1>
+<title>
 Windows NT/2K Printer Change Notify
------------------------------------
+</title>
 
+<para>
 When working with Windows NT+ clients, it is possible for a
 print server to use RPC to send asynchronous change notification
 events to clients for certain printer and print job attributes.
 This can be useful when the client needs to know that a new
 job has been added to the queue for a given printer or that the
-driver for a printer has been changed.  Note that this is done 
-entirely orthogonal to cache updates based on a new ChangeID for 
+driver for a printer has been changed.  Note that this is done
+entirely orthogonal to cache updates based on a new ChangeID for
 a printer object.
+</para>
 
+<para>
 The basic set of RPC's used to implement change notification are
-
-  * RemoteFindFirstPrinterChangeNotifyEx ( RFFPCN )
-  * RemoteFindNextPrinterChangeNotifyEx ( RFNPCN )
-  * FindClosePrinterChangeNotify( FCPCN )
-  * ReplyOpenPrinter
-  * ReplyClosePrinter
-  * RouteRefreshPrinterChangeNotify ( RRPCN )
-
+</para>
+
+<itemizedlist>
+	<listitem><para>RemoteFindFirstPrinterChangeNotifyEx ( RFFPCN )</para></listitem>
+	<listitem><para>RemoteFindNextPrinterChangeNotifyEx ( RFNPCN )</para></listitem>
+	<listitem><para>FindClosePrinterChangeNotify( FCPCN )</para></listitem>
+	<listitem><para>ReplyOpenPrinter</para></listitem>
+	<listitem><para>ReplyClosePrinter</para></listitem>
+	<listitem><para>RouteRefreshPrinterChangeNotify ( RRPCN )</para></listitem>
+</itemizedlist>
+
+<para>
 One additional RPC is available to a server, but is never used by the
 Windows spooler service:
+</para>
 
-  * RouteReplyPrinter()
+<itemizedlist>
+	<listitem><para>RouteReplyPrinter()</para></listitem>
+</itemizedlist>
 
+<para>
 The opnum for all of these RPC's are defined in include/rpc_spoolss.h
+</para>
 
+<para>
 Windows NT print servers use a bizarre method of sending print
 notification event to clients.  The process of registering a new change
 notification handle is as follows.  The 'C' is for client and the
 'S' is for server.  All error conditions have been eliminated.
+</para>
 
+<para><programlisting>
 C:	Obtain handle to printer or to the printer
 	server via the standard OpenPrinterEx() call.
 S:	Respond with a valid handle to object
 
 C:	Send a RFFPCN request with the previously obtained
 	handle with either (a) set of flags for change events
-	to monitor, or (b) a PRINTER_NOTIFY_OPTIONS structure 
+	to monitor, or (b) a PRINTER_NOTIFY_OPTIONS structure
 	containing the event information to monitor.  The windows
 	spooler has only been observed to use (b).
 S:	The opens a new TCP session to the client (thus requiring
 	all print clients to be CIFS servers as well) and sends
 	a ReplyOpenPrinter() request to the client.
-C:	The client responds with a printer handle that can be used to 
+C:	The client responds with a printer handle that can be used to
 	send event notification messages.
 S:	The server replies success to the RFFPCN request.
 
 C:	The windows spooler follows the RFFPCN with a RFNPCN
-	request to fetch the current values of all monitored 
+	request to fetch the current values of all monitored
 	attributes.
 S:	The server replies with an array SPOOL_NOTIFY_INFO_DATA
 	structures (contained in a SPOOL_NOTIFY_INFO structure).
 
-C:	If the change notification handle is ever released by the 
+C:	If the change notification handle is ever released by the
 	client via a PCPCN request, the server sends a ReplyClosePrinter()
-	request back to the client first.  However a request of this 
+	request back to the client first.  However a request of this
 	nature from the client is often an indication that the previous
 	notification event was not marshalled correctly by the server
 	or a piece of data was wrong.
-S:	The server closes the internal change notification handle 
+S:	The server closes the internal change notification handle
 	(POLICY_HND) and does not send any further change notification
 	events to the client for that printer or job.
+</programlisting></para>
 
-The current list of notification events supported by Samba can be 
+<para>
+The current list of notification events supported by Samba can be
 found by examining the internal tables in srv_spoolss_nt.c
+</para>
 
-  * printer_notify_table[]
-  * job_notify_table[]
+<itemizedlist>
+	<listitem><para>printer_notify_table[]</para></listitem>
+	<listitem><para>job_notify_table[]</para></listitem>
+</itemizedlist>
 
+<para>
 When an event occurs that could be monitored, smbd sends a messages
-to itself about the change.  The list of events to be transmitted 
-are queued by the smbd process sending the message to prevent and 
+to itself about the change.  The list of events to be transmitted
+are queued by the smbd process sending the message to prevent and
 overload of TDB usage and the internal message is sent during smbd's
 idle loop (refer to printing/notify.c and the functions
 send_spoolss_notify2_msg() and print_notify_send_messages() ).
+</para>
 
-
-The decision of whether or not the change is to be sent to connected 
+<para>
+The decision of whether or not the change is to be sent to connected
 clients is made by the routine which actually sends the notification.
-( refer to srv_spoolss_nt.c:recieve_notify2_message() ).  
+( refer to srv_spoolss_nt.c:recieve_notify2_message() ).
+</para>
 
-Because it possible to recieve a listing of multiple changes for 
+<para>
+Because it possible to recieve a listing of multiple changes for
 multiple printers the notification events must be split into
-categories by the printer name.  This makes it possible to group 
+categories by the printer name.  This makes it possible to group
 multiple change events to be sent in a single RPC according to the
 printer handle obtained via a ReplyOpenPrinter().
+</para>
+
+<para>
+The actual change notification is performed using the RRPCN request
+RPC.  This packet contains
+</para>
+
+
+<itemizedlist>
+	
+<listitem><para>the printer handle registered with the
+client's spooler on which the change occurred</para></listitem>
+
+<listitem><para>The change_low value which was sent as part
+of the last RFNPCN request from the client</para></listitem>
+
+<listitem><para>The SPOOL_NOTIFY_INFO container with the event
+information</para></listitem>
+
+</itemizedlist>
+
+<para>
+A <VarName>SPOOL_NOTIFY_INFO</VarName> contains:
+</para>
+
+<itemizedlist>
+
+<listitem><para>the version and flags field are predefined
+and should not be changed</para></listitem>
+
+<listitem><para>The count field is the number of entries
+in the SPOOL_NOTIFY_INFO_DATA array</para></listitem>
+
+</itemizedlist>
+
+<para>
+The <VarName>SPOOL_NOTIFY_INFO_DATA</VarName> entries contain:
+</para>
+
+<itemizedlist>
+
+<listitem><para>The type defines whether or not this event
+is for a printer or a print job</para></listitem>
+
+<listitem><para>The field is the flag identifying the event</para></listitem>
+
+<listitem><para>the notify_data union contains the new valuie of the
+attribute</para></listitem>
+
+<listitem><para>The enc_type defines the size of the structure for marshalling
+and unmarshalling</para></listitem>
+
+<listitem><para>(a) the id must be 0 for a printer event on a printer handle.
+(b) the id must be the job id for an event on a printer job
+(c) the id must be the matching number of the printer index used
+in the response packet to the RFNPCN when using a print server
+handle for notification.  Samba currently uses the snum of
+the printer for this which can break if the list of services
+has been modified since the notification handle was registered.</para></listitem>
 
-The actual change notification is performed using the RRPCN request 
-RPC.  This packet contains 
-
-  * the printer handle registered with the client's spooler on 
-    which the change occurred
-  * The change_low value which was sent as part of the last 
-    RFNPCN request from the client
-  * The SPOOL_NOTIFY_INFO container with the event information
-    - the version and flags field are predefined and should not 
-      be changed
-    - The count field is the number of entries in the 
-      SPOOL_NOTIFY_INFO_DATA array
-      o The type defines whether or not this event is for a printer 
-        or a print job
-      o The field is the flag identifying the event
-      o the notify_data union contains the new valuie of the attribute
-      o The enc_type defines the size of the structure for marshalling
-        and unmarshalling
-      o (a) the id must be 0 for a printer event on a printer handle.
-        (b) the id must be the job id for an event on a printer job
-	(c) the id must be the matching number of the printer index used
-	    in the response packet to the RFNPCN when using a print server
-	    handle for notification.  Samba currently uses the snum of
-	    the printer for this which can break if the list of services
-	    has been modified since the notification handle was registered.
-       o The size is either (a) the string length in UNICODE for strings,
-         (b) the size in bytes of the security descriptor, or (c) 0 for
-	 data values.
+<listitem><para>The size is either (a) the string length in UNICODE for strings,
+(b) the size in bytes of the security descriptor, or (c) 0 for
+data values.</para></listitem>
 
+</itemizedlist>
 
+</sect1>
+</chapter>