Index: /pykota/trunk/docs/pkprinters.sgml
===================================================================
--- /pykota/trunk/docs/pkprinters.sgml (revision 1406)
+++ /pykota/trunk/docs/pkprinters.sgml (revision 1406)
@@ -0,0 +1,43 @@
+<!-- $Id$ -->
+
+<chapter>
+  <title>Manage printers with pkprinters</title>
+  <para>Last modified on $Date$</para>
+  
+  <para>
+    <filename>pkprinters</filename> is now the preferred tool to manage printers in <application>PyKota</application>.  
+    It only manages printers, and do it well. With it you can add or delete printers or printer groups, or modify
+    existing printers or printers groups. This is also the tool to use to put printers into one or more printers groups.
+  </para>  
+  
+  <sect1>
+    <title>Reference</title>
+    <para>
+      <cmdsynopsis>
+        <command>pkprinters</command>
+        <group choice="opt"><arg>-v</arg><arg>--version</arg></group>
+        <group choice="opt"><arg>-h</arg><arg>--help</arg></group>
+        <group choice="opt"><arg>-a</arg><arg>--add</arg></group>
+        <group choice="opt"><arg>-d</arg><arg>--delete</arg></group>
+        <group choice="opt"><arg>-r</arg><arg>--remove</arg></group>
+        <group choice="opt">
+          <arg>-c <replaceable>p</replaceable>,<replaceable>j</replaceable></arg>
+          <arg>--charge <replaceable>p</replaceable>,<replaceable>j</replaceable></arg>
+        </group>  
+        <group choice="opt">
+          <arg>-g <replaceable>pgroup1</replaceable>,<replaceable>pgroup2</replaceable>,<replaceable>...</replaceable></arg>
+          <arg>--groups <replaceable>pgroup1</replaceable>,<replaceable>pgroup2</replaceable>,<replaceable>...</replaceable></arg>
+        </group>  
+      </cmdsynopsis>
+    </para>
+  </sect1>
+</chapter>
+
+<!--
+
+$Log$
+Revision 1.1  2004/03/16 14:42:31  jalet
+Improved documentation
+
+
+-->
Index: /pykota/trunk/docs/pykota.sgml
===================================================================
--- /pykota/trunk/docs/pykota.sgml (revision 1288)
+++ /pykota/trunk/docs/pykota.sgml (revision 1406)
@@ -2,9 +2,11 @@
 
   <!entity INSTALLATION system "installation.sgml">
+  <!entity FILTERPYKOTA system "filterpykota.sgml">
+  <!entity PKPRINTERS system "pkprinters.sgml">
   <!entity EDPYKOTA system "edpykota.sgml">
   <!entity REPYKOTA system "repykota.sgml">
   <!entity PYKOTME system "pykotme.sgml">
   <!entity WARNPYKOTA system "warnpykota.sgml">
-  <!entity FILTERPYKOTA system "filterpykota.sgml">
+  <!entity SCRIPTS system "scripts.sgml">
   <!entity GNUGPL system "gnugpl.sgml">
 
@@ -101,6 +103,8 @@
 
   &INSTALLATION;
-
+  
   &FILTERPYKOTA;
+  
+  &PKPRINTERS;
 
   &EDPYKOTA;
@@ -111,4 +115,6 @@
   
   &WARNPYKOTA;
+  
+  &SCRIPTS;
     
   &GNUGPL;
@@ -119,4 +125,7 @@
 
 $Log$
+Revision 1.11  2004/03/16 14:42:31  jalet
+Improved documentation
+
 Revision 1.10  2004/01/12 23:16:42  jalet
 Copyright year.
Index: /pykota/trunk/docs/scripts.sgml
===================================================================
--- /pykota/trunk/docs/scripts.sgml (revision 1406)
+++ /pykota/trunk/docs/scripts.sgml (revision 1406)
@@ -0,0 +1,125 @@
+<!-- $Id$ -->
+
+<chapter>
+  <title>Useful Shell Scripts</title>
+  <para>Last modified on $Date$</para>
+  
+  <para>
+    <application>PyKota</application> comes with a number of shell scripts which
+    help do complex things. They can be used as-is, but you may prefer to adapt
+    them to your own configuration. All are installed in the <filename>/usr/share/pykota</filename>
+    directory.
+  </para>  
+  
+  <sect1>
+    <title>waitprinter.sh</title>
+    <para>
+      This script which accepts a printer's hostname or <acronym>IP</acronym> address as its first parameter 
+      is used to wait for a printer which supports the <acronym>SNMP</acronym> protocol to be in <literal>idle</literal> state.
+      It exits as soon as the printer is <literal>idle</literal>, else loops forever.
+    </para>
+    
+    <para>
+      When defining an external <literal>requester</literal> for a printer, it is important to wait for the printer being
+      <literal>idle</literal> before asking it for its internal page counter, otherwise results could
+      be inaccurate. If the printer is asked while the job is still being printed, then the page counter's
+      value will be lower than expected with regard to the real job's size.
+    </para>
+    
+    <para>
+      <filename>waitprinter.sh</filename> can be used to be sure that <application>PyKota</application>
+      waits until no job is being printed, and no paper sheet is travelling inside the printer. 
+    </para>
+    
+    <tip>
+      <title>Tip</title>
+      <para>
+        See the sample configuration file <filename>conf/pykota.conf.sample</filename> for examples.
+      </para>
+    </tip>  
+  </sect1>
+  
+  <sect1>
+    <title>papwaitprinter.sh</title>
+    <para>
+      This script which accepts a printer's AppleTalk name as its first parameter 
+      is used to wait for a printer which supports the <acronym>AppleTalk</acronym> protocol to be in <literal>idle</literal> state.
+      It exits as soon as the printer is <literal>idle</literal>, else loops forever.
+    </para>
+    
+    <para>
+      When defining an external <literal>requester</literal> for a printer, it is important to wait for the printer being
+      <literal>idle</literal> before asking it for its internal page counter, otherwise results could
+      be inaccurate. If the printer is asked while the job is still being printed, then the page counter's
+      value will be lower than expected with regard to the real job's size.
+    </para>
+    
+    <para>
+      <filename>papwaitprinter.sh</filename> can be used to be sure that <application>PyKota</application>
+      waits until no job is being printed, and no paper sheet is travelling inside the printer. 
+    </para>  
+    
+    <tip>
+      <title>Tip</title>
+      <para>
+        See the sample configuration file <filename>conf/pykota.conf.sample</filename> for examples.
+      </para>
+    </tip>  
+  </sect1>
+  
+  <sect1>
+    <title>mailandpopup.sh</title>
+    <para>
+      This script can be used in the <literal>mailto</literal> directive of <filename>pykota.conf</filename>
+      to both send an email and display a <application>Winpopup</application> message on the user's screen,
+      whenever print quota is low or reached.
+    </para>
+    
+    <para>
+      For this script to work successfully, you may need to have a <application>Samba</application> 
+      Primary Domain Controller. Some modifications may be needed in other configurations.
+    </para>
+    
+    <tip>
+      <title>Tip</title>
+      <para>
+        See the sample configuration file <filename>conf/pykota.conf.sample</filename> for examples.
+      </para>
+    </tip>  
+  </sect1>
+  
+  <sect1>
+    <title>pagecount.pl</title>
+    <para>
+      This <application>Perl</application> script can be used in the <literal>requester</literal> directive of <filename>pykota.conf</filename>,
+      to ask a printer for its internal page counter by sending a specially crafted <acronym>PJL</acronym> job
+      to it over the AppSocket protocol, usually on <acronym>TCP</acronym> port 9100.
+      It accepts the printer's hostname or <acronym>IP</acronym> address as its first parameter,
+      and the optional <acronym>TCP</acronym> port as its second parameter (it defaults to 9100).
+    </para>  
+    
+    <para>
+      Most of the time you'll use this script in combination with a script which waits for the printer
+      to be in <literal>idle</literal> state, in something like :
+<screen>      
+requester: external(somewaitscript.sh && pagecount.pl %(printer)s)
+</screen>
+    </para>
+    
+    <tip>
+      <title>Tip</title>
+      <para>
+        See the sample configuration file <filename>conf/pykota.conf.sample</filename> for examples.
+      </para>
+    </tip>  
+  </sect1>
+</chapter>
+
+<!--
+
+$Log$
+Revision 1.1  2004/03/16 14:42:31  jalet
+Improved documentation
+
+
+-->
