*******************************************************************************
  File:     @(#)$Id: how-to-report.txt,v 1.13 2001/08/01 05:36:37 Martin Rel $
  Contents: How to report bugs and hardware compatibility for pcl3
  Author:   Martin Lottermoser, Greifswaldstrasse 28, 38124 Braunschweig,
            Germany. E-mail: Martin.Lottermoser@t-online.de.

*******************************************************************************
*									      *
*	Copyright (C) 2000, 2001 by Martin Lottermoser			      *
*	All rights reserved						      *
*									      *
*******************************************************************************


Bugs and Failures
*****************
This document distinguishes between "bugs" and "failures". A bug is incorrect
behaviour on the part of pcl3, a failure is described by a set of
hardware-relevant parameter values which are not accepted by a particular
printer. Most often a failure is due to hardware limitations in the printer,
not to a problem in pcl3, although it might be difficult to find out which is
the case. For the user, this distinction is fortunately irrelevant.


Bugs
****
The basic rule is that it's a bug if there is disagreement between the
behaviour and the documentation (the bug might be in the documentation, though).
For example, if the documentation states that pcl3 produces a core dump under
certain circumstances, this is by definition not a bug, which means that you
should not report it (I'll have to fix it nevertheless, of course).

If your printer has a specific subdevice in pcl3 (e.g., if you have a
Hewlett-Packard DeskJet 540, this is the "hpdj540" subdevice) and the result
when using this subdevice is not accepted by the printer or there is printer
functionality you cannot access through this subdevice, this is a bug.

If you find a bug in pcl3, please report it. The format of your message is
irrelevant, but the content should be sufficiently detailed that I can
reproduce the behaviour. You should always specify the versions of gs and pcl3
you used. Please make sure that the behaviour is due to pcl3 and not to other
causes. In particular, if nothing seems to work and you are on a UNIX system,
do the following:

  - Generate the PCL file by calling gs yourself, and print through a
    "raw"/"transparent" queue which does not modify the file.
  - If spooled printing fails, log in as root and try to send the file
    directly to the device file. If it works, the problem is in the spooler.
  - If even that fails, send a line of text (still as superuser) directly
    to the device, followed by a form feed:

      printf 'Hello!\r\n\f' > /dev/...

    If this also does not work, you very likely have a kernel or hardware
    problem.

I am writing this because there have been cases where people complained that my
driver wasn't working at all and where the cause turned out to be, e.g., a
misconfiguration of the spooler. Please don't bother me with problems of this
kind; I have enough to do correcting my own mistakes. However, I only demand
that you take reasonable steps to ensure that it isn't you who has created the
problem. If you can't decide which component is at fault, by all means contact
me -- just don't expect a quick answer and don't start by telling me that my
driver doesn't work :-).



Hardware compatibility reports
******************************
The pcl3 driver is intended to support a large number of printers. Because the
PCL-3 documentation supplied by Hewlett-Packard is incomplete and occasionally
wrong (sometimes obviously so because of inconsistencies), tests must be made
on various printers in order to discover whether the driver can really be used
for a particular printer model and which parameter values one should specify.
As I do not have access to a complete range of PCL-3 printers, I must rely on
others to do this for me.

If you have a PCL-3 printer and are using pcl3, please check the file
reports.txt whether there is already an entry for your printer or not. If there
is none or if the hardware-relevant parameters listed are different from the
ones you used, please compose a report in the format described below and send
it to me. You need not cover all possible combinations; in fact, this might be
too confusing for others anyway. Even a single success report, however, can
help someone else with less knowledge or experience to get started. This is a
service *you* can provide to the community of pcl3 users.



Guidelines for testing
======================
- Read the documentation. Please. :-)

- As test files, use publicly available PostScript files, preferably those
  included in the ghostscript or pcl3 distributions. The file levels-test.ps in
  the latter is a good starting point.

- Keep in mind that some environment variables influence ghostscript's
  behaviour and make sure their values are as intended.

- If you have access to a manufacturer-endorsed driver for your printer, use
  it to generate some test files with various settings, analyse them with
  pcl3opts, and try the suggested option combinations first.

- The basic hardware parameters to test are colour model, resolution, and the
  number of intensity levels.

    - Colour model: The interesting models are Gray, CMY, and CMY+K/CMYK,
      depending on your printer. You need not bother with CMY for a CMY+K or
      CMYK printer unless you discover that the CMY cartridge supports a
      higher resolution than the black cartridge.

    - Resolution: Check your printer's documentation first. It should at least
      list the highest supported resolution, possibly separately for black and
      colour printing. If you don't have access to the documentation, a good
      set to test with is {300, 600x300, 600, 1200}. Smaller resolutions
      ({75, 100, 150}) are sometimes also supported but they are uninteresting
      for serious printing.

      Resolution tests are best made with a file where only the top left corner
      of the sheet is used. It should contain some structure of known extension.
      If a resolution is not accepted, the printer usually prints the picture
      anyway, but at a supported resolution, leading to magnified or reduced
      output.

    - Intensity levels: Test this only if your printer's documentation claims
      that some kind of Resolution Enhancement (e.g., C-REt) is supported or
      pcl3opts tells you that an official driver generates files with this
      property. Unless pcl3opts tells you differently, start with 300 ppi and
      4 levels for all colorants used.

  Whether a particular value for a parameter is supported often depends on
  the values for other parameters. In some cases, even the print quality is
  important. If in doubt, test with "presentation".

- If your printer has special hardware functionality, tests for that are
  also interesting (duplex printing, banner printing, different input or
  output trays). If you are using "unspec" or "unspecold", you should also
  always try compression method 9 unless the pcl3 documentation states that it
  is not supported by your printer.



General rules for reports
=========================
- You can use all characters in ISO 8859-1, plus HT and NL/LF.
- Please keep to the following syntactic rules which simplify converting the
  information into other formats:
  - The report consists of a sequence of fields, each occupying an integral
    number of lines.
  - Each field begins with a field name, starting in column 1 and ending with
    the first following colon (':') in the same line.
  - The content of a field may be continued over several lines provided all
    continuation lines are either empty or indented with blanks (SP or HT).
    Trailing empty lines are ignored.
  - With the exception of "Success" and "Failure", every field may appear at
    most once in a report. If it appears a second time in a file, a new report
    is assumed to start at this point.
- Make your report sufficiently detailed to be reproducible but don't tell us
  your life story.



Special remarks for individual fields
=====================================

- "Name": Supply your full name here. I don't accept anonymous or obviously
  nickname-signed reports.

- "E-mail address" (optional): choose a stable one, your information might be
  used for several years. Omit this field if you do not wish your e-mail
  address to be disclosed to other users of pcl3.

- "Date": I prefer the internationally standardized notation, YYYY-MM-DD.

- "Printer": Be as precise as possible in identifying the printer. Ideally,
  I should like to have the following kind of information (as an example
  I'm giving some values for a DJ 850C):
  - printer name ("HP DeskJet 850C")
  - manufacturer's model identification ("C2145A")
  - firmware revision ("9.20 02/14/95")
  At least some of Hewlett-Packard's printers issue this information when you
  print a diagnostic or self test. If your printer's manual doesn't tell you
  how to generate such a test, try sending the command "ESC z" to the printer
  (on a UNIX system, you can use "printf '\x1bz'" to generate it).

- pcl3opts (optional): Use this field to describe pcl3opts's output if you ran
  pcl3opts on files generated by manufacturer-endorsed drivers and you have
  obtained interesting information. You should always describe the driver you
  used.

  Interesting information is for example that the official driver generated
  files with certain settings for which pcl3opts did not give a warning but
  nevertheless you were not able to print such a file with pcl3. Expect me to
  ask you for a copy of such a file.

- "Media configuration file" (optional): If you used a media configuration file
  and its content was relevant for the test or you wish to make the file
  available to other users, include it or a reference to it here. You must
  state where the information came from, so it can be verified in case of
  discrepancies.

- "Remarks" (optional): Use this, if needed, for global information applying
  to a number of tests (perhaps a summary) or any other relevant information.

- "Success:" and "Failure": These are intended for describing the result of
  using a single option combination and may be repeated any number of times
  (including zero). Each report should be independent of the others so they can
  be sorted differently if needed.

  Keep in mind that the key purpose of a report is to find out which hardware
  parameters work and which don't. It is therefore a success if the driver is
  at least able to correctly tell the printer how to paint shapes at the level
  of the printer's hardware capabilities (resolution, colorants and
  intensities). A good test file is levels-test.ps which has been designed for
  this purpose. I don't count it a failure when the result of printing a
  photograph or a similarly demanding document is not as aesthetically pleasing
  as it should be or when a problem is due to a bug in ghostscript. Use
  comments for such statements if desired. However, the decision whether an
  entry is a success or a failure remains yours to make, not mine.

  These fields should start with the list of options given to ghostscript via
  the command line, including the "-sDEVICE" option. You should omit options
  which are obviously irrelevant for the outcome of the test (like "-dNOPAUSE"
  or "-sOutputFile"), but otherwise the option list must be complete. If you
  wish to add a comment (and for a failure you must always do that), terminate
  this list with a period followed by a newline and add the comment after that.
  Here's an example:

    Failure: -sDEVICE=pcl3 -r1200 -sColourModel=CMYK
      -sPrintQuality=best -sMedium=transparency.
      Printed at twice the size intended.

  The option list terminates immediately after "transparency" in this case.
  Note that you don't need backslashes here if you break the command line
  into several text lines.

  If you did something interesting in the PostScript file (like setting page
  device parameters to unusual values), append the PostScript code in the
  comment part or in the "Remarks" field.

*****************<Start of form; cut here>*************************************

Name: [your full name]
E-mail address: [optional]
Date: [YYYY-MM-DD]
Printer: [at least manufacturer and model]
Ghostscript version: [GNU or AFPL, version number]
pcl3 version: [version number]
pcl3opts: [optional; information on printer capabilities obtained by running
  pcl3opts on other drivers' output files]
Media configuration file: [optional]
Remarks: [optional; use, e.g., for global comments or a summary]
Success: [options used, repeat any number of times]
Failure: [options used, repeat any number of times. Don't forget to give your
  reason for classifying this as a failure (after terminating the options with
  a period followed by a newline).]