*******************************************************************************
  File:     @(#)$Id: README.hpdj,v 1.23 1998/11/22 10:50:49 mjl Rel $
  Contents: README file for the hpdj distribution
  Author:   Martin Lottermoser, Metzgerfeldweg 9, 85737 Ismaning, Germany.
	    E-mail: Martin.Lottermoser@mch.sni.de

*******************************************************************************
*									      *
*	Copyright (C) 1997, 1998 by Martin Lottermoser			      *
*	All rights reserved						      *
*									      *
*******************************************************************************


Table of Contents
=================
- What is hpdj?
- Conditions of use
- Status of this release
- Files needed
- How to compile ghostscript with hpdj
- What to do on errors



What is hpdj?
=============
hpdj is a ghostscript device driver for printers understanding Hewlett-Packard's
Printer Command Language, Level 3 (PCL-3). The printer models explicitly
supported are the following HP DeskJets:

  500, 500C, 510, 520, 540, 550C, 560C, 850C, 855C

There is also some generic support for other PCL-3 printers. So far I have
not heard of any PCL-3 printer for which hpdj cannot be used. For a more
positive statement, i.e., a list of printer models for which hpdj is currently
known to work, see the manual page.



Conditions of use
=================
hpdj is open source software and can be used under the terms of the GNU Library
General Public License (LGPL), Version 2 (June 1991). You can find a copy of
the LGPL in the hpdj distribution, in several software packages distributed by
the Free Software Foundation (FSF), and at
http://www.gnu.org/copyleft/lgpl.html.

This implies in particular that you are using hpdj AT YOUR OWN RISK!



Status of this release
======================
This is version 2.5 of hpdj, released 1998-11-22. See the manual page for
possible restrictions.



Files needed
============
First, you need a ghostscript distribution. This version of hpdj has been
successfully integrated with the following ghostscript distributions:

  - Aladdin ghostscript 5.50 with the following files:
      ghostscript-5.50.tar.gz
      jpegsrc.v6b.tar.gz
      libpng-1.0.2.tar.gz
      zlib-1.1.3.tar.gz
  - Aladdin ghostscript 5.10
      ghostscript-5.10.tar.gz
      jpegsrc.v6a.tar.gz
      libpng-0.96.tar.gz
      zlib-1.0.4.tar.gz
  - GNU ghostscript 4.03
      ghostscript-4.03.tar.gz
      jpegsrc.v6a.tar.gz
      libpng-0.89c.tar.gz
      zlib-1.0.2.tar.gz
  - GNU ghostscript 3.33
      ghostscript-3.33.tar.gz
      jpegsrc.v5a.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.0.2.tar.gz is also available as ghostscript-4.03zlib.tar.gz.
You might need additional or possibly alternate files when you are not on a
UNIX system. Consult Make.htm (or make.txt in releases before 5.50) in the
ghostscript distribution for this information.

Second, you need a font distribution containing at least a basic set of fonts.
As these consist of PostScript files, they are normally not restricted to a
particular version of ghostscript although they have a ghostscript version
number in their file names. Some of the possibilities are:

      ghostscript-fonts-std-5.50.tar.gz
      ghostscript-fonts-std-5.10a.tar.gz
      ghostscript-fonts-5.10.tar.gz
      ghostscript-fonts-std-4.03.tar.gz
      ghostscript-fonts-4.0.tar.gz

Choose the one with the highest version number you can lay your hands on but,
if possible, avoid versions before 3.68. Different file names do not
necessarily mean different contents.

Third, you need the hpdj distribution:

      hpdj-<version>.tar.gz

But if you are reading this file, you should already have it. If not,
you can obtain the current distribution from the following location:

      ftp://ftp.pdb.sni.de/pub/utilities/misc/

I am distributing hpdj only in the form of gzipped tar archives. If you wish to
compile hpdj 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://www.cygnus.com/misc/gnu-win32), 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 hpdj
====================================
You need an ISO/ANSI-C-conforming compiler and library in order to compile hpdj.

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.gz. Unpacking it will create a
    subdirectory "gsN.NN" in the current directory. The former will be called
    the "gs directory" in what follows.

 2. Read Make.htm (make.txt in ghostscript versions before 5.50) 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.
    Usually, this must be done from the gs directory.

 4. Unpack hpdj from the gs directory. The file hpdj-<version>.tar unpacks
    into a subdirectory hpdj-<version> with only three files:

	README
	hpdj.tar	the distribution proper
	hpdj.tar.pgp	a PGP signature for hpdj.tar

    Change into hpdj-<version> and unpack hpdj.tar from there. This should give
    you in addition the following files in that directory:

	LGPL.txt		text of the GNU LGPL
	NEWS			list of user-visible changes between versions
	README.hpdj		this file
	*.c, *.h		source code for the driver
	contrib.mak-N.NN.diff	diffs for patching either contrib.mak or
	  devs.mak-N.NN.diff	  devs.mak in ghostscript N.NN
				  (at least for all ghostscript distributions
				  listed in "Files needed" above)
	example.mdf		example of a margin description file
	gs-hpdj.1		UNIX manual page for hpdj in source form
	gs-hpdj.ps		PostScript version of gs-hpdj.1
	hpdj.html		copy of hpdj's WWW home page
	if-hpdj			input filter using hpdj for the BSD spooler
	margins-*.ps		margin test files for the ISO A4 and US Letter
				  paper sizes in portrait and landscape
				  orientation
	zmedia2.c-N.NN.diff	patches for zmedia2.c based on gs N.NN

    Move or link the source files and the manual page (*.c *.h *.1) into the
    gs directory.

 5. Extend either contrib.mak (gs >= 5.27) or devs.mak. The hpdj distribution
    contains patch files "contrib.mak-N.NN.diff" and "devs.mak-N.NN.diff" for
    this, where "N.NN" is a ghostscript version. A patch might work for other
    versions in addition to the designated one.

    If you do not have the 'patch' command, look into one of these patch files:
    it is a comparison between the original version of the file and one
    extended for hpdj. It should be clear where lines have been modified (!),
    deleted (-) or added (+).

    After patching, select the defines you want to set for hpdj in the make
    variable 'hpdj_defines'. A description of the defines with examples is
    contained in the patched contrib.mak or devs.mak (look for the string
    "HPDJ"), although you might have to look into some (specified) source files
    in order to learn which values are permissible. If you want hpdj to install
    its own 'InputAttributes' dictionary, read the following description
    (step 6) at this point, too.

    It is a good idea to at least deliberately choose HPDJ_DEFAULT_MODEL. If
    you feel unsure about values to be selected, read the manual page first.
    On the other hand, the values of all parameters with "_DEFAULT_" in their
    name can be overridden at runtime, hence there is no sense in spending a
    lot of time brooding over this question. At least for the most recent
    version of ghostscript mentioned above, hpdj should work if you don't
    change anything after patching.

    If you are not on a UNIX platform and you are compiling with gs < 5.20,
    this step is actually fairly useless. (And if you had read make.txt in
    step 2 as I told you, you would have known that.) You must edit your
    platform-specific make file directly. It should contain a subsection
    equivalent to devs.mak.

 6. If you don't know what the 'InputAttributes' dictionary in PostScript can
    be used for or if you are compiling with a ghostscript version before
    probably 3.46, skip this step and don't set HPDJ_INPUTATTRIBUTES.

    If you want hpdj to install its own version of 'InputAttributes' in its
    page device dictionary, you should set HPDJ_INPUTATTRIBUTES. However, if
    your printer model supports custom page sizes and your ghostscript version
    has a bug in make_adjustment_matrix() when given significantly positive
    lower bounds for custom page sizes (this is the case at least for gs 3.53,
    4.03, 5.10, and 5.50) you should apply an appropriate zmedia2.c-N.NN.diff
    patch as well. 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 600 900 ] >> >>
      >> setpagedevice
      << /PageSize [ 200 300 ] >> setpagedevice
      matrix defaultmatrix ==
      quit

    This tells ghostscript to assume that the device supports media widths
    between 100 and 600 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 have reported this bug to L. Peter Deutsch on 1997-12-02. He promised to
    look at it when he had time.

    Note that setting HPDJ_INPUTATTRIBUTES will lead to less intelligible error
    messages when a page size is not supported by your printer. Instead of,
    e.g.,

      ? Device hpdj: This document requests a page size of 210 x 297 bp.
	This exceeds the custom page size limits for the DeskJet 850C.

    you will be presented with

      Error: /configurationerror in --setpagedevice--
      Additional information: [/PageSize [210 297]]

    in some gs versions even without the second of these lines.

 7. Add "hpdj.dev" to one of the DEVICE_DEVS* variables in the platform-specific
    make file. The conventional place is DEVICE_DEVS3, DEVICE_DEVS4, or
    DEVICE_DEVS5. 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 (gcc-head.mak for
    gs < 5.20).

 8. 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). (For
    gs < 5.20 this is defined in the *head.mak file for your platform;
    gcc-head.mak for Linux). This directory must exist before step 11. If you
    just want to run ghostscript from the source directory without installing
    it you can ignore "prefix" except that it influences the font path, see
    step 12.

    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; for some installations, possibly
    because of older versions of the C library, "Xt Xext X11" is sufficient for
    XLIBS. 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).

    Outside 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 (hpdj, of course, does not have this
    limitation :-) ), but the second is essential.

    On a UNIX system, edit unixinst.mak (unix-end.mak for gs < 5.20) to add
    "gs-hpdj" to the make variable MAN1_PAGES. With ghostscript 3.33 and 3.53,
    add it instead to the values for the "for" loop in the rules for the
    "install-data" target.

 9. 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" to the platform-specific file.
    (You didn't know that? Go back to step 2.)

10. Compile: "make".

11. Install (optional): "make install". If you do this, you can do "make clean"
    afterwards.

12. 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 some font distributions unpack into
    "./fonts" and others 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.

13. If your printer is not directly supported by hpdj and you wish to get the
    margins right, look into the file example.mdf and then create a margin file
    for your model from information in your printer's manual. You must at least
    specify the margins for the default paper size (A4 or US Letter as selected
    in step 8).

    If you have selected to set HPDJ_MARGIN_FILE in step 5, the margin 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.

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

    Similar remarks apply if you are on a machine with an AT&T spool system
    (lp/cancel/lpstat), although one queue should be sufficient in that case
    because you can pass command line options to the backend. However, I am not
    aware of a public domain implementation of the AT&T spooler interface.

    The hpdj distribution contains an example of a configurable input filter
    for a BSD spooler in the file 'if-hpdj'. This is not an intelligent filter
    but it has several interesting properties which are lacking 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 hpdj's manual page: some parts are particularly relevant for
    spooler backends.

15. As a final test, print one of the margin test files margins-*.ps appropriate
    for your default media size. It should print marks with a distance of 25 mm
    or 1 in (depending on the media size) from the margins. In particular, try
    first viewing and then printing the one in landscape orientation
    (margins-*Rotated.ps).

    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.



What to do on errors
====================

  - First, make the behaviour repeatable.
  - Second, check the documentation whether this really is a bug.
  - Third, find out whether the behaviour you observe is due to hpdj.
    In particular, you should eliminate the influence of the spooler.
  - Fourth, look on hpdj's FTP site to find out whether your version of hpdj
    might be outdated. If it is, repeat with the new version.

Finally, tell me about it. My address can be found at the beginning of this
file. In addition to a description of the bug, I should like to see the
following general information in your message:

  - operating system type (version seems unnecessary)
  - compiler (if you compiled hpdj yourself)
  - ghostscript distribution and version
  - hpdj version (the version is the <something> in the subdirectory name
    "hpdj-<something>"), or list the output from running "what" (or "ident")
    on the sources or the binary.
  - hpdj compilation options used (from step 5 above, or use the PostScript
    program described in the manual page)
  - your printer model

If you come across a situation where your printer does not accept the PCL
commands generated by hpdj and you have other means of creating "similar"
PCL files which are accepted by the printer, I'd also appreciate a copy of
such a file.

There is, of course, another and an optional step: fix the bug yourself and
send me the patch :-).
