1This file describes issues that packagers and distributors of
2Gutenprint should be aware of.  This information is targeted at Linux
3distributions and others who deliver Gutenprint packages intended for
4end-user use.
5
61) As of 5.2 and until further notice, Gutenprint will no longer
7   deliver separate "development" and "stable" release series.
8
9   The point release will be advanced between beta/RC releases and
10   stable releases.  The first stable release of 5.2 will be numbered
11   5.2.1; the betas and release candidates will be numbered
12   5.2.0-betaN or 5.2.0-rcN.  Any betas for the next stable release
13   will be numbered 5.2.2-betaN; the next stable release will be
14   numbered 5.2.3 (if there are beta or release candidate builds) or
15   5.2.2 (if there are not).
16
17   This ensures that the highest numbered release is always the most
18   current, and that there will be no confusion between beta releases
19   and stable releases.  Our experience with 5.0 was that many users
20   continued to use beta releases of 5.0 even after 5.0.0 was
21   released, and worse, in some cases referred to the 5.0.0-beta2
22   release (for example) as "5.0.2".  We believe that the numbering
23   scheme described above will avoid that problem.
24
252) We request that you subscribe to
26   gimp-print-devel@lists.sourceforge.net to get the latest
27   information about upcoming changes.
28
293) If you intend to make any changes or patches to the source code of
30   this package, we request that you inform us of these changes and
31   discuss them with us prior to distribution, and identify a point of
32   contact to us.
33
34   While this is not required by the GPL, we would greatly appreciate
35   knowing about any changes you plan to make for three reasons:
36
37   * The changes may benefit all users of Gutenprint.
38
39   * We may have already considered this kind of change in the past
40     and elected not to make it, or may be planning to make this kind
41     of change in a different way from what you have done.
42     Coordination in this case may save everyone a lot of work.
43
44   * If we receive bug reports or support requests from users of your
45     package, we will either know who we can direct them to or will
46     have a better understanding of what is different in your package
47     that may cause observed differences from what we expect.
48
494) We specifically request that you *not* make changes to the margins
50   of any paper size in src/xml/papers.xml, or in general change
51   papers.xml other than to add additional paper sizes.  In the past,
52   a number of distributions have imposed margins for certain paper
53   sizes in this file because printing on certain printers was cut off
54   (cropped).  Change to papers.xml to work around these problems is
55   not an appropriate workaround for this problem, as it results in
56   *all* printers being bound by those margins.  Furthermore, the
57   margin problem has since been fixed in a different way.  Margins
58   should only be listed in papers.xml for papers that intrinsically
59   have margins of their own, such as photo papers with tear-off
60   margins.
61
62   Historically, in Gutenprint 5.0.0 all printers that offered
63   different margins under different circumstances (e. g. a choice
64   between normal margins and full-bleed printing, such as many Epson
65   inkjet printers, or different margins for certain paper sizes, such
66   as many laser printers that offer different margins for A4 than for
67   other paper sizes) always listed the wide margins in the PPD files,
68   and if the full bleed option was not selected (or a paper size that
69   required narrower margins was), the printed image was simply
70   clipped to the margins.  This preserved the image dimension on the
71   page, but in some cases resulted in parts of the image being
72   clipped.  The workaround that some packagers applied, to add
73   margins in papers.xml, made it impossible to print full bleed to
74   these paper sizes even on printers capable of this.  None of these
75   packagers ever discussed this change with us, and as a result we
76   were caught by surprise by some bug reports that it took us a while
77   to track down.
78
79   This issue was fixed in 5.0.1 (in the native CUPS driver) by means
80   of a new PPD option to allow users to either shrink the image to
81   the appropriate margins or to crop the image.  This allows users to
82   select whether they prefer dimensional accuracy or printing the
83   entire image.  However, we have observed that this workaround has
84   still not been removed from all distributors' packages.
85
86   At this point, there should be no reason to specify margins in
87   papers.xml for any reason other than adding a media size that has
88   intrinsic margins of its own, such as a new paper with tear-off
89   margins.  If you think you need to do this for any other reason,
90   please discuss it with us first!
91
925) Packaging the Core Library (libgutenprint)
93
94   * You may wish to create a development package containing header
95     files and linkable libraries separate from the runtime package.
96     There are a few third party applications that link against
97     Gutenprint.
98
99   * Gutenprint permits installation of Gimp-Print 4.2 and Gutenprint
100     5.0 alongside Gutenprint 5.2, and in the future will permit
101     concurrent installation of different stable versions of
102     Gutenprint with different minor version numbers.  Therefore, you
103     may consider allowing Gutenprint 5.0, Gutenprint 5.2, and
104     Gimp-Print 4.2 to be installed concurrently.
105
106   * The core driver library component also includes XML data files
107     (in src/xml), locale files for the library, and documentation.
108     The XML data files in src/xml are mandatory; the driver will not
109     function without these files.
110
111   * We do not recommend installing any program linked against
112     libgutenprint with enhanced privileges (via the setuid or setgid
113     mechanism, or any other such mechanism).  We have not audited
114     libgutenprint for safety in this kind of environment, and changes
115     in Gutenprint 5.2 (in particular, moving the Epson driver data
116     into external data files whose root can be changed by means of
117     the environment variable STP_DATA_PATH) may increase risk.
118     Furthermore, if you build the Gutenprint library in modular
119     fashion, such that drivers may be dynamically loaded into running
120     applications, there is an additional hazard in the form of an
121     environment variable that allows specifying where those modules
122     should be loaded from (STP_MODULE_PATH).
123
124     The only program in the core Gutenprint package that has any
125     reason to be installed this way is escputil, because it needs to
126     talk directly to the printer.  See the discussion of escputil
127     below.
128
1296) Packaging the CUPS Driver
130
131   * IMPORTANT: As a special part of the install/upgrade procedure,
132     your installer should check for any queues using the "epson" or
133     "canon" backends and convert them to use an appropriate standard
134     backend, usually the "usb" or "parallel" backend.  Please see the
135     Critical Upgrade Note in the release notes (NEWS file) for more
136     information.
137
138     Note that the epson and canon backends are no longer distributed
139     by Gutenprint, so your installer will have to fix this up in any
140     event.
141
142   * We recommend that your installation package run cups-genppdupdate
143     and restart CUPS as part of the installation process.  This will
144     copy changes made by the user and ensure that the user has
145     correct PPD files.  The CUPS driver will refuse to use a PPD file
146     built with a different version of Gutenprint.
147
148   * Some applications do not translate PPD file contents (option
149     names and values) when globalized PPD files are used (see the
150     release notes for general discussion of globalized PPD files).
151     At the time these notes are being written, we have determined
152     that versions of OpenOffice.org up to and including 3.0.0-rc1 do
153     not translate PPD file contents with globalized PPD files, but
154     language-specific localized PPD files are translated correctly.
155     We have also determined that GIMP 2.4, using the GtkPrint plugin,
156     does not translate PPD contents using globalized PPD files, but
157     does with single language files.
158
159     The CUPS development team has informed us that they have not
160     received complaints from users about this, despite the fact that
161     the basic set of PPD files distributed by CUPS is globalized.
162     Unlike Gutenprint, however, CUPS does not require that its PPD
163     files be upgraded with each release, so users upgrading from
164     older versions of CUPS may not be exposed to this issue.
165
166     Gutenprint does provide a way to upgrade PPD files to
167     language-specific ones, using the -l option to
168     cups-genppdupdate.  PPD files that are being upgraded from a
169     previous release of Gutenprint may be upgraded with
170     cups-genppdupdate -loriginal to update to the original language.
171     Note that this works even if the PPD files have been updated to
172     globalized files, since cups-genppdupdate stores the language of
173     the PPD file it was upgrading.  cups-genppdupdate -l<language>
174     updates PPD files into the specified language; see the release
175     notes or user's manual for the set of languages supported.
176
177     Note that -loriginal will *not* work with PPD files that had been
178     upgraded with Gutenprint 5.2.0-beta4, since cups-genppdupdate in
179     that release does not preserve the original language of the PPD
180     file.
181
182     Distributions have a number of possible options to address this
183     issue, for example:
184
185     - Use globalized PPD files and accept the translation problem or
186       fix the applications that do not translate the PPD files
187       correctly.  You may wish to document the procedure of using
188       cups-genppdupdate to generate language-specific PPD files in
189       this case.
190
191     - Configure Gutenprint with --disable-globalized-cups-ppds, to
192       generate only single-language PPD files.
193
194     - Provide an administrative utility to update either individual
195       PPD files or all PPD files on the system.  If you provide this
196       kind of utility, we recommend using the -l<language> option
197       rather than -loriginal.
198
199   * All files and directories with versioned names (such as
200     rastertogutenprint and the PPD files) may be installed and used
201     concurrently with other versions of Gimp-Print and Gutenprint as
202     described above.  Other executables (such as cups-calibrate) are
203     not versioned, but are not linked against libgutenprint and do
204     not have any other dependencies on Gutenprint.
205
2067) Packaging the Enhanced Print Plugin for GIMP
207
208   * The enhanced Print plugin for GIMP, unlike the core library and
209     CUPS drivers, may not be installed concurrently with other
210     versions.  For example, you may not install both the Gimp-Print
211     4.2 and the Gutenprint 5.2 version of the Print plugin, as they
212     use different configuration file formats.
213
2148) Packaging the Epson Inkjet Management Utility, escputil
215
216   * We do not recommend installing this utility with enhanced
217     privileges (via the setuid or setgid mechanism, or any other such
218     mechanism) without a careful security audit on your part.  If
219     elevated privileges are required in your installation, we suggest
220     ensuring that the variables STP_DATA_PATH and STP_MODULE_PATH be
221     cleared prior to invoking escputil (or that you patch escputil to
222     clear those variables prior to calling stp_init()) and otherwise
223     using the least privilege required to allow escputil to run.
224     Another option may be to allow (by means of device permissions)
225     an appropriate group of users to run this command.
226
227     With the conversion of the Epson driver to using external data
228     files in XML format rather than data hard-coded into the library
229     binary, there are more opportunities for injection of bad data
230     into the driver.
231
232     Note that the default configuration of Gutenprint does not
233     install escputil with elevated privileges.
234