INTRODUCTION This is Gimp-Print version 4.2.0, the first stable release in the 4.2 line. Gimp-print is the print facility for the Gimp, and in addition a suite of drivers that may be used with common UNIX spooling systems using GhostScript or CUPS. These drivers provide printing quality for UNIX/Linux in many cases equal to or better than proprietary vendor-supplied drivers, and can be used for many of the most demanding printing tasks. Please read this README, and the NEWS file carefully! Many things have changed from previous releases. The package is quite different in many ways from Gimp-Print 4.0, and you should read these instructions carefully. A user's manual exists in doc/users_guide; it is normally installed in PDF and HTML form in /usr/local/share/gimp-print/doc. This manual covers setup and use of the GIMP Print plug-in and the CUPS driver. We urge all distributors of this package to read the PACKAGING and KNOWN BUILD ISSUES section below. BASIC INSTALLATION Gimp-Print includes the following primary components: - The core driver, libgimpprint.so - A user's manual - A Print plug-in for the GIMP - A Ghostscript driver, stp - A CUPS (Common UNIX Printing System) driver - Support for the Foomatic spooler configuration system By default, Gimp-Print builds the Print plugin for the GIMP, the user's manual, and a utility to perform head cleaning, nozzle alignment, and other tasks on EPSON Stylus inkjet printers, named "escputil". Directions for building other components are listed below. Please check our web site at http://gimp-print.sourceforge.net for details about what is and is not supported. Please report any problems to gimp-print-devel@sourceforge.net. In general, to build Gimp-Print, you run the following commands: ./configure [options] make make install Note: This package requires the use of GNU Make to compile. On systems with both GNU make and another make installed, GNU make may be named `gmake' or `gnumake' THE GIMP Gimp-print 4.2 requires the Gimp 1.2. To build and install the Gimp Print plug-in: ./configure [--with-gimp] make make install You may optionally specify --with-gimp if you wish to be explicit about building the Gimp Print plugin; --with-gimp is implied, so you do not actually need to specify it. This installs the GIMP Print plugin in your system plug-in directory. If you wish to install it in your personal plugin directory, you may use ./configure --enable-user-install If you have installed the Gimp as a precompiled package (e. g. from an RPM), you will need to install the gimp-devel package as well as the gimp package. The gimp package as supplied in most distributions only contains what's needed to run the Gimp. The gimp-devel package contains additional files required to actually build new plugins. On some systems, you will also need to install gtk-devel and glib-devel packages as well. If you have installed the Gimp from source on Linux: after running make install, you must run ldconfig as root before attempting to build this plugin. CUPS Gimp-print 4.2 requires CUPS 1.1.9 or higher. We recommend use of 1.1.12; that release of CUPS features better internationalization and fixes some important bugs. This package includes a CUPS driver that may be built, allowing use of this software for general printing purposes. To build and install the CUPS driver, you must run: ./configure --with-cups make make install /etc/software/init.d/cups restart The last command varies with your operating system. It is typically /etc/init.d/cups, /etc/rc.d/cups, or even /etc/rc.d/init.d/cups. NOTE: If you are using CUPS 1.1.11 or higher, and you have a USB-connected printer, you must have a printer connected to each USB port that you plan to use and powered on when you restart CUPS. If you do not do so, you will not be able to perform the following step (reinstalling the printer), as described below. Following this, you must reinstall any printers that you are using Gimp-Print PPD's with. Such printers may be identified in any CUPS front end (e. g. KUPS, or via the web interface) because they look something like this: EPSON Stylus Photo EX, CUPS+GIMP-print v4.2.0(en) If the version number (in this case, 4.2.0) does not match the version of Gimp-Print that you are installing, you must use Modify Printer to force the new PPD file to get installed. Failure to do so may lead to incorrect output and/or other errors! Starting with CUPS 1.1.11, you cannot choose an AppSocket connection and enter "usb:/dev/usblp0" or the like as the URI; you will get a "client-error-not-possible" error at the end of the installation process, and you will have a message like the following in your CUPS error log (typically /var/log/cups/error_log): E [21/Nov/2001:17:59:07 +0500] add_printer: bad device-uri attribute 'usb:/dev/usblp0'! If the printer was turned on correctly, you will be given a choice of a USB connection in the Device dialog. You may also have problems if you have a .lpoptions file that has old options set. If you have problems printing, please remove any existing .lpoptions file in your home directory and try printing again. This package normally builds translated versions of the PPD files. This provides PPD files translated into the languages that this package supports. However, the translation process does not work correctly on all systems; in particular, many BSD systems are known to simply build multiple copies of the English PPD files. If your system does not build these files correctly, which will be apparent when you use a CUPS front end to select a PPD file and you see something like this: EPSON Stylus Photo EX, CUPS+GIMP-print v4.2.0(en) EPSON Stylus Photo EX, CUPS+GIMP-print v4.2.0(en) EPSON Stylus Photo EX, CUPS+GIMP-print v4.2.0(en) rather than this: EPSON Stylus Photo EX, CUPS+GIMP-print v4.2.0(en) EPSON Stylus Photo EX, CUPS+GIMP-print v4.2.0(sv) EPSON Stylus Photo EX, CUPS+GIMP-print v4.2.0(fr) you may wish to turn off the translation of PPD files: ./configure --with-cups --without-translated-ppds You may also wish to do this to reduce the number of PPD files installed on your system The PPD files associated with this driver are for Level 2 PostScript. CUPS implements most level 3 PostScript, but there are a few constructs that are not implemented. For this reason, we have chosen to define a LanguageLevel of 2 rather than 3. PostScript level 3 files are smaller in some cases, and can produce smoother gradients, but few applications generate Level 3 PostScript. If you would like to use level 3 PostScript, you may do ./configure --with-cups --enable-cups-level3-ppds Unless you fully understand what you are doing, we recommend not doing this. If you do not wish to build the Gimp Print plugin, you must run ./configure --with-cups --without-gimp We recommend that all users who wish to use this package for general purpose printing install CUPS and use that as their printing system, rather than the traditional lpd or lp systems. It is much simpler to manage than lpd, and provides an excellent web-based interface for both administration and use. Please visit http://www.cups.org for information on downloading and installing CUPS. FOOMATIC This package includes support for the Foomatic meta-driver package. This requires the foomatic-xml distribution. Foomatic is available from http://www.linuxprinting.org/foomatic.html. It is also available in Debian unstable. For best results, use the version in cvs. The first version of Foomatic (the one used with Gimp-Print 4.0) is not compatible with Gimp-Print 4.2. Note that the Foomatic driver is named `stp' in Gimp-Print 4.0; in Gimp-Print 4.2 it is named `gimp-print'. The data for the Gimp-Print 4.0 driver is not compatible with the 4.2 driver. To build the Foomatic data, you must run: ./configure --with-foomatic make make install The "make install" step will add the necessary data to your Foomatic installation. It will not create the spooler-specific data files; to do that, you must follow this procedure: - examine the output of `foomatic-configure -O', and find the foomatic ID for your printer. - Run foomatic-datafile with that printer ID, the driver name 'gimp-print', and the spooler type you wish to use. foomatic-datafile -h explains how to run this program. It will generate a foomatic filter datafile on stdout. - This datafile may then be used instead of the ones from the linxuprinting.org website. Follow the instructions for your spooler from the website to install the data file and filter. Note that it almost never makes sense to build the Foomatic driver without also building the Ghostscript driver, even if Foomatic is to be used with CUPS (CUPS-o-matic). Please read the instructions below in the GHOSTSCRIPT section. If you do not wish to build the Gimp Print plugin, you must run ./configure --with-foomatic --without-gimp Please visit http://www.linuxprinting.org/foomatic.html for more information on Foomatic. Foomatic provides an alternate interface to CUPS, in addition to an interface to lpd and LPRng. GHOSTSCRIPT This package includes a Ghostscript driver that may be built, allowing use of this software for general printing purposes. This package requires Ghostscript 5.10, 5.50, or 6.51. Later releases in the 6.5x GNU Ghostscript branch (e. g. 6.52) should also work. We *strongly* recommend that end users not attempt to use this driver directly. The available options are very complex, and the standard printer configuration tools (such as apsfilter and magicfilter) are not designed for drivers such as Gimp-print, and do not provide a convenient interface to the driver's capabilities. We recommend that end users either install CUPS, as described above, or use Foomatic to configure printer queues. CUPS is very easy to install, configure, and use, and is the recommended solution. Please read src/ghost/README for more information, including how to build and install it, and available options; the build procedure here merely creates the necessary source files that you must add to your Ghostscript source. The directions vary for different versions of Ghostscript. Only Ghostscript 5.10, 5.50, and 6.51 are currently supported. In particular, versions of Ghostscript that are not licensed under the GNU General Public License (GPL) are not supported, and this driver may not be distributed with such a version. Note that many of the options to the Ghostscript driver are incompatible with the options used prior to release 4.1.99-a3. Please read src/ghost/README for information on the current options. PRINTER-SPECIFIC NOTES: * The Epson Stylus C70 and C80 may give better results using Three Color Composite printing on Premium Glossy Photo Paper and Premium Semigloss. Epson's proprietary drivers are thought to do this on these papers. * The Epson Stylus C70 and C80 appear to support resolutions of 1440x1440 and 2880x1440, but these resolutions may not yield any improvement over 2880x720. Experiments suggest that 1440x1440 yields slightly better results than 2880x720 on Epson Photo Paper, but somewhat inferior results on Premium Glossy Photo Paper. 2880x1440 yields essentially no additional improvement on Photo Paper, and intermediate results on Premium Glossy Photo Paper. We expect that 1440x1440 would yield maximum improvement over 2880x720 on line art with very fine detail. It is unlikely that 2880x1440 would yield any significant additional improvement. Note that these resolutions are not officially supported by Epson, and may not work on all C70 and C80 printers. * Many Epson printers (specifically, the Epson Stylus Color 740 and all newer printers) will not respond to ASCII text without a special "activation" sequence (specifically, this command takes the printers out of "packet mode"). Therefore, the common suggestion to test a printer port by sending plain text to it will not work for these printers. These printers are, however, able to print plain text *after* the activation sequence is sent. A suggestion would be to use the escputil command to print a test pattern: escputil -n -u -P printer or escputil -n -u -r /dev/lp0 The `-u' option will send the activation sequence. In addition to printing the test pattern (if at least unidirectional communication is set up), this will enable printing plain ASCII text, at least until the printer is powered off (or used under Windows). To test bidirectional communication, the command escputil -i -u -r /dev/lp0 is a good choice, as it will print (to the screen) the amount of ink in the printer. Note that this activation sequence is both unnecessary and incorrect on older printers. The current list of printers for which the activation sequence must be sent is: EPSON Stylus C20SX EPSON Stylus C20UX EPSON Stylus C40SX EPSON Stylus C40UX EPSON Stylus C60 EPSON Stylus C70 EPSON Stylus C80 EPSON Stylus Color 440 EPSON Stylus Color 460 EPSON Stylus Color 480 EPSON Stylus Color 580 EPSON Stylus Color 640 EPSON Stylus Color 660 EPSON Stylus Color 670 EPSON Stylus Color 680 EPSON Stylus Color 740 EPSON Stylus Color 760 EPSON Stylus Color 777 EPSON Stylus Color 860 EPSON Stylus Color 880 EPSON Stylus Color 83 EPSON Stylus Color 900 EPSON Stylus Color 980 EPSON Stylus Color 1160 EPSON Stylus Photo 720 EPSON Stylus Photo 750 EPSON Stylus Photo 780/785/790 EPSON Stylus Photo 810/820 EPSON Stylus Photo 870/875 EPSON Stylus Photo 890/895 EPSON Stylus Photo 1200 EPSON Stylus Photo 1270 EPSON Stylus Photo 1280/1290 EPSON Stylus Photo 2000P EPSON Stylus Scan 2000 EPSON Stylus Scan 2500 RECOMMENDED SETTINGS We recommend starting with all default settings for the color settings. The settings can be adjusted as necessary for particular combinations of ink, paper, and subject material. We recommend use of the Adaptive Hybrid dithering algorithm in most cases. Ordered dithering also works very well in many cases, and is somewhat faster, but it does not work very well with text and very fine details (certain kinds of line art), particularly at high resolutions. Fast dithering is also quite usable in many cases. On most inkjet printers, 600 or 720 dpi will produce very high quality; 1200x1200 or 1440x720 dpi will produce extremely high quality. SUPPORT 1) Read the FAQ, in doc/FAQ.html. Your question may be answered there. 2) Read the user's manual, in doc/users_guide. 3) There are public forums on Sourceforge dedicated to this package. Please see http://sourceforge.net/forum/?group_id=1537 for more information. The Help forum is a good source of information. 4) If you have a technical support issue that does not appear to be a bug in the software, you can use the Tech Support Manager. Please see http://sourceforge.net/support/?group_id=1537. 5) If you have found a clear bug in the package, you may file a bug report at http://sourceforge.net/bugs/?group_id=1537. 6) You may send mail to the gimp-print-devel@sourceforge.net mailing list. This is recommended as a last resort only. KNOWN BUILD ISSUES * There is a known complication building "escputil" that causes problems on some systems. "escputil" uses the "readline" package, to support command editing and history within the program. Unfortunately, linking programs with "readline" often requires linking against additional libraries, and the exact library depends upon the system (e. g. not all Linux systems have the same requirements). The configure script attempts to determine which additional library must be linked against. It tries using the following libraries in this order to build a test executable: -lncurses -lcurses -ltermcap no additional libraries The reason it tries other libraries first is that some systems will link successfully, but only fail when an attempt is made to actually call readline. Therefore, we assume that additional libraries are required. Since we try the extra libraries in order from most recent to oldest, we expect that the first one we find will be appropriate. For example, if the "ncurses" library is the standard on a given system, the "termcap" library may be provided for back compatibility, but it is unlikely that "termcap" will be the standard with "curses" or "ncurses" being provided for compatibility only (so that the link will succeed but the command will use the incorrect library). As this procedure is not failsafe, we provide the following configure options to control this behavior: ./configure --with-readline=yes (the default; attempts to determine the correct library to link against) ./configure --with-readline=no (turns off use of readline altogether) ./configure --with-readline=only (specifically instructs configure to not attempt to link against any other libraries) ./configure --with-readline=libs (specifies the libraries to be linked against) An hypothetical (this won't work anywhere!) example of the latter would be ./configure --with-readline='-lncurses -ltermcap' Note that configure will not allow readline to be used if it cannot successfully build the test program, regardless of the option selected. If you are having difficulty getting escputil to build, we suggest using --with-readline=no. The commands used within escputil are very short and seldom require significant editing. * There is a known translation problem building the PPD files used by the CUPS driver such that on many systems all of the PPD files are in the English language. This causes CUPS tools, such as KUPS or http://localhost:631 to display many copies of each PPD file, all in the English (en) language. In fact, the PPD files should be translated into Swedish, Polish, Norwegian, French, Danish, and British English. With CUPS 1.1.10 and lower, there should be two copies of the (en) PPD file, and one copy each of (sv), (no), (fr), (pl) and (da). With CUPS 1.1.11 and above, there should be (en), (en_GB), (sv), (no), (fr), (pl), and (da) PPD files. The PPD files are created by a program named "genppd" in the src/cups directory. This program is called once for each language, and creates all of the PPD files for the language in one shot. The command 'zgrep' can be used to determine if genppd is creating the PPD files correctly, as follows: src/cups$ zgrep LanguageVersion ppd/*/pcl-4.ppd.gz ppd/C/pcl-4.ppd.gz:*LanguageVersion: English ppd/da/pcl-4.ppd.gz:*LanguageVersion: Danish ppd/en_GB/pcl-4.ppd.gz:*LanguageVersion: English-GB ppd/fr/pcl-4.ppd.gz:*LanguageVersion: French ppd/no/pcl-4.ppd.gz:*LanguageVersion: Norwegian ppd/no/pcl-4.ppd.gz:*LanguageVersion: Polish ppd/sv/pcl-4.ppd.gz:*LanguageVersion: Swedish If the PPD file for each language has a different language version, the genppd program operated correctly. If instead the output looks like this: src/cups$ zgrep LanguageVersion ppd/*/pcl-4.ppd.gz ppd/C/pcl-4.ppd.gz:*LanguageVersion: English ppd/da/pcl-4.ppd.gz:*LanguageVersion: English ppd/en_GB/pcl-4.ppd.gz:*LanguageVersion: English ppd/fr/pcl-4.ppd.gz:*LanguageVersion: English ppd/no/pcl-4.ppd.gz:*LanguageVersion: English ppd/no/pcl-4.ppd.gz:*LanguageVersion: English ppd/sv/pcl-4.ppd.gz:*LanguageVersion: English the program did not operate correctly. If you do not have 'zgrep' on your system, you can gunzip the PPD files, and use grep LanguageVersion ppd/*/pcl-4.ppd to accomplish the same test. The normal mechanism for performing translations is to set the LANG environment variable to the appropriate language prior to running the program. This normally causes the program to search the translations (normally in /usr/share/locale or /usr/lib/locale) for the chosen language. When a specially marked string is used, a special macro calls `gettext()' on the string to retrieve the translation, and substitutes the translation for the string in question. There are two problems with this approach in the context of genppd. The translation engine is intended to be used after installation, not during build, and this causes problems. 1) At the time genppd is run, the translations have not been installed in the normal system directories. Fortunately, it's possible to tell the translation machinery (via bindtextdomain) to look elsewhere for the translation catalogs. What we do is install the catalogs in a temporary directory under src/cups, and tell genppd to instruct the translation machinery to look there. This workaround is straightforward, and doesn't normally cause problems. 2) LANG only lets us pick a valid locale (normally determined by listing the directories in /usr/share/locale or /usr/lib/locale). Unfortunately, while language codes (which form the base of locales) are standard, the actual locale names aren't always. On some systems, the locale names are just the language base names; on others, they are the language names concatenated with country codes (e. g. en_US), while on others they are language codes concatenated with character sets. We are not aware of any workaround for this, possibly short of actually running make install and then rebuilding the PPD's. 'make install' will install the message catalogs, and that may create the necessary locale directories. This is not exactly a very elegant approach. The GNU gettext library (libintl.a) provides another environment variable, LANGUAGE, which unconditionally looks up translations according to the language, ignoring LANG and the LC_* environment variables that are normally used for translation. This library is included with the Gimp-Print tarball, but it is not used unless --with-included-gettext is specified on the configure command line. This is because many systems provide translation machinery in their standard libraries, and it may not always be best to use foreign libraries to replace standard system functionality. We have chosen to use LANGUAGE for this purpose, as the GNU gettext library appears to offer the most reliable translation, and LANGUAGE appears to offer the most reliable mechanism. We have actually found that LANG and LC_* can interfere with LANGUAGE, thus we do not use both. To determine if the translations are working, you must actually inspect the PPD files. You will need to cd src/cups/ppd/sv gunzip * more * or the like to determine if this is successful. In particular, look for LanguageVersion, and make sure that it is correct (it should be "Swedish" in the sv directory, for example), and also make sure that the paper sizes are also translated. We currently suggest using the Swedish translation for this purpose as it is the most complete. If packagers find that the PPD files are all in English, rather than translated into the appropriate languages, we suggest the following: 1) Use --with-included-gettext to use the GNU gettext. If your system is not based on GNU libc (Linux usually is based on GNU libc; BSD, Solaris, IRIX, etc. are not), you will need this option to have any possibility of creating the translated PPD files. 2) Run 'make install' to install the package (including the message catalogs) onto the system first, and then do the following: cd src/cups rm ppd-stamp make to rebuild the PPD files. Having the message catalogs on the system may permit this to succeed. 3) Ensure that your system actually has locales named 'sv', 'pl', and all of the other supported languages, and change LANGUAGE to something more appropriate (most likely LANG, LC_MESSAGES, or LC_ALL). 4) Build the PPD files on a Linux-based system; they are portable. 5) Use --without-translated-ppds on the configure command line to suppress the translated PPD files altogether. Please feel free to contact us about this issue. PACKAGING We recommend that packagers and distributors of Gimp-print use the following settings to build the package: --with-foomatic --with-user-guide --with-samples --with-escputil We suggest the following packaging: * A gimp-print core package should contain the following. You may wish to install the user's guide only in certain formats. /usr/lib/libgimpprint.so.1.0 (the core shared library) /usr/bin/escputil (Epson Stylus utility) /usr/share/gimp-print/doc/html (HTML documentation) /usr/share/gimp-print/doc/users-guide.pdf /usr/share/gimp-print/doc/users-guide.ps /usr/share/locale/*/LC_MESSAGES/gimp-print.mo * A gimp-print-devel package (for developers) should contain the following. Again, you may wish to install the programmer's manual only in certain formats. /usr/include/gimp-print /usr/bin/gimpprint-config /usr/share/gimp-print/doc/manual-html /usr/share/gimp-print/doc/gimpprint.ps /usr/share/aclocal/gimpprint.m4 /usr/lib/libgimpprint.a /usr/lib/libgimpprint.so You may wish to include the test pattern generator source and the sample test pattern in this package, and you may wish to include test patterns of your own. You may also wish to include the various unprint programs and the parse-* scripts from the test directory, although these are typically of more use to developers of the Gimp-Print package per se than developers of applications layered on Gimp-Print. However, the test programs have received less testing than the others, and are known to have some limitations that are not documented. * A gimp-print-extras package should contain /usr/share/gimp-print/samples You may wish to include the test pattern generator and the sample test pattern from src/testpattern if you don't include it in the developer package; test/unprint; test/pcl-unprint; test/bjc-unprint; test/parse-escp2; and test/parse-bjc in this package. * Ghostscript should be built with the stp driver using the "new" instructions (requiring only gdevstp.c, and linking dynamically against libgimpprint). This will allow Ghostscript to operate with future 4.2 upgrade releases without requiring recompilation. * CUPS packages should include the Gimp-print PPD's in /usr/share/cups/model, and the following utilities: + "epson" and "canon" belong in /usr/lib/cups/backend. + "rastertoprinter", "commandtoepson", and "commandtocanon" belong in /usr/lib/cups/filter. + "cups-calibrate" belongs in /usr/bin. + "command.types" belongs in /etc/cups. + "calibrate.ppm" belongs in /usr/share/cups. The PPD's packaged with Gimp-print are rather bulky, about 1 MB for each language installed. At present, six language translations are installed, in addition to the US English defaults: GB English, Swedish, Danish, Norwegian, French, and Polish. You may wish to install these selectively. Please see KNOWN BUILD ISSUES above for more discussion about build issues related to the PPD files. * A gimp-print-foomatic package, containing src/foomatic/foomatic-db, should be provided to allow people who wish to use foomatic to install the corresponding data files. The packaging should arrange to call "foomatic-kitload" (or the equivalent) on this tree when it is installed. * We recommend that you replace the Print plugin bundled with the Gimp (1.2.0~1.2.2) with the Gimp Print plugin in this distribution. There are various ways to do this; you can run 'make gimp-dist' from top level and untar the resulting tarball into the Gimp source directory prior to building the Gimp, or you can install the plugin (src/gimp/print) over an existing Gimp Print plugin. The plugin in the Gimp 1.2 tree is based on the older Gimp-Print 4.0 source base; 4.2 supports more printers with better quality, and has more features than 4.0. * Please read the release notes carefully! * Distributors (UNIX vendors and Linux distributors) should subscribe to the gimp-print-devel@sourceforge.net mailing list to monitor development activities. When reporting a problem related to building the package for distribution, please identify yourself as such. The Gimp-Print package is primarily an infrastructure package, rather than an end-user application, and as such we particularly want to fix any problems that interfere with building and distribution of this package on any POSIX-compliant operating system. DEBIAN The Debian packaging has been rewritten from scratch in 4.2. It is compliant with Standards-Version 3.5.6.0, and is lintian-clean. It should build from source on woody and sid, but will not build on potato. There are seven separate packages: gimp1.2-print The GIMP Print plugin. Also contains HTML and SGML documentation that is registered with doc-base. cupsys-driver-gimpprint The CUPS driver and PPD files. libgimpprint1 The libgimpprint library (GIMP-Print core). libgimpprint-dev Headers, symlinks, m4 macro (AM_PATH_GIMPPRINT) and gimpprint-config needed to develop programs that link with libgimpprint. gimpprint-doc User's Guide in HTML and PDF format libgimpprint-doc Programmer's Guide in Info, DVI and HTML format. escputil The escputil printer tool for Epson printers. The library symlinks will get packaged without any modification needed to the debian packaging whatever library versioning scheme is used. Most packages depend on libgimpprint as this will provide translations for i18n in the future that they will use, or they require libgimpprint anyway. The newer Debian gs packages (>= 5.50) are linked with libgimpprint, so you need not do any patching! However, if you compile a newer version of libgimpprint, the newer version will be used by ghostscript. USE OF THE CVS REPOSITORY Please read doc/README.maintaining for instructions on how to build from the CVS repository.