*******************************************************************************
  File:     @(#)$Id: how-to-report.txt,v 1.7 2000/10/21 17:21:31 Martin Beta $
  Contents: How to report bugs, failure and success for pcl3
  Author:   Martin Lottermoser, Greifswaldstrasse 28, 38124 Braunschweig,
            Germany. E-mail: Martin.Lottermoser@t-online.de.

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


Bugs, Failures, and Successes
*****************************
This document distinguishes between "bugs" and "failures". A bug is incorrect
behaviour on the part of pcl3, a failure is a limitation of the driver with
respect to a particular printer. It's a bug if there is disagreement between
the behaviour and the documentation (the bug might be in the documentation,
though). On the other hand, if the documentation for example 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 (but I'll have to fix it
nevertheless, of course).

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.

Apart from bugs which are primarily of interest to myself, other users of this
driver would like to know to which extent a particular printer is supported by
pcl3. At the end of this document you can find guidelines and a template for
such information. Reports received in this manner will be included in future
releases of pcl3.



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 most important options are "-sDEVICE"/"-sSubdevice", "-r",
  "-sColourModel/-sColorModel", "-dBlackLevels" and "-dCMYLevels", followed by
  "-sPrintQuality" and "-sMedium". If you describe a test you made it must
  be clear from the description which of these options you specified and which
  values you used.




Guidelines for filling out the form below
*****************************************
General
=======
- 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": I don't accept anonymous or obviously nickname-signed reports.

- "E-mail address": 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")
  - PCL 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'").

- "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 should
  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 or any other relevant information.

- "Success:" and "Failure": These are intended for a single success or failure
  report, respectively, and may be repeated any number of times (including
  zero).

  By "success" I mean that 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. 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. (This is currently not under the influence of the driver.)
  Use comments for such statements if desired.

  These fields should start with the list of options given to ghostscript via
  the command line, including the "-sDEVICE" option. If you wish to add a
  comment (and for a failure you should 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.

  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:
E-mail address:
Date:
Printer:
Ghostscript version:
pcl3 version:
pcl3opts:
Media configuration file:
Remarks:
Success:
Failure:
