*******************************************************************************
File: @(#)$Id: README,v 1.1 2002/07/12 16:11:41 tillkamppeter Exp $
Contents: README file for the pcl3 distribution
Author: Martin Lottermoser, Greifswaldstrasse 28, 38124 Braunschweig,
Germany. E-mail: Martin.Lottermoser@t-online.de.
*******************************************************************************
* *
* Copyright (C) 1997, 1998, 1999, 2000, 2001 by Martin Lottermoser *
* All rights reserved *
* *
*******************************************************************************
Table of Contents
=================
- What is pcl3?
- Conditions of use
- Status of this release
- Files needed
- How to compile ghostscript with pcl3
What is pcl3?
=============
pcl3, formerly called hpdj, is a ghostscript device driver for printers
understanding Hewlett-Packard's Printer Command Language, Level 3+ (PCL 3+).
Some printer models (currently exclusively HP DeskJets) are explicitly
supported, but there is also generic support for other PCL-3+ printers.
So far I have not heard of any PCL-3 printer for which the driver cannot be
used at all and it even works for some printers which claim to be
PCL-3-conforming but aren't. For a more positive statement, i.e., a list of
printer models for which pcl3 is currently known to work and how, see the file
doc/reports.txt.
Conditions of use
=================
pcl3 is free software and can be used under the terms of the GNU Lesser General
Public License (LGPL), Version 2.1 (February 1999). You can find a copy of the
LGPL in the pcl3 distribution, in several software packages distributed by the
Free Software Foundation, and at http://www.gnu.org/copyleft/lesser.html.
This implies in particular that you are using pcl3 AT YOUR OWN RISK!
Status of this release
======================
This is version 3.3 of pcl3, released 2001-08-19. This is an ordinary
(non-beta) release. Read the manual page to learn about the supported
functionality and restrictions.
Files needed
============
First, you need a ghostscript distribution. This version of pcl3 has been
successfully integrated with the following ghostscript distributions:
- AFPL ghostscript 7.0
- GNU ghostscript 6.51
Other ghostscript versions than those mentioned here are very likely to work,
too.
To obtain a ghostscript distribution, visit http://www.cs.wisc.edu/~ghost.
You will also need some third-party archives in addition. See the URL just
mentioned or check Make.htm in the ghostscript distribution you have obtained.
Second, you need a font distribution containing at least a basic set of
PostScript fonts. Such a set is distributed with ghostscript as an "std" and an
"other" archive. Because font files are PostScript files, they are normally not
restricted to a particular version of ghostscript although the archives have a
ghostscript version number in their file names. Some of the possibilities are:
ghostscript-fonts-std-6.0.tar.gz
ghostscript-fonts-other-6.0.tar.gz
gnu-gs-fonts-std-6.0.tar.gz
gnu-gs-fonts-std-5.50.tar.gz
gnu-gs-fonts-other-6.0.tar.gz
gnu-gs-fonts-other-5.50.tar.gz
Unless you already have such a set on your system, fetch at least an "std"
archive and choose the one with the highest version number you can readily lay
your hands on. Different file names do not necessarily mean different contents.
A side remark: The "StandardSymL" font dated 1998-03-26 (first present in
a 5.10 font archive) contains the Euro glyph. However, it has the wrong
PostScript name ("euro" instead of "Euro") and the wrong default encoding
(decimal 240 instead of octal 240). This is corrected in the version dated
1999-10-21. Ghostscript's "SymbolEncoding" encoding vector had the same bugs
in gs 5.50 and this was fixed in gs 6.0.
Third, you need the pcl3 distribution:
pcl3-<version>.tar.gz
But if you are reading this file, you should already have it. If not,
you can obtain the current distribution through the following URL:
http://home.t-online.de/home/Martin.Lottermoser/pcl3.html
I am distributing pcl3 only in the form of gzipped tar archives. If you wish to
compile pcl3 on a non-UNIX platform, you need gzip, tar (on a Microsoft Windows
system, you can use the Cygnus port of the GNU tools, available from
http://sources.redhat.com/cygwin), and a command to convert text files from
LF-terminated lines to whatever the line termination conventions are on your
system.
How to compile ghostscript with pcl3
====================================
You need an ISO-C-conforming compiler and library in order to compile pcl3.
The following description is heavily biased towards UNIX systems and in
particular Linux.
1. Unpack the core distribution
This is the file ghostscript-N.NN.tar or gnu-gs-N.NN.tar. Unpacking it will
create a subdirectory "gsN.NN" in the current directory.
In order to clearly identify directories I'm going to use the following
expressions:
- "gs directory": the directory gsN.NN you have just created
- "documentation directory": In gs 5.50 this is identical to the
gs directory, in newer versions it is the subdirectory "doc" in the
gs directory.
- "source directory": In gs 5.50 this is identical to the gs directory,
in newer versions it is the subdirectory "src" in the gs directory.
2. Read Make.htm in the documentation directory on how to compile ghostscript.
In particular, you should learn
- which other files you need to unpack and how, and
- what the platform-specific make file for your platform is.
3. Unpack the other files needed (except the font files) as directed by
Make.htm.
4. Unpack pcl3, preferably in the gs directory. The file pcl3-<version>.tar
unpacks into a subdirectory pcl3-<version> with only three files:
README-cover
pcl3.tar the distribution proper
pcl3.tar.sig an OpenPGP signature for pcl3.tar
Make the directory accessible under the name "pcl3" from the gs directory,
either by renaming it or by creating an appropriate symbolic link. Then
change into the pcl3 directory and unpack pcl3.tar from there. This should
give you in addition the following regular files in that directory:
BUGS pcl3's bug list
LGPL text of the GNU LGPL
NEWS list of user-visible changes between versions
README this file
Furthermore, a number of subdirectories will have been created:
doc documentation
eprn C source code for the eprn device on which pcl3 is based
lib cups-pcl3, example.mcf, if-pcl3
ppd PostScript printer description files
ps PostScript files
src C source code and build files for pcl3
5. Extend contrib.mak in the source directory.
The pcl3 distribution contains extension files "src/contrib.mak-N.NN.add"
for this purpose, where "N.NN" is a ghostscript version (at least for all
ghostscript distributions listed in "Files needed" above). These files
contain text to be inserted into contrib.mak at some point, for example at
the end. An extension file might work for other gs versions in addition to
the designated one.
The extension files contain an initial comment which gives you some
further instructions (compile options, files shared with hpdj, available
devices).
6. Add at least "$(DD)pcl3.dev" ("pcl3.dev" in gs 5.50) to one of the
DEVICE_DEVS* variables in the platform-specific make file. The conventional
place is DEVICE_DEVS3, DEVICE_DEVS4, or DEVICE_DEVS5. For a complete list
of pcl3 devices you can define here, see the contrib.mak-N.NN.add file.
You might also wish to modify the device and feature lists in other
respects.
On a Linux system, the file to edit is unix-gcc.mak.
7. Read the file doc/gs-mods.txt about modifications I suggest for making in
ghostscript's source code or configuration files.
8. Other changes to the platform-specific make file
For a UNIX system and if you wish to install the software in a non-default
directory, edit the make variable "prefix" (normally /usr/local).
This directory must exist before step 10.
If you intend to use the X Window System, check whether the values for the
variables XINCLUDE, XLIBDIRS, and XLIBS are correct. On Linux, they should
usually be "-I/usr/X11R6/include", "-L/usr/X11R6/lib", and
"Xt SM ICE Xext X11", respectively. You can ignore XINCLUDE if one of the
directories searched by the compiler anyway contains an appropriate "X11"
subdirectory (e.g., there is a link from /usr/include/X11 to
/usr/X11R6/include/X11).
9. On a UNIX system, check that the platform-specific make file (unix-gcc.mak
for Linux) is available to make from the gs directory (or use "-f"). Then,
in the gs directory, type "make" to generate the gs binary, and
"make pcl3opts" to generate the pcl3opts binary. The latter step is likely
to fail if you are not on an XPG-conforming UNIX system.
10. Install: "make install pcl3-install".
If you are not on a UNIX system, you'll probably have to omit the
"pcl3-install" part. Instead, copy pcl3's doc/*.html files and the compiled
pcl3opts binary (provided it did compile) to appropriate places yourself.
If "make pcl3-install" gives you a usage message from the "instcopy"
command you've forgotten "make pcl3opts" in step 9.
The "make pcl3opts" call, if successful, has also generated two NLS message
catalogues for pcl3opts in ghostscript's object file directory ("obj" in
the gs directory): pcl3opts-en.cat (English) and pcl3opts-de.cat (German).
These catalogues are not installed automatically. If you wish to use them,
copy each file into an appropriate NLS directory under a name matching your
NLSPATH conventions with "pcl3opts" for %N. (On Linux the default value for
NLSPATH usually includes /usr/share/locale/%L/%N and
/usr/share/locale/%L/LC_MESSAGES/%N.) You need the English catalogue only
if you want pcl3opts to issue media sizes in inches instead of millimetres.
Note that pcl3's PostScript example files (subdirectory "ps") are also not
installed. If you find them useful, copy them to an appropriate place
yourself.
11. Install the fonts.
First call the newly generated "gs" with the option "-h". The output will
show you ghostscript's search path. The fonts should be present in one of
these directories. On UNIX systems, the convention is to use a ".../fonts"
directory for this purpose. Note that newer font distributions unpack into
"./fonts" and some older ones into ".".
If you already have a ghostscript installation somewhere else on your
system and its font directory is not included in the font path of your new
gs binary, you can create a symbolic link from the ".../fonts" directory to
your installed fonts, or use the environment variable GS_FONTPATH to direct
gs to the directory/ies in question.
12. This is a good point to take a first look at pcl3's documentation if you
haven't done that yet. It is available as a manual page (type "man gs-pcl3")
and in HTML format (open gs-pcl3.html in the installed ghostscript's
documentation directory with an HTML browser).
13. If your printer is not directly supported by pcl3 and you wish the driver
to be correctly informed about supported media sizes and the associated
hardware margins, look into the file lib/example.mcf and then create a
media configuration file for your printer from information in its manual.
You must at least specify an entry for the default page size (A4 or
US Letter as selected in your ghostscript configuration).
If you have selected to set PCL3_MEDIA_FILE in step 5, the media file
you have just created should be installed under that path name.
14. Integration with a spool system
This depends on your spooler :-). The minimum you need is the ability to
print a file without any modifications by spool commands. In that case
you can generate a PCL file by calling ghostscript with option values
appropriate for your current needs and pass the generated file through the
spool system for printing. Such spool queues are usually called "raw"
queues.
If you are using CUPS (Common UNIX Printing System, http://www.cups.org),
you can proceed as follows:
- Create a file ppd/gs.ppd describing the site-specific properties of
your ghostscript installation.
- Select a PPD file suitable for your printer model and copy it into
CUPS' "model" directory using the ppd/catppd script.
- Copy the lib/cups-pcl3 filter to CUPS' "filter" directory.
- Install a new print queue based on the new PPD file.
The details of the first two steps are described in the ppd/README file.
You should also at some stage read the initial comments in lib/cups-pcl3.
Most Linux systems still use a Berkeley spooler (lpr/lprm/lpq) which maps
the queue name in the print request to a call to some backend command,
based on /etc/printcap. Frequently, the backend is an intelligent filter
which will examine the contents of the file to be printed and perform
appropriate processing based on the file type.
Because with an ordinary Berkeley spooler one cannot pass command line
options to the backend, it is a good idea to install several print queues
for those option combinations one needs frequently. You could for example
install seven print queues: one for passing any file to the printer
unchanged, three for monochrome and three for colour printing, each of the
last two groups having a queue for "draft", "normal" and "presentation"
quality.
If you are on a machine with an AT&T spool system (lp/cancel/lpstat),
one queue can be sufficient because you can pass command line options to
the backend. However, if your printer has different hardware configurations
(either black or CMY cartridge, either banner or tray feed) and you cannot
completely control when print jobs are submitted, you should still install
separate queues for these configurations, take steps to make it at least
likely that the jobs submitted to each queue have the necessary properties,
and enable only the queue agreeing with the printer's current configuration.
You also need only one queue independent of the spool system if you have a
spooler frontend capable of inserting PostScript setup commands into the
document to be printed or if such a document manager is part of your
spooler (the latter applies to CUPS). The pcl3 distribution contains the
necessary PPD files for these cases; read the file ppd/README for further
instructions. Note that the remarks above on separate queues for distinct
hardware configurations apply also to this case.
The pcl3 distribution contains configurable input filters for the Berkeley
spooler and for CUPS in the files "lib/if-pcl3" and "lib/cups-pcl3",
respectively. Read the initial comments in these files for further
instructions.
You should also not forget to skim the "OPTIONS" and "CONFIGURATION"
sections in pcl3's manual page: some parts are particularly relevant for
spooler backends.
15. Test your configuration by printing a few example documents.
As a first step and in particular when you are using a media configuration
file, print some of the margin test files ps/margins-*.ps appropriate for
your current media size. They should show marks with a distance of 25 mm or
1 in (depending on the media size) from the margins. If you find deviations
from what you expect, read the manual page and in particular the
description of how to use the "Margins" or "PageOffset" entries to correct
misalignments.
For trying out various rendering parameters, ps/levels-test.ps is a good
test file, in particular if you print through a spooler, because the
printed page will tell you which settings were effective.
