root / pkpgcounter / trunk / README @ 375

# $Id$

pkpgcounter : a generic Page Description Language parser

(c) 2003, 2004, 2005, 2006 Jerome Alet <alet@librelogiciel.com>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

=============================================================================

pkpgcounter is a generic Page Description Language parser which can either
compute the number of pages in a document, or compute the percent of
ink coverage needed to print each page, in different colorspaces.

pkpgcounter currently recognizes the following document formats :

        - PostScript (both DSC compliant and binary)
        
        - PDF
        
        - PCL3/4/5
        
        - PCLXL (aka PCL6)
        
        - DVI
        
        - TIFF
        
        - ESC/P2
        
        - OpenDocument (ISO/IEC DIS 26300)
        
        - Zenographics ZjStream
        
The three latter ones, as well as some TIFF documents, are currently 
only supported in page counting mode. 

By default, when launched pkpgcounter prints on its standard output 
a single integer representing the total number of pages in all the 
files which filenames you've passed on the command line. 

With no argument, or with a single dash in non-option arguments,
pkpgcounter reads datas to parse from its standard input in addition
to other non-options arguments which are treated as filenames
representing the files to parse.

See pkpgcounter --help for details and examples.

=============================================================================

Installation :
--------------

  0 - Download pkpgcounter from :
  
        http://www.pykota.com/software/pkpgcounter/download
        
      and extract it :  
      
        $ tar -zxf pkpgcounter-x.yy.tar.gz
        
        where x.yy is pkpgcounter' version number.
        
  1 - Run the installation script :
      
        $ python setup.py install
        
      This will usually install the pkpgcounter into /usr/bin and  
      the library into /usr/lib/python2.?/site-packages/pkpgpdls/
        
  2 - Use pkpgcounter :
  
      $ pkpgcounter file1.ps file2.pclxl ... <fileN.escp2
      
      pkpgcounter will display the total size in pages of all the files
      passed on the command line.
      
      $ pkpgcounter --colorspace bw --resolution 150 file1.ps
  
      Will output the percent of black ink needed on each page of
      the file1.ps file rendered at 150 dpi.
      
  3 - That's all !    
  
  
IMPORTANT : To compute ink coverage, pkpgcounter relies on third party
software which must be installed. These third party software are :

        - GhostScript (this one is needed for all file formats).
        
        - The Python Imaging Library, aka PIL (this one is needed for all
          file formats).
        
        - GhostPCL (this one is needed for the PCL3/4/5 and PCLXL formats)
          
        - The LaTeX typesetting software, in particular the dvips command
          (this one is needed for the DVI file format).
        
=============================================================================

Troubleshooting : 
-----------------

  If pkpgcounter gives incorrect results to you, please make an incorrectly
  parsed data file available to us on some website, and tell us which 
  driver was used.
  
  If pkpgcounter complain about your system lacking the Python Psyco module,
  please consider installing it to speedup file parsing. However, don't forget
  that Psyco currently only runs on the 32 bits x86 platform, so no need to 
  install it if you've got another system type.
  
=============================================================================

The PCL3/4/5 parser included in pkpgcounter is a Python backport of an early
release of the PCLCount software by Eduardo Gielamo Oliveira and Rodolfo Broco
Manin. 

Although this IS NOT needed for pkpgcounter to work, you can download the
original PCLCount software from :

    http://www.fea.unicamp.br/pclcount/
    
Their software is distributed under either the terms of a BSD-like license,    
or the terms of the GNU General Public License of the Free Software Foundation.
    
Over time both software evolved following different paths, and the accounting
results they give may differ depending on the printer driver being used.
We know that pkpgcounter's PCL3/4/5 parser sometimes is not accurate,
and we are working on improving the situation. We currently don't know how 
PCLCount would behave with the same input files.

pkpgcounter's PCLXL (aka PCL6) parser doesn't originate from PCLCount, but 
was written from scratch. 

=============================================================================

pkpgcounter's ink coverage algorithm for the CMYK colorspace is a 
direct Python port from the PrintBill project by Daniel Franklin. 
PrintBill is distributed under the terms of the GNU General Public 
License of the Free Software Foundation, just like pkpgcounter. The 
algorithms used for the other colorspaces are a complete rewrite of 
PrintBill's algorithms using both Python and the Python Imaging 
Library's facilities. 

=============================================================================

Please e-mail bugs to : alet@librelogiciel.com (Jerome Alet)