*******************************************************************************
  File:     @(#)$Id: README,v 2.6 2000/11/09 18:33:58 Martin Beta $
  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 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 to do on errors



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. For a more positive statement, i.e., a list of printer models for
which pcl3 is currently known to work (possibly with restrictions), see the
manual page.



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 (FSF), 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.0.2 of pcl3, released 2000-11-09. This is a beta release.
See the manual page and the BUGS file for further restrictions.



Files needed
============
First, you need a ghostscript distribution. This version of pcl3 has been
successfully integrated with the following ghostscript distributions and
the specified files (which you will usually find as gzip-compressed files
with an additional .gz suffix):

  - Aladdin ghostscript 6.01:
      ghostscript-6.01.tar
      jpegsrc.v6b.tar
      libpng-1.0.5.tar
      zlib-1.1.3.tar
  - GNU ghostscript 5.50:
      gnu-gs-5.50a.tar
      jpegsrc.v6b.tar
      libpng-1.0.2.tar
      zlib-1.1.3.tar

Other ghostscript versions than those mentioned here are very likely to work,
too.

The third-party archives can frequently also be found under a file name
matching the ghostscript distribution they can be used with. For example,
zlib-1.1.3.tar is also available as ghostscript-6.01zlib.tar.
You might need additional or possibly alternate files when you are not on a
UNIX system. Consult http://www.cs.wisc.edu/~ghost or Make.htm in the
ghostscript distribution for this information.

Second, you need a font distribution containing at least a basic set of 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

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.00.

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	a GnuPG 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:

	BETA		remarks addressed to beta testers
	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
	lib		if-pcl3, example.mcf
	ps		PostScript files
	src		C source code and build files

 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 the appropriate original file 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. If your ghostscript version has a bug in make_adjustment_matrix() when
    given significantly positive lower bounds for size ranges in
    "InputAttributes" you should apply an appropriate src/zmedia2.c-N.NN.diff
    patch. To test for this bug if you have a working binary of ghostscript
    including the "bit" device, run

      gs -sDEVICE=bit

    on the following PostScript code:

      << /InputAttributes
	<< 0 << /PageSize [ 100 100 700 900 ] >> >>
      >> setpagedevice
      << /PageSize [ 200 300 ] >> setpagedevice
      matrix defaultmatrix ==
      quit

    This tells ghostscript to assume that the device supports media widths
    between 100 and 700 and heights between 100 and 900 bp, and requests a
    page size 200 bp wide and 300 bp tall. Ghostscript should print

      [1.0 0.0 0.0 -1.0 0.0 300.0]

    on standard output if you don't have the bug and

      [1.0 0.0 0.0 -1.0 200.0 0.0]

    if you do. You can use other drivers to test for this, too, but to reliably
    evaluate the result you need information on the driver's device coordinate
    system and resolution.

    A simple visual test can be made by replacing the last two lines in the
    program, "matrix ... quit", by

      /Courier findfont 10 scalefont setfont
      100 150 moveto (Hello) show
      showpage

    and running it through a real device driver, preferably for the screen.
    If you have the bug, the page will be empty, if you don't, you'll see
    "Hello" in the middle.

    I had reported this bug to L. Peter Deutsch on 1997-12-02. He promised to
    look at it when he would have time. The behaviour is still the same in
    gs 6.01.

 8. There is also a bug in ghostscript's default configuration for the
    undercolour removal and black generation functions. It shows up when
    printing PostScript documents using the RGB colour space ("setrgbcolor" or
    "sethsbcolor") on a device where the CMYK space is the native colour space;
    this is the case for pcl3 if you specify "-sColourModel=CMYK". The bug
    results in black being printed as a mixture of cyan, magenta, and yellow.
    On my printer, this is a slightly greenish grey with fuzzy edges. My
    subjective impression is that correcting this bug leads to sharper-looking
    images.

    To check for the presence of this bug, run gs on the following command:

      0 0 0 setrgbcolor [ currentcmykcolor ] ==

    gs will issue "[1.0 1.0 1.0 0.0]" on standard output if it would print the
    mixture and "[0.0 0.0 0.0 1.0]" if it would print true black. You should
    specify a CMYK device like "bitcmyk" for this test.

    To correct this behaviour, look for the following lines in gs_init.ps
    (starting at line 1229 in Aladdin gs 6.01):

      % Set the default screen and BG/UCR.
      /.setdefaultbgucr {
	systemdict /setblackgeneration known {
	  { pop 0 } dup setblackgeneration setundercolorremoval
	} if
      } bind def

    Replace the line containing "setundercolorremoval" with the following:

      {} dup setblackgeneration setundercolorremoval

    In GNU ghostscript 5.50 the corresponding section is positioned at
    line 1450:

      % Set the default screen and BG/UCR based on the device resolution and
      % process color capability.
      /.setdefaultbgucr systemdict /setblackgeneration known { {
	processcolors 1 eq { { } } { { pop 0.0 } } ifelse
	dup setblackgeneration setundercolorremoval
      } } { {
      } } ifelse bind def

    You should replace the line containing "processcolors" with:

      {}

    I had reported this bug to L. Peter Deutsch on 1998-12-09 and he wrote he
    would change the behaviour in the next release. This happened subsequently
    in gs 6.00, but gs 6.01 reverted to the previous behaviour.

 9. Other changes to the platform-specific make file and other files

    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 12. If you just want to run
    ghostscript from the compilation directories without installing it you can
    ignore "prefix" except that it influences the font path, see step 13.

    If you intend to use PostScript resources, you should also at some stage
    edit the definitions of "FontResourceDir" and "GenericResourceDir" in
    gs_res.ps to reflect your local conventions. (And if you don't know what
    I'm talking about you don't need it.)

    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).

    Everywhere except in the US, it is also a good idea to set GENOPT to "-DA4"
    in the make file and to uncomment the "% (a4)..." line in gs_init.ps in
    order to set the default paper size to ISO A4 instead of US Letter. The
    first is only necessary for some drivers which are not able to deduce the
    media size from the PostScript code (pcl3, of course, does not have this
    limitation :-) ), but the second is essential for all documents not
    requesting a particular page size.

10. On a UNIX system and with gs < 5.20, you must now run tar_cat to regenerate
    your platform-specific make file (unix-gcc.mak for Linux). Independent of
    that you need a symbolic link from "makefile" in the gs directory to the
    platform-specific file. (You didn't know that? Go back to step 2.)

11. Compile: "make" to generate the ghostscript binary, then "make pcl3opts" to
    generate the pcl3opts binary. The latter step might fail if you are not on
    a standard UNIX system.

12. Install (optional): "make install pcl3-install".

    If you are not on a standard 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.

    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): pcltools-en.cat (English) and pcltools-de.cat (German).
    These catalogues are not installed automatically. Each file should be
    copied into an appropriate NLS directory under a name matching your NLSPATH
    conventions with "pcltools" for %N (on Linux, check the documentation for
    the GNU C library to find the default value for NLSPATH; usually it
    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.

13. 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 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.

14. This might be 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).

15. 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 paper size (A4 or
    US Letter as selected in step 9).

    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.

16. 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.

    On Linux systems, one usually has a BSD 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 BSD 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. On my system, I have installed
    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 should be sufficient because you can pass command line options to
    the backend.

    The pcl3 distribution contains an example of a configurable input filter
    for a BSD spooler in the file "lib/if-pcl3". This is not an
    intelligent filter but it has several useful features which are missing in
    more elaborate filters. Read the comments in the file for further
    information.

    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.

17. As a final test, you can print one of the margin test files
    ps/margins-*.ps appropriate for your default media size. It 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.
