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