source: trunk/gui/printer/cupswiz/readme.1st@ 60

CUPSWIZ - CUPS printer-creation wizard
Version 1.1

  This program is simple graphical front-end for creating CUPS-based printers
  under OS/2.

  Without this program, creating a CUPS printer under OS/2 is something of a
  headache.  First, you need to go into the CUPS web GUI and go through its
  (often agonizingly slow) creation wizard.  Then you need to make sure support
  for your printer has been imported into the OS/2 CUPS printer driver (which
  may require you to manually prep and then import a PPD file yourself).  Then
  you have to create a new OS/2 CUPS port and point it to the CUPS queue you
  created earlier.  Finally, you have to create an actual OS/2 printer object
  for your applications to print to.  This may be fine for a few expert users,
  but the average person just wants to create a printer quickly and simply.

  This program attempts to automate most of these steps.  The basic idea is 
  that you select your printer make/model from the list of those supported 
  (which will depend on your installed CUPS setup), or import a special CUPS
  PPD file which defines your printer, indicate how the printer is connected
  (whether via USB or one of a number of types of network connection), give
  it a name and description, and the program does the rest.

  Some of the highlights:
   - When you create the printer, both the CUPS printer queue and a
     corresponding OS/2 printer object are created; the CUPS port linking
     the two is also created and configured automatically.  (You can also
     opt to only create the CUPS queue if you wish.)
   - You can also select an existing CUPS printer queue (locally or on a
     remote server), in which case a corresponding OS/2 printer object will
     be created for it.
   - The appropriate model in the OS/2 PM printer driver (ECUPS.DRV or
     ECUPS-HP.DRV) is automatically identified and installed in the new OS/2
     printer object.  If an exact match is not found (and no PPD is available
     - see next point) you will offered a list of similar models, or allowed 
     to select generic support.
   - When installing a printer which is not currently defined in the OS/2
     printer driver, if a PPD exists for the new printer it will be imported
     automatically.  (If not, you will be prompted as above.)

  As this program is still under development, it is not yet as smooth as it
  could be.  See the 'Limitations & Known Problems' section below for more.


REQUIREMENTS

   CUPS (that is, a full, functioning CUPS server) must be installed and 
   running, either on the same computer or a remote server on your network.

   At least one of the following CUPS-compatible OS/2 printer presentation
   ("PrinterPak") drivers must be installed: 
     - ECUPS.DRV     (eCups driver for Gutenprint and other filter packages)
     - ECUPS-HP.DRV  (eCups driver for HPLIP) 
     - PSPRINT.DRV   (Enhanced OS/2 Postscript driver replacement)

   CUPS.PDR (the eCups port driver) must be installed.  In addition, it 
   should have a bldlevel of 1.03 (February 2011) or later.  (With earlier
   versions, you will be required to restart the WPS after creating a 
   printer.)  This also requires CUPSLPR.EXE to be installed on your PATH
   (preferably in the \TCPIP\BIN directory).

   (If you installed CUPS on your system from WarpIN packages, all of the
   above requirements should be fulfilled.)

   Other required files (all included out of the box with eComStation;
   other versions of OS/2 may or may not have them installed):
     - VROBJ.DLL (VX-REXX standard runtime; must be in the LIBPATH)
     - GZIP.EXE (GNU gzip; must be on the PATH)


INSTALLATION

  1. Place CUPSWIZ.EXE into a suitable directory.  
  2. Place CUPSPORT.EXE and PRNTOBJ.EXE either in the same directory as
     CUPSWIZ.EXE, or else in a directory on the PATH.


USAGE

  cupswiz [ <path-to-cups> | /R ]

  Where <path-to-cups> is the location of the top-level directory in which
  CUPS is installed on your system (if you are using a local CUPS server).
  This can be omitted if CUPSWIZ.EXE resides on the same drive as CUPS, or 
  if OS2.INI defines the CUPS path in the key "eCups" -> "CUPS".  If CUPS
  cannot be located, a warning popup will be displayed and the program will
  proceed as though the /R option was used.

  The /R option indicates that a WPS printer object is to be created for an
  already-existing printer queue on a remote CUPS server.  In this case, CUPS
  does not need to be installed locally, but you will need to provide a CUPS-
  specific PPD file for the printer in question.  

  Only one of the above parameters can be specified.  

  You may wish to create a program object which calls CUPSWIZ.EXE with the
  appropriate parameter.


LIMITATIONS & KNOWN PROBLEMS

  - There is no way to go 'back' in the wizard; if you need to go back and
    change a previous selection, you must cancel and start over.
  - The program has only been tested with Gutenprint, HPLIP, and native
    Postscript printers with imported PPDs.  Other drivers packages such as
    SpliX or foo2qpdl may work but this is not guaranteed.
  - If your %TMP% directory has spaces in the pathname, the program will almost
    certainly fail to work properly.  The same applies to your %LOGFILES%
    directory.
  - The CUPS printer is always created with default job options.  If you want
    to change them, you will have to do so from the CUPS administration GUI.
  - Password-protected local CUPS queues are not supported.  (Network printers
    connected with LPD, IPP or SMB should work, however.)
  - There may well be undiscovered bugs; please report any you find.

Contact: Alex Taylor (alex at altsan dot org)