eqpcl utility ============= Revision: 0.1 (2010-11-26) Thank you for your interest in the Eloquence eqpcl utility. This is an alpha test release of the eqpcl utility. By making test releases available publicly we hope to encourage wider testing and additional feedback. Please contact support@marxmeier.com to share your feedback or report a problem. Please note: This release is available under the terms of the Eloquence Beta Test Agreement which is specified in the file AGREEMENT. http://www.marxmeier.com/eloquence/download/beta/B0810/AGREEMENT Downloading and installing the software indicates your agreement to the Beta Test terms and conditions. This test release may not meet the release criteria for quality or performance and is intended for test and non-critical use. Introduction ------------ The eqpcl utility allows converting PCL documents to PDF or PostScript. It implements a commonly used subset of PCL functionality and is expected to work with a majority of the existing documents. eqpcl internally translates the PCL command sequences and text into Postscript and uses the Ghostscript utility to create the PDF output. Please note: This is a alpha test version. Please report any problems to the Eloquence support team with an example PCL file that demonstrates the problem. Installation ------------ Please extract the eqpcl tar archive into an arbitrary directory. The following files and directories are included in the ditribution archive: bin/eqpcl newconfig/config/eqpcl.cfg share/eqpcl/ps/SYM-0N.ps share/eqpcl/ps/SYM-4U.ps share/eqpcl/ps/SYM-8U.ps share/eqpcl/ps/barcode.ps The file structure is compatible with the Eloquence B.08.00 or B.08.10 release and may be installed in the Eloquence directory. # cd /opt/eloquence/8.1 # tar xzf /tmp/eqpcl-0.1.tar.gz Optionally, the configuraiton template file may be copied to the Eloquence config directory to provide a customized default configuration. # cp newconfig/config/eqpcl.cfg /etc/opt/eloquence/8.1/ The eqpcl utility is currently only available for the Linux x86 platform. Pre-requisites: Creation of PDF documents depends on the GhostScript utlity which must be present on the system. Options ------- usage: eqpcl [options] [pcl files ...] options: -help This usage information -c cfg specify config file (default is eqpcl.cfg, ~/.eqpcl) -o out specify output file (default is stdout) -p create PDF output -s create postscript output -a analyze pcl data (-aa more verbose) -d additional debug output -V output version and exit The option -c is used to specify a config file that defines some configuration and PCL defaults. When a configuraton file is not specified, eqpcl will first look for a file eqpcl.cfg in the current directory and then for a file .eqpcl in the home directory (~/.eqpcl). The option -o is used to specify the name of an output file. If not present, the output is placed to stdout. The option -p is is used to create a PDF file as a result. In this case, eqpcl internally creates an intermediate Postscript result which is passed to Ghostscript to create the PDF. The option -s specifies to create an Postscript output instead. The option -a is used to analyze the PCL command stream. It prints its results to stdout. This option may not be used with the option -p or -s as this results in a corrupted output. Any number of PCL command files may be specified on the command line that are then combined in a single document, each file separated by a PCL reset. If no file name is present, the input is read from stdin. This allows use of eqpcl in a pipe. Typical use: eqpcl -c eqpcl.cfg -p -o sample.pdf sample.pcl This creates a PDF document (sample.pdf) from PCL file sample.pcl. The config file eqpcl.cfg is used. cat sample.pcl | eqpcl -c eqpcl.cfg -p > sample.pdf The PCL data is read from stdin and converted to PDF on stdout. eqpcl -a sample.pcl Analyze the file sample.pcl. This decodes the PCL commands and text. Outputs the results to stdout. Config file ----------- The eqpcl utility uses a config file to define custom settings. The config file is a text file with sections marked in square brackets and items and values separated by an equal sign. A hash sign (#) or semicolon denotes a comment. Values can be enclosed in single or double quotes. In this case leading and trailing spaces are preserved. Section names and items are case insensitive. The following options are available: [config] This section specifies some global settings for the eqpcl utility. ps.include = /opt/eloquence/8.1/share/eqpcl/ps This specifies the path to the eqpcl installation directory. It defaults to the current directory or /opt/eloquence/8.1/share/eqpcl barcode = 1 A non-zero value enables barcode support. By default barcode support is disabled. Please refer to the section on barcode support for details. overlay = 1 A non-zero value of 1 or 2 enables overlays from virtual trays (see below). If overlay is set to one (default), the overlay is processed before rendering the page. If overlay is set to two then the overlay is applied when the page is completed. The default value is 1. gs = /usr/bin/gs The gs option specifies the path to the GhostScript executable. By default (unless configured) the current PATH is used. gs.paper.size = Allows to specify the paper size assumed by GhostScript. By default GhostScript assumes LETTER paper format (some versions are customized to assume A4 as a default). This needs to be set when the PCL document assumes LETTER. Please refer to the Ghostscript documentation for details. gs.opt = This allows to specify custom GhostScript command line options. Please refer to the Ghostscript documentation for details. [default] This section specifies the PCL defaults. paper.source = 1 paper.source specifies the default paper tray. If a virtual tray is configured for this paper source then the defined overlay is applied to each page. paper.size = 26 This specifies the default PCL paper size. The following values are recognized: 1 = EXECUTIVE 2 = LETTER 3 = LEGAL 6 = LEDGER 26 = A4 27 = A3 The default is 26 (A4) symset = 4U symset specifies the default symbol set. The following values are recognized. 8U = HP roman8 4U = HP roman9 (same as Roman8 with EUR sign) 9U = CP1252 0N = ISO latin1 (subset of cp1252) The default is 8U eolterm = 0 eolterm specifies the default for the PCL CR/LF handling. The following values are recognized: 0 - CR = CR, LF = LF, FF = FF 1 - CR = CR+LF, LF = LF, FF = FF 2 - CR = CR, LF = CR+LF, FF = CR+FF 3 - CR = CR+LF, LF = CR+LF, FF = CR+FF The default is 0. A value of 2 would be used to print UNIX text files. [barcode] This section is used to define the mapping of barcode and font id. Please refer to the section "barcode" for details. [trayN] The Tray sections are used to define the virtual tray. Please refer to the section "virtual tray" for details. Limitations ----------- The eqpcl utility implements a commonly used subset of the PCL functionality. Any unsupported functions are silently ignored. The following PCL functions are not supported: - user defined fonts - user defined symbol sets - user defined patterns - area fill with patterns - HP GL/2 - Raster graphics - PCL macro support is currently not functional The following fonts are currently available: - Times-Roman - Courier - Helvetica - Symbol The following symbol sets are available: - 8U - HP Roman8 - 4U - HP Roman9 (Roman8 with EUR sign) - 9U - CP1252 - 0N - ISO Latin1 - 0M (only symbol font) Commonly used PCL fonts are mapped as below: 0 (Line Printer) - Courier 1 - Courier 2 - Courier 3 - Courier 4 - Helvetica 5 - Times-Roman 6 - Courier 4101 (CG Times) - Times-Roman 4148 (Univers) - Helvetica 16602 (Arial) - Helvetica Any other fonts are mapped to Courier. Virtual Trays ------------- The eqpcl utility provides a virtual tray that may be configured in the config file. A tray config may specify eps include files along with position and scaling options. This is intended to ease the creation of custom forms. Instead of converting a custom form or logo into PCL format you may specify one or more EPS files (single page PS files _may_ work) to be used as overlay when the tray is used as a media source. An EPS file is a special postscript format that can only hold a single page. [trayn] # eps.file = path to include file (absolute path) # xofs = move object x position (in decipoints, from left) # yofs = move object y position (in decipoints, from bottom) # scale = scale factor (in percent) # multiple objects are allowed, each starting with eps.file The section name [trayn] identfies the tray and is accessed from the PCL command. eps.file designates the path to an EPS file that is used to overlay the page. Multiple overlays are supported, each starting with eps.file. scale may be used to specify a percentage by which the EPS file is scaled. If not present, the original size is used. A value of 50 scales the EPS file to 50%. xofs and yofs may be used to specify an offset of the placement of the EPS file content. By default, the original position as specified in the EPS bounding box is used (or the top left corner of no bounding box is specified). The xofs and yofs allow to move the object accordingly, relative to the original position. The value is denoted in decipoints, that is 1/720 inch (or 1/10 point, ~0.0353 mm). An offset of 1000 would indicate 1.38 inch and 35.28 mm. To create an EPS, save or export your image or document as EPS file. A single page Postscript file _may_ work as well. You may use the netpbm utilities to convert a variety of image formats to an eps file. For example: giftopnm sample.gif | pnmtoeps > sample.eps jpegtopnm sample.gif | pnmtoeps > sample.eps Barcode Support --------------- The eqpcl utility provides support for the Postscript barcode writer created by Terry Burton. When the barcode functionality is enabled in the configuration, the barcode code is included in the PS output and eqpcl creates calls from the PCL data. Please refer to http://groups.google.com/group/postscriptbarcode/web for more information on supported bar code types and options. When enabled, the barcode is identified by a font id (type face) and mapped to a barcode encoding and option. The barcode height is automatically scaled according to the font height. The barcode encoding and any number of options may be specified, separated by a space. Any number of bar code definitions may be present. To enable barcode support the following setting in the configuration is required: [config] barcode = 1 The following setting defines the font 9900 as code39 with the option "includetext". The font 9901 is defined as code93 with the additional options "includetext" and "includecheck". [barcode] 9900 = code39 includetext 9901 = code93 includetext includecheck Various bar code types are supported, including Code 39, Code 93, Code 128, EAN, Code 2 of 5, Data Matrix, etc. The supported options depend on the barcode type. The includetext option is typically supported and results in printing the clear text beneath the bar code. The includecheck option is supported with some bar code types and causes an extra check digit to be generated. For a list of suppored bar code types ("symbologies") and options please refer to the documentation on the web http://groups.google.com/group/postscriptbarcode/web The bar codes and options may be tried interactively on the web site http://www.terryburton.co.uk/barcodewriter/generator/ Third party licenses -------------------- The Postscript code in ps/barcode.ps is provided under the following license: Barcode Writer in Pure PostScript http://www.terryburton.co.uk/barcodewriter/ Copyright (c) 2004-2010 Terry Burton - tez@terryburton.co.uk Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.