Index: pykota/trunk/conf/pykotadmin.conf.sample
===================================================================
--- pykota/trunk/conf/pykotadmin.conf.sample (revision 2819)
+++ pykota/trunk/conf/pykotadmin.conf.sample (revision 2837)
@@ -11,5 +11,7 @@
 #     Contains configuration directives to specify the username and
 #     optional password for the PyKota's database administrator.
-#     This user is either a PostgreSQL user, or an LDAP dn.
+#     This user is either a PostgreSQL or MySQL user, or an LDAP complete dn.
+#     For SQLite, only the [global] section itself is required, but
+#     the rest of the file can be empty.
 #
 # Directives format :
Index: pykota/trunk/conf/pykota.conf.sample
===================================================================
--- pykota/trunk/conf/pykota.conf.sample (revision 2819)
+++ pykota/trunk/conf/pykota.conf.sample (revision 2837)
@@ -46,10 +46,10 @@
 #
 
+
+#
+# All directives must be placed below the following line
 [global]
-# Storage backend for quotas
-# only PGStorage (PostgreSQL), LDAPStorage (OpenLDAP or else),
-# MySQLStorage (MySQL) and SQLiteStorage (SQLite 3) are supported.
-#
-# BerkeleyDB is planned.
+
+
 
 ####################################################################
@@ -59,4 +59,8 @@
 #storagebackend : sqlitestorage
 #storagename: /etc/pykota/pykota.db
+
+####################################################################
+
+
 
 ############################################################################
@@ -86,4 +90,8 @@
 # In the line below change the password's value if needed.
 storageuserpw : readonlypw
+
+############################################################################
+
+
 
 ####################################################################
@@ -159,4 +167,5 @@
 #
 # LDAP attribute which stores the user's email address
+#
 #usermail : mail
 
@@ -164,4 +173,5 @@
 # Choose what attribute contains the list of group members
 # common values are : memberUid, uniqueMember, member
+#
 #groupmembers: memberUid
 
@@ -175,9 +185,14 @@
 # BEWARE : SETTING THIS TO 'YES' CAUSES PROBLEMS FOR NOW
 # BETTER TO LET IT SET TO 'NO'
+#
 # ldapcache: no
 
+####################################################################
+
 #############################################################
-# ALL directives below are common to ALL storage backends   #
+# END of database specific directives                       #
 #############################################################
+
+
 
 # Should the database caching mechanism be enabled or not ?
@@ -197,4 +212,6 @@
 #
 storagecaching: No
+
+
 
 # Should full job history be disabled ?
@@ -204,10 +221,16 @@
 # Disabling the job history with a relationnal backend works too
 # but it's probably less useful than with LDAP.
+#
 disablehistory: No
 
-# Where to log ?
-# supported values : stderr, system (system means syslog, but don't use 'syslog' here)
-# if the value is not set then the default SYSTEM applies.
+
+
+# Where to log ?[A
+# supported values : stderr, system (system means syslog, but don't use 
+# 'syslog' here). if the value is not set then the default SYSTEM applies.
+#
 logger: system
+
+
 
 # Enable debugging ? Put YES or NO there.
@@ -221,30 +244,39 @@
 # so the impact per job is really minimal. Note however that this will
 # add up over a large number of jobs.
+#
 debug : Yes
 
-#
+
+
 # The URL to PyKota's logo when used from the CGI scripts.
 # You can use your own logo by modifying the URL below.
 # If not defined, the default URL is the same as the
-# one defined below
+# one defined below :
+#
 logourl : http://www.librelogiciel.com/software/PyKota/pykota.png
 
-# 
+
+
 # The destination to which the web browser will be redirected
 # when you click on the logo defined above.
 # If not defined, the default URL is the same as the
-# one defined below
+# one defined below :
+#
 logolink : http://www.librelogiciel.com/software/
 
-#
+
+
 # Mail server to use to warn users
 # If the value is not set then localhost is used.
+#
 smtpserver: localhost
+
+
 
 # Crash messages' recipient : in addition to the log files
 # each software crash can be sent to the author of PyKota
 # or any other person of your choice. By default this
-# is disabled. The recipient pykotacrashed@librelogiciel.com
-# reaches PyKota's author.
+# is disabled for privacy concerns (see below). The address
+# pykotacrashed@librelogiciel.com reaches PyKota's author.
 # The 'adminmail' (defined a bit below) is CCed.
 #
@@ -255,6 +287,9 @@
 #        - a copy of the software's environment variables
 # 
-# suggested value
+# suggested value :
+#
 # crashrecipient: pykotacrashed@librelogiciel.com
+
+
 
 # Email domain
@@ -268,9 +303,12 @@
 #
 # Set the appropriate value below, example.com set as per RFC2606.
+#
 maildomain: example.com
+
+
 
 # Should we force usernames to be all lowercase when printing ?
 # Default is No. 
-# This is a global option only.
+# This is a [global] option only.
 # Some people reported that WinXP sends mixed case usernames
 # setting 'utolower: Yes' solves the problem.
@@ -286,9 +324,12 @@
 # is done, this means that users 'Jerome' and 'jerome' are
 # different. Printer and groups names are ALWAYS case sensitive.
+#
 utolower: No
+
+
 
 # Should we split usernames on a specific separator when printing ?
 # Default is No, i.e. if the value is unset.
-# This is a global option only.
+# This is a [global] option only.
 # This option adds support for Samba's Winbind utility, which
 # prefixes usernames with domain name and separator character.
@@ -304,5 +345,8 @@
 # of the 'utolower' directive), this means that users 'DOMAIN1/jerome',
 # 'Domain2/jerome' and 'jerome' are different. 
+#
 # winbind_separator: /
+
+
 
 # When creating users or groups accounts, should we reject users
@@ -316,4 +360,6 @@
 #
 # reject_unknown: No
+
+
 
 # Do we want to hide jobs' title, filename and options for privacy
@@ -325,5 +371,8 @@
 # This option can't be set on a per printer basis, only into the 
 # [global] section.
+#
 privacy : no
+
+
 
 # When the real CUPS backend fail, should we modify the
@@ -351,4 +400,5 @@
 # This value can be set either globally or on a per printer basis
 # If both are defined, the printer option has priority.
+#
 # onbackenderror : charge,retry:5:60
 # onbackenderror : retry:0:300
@@ -356,4 +406,6 @@
 # onbackenderror : charge
 onbackenderror : nocharge
+
+
 
 # Should we strip off some characters from the beginning of
@@ -366,5 +418,8 @@
 # This value can be set either globally or on a per printer basis
 # If both are defined, the printer option has priority.
+#
 # striptitle : smbprn.??????
+
+
 
 # Should we launch a command to overwrite the job's ticket ?
@@ -395,5 +450,10 @@
 # If both are defined, the printer option has priority.
 #
+# examples :
+# 
+# overwrite_jobticket : /usr/bin/pknotify --destination $PYKOTAJOBORIGINATINGHOSTNAME:7654 --timeout 180 --denyafter 3 --checkauth --ask "Username:username:$PYKOTAUSERNAME" "Password:password:"
 # overwrite_jobticket : /path/to/some/script/or/command
+
+
 
 # What should we do when we print and the billing code used is
@@ -414,6 +474,9 @@
 #
 # unknown_billingcode : deny
+# unknown_billingcode : deny(/usr/bin/pknotify --destination $PYKOTAJOBORIGINATINGHOSTNAME:7654 --timeout 60 --notify "The billing code specified is not allowed")
 # unknown_billingcode : deny(/path/to/some/script)
 # unknown_billingcode : create
+
+
 
 # Where should we store our (temporary) files when printing ?
@@ -427,4 +490,6 @@
 # directory : /var/spool/cups
 
+
+
 # Should we keep our work files on disk after printing ?
 # If unset, temporary files are deleted once the work is finished.
@@ -434,157 +499,93 @@
 # If both are defined, the printer option has priority.
 # Default value is No, meaning temporary files are deleted
+# You should set it to yes only during installation to not
+# waste disk space during normal use.
+#
 # keepfiles : yes
 keepfiles : no
 
 
-# What is the accounting backend to use
-# 
-# supported values :
-#
-#    - hardware : asks the printer for its lifetime page counter
-#                 via either SNMP, AppleTalk, or any external
-#                 command. This method is the recommended one
-#                 in PyKota since its beginning.
-#
-#                 In the lines below "%(printer)s" is automatically replaced
-#                 at run time with your printer's Fully Qualified Domain Name
-#                 for network printers, if PyKota can extract it from its 
-#                 environment.
-#                 e.g. myprinter.example.com
-#
-#         Recommended values :
-#
-#             accounter: hardware(snmp)
-#
-#               Extracts the printer's internal page counter via SNMP.
-#
-#         Or :
-#
-#             accounter: hardware(pjl)
-# 
-#               Extracts the printer's internal page counter via PJL queries over port tcp/9100.
-#
-#         Advanced uses :
-#
-#             accounter: hardware(snmp:MyCommunity)
-#
-#               To use a different SNMP community name than the default one (which is 'public')
-#
-#             accounter: hardware(pjl:9101) 
-#
-#               To use a different port than the default one (which is 9100)
-#
-#
-#         Other Examples : 
+
+# What is the accounting backend to use : this defines the way PyKota
+# will compute the number of pages printed. This directive is the most
+# important one in PyKota's configuration.
+# 
+# NB : This directive is MANDATORY, there's no default value when not set.
+#
+# Supported values :
+#
+# - software([/path/to/some/script[ --with-args]])
+# - hardware(snmp[:community]|pjl[:port]|/path/to/some/script[ --with-args])
+#
+# Hardware asks the printer for its lifetime page counter through either
+# SNMP, PJL-over-TCP, or through any command of your choice. This is
+# the recommended way to use PyKota, although it might not work with some
+# printers. The page counter is asked twice per job : before the job
+# is sent to the printer, and after it has been entirely sent.
+# The big advantages of hardware accounting are lighter CPU usage compared
+# to software accounting described below, although it can take more time
+# because of necessary internal counter stabilization delays, and the fact 
+# that paper jams don't cause users to be charged for pages they couldn't
+# print.
+# For hardware accounting, two special values are accepted in addition
+# to a script name : snmp and pjl. 'snmp' asks PyKota to use its internal
+# SNMP code, 'pjl' asks PyKota to internally send a specially crafter PJL 
+# job to the printer's TCP port 9100 (by default).
+#
+# Software counts pages by parsing the print job's datas, either internally
+# when no script is specified, or through any script of your choice.
+# This works with ALL printers, provided you've got a script to parse
+# datas produced by your printer driver. PyKota's internal parser, also
+# available under the name 'pkpgcounter', recognizes several page description
+# languages, but may occasionally fail for some printer drivers.
+# You can however use any other command, provided it can read the datas to
+# parse from its standard input, and prints a single integer on its standard
+# output, representing the number of pages in the print job.
+# Software accounting unfortunately may overcharge users in case of paper
+# jams.
+# 
+# You can get hints on which configuration is best for your printers by
+# typing : pkturnkey --doconf
+#
+# In the lines below "%(printer)s" is automatically replaced at run time
+# with your printer's Fully Qualified Domain Name for network printers, 
+# if PyKota can extract it from its environment.
+#
+# Examples :
+#
+# accounter : hardware(snmp)
+# accounter : hardware(snmp:private)
+# accounter : hardware(pjl)
+# accounter : hardware(pjl:9101)
+# accounter : hardware(/usr/share/pykota/waitprinter.sh %(printer)s && /usr/bin/snmpget -v1 -c public -Ov %(printer)s mib-2.43.10.2.1.4.1.1 | cut -f 2,2 -d " ")
+# accounter : hardware(/usr/bin/npadmin --pagecount %(printer)s)
+# accounter : hardware(/usr/share/pykota/papwaitprinter.sh "MyPrinter:LaserWriter@*" && /usr/bin/pap -p "MyPrinter:LaserWriter@*" /usr/share/pykota/pagecount.ps  2>/dev/null | /bin/grep -v status | /bin/grep -v Connect | /usr/bin/tail -1)
+# accounter : hardware(/bin/cat /usr/share/pykota/pagecount.pjl >/dev/lp0 && /usr/bin/head -2 </dev/lp0 | /usr/bin/tail -1)
+# accounter : hardware(/opt/local/net-snmp/bin/snmpwalk -v 1 -Cc -c public %(printer)s | grep mib-2.43.10.2.1.4.1.1 | cut -d " " -f4)
+# accounter : hardware(/opt/local/net-snmp/bin/snmpwalk -v 1 -Cc -c public -Ov %(printer)s | grep Counter32 | tail -2 | head -1 | cut -d " " -f2)
+# accounter : software(/usr/bin/pkpgcounter) 
+# accounter : software()
 #         
-#             accounter: hardware(/usr/bin/snmpget -v1 -c public -Ov %(printer)s mib-2.43.10.2.1.4.1.1 | cut -f 2,2 -d " ")
+# This directive can be set either globally or per printer or both.
+# If both are defined, the printer option has priority.
 #         
-#         Another untested example, using npadmin :
+# IF YOU PLAN TO USE YOUR OWN SCRIPTS FOR HARDWARE ACCOUNTING,      
+# YOU ABSOLUTELY HAVE TO BE SURE YOU HAVE A SCRIPT WHICH WAITS FOR THE
+# PRINTER BEING READY BEFORE ASKING FOR ITS INTERNAL PAGE COUNTER.
 #         
-#             accounter: hardware(/usr/bin/npadmin --pagecount %(printer)s)
+# PYKOTA'S 'snmp' and 'pjl' HARDWARE ACCOUNTING METHODS DO THE CORRECT WORK
+# INTERNALLY, BUT SOME OF THE EXAMPLES ABOVE DON'T, YOU HAVE BEEN WARNED.
+#
+# WITH THE SPECIAL MAGIC hardware(snmp) AND hardware(pjl) VALUES, PYKOTA
+# TAKES CARE OF ALL THIS FOR YOU, SO PLEASE UNDERSTAND THAT IT IS PREFERABLE
+# TO USE THESE TWO METHODS : THEY WORK FINE, REQUIRE LITTLE TO NO CPU,
+# AND DO ALL THE HARD WORK AUTOMATICALLY. IF YOU REALLY NEED TO YOU CAN USE
+# YOUR OWN EXTERNAL COMMANDS AS DESCRIBED ABOVE, JUST BE CAREFUL WITH THIS.
 #         
-#         Another example, for AppleTalk printers which works fine :
-#         (You may need the pap CUPS backend installed, and copy the 
-#         pagecount.ps file from untested/netatalk into /etc or any 
-#         appropriate location)
-#         
-#             accounter: hardware(/usr/share/pykota/papwaitprinter.sh "MyPrinter:LaserWriter@*" && /usr/bin/pap -p "MyPrinter:LaserWriter@*" /usr/share/pykota/pagecount.ps  2>/dev/null | /bin/grep -v status | /bin/grep -v Connect | /usr/bin/tail -1)
-#         
-#         An example for parallel printers like the HP Laserjet 5MP :
-#         
-#             accounter: hardware(/bin/cat /usr/share/pykota/pagecount.pjl >/dev/lp0 && /usr/bin/head -2 </dev/lp0 | /usr/bin/tail -1)
-#         
-#         This value can be set either globally or per printer or both.
-#         If both are defined, the printer option has priority.
-#         
-#         Some examples and comments provided by Bob Martel from csuohio.edu
-#         
-#         For several printers I could not get the page count using snmpget.  I
-#         resorted to snmpwalk:
-#         
-#             accounter: hardware(/opt/local/net-snmp/bin/snmpwalk -v 1 -Cc -c public %(printer)s | grep mib-2.43.10.2.1.4.1.1 | cut -d " " -f4)
-#         
-#         The last example is still more ugly, some of the printers only provided
-#         their counters without names, but at least always on the same line:
-#         
-#             accounter: hardware(/opt/local/net-snmp/bin/snmpwalk -v 1 -Cc -c public -Ov %(printer)s | grep Counter32 | tail -2 | head -1 | cut -d " " -f2)
-#         
-#         An example using netcat and a preformatted PJL job which you can find
-#         in the untested/pjl directory, which is sent to a JetDirect print
-#         server on port 9100 :
-#         
-#             accounter: hardware(/bin/nc -w 2 %(printer)s 9100 </usr/share/pykota/pagecount.pjl | /usr/bin/tail -2)
-#         
-#         An example using the contributed pagecount.pl script which does 
-#         the same as above, but should work on more printers : 
-#         
-#             accounter: hardware(LC_ALL=C /usr/share/pykota/pagecount.pl %(printer)s 9100)
-#         
-#         NB : the LC_ALL=C is used because sometimes Perl can correctly set locale and is verbose
-#              about it, causing PyKota to miss the correct answer.
-#
-#         WARNING : In any case, when using an hardware accounter, please test the command line outside
-#                   of PyKota before. This will save you some headaches in case it doesn't work as expected.
-#         
-#         The waitprinter.sh is there to wait until the printer is idle again.
-#         This should prevent a job to be sent to the printer while another one is 
-#         not yet finished (not all pages are printed, but the complete job is in 
-#         the printer)
-#         
-#   YOU ABSOLUTELY HAVE TO BE SURE YOU HAVE A SCRIPT WHICH WAITS FOR THE
-#   PRINTER BEING READY BEFORE ASKING FOR ITS INTERNAL PAGE COUNTER.
-#         
-#   PYKOTA INCLUDES SUCH SCRIPTS FOR SNMP AND APPLETALK PRINTERS, MORE TO COME
-#
-#   SOME OF THE ABOVE EXAMPLES DON'T USE SUCH A SCRIPT, YOU HAVE BEEN WARNED
-#
-#
-#   WITH THE SPECIAL MAGIC hardware(snmp) AND hardware(pjl) VALUES, PYKOTA
-#   TAKES CARE OF ALL THIS FOR YOU, SO PLEASE UNDERSTAND THAT IT IS PREFERABLE
-#   TO USE THESE TWO METHODS : THEY WORK FINE, REQUIRE LITTLE TO NO CPU,
-#   AND DO ALL THE HARD WORK AUTOMATICALLY. IF YOU REALLY NEED TO YOU CAN USE
-#   YOUR OWN EXTERNAL COMMANDS AS DESCRIBED ABOVE, JUST BE CAREFUL WITH THIS.
-#         
-#
-#    - software : delegates the job's size computation to any 
-#                 external command of your choice. 
-#
-#                 best choice for this is probably to set it
-#                 this way :
-#
-#                   accounter: software()
-#
-#                 which uses pkpgcounter's code internally to compute
-#                 the size of the job.
-#                 NB : YOU MUST NOW INSTALL pkpgcounter FOR PyKota TO WORK.
-#
-#                 You could obtain exactly the same result with :
-#
-#                   accounter: software(/usr/bin/pkpgcounter)
-#
-#                 But in this case the job would be passed through
-#                 pkpgcounter's parser a second time.
-#
-#                 pkpgcounter is a command line tool which was
-#                 part of PyKota and which can handle several types
-#                 of documents. It is now distributed separately.
-#
-#                 while pkpgcounter is the recommended value if you want
-#                 to use an external command here, you can use whatever 
-#                 command you want provided your command accepts the job's
-#                 data on its standard input and prints the job's size in 
-#                 pages as a single integer on its standard output.
-# 
-# This value can be set either globally or on a per printer basis
-# If both are defined, the printer option has priority.
-#
-# accounter: hardware(/usr/share/pykota/waitprinter.sh %(printer)s && /usr/bin/snmpget -v1 -c public -Ov %(printer)s mib-2.43.10.2.1.4.1.1 | cut -f 2,2 -d " ")
-# accounter: hardware(snmp)
-# accounter: hardware(pjl)
-# accounter: software(/usr/bin/pkpgcounter)
-#
-# The following, software without any argument, works since PyKota 1.21 
-# and uses pkpgcounter's code internally.
+# Sane default :
+#
 accounter: software()
+
+
 
 # What is the "pre"-accounter used for precomputing the job's size.
@@ -595,12 +596,20 @@
 #  preaccounter: software(/path/to/your/script)
 #
-# NB : the preaccounter directive doesn't support hardware() for obvious reasons.
-# If unset, "software()" is assumed. If you use your own script, ensure that it
-# only prints the job's number of pages (or an estimation of it) on its standard output.
+# NB : the preaccounter directive doesn't support hardware() for obvious 
+# reasons. If unset, "software()" is assumed. If you use your own script, 
+# ensure that it only prints the job's number of pages (or an estimation 
+# of it) on its standard output.
+#
+# You may want to define for example 'preaccounter : software(/bin/echo 1)'
+# in the case your printer supports an hardware accounter but pkpgcounter
+# can't parse your printer driver's datas.
 #
 # This value can be set either globally or on a per printer basis
 # If both are defined, the printer option has priority.
 #
+# Sane default :
+#
 preaccounter: software()
+
 
 
@@ -629,4 +638,6 @@
 onaccountererror: stop
 
+
+
 # Print Quota administrator
 # These values can be set either globally or per printer or both.
@@ -637,5 +648,6 @@
 adminmail: root@localhost
 
-#
+
+
 # Who should we send an email to in case a quota is reached ?
 # possible values are : DevNull, User, Admin, Both, External(some command)
@@ -660,13 +672,13 @@
 #                               to use it.
 #
-#   On your command line, to pass arguments to your command.
-#   Example :
-#
-#       mailto: external(/usr/bin/callpager %(username)s "Quota problem on %(printername)s" >/dev/null)
+#   on your command line, to pass arguments to your command.
+#   Examples :
+#
+#     mailto: external(/usr/bin/callpager %(username)s "Quota problem on %(printername)s" >/dev/null)
 #
 #   To automatically send a WinPopup message (this may only work with a PDC, 
 #   here the same machine does Samba as PDC + CUPS) :
 #
-#       mailto: external(echo "%(message)s"  | /usr/bin/iconv --to-code utf-8 --from-code iso-8859-15 | /usr/bin/smbclient -M "%(username)s" 2>&1 >/dev/null)
+#     mailto: external(echo "%(message)s" | /usr/bin/iconv --to-code utf-8 --from-code iso-8859-15 | /usr/bin/smbclient -M "%(username)s" 2>&1 >/dev/null)
 #
 #   NB : I use ISO-8859-15, but Windows expects UTF-8, so we pipe the message
@@ -675,5 +687,5 @@
 # or more simply :
 #
-#       mailto: external(/usr/share/pykota/mailandpopup.sh %(username)s %(printername)s "%(email)s" "%(message)s" 2>&1 >/dev/null)
+#     mailto: external(/usr/share/pykota/mailandpopup.sh %(username)s %(printername)s "%(email)s" "%(message)s" 2>&1 >/dev/null)
 #
 #   NB : The mailandpopup.sh shell script is now included in PyKota
@@ -683,21 +695,7 @@
 #        underlying layer (filter or backend)
 #
-mailto: both
-
-#
-# Grace delay in days
-# This value can be set either globally or per printer or both.
-# If both are defined, the printer option has priority.
-# If the value is not set then the default seven (7) days applies.
-gracedelay: 7
-
-#
-# Poor man's threshold
-# If account balance reaches below this amount,
-# a warning message is sent by email
-#
-# If unset, default poor man's threshold is 1.0.
-# This option can only appear in the global section
-poorman: 2.0
+mailto : both
+
+
 
 # The value of the zero for account balance limitations.
@@ -706,26 +704,59 @@
 # the default value is 0. Any floating point value
 # is accepted.
+# You'll want to use this to give free credits to your users
+# at the start of the year for example.
 #
 # This option can only appear in the global section
+#
 # balancezero : -0.25
+#
 balancezero: 0.0
+
+
+
+# Grace delay in days
+# This value can be set either globally or per printer or both.
+# If both are defined, the printer option has priority.
+# If the value is not set then the default seven (7) days applies.
+#
+gracedelay : 7
+
+
+
+# Poor man's threshold
+# If account balance reaches below this amount, a warning message 
+# is sent through the 'mailto' directive above.
+#
+# If unset, default poor man's threshold is 1.0.
+# This option can only appear in the global section
+#
+poorman : 1.0
+
+
 
 # Poor man's warning message
 # The warning message that is sent if the "poorman" value is reached
 # Again this must appear in the global section
-poorwarn: Your Print Quota account balance is low. 
+#
+poorwarn : Your Print Quota account balance is low. 
  Soon you'll not be allowed to print anymore.
+
+
 
 # Soft limit reached warning message
 # The warning message that is sent if the soft quota limit is reached
 # May appear either globally or on a per-printer basis
+#
 softwarn: Your Print Quota Soft Limit is reached.
  This means that you may still be allowed to print for some
  time, but you must contact your administrator to purchase 
  more print quota.
- 
+
+
+
 # Hard limit reached error message
 # The error message that is sent if the hard quota limit is reached
 # May appear either globally or on a per-printer basis
+#
 hardwarn: Your Print Quota Hard Limit is reached.
  This means that you are not allowed to print anymore.
@@ -733,10 +764,4 @@
  as soon as possible to solve the problem.
 
-# one section per printer, or no other section at all if all options 
-# are defined globally.
-# Each section's name must be the same as the printer's queue name as defined
-# in your printing system, be it CUPS or LPRng, between square brackets, for
-# example a print queue named 'hpmarketing' would appear in this file as
-# [hpmarketing]
 
 
@@ -755,13 +780,13 @@
 #
 # external policy can be used to launch any external command of your choice,
-# for example to automatically add the user to the quota storage 
-# if he is unknown. Example :
-# 
-#   policy: external(/usr/bin/edpykota --add --printer %(printername)s --softlimit 50 --hardlimit 60 %(username)s >/dev/null) 
+# for example to automatically add the user to the quota database, and set
+# page limits on the current printer if he is unknown :
+# 
+#   policy: external(/usr/bin/pkusers --add --skipexisting %(username)s && /usr/bin/edpykota --add --skipexisting --printer %(printername)s --softlimit 50 --hardlimit 60 %(username)s) 
 #
 # NB : If you want to limit users by their account balance value, it is preferable to
 # use the following policy to automate user account creation on first print :
 #
-#   policy: external(/usr/bin/autopykota --initbalance 25.0 >/dev/null) 
+#   policy: external(/usr/bin/autopykota --initbalance 25.0) 
 #
 #   This will automatically add the user if he doesn't already exist, and
@@ -774,5 +799,5 @@
 # Of course you can launch any command of your choice with this, e.g. :
 #
-#   policy: external(/usr/local/bin/myadminscript.sh %(username)s >/dev/null)
+#   policy: external(/usr/local/bin/myadminscript.sh %(username)s)
 
 # You can use :
@@ -782,8 +807,4 @@
 #
 #   On your command line, to pass arguments to your command. 
-#
-#   NB : Don't forget to redirect your command's standard output somewhere 
-#        (e.g. >/dev/null) so that there's no perturbation to the underlying
-#        layer (filter or backend)
 #
 # If the printer, user, or user quota entry still doesn't exist after 
@@ -792,5 +813,9 @@
 # command, then the job is rejected.
 #
+# By default, we reject all jobs from users not in the database :
+#
 policy: deny
+
+
 
 # Pre and Post Hooks 
@@ -865,4 +890,6 @@
 # prehook: /usr/bin/printenv >/tmp/before
 
+
+
 # PostHook : gets executed after the job has been added to the history.
 # posthook has access to all the environment variables defined above,
@@ -874,8 +901,8 @@
 # posthook: /usr/bin/printenv >/tmp/after
 
+
+
 # AccountBanner : how should banner accounting be done ?
 #
-# NB : CUPS ONLY FOR NOW !
-# 
 # If enabled, banner pages printed from StartingBanner and/or EndingBanner 
 # (depending on the value) will be included in the accounting for the
@@ -898,22 +925,23 @@
 # accountbanner: Both
 
+
+
 # Maximal number of times the banner will still be printed if
 # the user is forbidden to print.
 #
-# NB : CUPS ONLY FOR NOW !
-# 
 # This option can be set either globally or on a per printer basis.
 # Allowed values are 0 or any positive integer.
 # Default value is 0, which means that the banner won't be printed
 # at all if the user is forbidden to print.
+#
 maxdenybanners: 0
+
+
 
 # StartingBanner : if defined will print a banner before the rest of the job 
 # is printed. The argument can be a printable file, or an executable file.
 # If not executable, the file will be printed as is. If executable, the 
-# file will be executed and its output will be printed.
-#
-# NB : CUPS ONLY FOR NOW !
-# 
+# file will be executed and its standard output will be sent to the printer.
+#
 # In any case, the banner content which will be sent to the printer
 # MUST be in a format your printer will accept !!! 
@@ -930,10 +958,10 @@
 # startingbanner: /usr/bin/pkbanner
 
+
+
 # EndingBanner : if defined will print a banner after the job 
 # has been printed. The argument can be a printable file, or an executable file.
 # If not executable, the file will be printed as is. If executable, the 
-# file will be executed and its output will be printed.
-#
-# NB : CUPS ONLY FOR NOW !
+# file will be executed and its standard output will be sent to the printer.
 #
 # In any case, the banner content which will be sent to the printer
@@ -963,4 +991,6 @@
 # endingbanner: /usr/bin/pkbanner 
 
+
+
 # How should enforcement be done for this printer ?
 #
@@ -976,8 +1006,11 @@
 # valid values : "strict" or "laxist"
 #
-# default value
+# default value when not set is "laxist"
+#
 # enforcement : laxist
 enforcement : strict
 
+
+
 # Should we trust the job size on this printer ?
 #
@@ -985,5 +1018,6 @@
 # by the hardware or by software is trusted.
 #
-# "trustjobsize : >N:precomputed" : uses the precomputed value if jobsize > N pages
+# "trustjobsize : >N:precomputed" : uses the precomputed value
+#                                   if jobsize > N pages
 # "trustjobsize : >N:25" : uses 25 if jobsize is >N pages
 #
@@ -1003,5 +1037,8 @@
 # AND THE JOB SIZE AS COMPUTED BY PYKOTA EITHER USING HARDWARE OR
 # SOFTWARE.
+#
 trustjobsize : yes
+
+
 
 # Should we deny duplicate jobs ?
@@ -1032,4 +1069,6 @@
 denyduplicates : no
 
+
+
 # Sets the delay in seconds after which two identical jobs are 
 # not considered as being a duplicate.
@@ -1040,2 +1079,4 @@
 duplicatesdelay : 0
 
+
+
