Index: /pykota/trunk/docs/introduction.sgml
===================================================================
--- /pykota/trunk/docs/introduction.sgml (revision 2834)
+++ /pykota/trunk/docs/introduction.sgml (revision 2836)
@@ -219,4 +219,10 @@
                 </para>
               </listitem>  
+              <listitem>
+                <para>
+                  <command>pkinvoice</command> : an invoice generator which can create personalized PDF invoices
+                  for your users from their printing history.
+                </para>
+              </listitem>  
             </itemizedlist>
           </para>
Index: /pykota/trunk/docs/pkinvoice.sgml
===================================================================
--- /pykota/trunk/docs/pkinvoice.sgml (revision 2836)
+++ /pykota/trunk/docs/pkinvoice.sgml (revision 2836)
@@ -0,0 +1,27 @@
+<!-- $Id$ -->
+
+<chapter>
+  <title>Invoice your users with pkinvoice</title>
+  <para>Last modified on $Date$</para>
+  
+  <para>
+    <command>pkinvoice</command> is a command line tool with which you'll be able to extract jobs from the printing history,
+    and generate nice looking and configurable <acronym>PDF</acronym> invoices.
+  </para>  
+  
+  <para>
+    You'll be allowed to optionally filter the data extraction based on starting and ending dates, which
+    defaults to the complete history,
+    and a set of usernames, which defaults to all users.
+  </para>
+  
+  <para>
+    The generated documents will contain one page per user, and the amount on the invoice will represent
+    how many credits each user spent during the specified time period.
+  </para>
+  
+  <para>
+    For more details, please refer to <command>pkinvoice</command>'s manual page.
+  </para>
+</chapter>
+
Index: /pykota/trunk/docs/pknotify.sgml
===================================================================
--- /pykota/trunk/docs/pknotify.sgml (revision 2836)
+++ /pykota/trunk/docs/pknotify.sgml (revision 2836)
@@ -0,0 +1,87 @@
+<!-- $Id$ -->
+
+<chapter>
+  <title>Interact with end users with pknotify and pykoticon</title>
+  <para>Last modified on $Date$</para>
+  
+  <para>
+    Printing under GNU/Linux and UNIX-Like systems usually lack features to dialog with end users.
+    They usually submit their print jobs, and then wait for them to complete, most of the time
+    silently.
+  </para>
+  
+  <para>
+    Some add-ons to printing systems, like print accounting software, could however benefit
+    a lot from being able to interact with users who submitted print jobs. That's exactly what
+    allow the <command>pknotify</command> and <command>pykoticon</command> commands, and they
+    do so in a completely generic way.
+  </para>
+  
+  <para>
+    <application>PyKotIcon</application> is a cross-platform, generic, networked, dialog box manager
+    which sits on client hosts and listen for incoming connections coming from the print servers.
+    This application is in fact a small server which publishes some of its functions over XML-RPC.
+    These functions offer the following possibilities :
+    <itemizedlist>
+      <listitem>
+        <para>
+          Display an informational message to the end user ;
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Display a message to the end user and asks for confirmation or cancellation.
+          The result is sent back to the calling program, usually on the print server ;
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Asks the end user to fill a simple form containing a number of labelled fields.
+          The values the user typed in are sent back to the calling program, usually on the print server ;
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Automatically shutdown the <application>PyKotIcon</application> application when asked to
+          do so by an authorized host, usually the print server.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </para>
+  
+  <para>
+    It is important to know that <application>PyKotIcon</application> is completely independant from <application>PyKota</application>
+    and can be used outside of <application>PyKota</application>. In reality <application>PyKotIcon</application>
+    knows NOTHING about print accounting, and doesn't need to. That's why it's distributed separately.
+  </para>
+  
+  <para>
+    <application>pknotify</application> is a client program for <application>PyKotIcon</application>, which is usually
+    launched from directives in <filename>~pykota/pykota.conf</filename>, but which can be used directly
+    from the command line as well, if needed.
+  </para>
+  
+  <para>
+    <application>pknotify</application>, through command line options, can use any of the functions published
+    by <application>PyKotIcon</application>. In addition, if it is configured to tell <application>PyKotIcon</application>
+    to ask the end user for an username and password, it can try to authenticate this user with this password on the print server side.
+    This possibility is extremely useful when you allow anonymous logins on printing clients, but still want
+    print accounting to be done on a per user basis : each time an anonymous user prints, we can ask
+    him remotely to enter his authentication credentials. These credentials are then sent back to the
+    print server (NB : in the clear for now), which uses them to decide if printing is to be denied, or
+    allowed to continue until the next phase of print accounting and optional quota enforcement.
+  </para>
+  
+  <para>
+    For more details, see <command>pknotify</command>'s manual page.
+  </para>
+  
+  <warning><title>Warning</title>
+    <para>
+      While <application>PyKotIcon</application> sits on the printing clients, it is in fact
+      a server application. While <application>pknotify</application> is run on the print server,
+      it is in fact a client application to <application>PyKotIcon</application>.
+    </para>
+  </warning>
+</chapter>
+
Index: /pykota/trunk/docs/pykota.sgml
===================================================================
--- /pykota/trunk/docs/pykota.sgml (revision 2833)
+++ /pykota/trunk/docs/pykota.sgml (revision 2836)
@@ -18,4 +18,6 @@
   <!entity PKMAIL system "pkmail.sgml">
   <!entity PKUSERS system "pkusers.sgml">
+  <!entity PKNOTIFY system "pknotify.sgml">
+  <!entity PKINVOICE system "pkinvoice.sgml">
   <!entity GNUGPL system "gnugpl.sgml">
 
@@ -141,5 +143,9 @@
   &AUTOPYKOTA;
   
+  &PKINVOICE;
+  
   &PKBANNER;
+  
+  &PKNOTIFY;
   
   &PKMAIL;
