eqpcl utility

Thank you for your interest in the Eloquence eqpcl utility. This is an beta test release of the eqpcl utility that is developed for the upcoming B.08.20 release. By making test releases available publicly we hope to encourage wider testing and additional feedback.

Please note:

This release is available under the terms of the Eloquence Beta Test Agreement which is specified in the file 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 use only.

The eqpcl utility internally translates the PCL command sequences and text into Postscript and uses GNU Ghostscript to create the PDF output.

Content:

• Installation
• Command Line Options
• Using the eqpcl utility in an application
• Config File
• Limitations
• Virtual Trays
• Barcode Support
• Third Party Licenses
• Change history

Please note: This is a beta test version. Please report any problems to the Eloquence support team at support@marxmeier.com with an example PCL file that demonstrates the problem.

• eqpcl-*-linux-i686.tar.gz - Linux x86, 32 bit
• eqpcl-*-linux-x86_64.tar.gz - Linux x64, 64 bit
• eqpcl-*-linux-ia64.tar.gz - Linux ia64, 64 bit
• eqpcl-*-hpux-pa20.tar.gz - HP-UX PA-RISC
• eqpcl-*-hpux-ia64.tar.gz - HP-UX IA64
• eqpcl-*-win32.zip - Windows x86, 32 bit

The following files and directories are included in the distribution 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

# cd /opt/eloquence/8.1
# tar xzf /tmp/eqpcl-*.tar.gz

# cp newconfig/config/eqpcl.cfg /etc/opt/eloquence/8.1/

Windows installation instructions:

The following files and directories are included in the distribution archive:

  bin/eqpcl
  etc/eqpcl.cfg.sam
  share/eqpcl/ps/SYM-0N.ps
  share/eqpcl/ps/SYM-4U.ps
  share/eqpcl/ps/SYM-8U.ps
  share/eqpcl/ps/barcode.ps

1. Right-click the ZIP archive file and choose the "Extract All..." option from the context menu. This opens the "Compressed Folders Extraction Wizard". Click the "Next" button.
2. On the "Select a Destination" screen, click the "Browse" button and navigate to your Eloquence installation directory, for example C:\Program Files\Eloquence\8.1, then click the OK button in the file browser dialog.
3. The Eloquence installation directory should now be displayed in the "Files will be extracted to this directory" field.
4. Click the "Next" and then the "Finish" button.

Prerequisites:

Creation of PDF documents depends on the GNU Ghostscript utility which must be present on the system.

Linux

GNU Ghostscript is is available from your Linux distribution.

HP-UX

GNU Ghostscript for HP-UX is available for download from the HP-UX porting center. GNU Ghostscript 8.71

Windows

GNU Ghostscript for Windows is available for from a number of sources, including: gs871w32.exe and gs900w32.exe

When running the install program, please consider to enable the option "All users" so Ghostscript is available for all users on the system.

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
 -m file  specify file with PDF marks
 -a       analyze pcl data (-aa more verbose)
 -g       pass to ghostscript
 -V       output version and exit

If no configuration file is specified:

1. First, the eqpcl utility will look for a file named eqpcl.cfg in the current directory.

2. On HP-UX and Linux, the eqpcl utility will then look for a file named .eqpcl in the home directory (~/.eqpcl).

3. Finally, eqpcl will look for a file named eqpcl.cfg in the etc subdirectory of your Eloquence B.08.10 or B.08.00 installation.

The option -o is used to specify the name of an output file. If not present, the output is written to stdout so that eqpcl may be used in a pipe.

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 a Postscript output instead.

The option -a is used to analyze the PCL command stream. It writes its results to stdout. This option should not be used with the option -p or -s as this would result in a corrupted output.

The option -m specifies a text file containing PDFmarks. The file content is added verbatim to the postscript output. This allows to specify PDF meta information (such as title, author or bookmarks). This file must comply with the PDFmarks syntax. Please refer to the pdfmark Reference manual for details.

The option -g translates the PCL input and passes it to Ghostscript. This option does NOT create a PDF file but allows to use eqpcl as a simple frontend to Ghostscript (for example, to print the resulting document).

Any number of PCL command files may be specified on the command line, which are then combined to a single document, each file separated by a PCL reset. If no file name is present, the input is read from stdin. This allows to use eqpcl in a pipe.

Typical use:

eqpcl -c eqpcl.cfg -p -o sample.pdf sample.pcl

cat sample.pcl | eqpcl -c eqpcl.cfg -p > sample.pdf

eqpcl -a sample.pcl

• eqpcl may be used as the printer destination using a pipe. For example,

  PRINTER IS "|eqpcl -p -o out.pdf"
  PRINT "HELLO WORLD"
  PRINER IS 8
  

  This creates the output file out.pdf in the current directory.

• As an alternative, eqpcl may be configured as a printer in the eloqcore configuration file. For example, the following .eloqrc file defines a printer 90 that creates a PDF document in the user home directory:

  PRINTER 90 PIPE "eqpcl -p -o $HOME/output.pdf"
  

  A simple program as below

  PRINTER IS 90
  PRINT "HELLO WORLD"
  PRINTER IS 8
  

  then creates the PDF document output.pdf in the user home directory.

• Create a PCL text file and use the COMMAND statement to create the PDF document. For example,

  PRINTER IS "out.pcl"
  PRINT "HELLO WORLD"
  PRINTER IS 8
  COMMAND "eqpcl -p -o out.pdf "&MAPFNAME$("out.pcl.DATA")
  

  This first creates the output file out.pcl.DATA and then uses eqpcl to convert it to the PDF format.

Unless specified on the command line, the config file is searched in the following locations:

• The file eqpcl.cfg in the current directory
• The file .eqpcl in the home directory of the user (HP-UX and Linux)
• The config directory of the installed Eloquence release

Section [config]

ps.include = 

barcode = 1

overlay = 1

gs = /usr/bin/gs

On Windows, the default executable is gswin32c.exe, but the Ghostscript installation directory is usually not located in the PATH. Therefore, the gs option should be explicitly configured, for example: gs = C:\Program Files\gs\gs9.00\bin\gswin32c.exe

gs.paper.size =

gs.opt = 

gs.pdf.opt = 

gs.print.opt = 

gs.fontpath = 

include = 

Section [default]

paper.source = 1

paper.size = 26

  1 = EXECUTIVE
  2 = LETTER
  3 = LEGAL
  6 = LEDGER
 26 = ISO A4
 27 = ISO A3

symset = 4U

  8U = HP roman8
  4U = HP roman9 (same as Roman8 with EUR sign)
  9U = CP1252
  0N = ISO latin1 (subset of cp1252)

eolterm = 0

 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

Section [tfN]

[tfN]
width = font height/width ratio (percent)
#b#s = font name

• The section name [tfN] identfies the PCL typeface. It consists of the literal "tf" and a numeric value N that specifies the PCL typeface id. For example, [tf4102] specifies the PCL typeface 4102 (LetterGothic).

• width specifies the font width/hight ratio (in percent). This is used to scale monotype fonts. The default is 60, indicating the width is 60% of the height.

• The other entries are used to map stroke and style values to a specific Postscript font name.
  #b#s = font name
  Where # specifies the stroke and style value and font name specifies the name of the PostScript font.

The example below maps the PCL 4102 typeface id to the LetterGothic PostScript font.

[tf4102]
width = 54
0b0s = LetterGothic
1b0s = LetterGothic
3b0s = LetterGothic-Bold
0b1s = LetterGothic-Italic

Section [barcode]

Section [trayN]

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 (other than area fill)

• Times-Roman
• Courier
• Helvetica
• Symbol

• 8U - HP Roman8
• 4U - HP Roman9 (Roman8 with EUR sign)
• 9U - CP1252
• 0N - ISO Latin1
• 0M (only symbol font)

Font ID	Mapped to...
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
24580 (Helvetica)	Helvetica

As the eqpcl utility does does not read the font metrics and thus can't use the character width of proportial spaced fonts some text may be positionned improperly.

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)
# align = align to paper edge (0=tl, 1=tr, 2=bl, 3=br, 4=orig)
# multiple objects are allowed, each starting with eps.file

• The section name [trayN] identfies the tray. It consists of the word "tray" and a numeric value N that specifies the tray number in the PCL command. For example, [tray1] specifies the tray number one.

• eps.file designates the absolute path to an EPS file that is used to overlay the page. Multiple overlays are supported, each starting with eps.file. On the Windows platform a slash is used instead of a backslash.

• 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%.

• align may be used to specifiy the alignment of the EPS content, relative to the paper edges. The following values are supported:
  • 0 = top/left
  • 1 = top/right
  • 2 = bottom/left
  • 3 = bottom/right
  • 4 = Use the position as specified in the EPS bounding box (relative to the Postscript reference point, the bottom left).
  The default is 0 which positions a EPS file releative to the top/left paper edge. This has no effect if the EPS file does not specify a bounding box.

• xofs and yofs may be used to specify an offset of the placement of the EPS file content. The EPS file content is positioned to a paper edge, based on the information in the EPS bounding box. Any position specified in the bounding box is ignored. 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 file, save or export your image or document as EPS file. A single page Postscript file may work as well (but is not supported as there could be side effects). On Linux or HP-UX the ImageMagick conversion utility or the netpbm utilities may be used to convert a variety of image formats to an eps file. For example:

giftopnm sample.gif | pnmtoeps > sample.eps
jpegtopnm sample.jpeg | pnmtoeps > sample.eps
convert sample.png sample.eps

Please refer to http://code.google.com/p/postscriptbarcode/wiki/Options for more information on supported barcode types ("Symbologies") and their 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 barcode definitions may be present.

To enable barcode support the following setting in the configuration is required:

[config]
barcode = 1

[barcode]
9900 = code39 includetext
9901 = code93 includetext includecheck

The supported options depend on the barcode type. The includetext option is typically supported and results in printing the clear text beneath the barcode. The includecheck option is supported with some barcode types and causes an extra check digit to be generated.

The barcodes and options may be tried interactively on the web site http://www.terryburton.co.uk/barcodewriter/generator/

Barcode Writer in Pure PostScript http://www.terryburton.co.uk/barcodewriter/

Copyright (c) 2004-2011 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.

• Zero top margin was considered invalid
• Improve layout with proportional fonts.

The eqpcl 0.5 release incorporates the following changes:

• Support page length command (ESC&L#P). This is command is deprecated and typically used with hp impact printers to define page size. Values exceeding the current paper size will reduce VMI value. Top and bottom margins are set to zero and text length is set to the same value.
• Fix paper margins when landscape page orientation is used.
• Changing the top margin will change the cursor position as a side effect.
• Partial support for perforation skip command.
• New [config] include configuration item to define a list of postscript files to include. Any files are located in the directory specified with the [config] ps.include config item or the default eqpcl/ps directory. A .ps file extension is implied.
• Support page orientation
• Font stroke values larger than zero are considered bold. Previous versions only used bold fonts for stroke values larger than 2
• Estimate font width (HMI) from font height for proportial fonts
• The font list (output in a PS comment) was corrected to only list the fonts actually used in the document.
• Avoid redundant reencoding of PS fonts
• Support adding PDFmarks through a separate file.
• Update barcode postscript library to current version

The eqpcl 0.4 release incorporates the following changes:

• Fixed problem scaling monotype fonts according to specified CPI or HMI values.
• Fixed a rounding problem with HMI and VMI values.
• Fixed a problem correctly detecting a page overflow.
• Update HMI value when the font pitch is specified or the primary/secondary PCL font is selected.
• Support configuration of font mapping.
• Added config option to specify a custom font path for GNU Ghostscript.

The eqpcl 0.3 release incorporates the following changes:

• Fixed a problem in the positioning of overlays.
• Added support for the align config item to specify a reference point for the positioning of overlays