README.txt

   1 README - OpenPrinting CUPS Filters v1.0.18 - 2012-05-16
   2 -------------------------------------------------------
   3
   4 Looking for compile instructions?  Read the file "INSTALL.txt"
   5 instead...
   6
   7
   8 INTRODUCTION
   9
  10     CUPS is a standards-based, open source printing system developed by Apple
  11     Inc. for Mac OS® X and other UNIX®-like operating systems.  CUPS uses the
  12     Internet Printing Protocol ("IPP") and provides System V and Berkeley
  13     command-line interfaces, a web interface, and a C API to manage printers and
  14     print jobs.
  15
  16     This distribution contains backends, filters, and other software that was
  17     once part of the core CUPS distribution but is no longer maintained by
  18     Apple Inc. In addition it contains additional filters developed
  19     independently of Apple, especially filters for the PDF-centric printing
  20     workflow introduced by OpenPrinting.
  21
  22     From CUPS 1.6.0 on, this package will be required for using printer drivers
  23     with CUPS under Linux. With CUPS 1.5.x and earlier this package can be used
  24     optionally to switch over to PDF-based printing. In that case some filters
  25     are provided by both CUPS and this package. Then the filters of this package
  26     should be used.
  27
  28     For compiling and using this package CUPS, Poppler, libjpeg, libpng,
  29     libtiff, libijs, freetype, fontconfig, and liblcms (liblcms2 recommended)
  30     are needed. It is highly recommended, especially if non-PostScript printers
  31     are used, to have Ghostscript, foomatic-filters, and foomatic-db installed.
  32
  33     CUPS, this package, and Ghostscript contain some rudimentary printer
  34     drivers, see http://www.openprinting.org/drivers/ for a more
  35     comprehensive set of printer drivers for Linux.
  36
  37     See
  38
  39     http://www.linuxfoundation.org/collaborate/workgroups/openprinting/pdf_as_standard_print_job_format
  40
  41     for information about the PDF-based printing workflow.
  42
  43     Report bugs to
  44
  45     https://bugs.linuxfoundation.org/
  46
  47     Choose "OpenPrinting" as the product and "cups-filters" as the component.
  48
  49     See the "LICENSE.txt" files for legal information.
  50
  51 IMAGE PRINTING DEFAULT CHANGED TO "SCALE TO FIT"
  52
  53     Compared to the PostScript-based original CUPS filters there is a
  54     change of deafults: The imagetopdf and imagetoraster filters print
  55     in "scale-to-fit" mode (image is scaled to fill one page but
  56     nothing of the image being cut off) by default.
  57
  58     This is done to support photo printing via AirPrint. The photo
  59     apps on Apple's iOS devices send print jobs as JPEG images and do
  60     not allow to set any options like "scaling" or the page size. With
  61     "scale-to-fit" mode set by default, the iOS photos come out on one
  62     page, as expected.
  63
  64     To get back to the old behavior, supply one of the options
  65     "nofitplot" "filplot=Off", "nofit-to-page", or "fit-to-page=Off".
  66
  67 POSTSCRIPT PRINTING RENDERER AND RESOLUTION SELECTION
  68
  69     If you use CUPS with this package and a PostScript printer then
  70     the included pdftops filter converts the print job data which is
  71     in PDF format into PostScript. By default, the PostScript is
  72     generated with Ghostscript's "ps2write" output device, which
  73     generates a DSC-conforming PostScript with compressed embedded
  74     fonts and compressed page content. This is resource-saving and
  75     leads to fast wire transfer of print jobs to the printer.
  76
  77     Unfortunately, Ghostscript's PostScript output is not compatible
  78     with some printers due to interpreter bugs in the printer and in
  79     addition, processing (by Ghostscript or by the printer's
  80     interpreter) can get very slow with high printing resolutions when
  81     parts of the incoming PDF file are converted to bitmaps if they
  82     contain graphical structures which are not supported by
  83     PostScript. The bitmap problem especially occurs on input files
  84     with transparency, especially also the ones produced by Cairo
  85     (evince and many other GNOME/GTK applications) which unnecessarily
  86     introduces transparency even if the input PDF has no transparency.
  87
  88     Therefore there are two possibilities to configure pdftops at
  89     runtime:
  90
  91     1. Selection of the renderer: Ghostscript or Poppler
  92
  93     Ghostscript has better color management and is generally optimized
  94     more for printing. Poppler produces a PostScript which is
  95     compatible with more buggy built-in PostScript interpreters of
  96     printers and it leads to a somewhat quicker workflow when
  97     graphical structures of the input PDF has to be turned into
  98     bitmaps.
  99
 100     The selection is done by the "pdftops-renderer" option, setting it
 101     to "gs" or "pdftops":
 102
 103     Per-job:           lpr -o pdftops-renderer=pdftops ...
 104     Per-queue default: lpadmin -p printer -o pdftops-renderer-default=gs
 105     Remove default:    lpadmin -p printer -R pdftops-renderer-default
 106
 107     By default, pdftops uses Ghostscript if this does not get changed
 108     at compile time, for example by the Linux distribution vendor.
 109
 110     2. Limitation of the image rendering resolution
 111
 112     If graphical structures of the incoming PDF file have to be
 113     converted to bitmaps due to limitations of PostScript, the
 114     conversion of the file by pdftops or the rendering by the printer
 115     can get too slow if the bitmap resolution is too high or the
 116     printout quality can degrade if the bitmap resolution is too low.
 117
 118     By default, pdftops tries to find out the actual printing
 119     resolution and sets the resolution for bitmap generation to the
 120     same value. If it cannot find the printing resolution, it uses 300
 121     dpi. It never goes higher than a limit of 1440 dpi. Note that this
 122     default limit can get changed at compile time, for example by the
 123     Linux distribution vendor.
 124
 125     The resolution limit for bitmaps can be changed to a lower or
 126     higher value, or be set to unlimited. This is done by the option
 127     "pdftops-max-image-resolution-default", setting it to the desired
 128     value (in dpi) or to zero for unlimited. It can be used per-job or
 129     as per-queue default as the "pdftops-renderer" option described
 130     above.
 131
 132 POSTSCRIPT PRINTING DEBUG MODE
 133
 134     Sometimes a PostScript printer's interpreter errors, crashes, or
 135     somehow else misbehaves on Ghostscript's output. To find
 136     workarounds (currently we have already workarounds for Brother and
 137     Kyocera) it is much easier to work with uncompressed PostScript.
 138     To get uncompressed PostScript as output, send a job with the
 139     "psdebug" option, with commands like the following:
 140
 141       lpr -P <printer> -o psdebug <file>
 142       lp -d <printer> -o psdebug <file>
 143
 144     If you want to send your job out of a desktop application, run
 145
 146       lpoptions -p <printer> -o psdebug
 147
 148     to make "psdebug" a personal default setting for you.
 149
 150     To extract the PostScript output for a developer to analyse it,
 151     clone your print queue to a one which prints into a file:
 152
 153       cupsctl FileDevice=yes
 154       lpadmin -p test -E -v file:/tmp/printout \
 155       -P /etc/cups/ppd/<name of original queue>.ppd
 156
 157     and print into this queue as described above. The PostScript
 158     output is in /tmp/printout after the job has completed.
 159
 160     This option does not change anything if Poppler's pdftops is used
 161     as renderer.
 162
 163 CUPS FILTERS FOR PDF AS STANDARD PRINT JOB FORMAT
 164
 165     Here is documentation from the former CUPS add-on tarball with the filters
 166     for the PDF-based printing workflow: imagetopdf, texttopdf,
 167     pdftopdf, pdftoraster, pdftoopvp, and pdftoijs
 168
 169     The original filters are from http://sourceforge.jp/projects/opfc/
 170
 171     NOTE: the texttops and imagetops filters shipping with this package
 172     are simple wrapper scripts for backward compatibility with third-party
 173     PPD files and custom configurations. There are not referred to in the
 174     cupsfilters.convs file and therefore not used by the default
 175     configuration. Direct conversion of text or images to PostScript is
 176     deprecated in the PDF-based printing workflow. So do not use these
 177     filters when creating new PPDs or custom configurations. The parameters
 178     for these filters are the same as for texttopdf and imagetopdf (see
 179     below) as the ...tops filter calls the ....topdf filter plus
 180     Ghostscript's pdf2ps.
 181
 182 IMAGETOPDF
 183
 184 1. INTRODUCTION
 185
 186 This program is "imagetopdf". "imagetopdf" is a CUPS filter which reads
 187 a single image file, converts it into a PDF file and outputs it to stdout.
 188
 189 This program accepts the following image file format;
 190
 191   gif, png, jpeg, tiff, photocd, portable-anymap, portable-bitmap,
 192   portable-graymap, portable-pixmap, sgi-rgb, sun-raster, xbitmap,
 193   xpixmap, xwindowdump
 194
 195 xbitmap, xpixmap and xwindowdump images are converted into png images by
 196 the "convert" command. Other kinds of image file format can be supported
 197 if the "convert" command support them.
 198
 199 Output PDF file format conforms to PDF version 1.3 specification, and
 200 input image is converted and contained in the output PDF file as a binary
 201 format non-compression image.
 202
 203 "imagetopdf" may outputs multiple pages if the input image exceeds page
 204 printable area.
 205
 206 2. LICENSE
 207
 208 "imagetopdf.c" is under the CUPS license. See the "LICENSE.txt" file.
 209 For other files, see the copyright notice and license of each file.
 210
 211 3. COMMAND LINE
 212
 213 "imagetopdf" is a CUPS filter, and the command line arguments, environment
 214 variables and configuration files are in accordance with the CUPS filter
 215 interface.
 216
 217 imagetopdf <job> <user> <title> <num-copies> <options> [<filename>]
 218
 219 "imagetopdf" ignores <job> and <user>.
 220 <title> is appended into the PDF dictionary as /Title.
 221 <num-copies> specifies the number of document copies.
 222 <options> is a CUPS option list.
 223 <filename> is an input image file name.
 224
 225 When omit the <filename>, "imagetopdf" reads an image file from stdin.
 226
 227 4. ENVIRONMENT VARIABLES
 228
 229 This program refers the following environment variable;
 230
 231    PPD:  PPD file name of the printer.
 232
 233 5. COMMAND OPTIONS
 234
 235 "imagetopdf" accepts the following CUPS standard options;
 236
 237 fitplot
 238 mirror
 239 PageSize
 240 page-left, page-right, page-bottom, page-top
 241 OutputOrder
 242 Collate
 243 sides
 244 cupsEvenDuplex
 245 position
 246 scaling
 247 ppi
 248 natural-scaling
 249 landscape
 250 orientation-requested
 251
 252 See the CUPS documents for details of these options.
 253
 254 6. KNOWN PROBLEMS
 255
 256 Problem:
 257   PBM and SUN raster images can not be printed.
 258 Solution:
 259   Due to the CUPS libcupsimage library's bug. Update the CUPS on your system.
 260
 261 7. INFORMATION FOR DEVELOPERS
 262
 263 Following information is for developers, not for driver users.
 264
 265 7.1 Options handled by a printer or "imagetopdf"
 266
 267 Following options are handled by a printer or "imagetopdf".
 268   Collate, Copies, Duplex, OutputOrder
 269
 270 Which handles these options depends on following options and attributes.
 271   Collate, Copies, Duplex, OutputOrder, cupsEvenDuplex, cupsManualCopies
 272
 273 "imagetopdf" judges whether a printer can handle these options according to
 274 the followings option settings in a PPD file.
 275
 276 Collate:
 277   If Collate is defined, "imagetopdf" judges the printer supports Collate.
 278 Copies:
 279   If cupsManualCopies is defined as False, "imagetopdf" judges the printer
 280   does not support Copies feature.
 281
 282 Duplex:
 283   If Duplex is defined, "imagetopdf" judges the printer supports Duplex.
 284   If cupsEvenDuplex is True, Number of pages must be even.
 285 OutputOrder:
 286   If OutputOrder is defined, "imagetopdf" judges the printer supports
 287   OutputOrder.
 288
 289 If the printer cannot handle these options, "imagetopdf" handles it.
 290
 291 Following pseudo program describes how "imagetopdf" judges to handle
 292 these options.
 293
 294 Variables
 295
 296 Copies : specified Copies
 297 Duplex : specified Duplex
 298 Collate : specified Collate
 299 OutputOrder : specified OutputOrder
 300 EvenDuplex : specified cupsEvenDuplex
 301 pages : number of pages
 302 number_up : specified number-up
 303
 304 device_copies : Copies passed to the printer
 305 device_duplex : Duplex passed to the printer
 306 device_collate : Collate passed to the printer
 307 device_outputorder : OutputOrder passed to the printer
 308
 309 soft_copies : copies by imagetopdf
 310
 311
 312 device_copies = 1;
 313 device_duplex = False;
 314 device_collate = False;
 315 device_outputorder = False;
 316
 317 if (Copies == 1) {
 318   /* Collate is not needed. */
 319   Collate = False;
 320 }
 321
 322 if (!Duplex) {
 323   /* EvenDuplex is not needed */
 324   EvenDuplex = False;
 325 }
 326
 327
 328 if (Copies > 1 && the printer can handle Copies) device_copies = Copies;
 329 if (Duplex && the printer can handle Duplex) {
 330        device_duplex = True;
 331 } else {
 332    /* imagetopdf cannot handle Duplex */
 333 }
 334 if (Collate && the printer can handle Collate) device_collate = True;
 335 if (OutputOrder == Reverse && the printer can handle OutputOrder)
 336              device_outputorder = True;
 337
 338 if (Collate && !device_collate) {
 339    /* The printer cannot handle Collate.
 340       So imagetopdf handle Copies */
 341               device_copies = 1;
 342 }
 343
 344 if (device_copies != Copies /* imagetopdf handle Copies */ && Duplex)
 345     /* Make imagetopdf handle Collate, otherwise both paper side may have
 346        same page */
 347               Collate = True;
 348               device_collate = False;
 349 }
 350
 351 if (Duplex && Collate && !device_collate) {
 352    /* Handle EvenDuplex, otherwise the last page has
 353       the next copy's first page in the other side of the paper. */
 354    EvenDuplex = True;
 355 }
 356
 357 if (Duplex && OutputOrder == Reverse && !device_outputorder) {
 358    /* Handle EvenDuplex, otherwise the first page's other side of paper
 359       is empty. */
 360    EvenDuplex = True;
 361 }
 362
 363 soft_copies = device_copies > 1 ? 1 : Copies;
 364
 365 7.2 JCL
 366
 367 When you print PDF files to a PostScript(PS) printer, you can specify
 368 device options in PS. In this case, you can write PS commands in a PPD file
 369 like as follows.
 370
 371 *OpenUI *Resolution/Resolution : PickOne
 372 *DefaultResolution: 600
 373 *Resolution 300/300 dpi: "<</HWResolution[300 300]>>setpagedevice"
 374 *Resolution 600/600 dpi: "<</HWResolution[600 600]>>setpagedevice"
 375 *CloseUI: *Resolution
 376
 377 However, if options cannot be described in PS file, you can write JCLs
 378 as follows;
 379
 380 *JCLOpenUI *JCLFrameBufferSize/Frame Buffer Size: PickOne
 381 *DefaultJCLFrameBufferSize: Letter
 382 *OrderDependency: 20 JCLSetup *JCLFrameBufferSize
 383 *JCLFrameBufferSize Off: '@PJL SET PAGEPROTECT = OFF<0A>'
 384 *JCLFrameBufferSize Letter: '@PJL SET PAGEPROTECT = LTR<0A>'
 385 *JCLFrameBufferSize Legal: '@PJL SET PAGEPROTECT = LGL<0A>'
 386 *JCLCloseUI: *JCLFrameBufferSize
 387
 388 Because PDF cannot specify device options in a PDF file, you have to define
 389 all the device options as JCLs.
 390
 391 When a printer does not support PS nor PDF, you can use Ghostscript (GS).
 392 In this case, you can specify device options like a PS printer.
 393 If you want to use the same printer and same PPD file for both PDF and PS
 394 printing, when you print a PS file, you can specify that GS handles it,
 395 and when you print a PDF file, you can also specify that PDF filters handle
 396 it in the same PPD file. However in this case, previous methods is not
 397 appropriate to specify device options.
 398
 399 So, "imagetopdf" handles this case as follows;
 400 (In following pseudo program, JCL option is an option specified with JCLOpenUI)
 401
 402 if (Both JCLBegin and JCLToPSInterpreter are specified in the PPD file) {
 403     output JCLs that marked JCL options.
 404 }
 405
 406 if (pdftopdfJCLBegin attribute is specified in the PPD file) {
 407     output it's value
 408 }
 409
 410 if (Copies option is specified in the PPD file) {
 411     mark Number of copies specified
 412 } else if (pdftopdfJCLCopies is specified in the PPD file) {
 413     output JCL specified with JCLCopies
 414 }
 415
 416 for (each marked options) {
 417     if (pdftopdfJCL<marked option's name> is specified in the PPD file) {
 418         output it's value as a JCL
 419     } else if (pdftopdfJCLBegin attributes is specified in the PPD file) {
 420         output "<option's name>=<marked choice>;" as a JCL
 421     }
 422 }
 423 output NEWLINE
 424
 425 Thus, if you want to use both PDF filters and GS by single PPD file,
 426 what you should do is to add the following line in the PPD file;
 427
 428 *pdftopdfJCLBegin: "pdftoopvp jobInfo:"
 429
 430 Note:
 431   If you specify JCLBegin, you have to specify JCLToPSInterpreter as well.
 432
 433 Note:
 434   When you need to specify the value which is different from the choosen
 435   value based on the PPD into the jobInfo, you have to specify the values
 436   with the key started by "pdftopdfJCL" string.
 437
 438   For example, if the page size is defined in a PPD file as following;
 439
 440   *OpenUI *PageSize/Page Size: PickOne
 441   *DefaultPageSize: A4
 442   *PageSize A4/A4:
 443   *PageSize Letter/US Letter:
 444   *CloseUI: *PageSize
 445
 446   if you choose the page size "Letter", the string "PageSize=Letter;" is
 447   added to jobInfo. On the other hand, if the driver requires the different
 448   value for the "Letter" size, for instance driver requires "PS=LT;"
 449   instead of "PageSize=Letter;" as the jobInfo value, the PPD file has to
 450   be defined as following;
 451
 452   *OpenUI *PageSize/Page Size: PickOne
 453   *DefaultPageSize: A4
 454   *PageSize A4/A4:
 455   *pdftopdfJCLPageSize A4/A4: "PS=A4;"
 456   *PageSize Letter/US Letter:
 457   *pdftopdfJCLPageSize Letter/US Letter: "PS=LT;"
 458   *CloseUI: *PageSize
 459
 460 7.3 Temporally files location
 461
 462 "imagetopdf" creates temporally files if needed. Temporary files are created
 463 in the location specified by TMPDIR environment variable. Default location
 464 is "/tmp".
 465
 466
 467 PDFTOPDF
 468
 469 1. INTRODUCTION
 470
 471 There are two executable programs, "pdftopdf" and "pdf2pdf", in this package.
 472 "pdftopdf" is a filter for CUPS. It reads PDF files, changes page layout
 473 and output a new PDF file. "pdf2pdf" is a user command version of "pdftopdf".
 474 This document describes about only "pdftopdf". See man/pdf2pdf.1 for "pdf2pdf".
 475
 476 When a input PDF file which is given to "pdftopdf" does not include some
 477 required fonts, and if you set the font embedding option, "pdftopdf" embed
 478 fonts in the new PDF file
 479
 480 "pdftopdf" finds fonts to embed by fontconfig library.
 481 "pdftopdf" now embed only TrueType format fonts.
 482 PDF Standard fonts are not embedded.
 483
 484 Note: Do not embed fonts that the font licenses inhibit embedding.
 485
 486 "pdftopdf" does not support functions that are not related to printing
 487 features, including interactive features and document interchange features.
 488 Many of these operators and sections are just ignored.
 489 Some of these may be output, but those functions are not assured.
 490 Encryption feature is not supported.
 491
 492 2. NATIVE PDF PRINTER SUPPORT
 493
 494 pdftopdf introduces native PDF printer support to CUPS for the first
 495 time. PPD files must have a line
 496
 497 *cupsFilter: "application/vnd.cups-pdf 0 -"
 498
 499 and use the "*JCLToPDFInterpreter:" keyword, for example:
 500
 501 *JCLBegin:           "<1B>%-12345X@PJL JOB<0A>"
 502 *JCLToPDFInterpreter: "@PJL ENTER LANGUAGE = PDF <0A>"
 503 *JCLEnd:             "<1B>%-12345X@PJL EOJ <0A><1B>%-12345X"
 504
 505 They MUST NOT accept PostScript as input data format and will not work
 506 with stock CUPS. They will need cups-filters (which implements the PDF-
 507 based printing workflow) to work.
 508
 509 Options must not be implemented by specifying PostScript code to
 510 inject.  They must be injecting JCL code ("*JCLOpenUI:
 511 ... ... *JCLCloseUI: ...").
 512
 513 A sample PPD file, HP-Color_LaserJet_CM3530_MFP-PDF.ppd is included.
 514
 515 3. LICENSE
 516
 517 Almost all source files are under MIT like license. However,
 518 "pdftopdf" links some "poppler" libraries, and these files are under
 519 GNU public license.  See copyright notice of each file for details.
 520
 521 4. COMMAND LINE
 522
 523 "pdftopdf" is a CUPS filter, and the command line arguments, environment
 524 variables and configuration files are in accordance with the CUPS filter
 525 interface.
 526
 527 pdftopdf <job> <user> <title> <num-copies> <options> [<filename>]
 528
 529 "pdftopdf" ignores <job> and <user>.
 530 <title> is appended into the PDF dictionary as /Title.
 531 <num-copies> specifies the number of document copies.
 532 <options> is a CUPS option list.
 533 <filename> is an input PDF file name.
 534
 535 When omit the <filename>, "pdftopdf" reads a PDF file from stdin,
 536 and save it as a temporary file.
 537
 538
 539 CUPS options defined in <options> are delimited by space. Boolean
 540 type CUPS option is defined only by the option key, and other type
 541 CUPS option are defined by pairs of key and value, <key>=<value>.
 542
 543 5. COMMAND OPTIONS
 544
 545 "pdftopdf" accepts the following CUPS standard options;
 546
 547 fiplot
 548 mirror
 549 PageSize
 550 page-left, page-right, page-bottom, page-top
 551 number-up
 552 number-up-layout
 553 page-border
 554 OutputOrder
 555 page-set
 556 page-ranges
 557 Collate
 558 sides
 559 cupsEvenDuplex
 560
 561 See the CUPS documents for details of these options.
 562
 563 Margin given by the page-left, page-right, page-bottom and page-top is
 564 valid when fiplot or number-up option is set.
 565
 566 "pdftopdf" accepts the following original options;
 567
 568 pdftopdfFontEmbedding
 569   Boolean option.
 570   Force "pdftopdf" to embed fonts. "pdftopdf" does not embed fonts by default.
 571
 572 pdftopdfFontEmbeddingWhole
 573   Boolean option.
 574   Force "pdftopdf" to embed whole fonts.
 575   "pdftopdf" does not embed whole fonts by default.
 576   If this option is false, "pdftopdf" embed subset of the fonts.
 577   This option is valid only when the pdftopdfFontEmbedding option is true.
 578
 579 pdftopdfFontEmbeddingPreLoad
 580   Boolean option.
 581   Force "pdftopdf" to embed fonts specified as pre-loaded fonts in a PPD file.
 582   "pdftopdf" does not embed pre-loaded fonts by default.
 583   If this option is false, pdftopdf does not embed pre-loaded fonts.
 584   This option is valid only when the pdftopdfFontEmbedding option is true.
 585
 586 pdftopdfFontCompress
 587   Boolean option.
 588   Force "pdftopdf" to compress embed fonts.
 589   "pdftopdf" does not compress embed fonts by default.
 590   This option is valid only when the pdftopdfFontEmbedding option is true.
 591
 592 pdftopdfContentsCompress
 593   Boolean option.
 594   Force "pdftopdf" to compress page contents.
 595   "pdftopdf" does not compress page contents by default.
 596
 597 pdftopdfJCLBegin
 598   Boolean option.
 599   Force "pdftopdf" to create JCL info for the following PDF filter
 600   "pdftoopvp".
 601
 602 6. INFORMATION FOR DEVELOPERS
 603
 604 Following information is for developers, not for driver users.
 605
 606 6.1 Options handled by a printer or "pdftopdf"
 607
 608 Following options are handled by a printer or "pdftopdf".
 609   Collate, Copies, Duplex, OutputOrder
 610
 611 Which handles these options depends on following options and attributes.
 612   Collate, Copies, Duplex, OutputOrder, cupsEvenDuplex, cupsManualCopies
 613
 614 "pdftopdf" judges whether a printer can handle these options according to
 615 the followings option settings in a PPD file.
 616
 617 Collate:
 618   If Collate is defined, "pdftopdf" judges the printer supports Collate.
 619 Copies:
 620   If cupsManualCopies is defined as False, "pdftopdf" judges the printer
 621   does not support Copies feature.
 622 Duplex:
 623   If Duplex is defined, "pdftopdf" judges the printer supports Duplex.
 624   If cupsEvenDuplex is True, Number of pages must be even.
 625 OutputOrder:
 626   If OutputOrder is defined, "pdftopdf" judges the printer supports
 627   OutputOrder.
 628
 629 If the printer cannot handle these options, "pdftopdf" handles it.
 630
 631 Following pseudo program describes how "pdftopdf" judges to handle
 632 these options.
 633
 634 Variables
 635
 636 Copies : specified Copies
 637 Duplex : specified Duplex
 638 Collate : specified Collate
 639 OutputOrder : specified OutputOrder
 640 EvenDuplex : specified cupsEvenDuplex
 641 pages : number of pages
 642 number_up : specified number-up
 643
 644 device_copies : Copies passed to the printer
 645 device_duplex : Duplex passed to the printer
 646 device_collate : Collate passed to the printer
 647 device_outputorder : OutputOrder passed to the printer
 648
 649 soft_copies : copies by pdftopdf
 650
 651
 652 device_copies = 1;
 653 device_duplex = False;
 654 device_collate = False;
 655 device_outputorder = False;
 656
 657 if (Copies == 1) {
 658   /* Collate is not needed. */
 659   Collate = False;
 660 }
 661
 662 if (!Duplex) {
 663   /* EvenDuplex is not needed */
 664   EvenDuplex = False;
 665 }
 666
 667
 668 if (Copies > 1 && the printer can handle Copies) device_copies = Copies;
 669 if (Duplex && the printer can handle Duplex) {
 670        device_duplex = True;
 671 } else {
 672    /* pdftopdf cannot handle Duplex */
 673 }
 674 if (Collate && the printer can handle Collate) device_collate = True;
 675 if (OutputOrder == Reverse && the printer can handle OutputOrder)
 676              device_outputorder = True;
 677
 678 if (Collate && !device_collate) {
 679    /* The printer cannot handle Collate.
 680       So pdftopdf handle Copies */
 681               device_copies = 1;
 682 }
 683
 684 if (device_copies != Copies /* pdftopdf handle Copies */ && Duplex)
 685     /* Make pdftopdf handle Collate, otherwise both paper side may have
 686        same page */
 687               Collate = True;
 688               device_collate = False;
 689 }
 690
 691 if (Duplex && Collate && !device_collate) {
 692    /* Handle EvenDuplex, otherwise the last page has
 693       the next copy's first page in the other side of the paper. */
 694    EvenDuplex = True;
 695 }
 696
 697 if (Duplex && OutputOrder == Reverse && !device_outputorder) {
 698    /* Handle EvenDuplex, otherwise the first page's other side of paper
 699       is empty. */
 700    EvenDuplex = True;
 701 }
 702
 703 soft_copies = device_copies > 1 ? 1 : Copies;
 704
 705 6.2 JCL
 706
 707 When you print PDF files to a PostScript(PS) printer, you can specify
 708 device options in PS. In this case, you can write PS commands in a PPD file
 709 like as follows.
 710
 711 *OpenUI *Resolution/Resolution : PickOne
 712 *DefaultResolution: 600
 713 *Resolution 300/300 dpi: "<</HWResolution[300 300]>>setpagedevice"
 714 *Resolution 600/600 dpi: "<</HWResolution[600 600]>>setpagedevice"
 715 *CloseUI: *Resolution
 716
 717 However, if options cannot be described in PS file, you can write JCLs
 718 as follows;
 719
 720 *JCLOpenUI *JCLFrameBufferSize/Frame Buffer Size: PickOne
 721 *DefaultJCLFrameBufferSize: Letter
 722 *OrderDependency: 20 JCLSetup *JCLFrameBufferSize
 723 *JCLFrameBufferSize Off: '@PJL SET PAGEPROTECT = OFF<0A>'
 724 *JCLFrameBufferSize Letter: '@PJL SET PAGEPROTECT = LTR<0A>'
 725 *JCLFrameBufferSize Legal: '@PJL SET PAGEPROTECT = LGL<0A>'
 726 *JCLCloseUI: *JCLFrameBufferSize
 727
 728 For PostScript printers all these options are handled by the pdftops
 729 filter which is the PostScript printer driver in the PDF-based
 730 printing workflow.
 731
 732 If you have a native PDF printer you cannot use options which inject
 733 PostScript code into the data stream, you have to define all options
 734 with JCL. Only in this case pdftopdf adds the JCL header and trailer
 735 to the PDF job. Native PDF PPDs with JCL options are recognized by the
 736 "*JCLToPDFInterpreter:" keyword, for example with the following lines:
 737
 738 *JCLBegin:           "<1B>%-12345X@PJL JOB<0A>"
 739 *JCLToPDFInterpreter: "@PJL ENTER LANGUAGE = PDF <0A>"
 740 *JCLEnd:             "<1B>%-12345X@PJL EOJ <0A><1B>%-12345X"
 741
 742 To get the correct CUPS filter chain for them, they need the following
 743 line:
 744
 745 *cupsFilter: "application/vnd.cups-pdf 0 -"
 746
 747 and NO "*cupsFilter:" line which accepts PostScript input.
 748
 749 A sample PPD file for a native PDF printer,
 750 HP-Color_LaserJet_CM3530_MFP-PDF.ppd is included.
 751
 752 When a printer does not support PS nor PDF, you can use Ghostscript (GS).
 753 In this case, you can specify device options like a PS printer.
 754 If you want to use the same printer and same PPD file for both PDF and PS
 755 printing, when you print a PS file, you can specify that GS handles it,
 756 and when you print a PDF file, you can also specify that PDF filters handle
 757 it in the same PPD file. However in this case, previous methods is not
 758 appropriate to specify device options.
 759
 760 So, "pdftopdf" handles this case as follows;
 761 (In following pseudo program, JCL option is a option specified with JCLOpenUI)
 762
 763 if (Both JCLBegin and JCLToPDFInterpreter are specified in the PPD file) {
 764     output JCLs that marked JCL options.
 765 }
 766
 767 if (pdftopdfJCLBegin attribute is specified in the PPD file) {
 768     output it's value
 769 }
 770
 771 if (Copies option is specified in the PPD file) {
 772     mark Number of copies specified
 773 } else if (pdftopdfJCLCopies is specified in the PPD file) {
 774     output JCL specified with JCLCopies
 775 }
 776
 777 for (each marked options) {
 778     if (pdftopdfJCL<marked option's name> is specified in the PPD file) {
 779         output it's value as a JCL
 780     } else if (pdftopdfJCLBegin attributes is specified in the PPD file) {
 781         output "<option's name>=<marked choice>;" as a JCL
 782     }
 783 }
 784 output NEWLINE
 785
 786 Thus, if you want to use both PDF filters and GS by single PPD file,
 787 what you should do is to add the following line in the PPD file;
 788
 789 *pdftopdfJCLBegin: "pdftoopvp jobInfo:"
 790
 791 Note:
 792   If you specify JCLBegin, you have to specify JCLToPDFInterpreter as well.
 793
 794 Note:
 795   When you need to specify the value which is different from the choosen
 796   value based on the PPD into the jobInfo, you have to specify the values
 797   with the key started by "pdftopdfJCL" string.
 798
 799   For example, if the page size is defined in a PPD file as following;
 800
 801   *OpenUI *PageSize/Page Size: PickOne
 802   *DefaultPageSize: A4
 803   *PageSize A4/A4:
 804   *PageSize Letter/US Letter:
 805   *CloseUI: *PageSize
 806
 807   if you choose the page size "Letter", the string "PageSize=Letter;" is
 808   added to jobInfo. On the other hand, if the driver requires the different
 809   value for the "Letter" size, for instance driver requires "PS=LT;"
 810   instead of "PageSize=Letter;" as the jobInfo value, the PPD file has to
 811   be defined as following;
 812
 813   *OpenUI *PageSize/Page Size: PickOne
 814   *DefaultPageSize: A4
 815   *PageSize A4/A4:
 816   *pdftopdfJCLPageSize A4/A4: "PS=A4;"
 817   *PageSize Letter/US Letter:
 818   *pdftopdfJCLPageSize Letter/US Letter: "PS=LT;"
 819   *CloseUI: *PageSize
 820
 821 6.3 Special PDF comment
 822
 823 "pdftopdf" outputs the following special comments from the 4th line in the
 824 created PDF data.
 825
 826 %%PDFTOPDFNumCopies : <copies> --- <copies> specified Number of Copies
 827 %%PDFTOPDFCollate : <collate> --- <collate> is true or false
 828
 829 6.4 Temporally files location
 830
 831 "pdftopdf" creates temporally files if needed.　Temporary files are created
 832 in the location specified by TMPDIR environment　variable. Default location
 833 is "/tmp".
 834
 835
 836 TEXTTOPDF
 837
 838 This implements a texttopdf filter, and is derived from cups' texttops.
 839
 840 To configure:
 841 -------------
 842
 843 - texttopdf uses CUPS_DATADIR/charset/pdf.utf-8 for font configuration
 844   (when utf-8 was requested as charset). The font names given there are
 845   used as fontconfig selectors; the best matching font, that is both
 846   monospaced and in a supported format (TTC, TTF or OTF) will then be used.
 847
 848 - As a special exception, all fontnames that start with a '.' or '/' are
 849   considered filenames, and fontconfig is skipped; the name is used directly
 850   for loading the font file.
 851
 852 - Implementation note: TrueType Collections (.TTC) are internally handled
 853   by appending '/' and the index of the font inside the collection to
 854   the filename (e.g. to use the second font of uming.ttc, the filename
 855   uming.ttc/1 must be given to the fontembed-library).
 856   By appending the index-field returned from fontconfig, this is completely
 857   transparent to the user (but currently not widely tested).
 858
 859 - You may look at the two examples: pdf.utf-8.simple and pdf.utf-8.heavy.
 860
 861 To use:
 862 -------
 863
 864 The filter is called just like any other cups filter. Have a
 865 look at test.sh for example.
 866
 867 Known Issues
 868 ------------
 869
 870  - Text extraction does not work (at least for pdftotext from xpdf)
 871    for the resulting pdfs.
 872
 873  - OTF(CFF) embedding currently does not subset the fonts.
 874
 875  - Text wrapping in pretty-printing mode does not respect double-wide
 876    characters (CJK), and thus produce wrong results (wrap too late)
 877    for lines where they occur.  The fix is not trivial, since all the
 878    pretty-printing processing is done without knowledge of / prior to
 879    the font configuration (which is where single or double width
 880    code-ranges are specified).
 881
 882  - The hebrew example in test5.pdf shows one of our limitations:
 883    Compose glyphs are not composed with the primary glyph but printed
 884    as separate glyphs.
 885
 886 Further Infos
 887 -------------
 888
 889 Font embedding is handled by libfontembed in the filter/fontembed
 890 subdirectory.
 891
 892 Please report all bugs to https://bugs.linuxfoundation.org/, product
 893 "OpenPrinting", component "cups-filters".
 894
 895
 896 PDFTORASTER
 897
 898 1. INTRODUCTION
 899
 900 "pdftoraster" is a filter for CUPS. It reads PDF files, convert it and
 901 output CUPS raster.
 902
 903 "pdftoraster" does not support functions that are not related to printing
 904 features, including interactive features and document interchange features.
 905 Many of these operators and sections are just ignored.
 906 Some of these may be output, but those functions are not assured.
 907 Encryption feature is not supported.
 908
 909 2. LICENSE
 910
 911 Almost source files are under MIT like license. However, "pdftoraster" links
 912 some "poppler" libraries, and these files are under GNU public license.
 913 See copyright notice of each file for details.
 914
 915 3. COMMAND LINE
 916
 917 "pdftoraster" is a CUPS filter, and the command line arguments, environment
 918 variables and configuration files are in accordance with the CUPS filter
 919 interface.
 920
 921 pdftoraster <job> <user> <title> <num-copies> <options> [<filename>]
 922
 923 "pdftoraster" ignores <job> and <user>.
 924 <title> is appended into the PDF dictionary as /Title.
 925 <num-copies> specifies the number of document copies.
 926 <options> is a CUPS option list.
 927 <filename> is an input PDF file name.
 928
 929 When omit the <filename>, "pdftoraster" reads a PDF file from the stdin,
 930 and save it as a temporary file.
 931
 932 4. ENVIRONMENT VARIABLES
 933
 934 This program refers the following environment variable;
 935    PPD:  PPD file name of the printer.
 936
 937 5. COMMAND OPTIONS
 938
 939 See CUPS documents for details.
 940
 941 6. INFORMATION FOR DEVELOPERS
 942
 943 Following information is for developers, not for driver users.
 944
 945 6.1 Options handled by a printer or "pdftoraster"
 946
 947 "pdftopdf" outputs the following special comments from the 4th line in the
 948 created PDF data.
 949
 950 %%PDFTOPDFNumCopies : <copies> --- <copies> specified Number of Copies
 951 %%PDFTOPDFCollate : <collate> --- <collate> is true or false
 952
 953 "pdftoraster" overrides the command line options by above two option's values.
 954
 955 6.2 Temporally files location
 956
 957 "pdftoraster" creates temporally files if needed. Temporary files are created
 958 in the location specified by TMPDIR environment variable. Default location
 959 is "/tmp".
 960
 961
 962 PDFTOIJS
 963
 964 1. INTRODUCTION
 965
 966 "pdftoijs" is a filter for CUPS. It reads PDF files, converts it
 967 and sends it to an IJS server.
 968
 969 2. LICENSE
 970
 971 Almost source files are under MIT like license. However, "pdftoijs" links
 972 some "poppler" libraries, and these files are under GNU public license.
 973 See copyright notice of each file for details.
 974
 975 3. COMMAND LINE
 976
 977 "pdftoijs" is a CUPS filter, and the command line arguments, environment
 978 variables and configuration files are in accordance with the CUPS filter
 979 interface.
 980
 981 pdftoijs <job> <user> <title> <num-copies> <options> [<filename>]
 982
 983 "pdftoijs" ignores <job> and <user>.
 984 <title> is appended into the PDF dictionary as /Title.
 985 <num-copies> specifies the number of document copies.
 986 <options> is a CUPS option list.
 987 <filename> is an input PDF file name.
 988
 989 When omit the <filename>, "pdftoijs" reads a PDF file from the stdin,
 990 and save it as a temporary file.
 991
 992 4. ENVIRONMENT VARIABLES
 993
 994 This program refers the following environment variable;
 995    PPD:  PPD file name of the printer.
 996
 997 5. NEW PPD KEYWORDS
 998
 999 *ijsServer : the ijsserver executable
1000 *ijsManufacturer, *ijsModel : as used by the ijs server
1001 *ijsColorspace : the desired output colorspace, one of
1002                  'rgb'
1003                  'cmyk' (availability depending on poppler compile-options)
1004                  'white1', 'black1':  1-bit normal/inverted
1005                  'white8', 'black8':  8-bit greyscale normal/inverted
1006 *ijsResolution [option]=[choice]: the desired output resolution e.g. "600 600"
1007 *ijsParams [option]=[choice]: custom ijs parameters, separated by ','
1008                  (to escape: use \,)
1009
1010 6. COMMAND OPTIONS
1011
1012 (See CUPS documents for details.)
1013
1014 ijsOutputFile : the destination file, stdout otherwise
1015
1016 7. INFORMATION FOR DEVELOPERS
1017
1018 Following information is for developers, not for driver users.
1019
1020 7.1 Temporally files location
1021
1022 "pdftoijs" creates temporally files if needed. Temporary files are created
1023 in the location specified by TMPDIR environment variable. Default location
1024 is "/tmp".
1025
1026
1027 PDFTOOPVP
1028
1029 1. INTRODUCTION
1030
1031 "pdftoopvp" is a CUPS filter which reads PDF file, renders pages and
1032 outputs PDL to a printer driver which is compliant with the OpenPrinting
1033 Vector Printer Driver Interface "opvp".
1034
1035 2. CONFIGURATION
1036
1037 "pdftoopvp" refers the poppler configuration file. Be aware that poppler
1038 uses "fontconfig" for its font configuration.
1039
1040 3. JCL
1041
1042 When "pdftoopvp" reads a PDF file from stdin, "pdftoopvp" handles the data
1043 prior to PDF header (%PDF ...) as JCL options. JCL options for "pdftoopvp"
1044 must begin with "pdftoopvp jobInfo:". "pdftoopvp" passes the option string
1045 just after ":" to the driver as the jobInfo option.
1046
1047 4. COMMAND LINE
1048
1049 "pdftoopvp" is a CUPS filter, and the command line arguments,
1050 environment variables and configuration files are in accordance with
1051 the CUPS filter interface.
1052
1053 pdftoopvp <job> <user> <title> <num-copies> <options> [<filename>]
1054
1055 "pdftoopvp" ignores <job>, <user>, <title> and <num-copies>.
1056 <options> is a CUPS option list.
1057
1058 When omit the <filename>, "pdftoopvp" reads a PDF file from stdin,
1059 and save it as a temporary file.
1060
1061 CUPS options defined in <options> are delimited by space. Boolean
1062 type CUPS option is defined only by the option key, and other type
1063 CUPS option are defined by pairs of key and value, <key>=<value>.
1064
1065 5. COMMAND OPTIONS
1066
1067 "pdftoopvp" accepts the following CUPS standard options;
1068
1069 Resolution=<int>
1070   Specifies a printer resolution in dpi.
1071   When this option is omitted, the resolution is treated as 300dpi.
1072   Horizontal and vertical resolution are treated as the same resolution.
1073
1074 PageSize=<string>
1075   Specifies a paper size by name defined in the PPD file.
1076   This option is ignored when no PPD file is assigned for the printer
1077   queue.
1078
1079 "pdftoopvp" accepts the following original options;
1080
1081 opvpDriver=<string>
1082   Specifies a driver library name.
1083
1084 opvpModel=<string>
1085   Specifies a printer model name.
1086
1087 opvpJobInfo=<string>
1088   Specifies "jobInfo" printing options that are passed to the driver.
1089   Printing options are overridden by JCL options.
1090
1091 opvpDocInfo=<string>
1092   Specifies "docInfo" document options that are passed to the driver.
1093
1094 opvpPageInfo=<string>
1095   Specifies "pageInfo" page options that are passed to the driver.
1096
1097 pdftoopvpClipPathNotSaved (Boolean option)
1098   Specifies that the driver cannot save clipping path operators in PDF.
1099
1100 nopdftoopvpShearImage (Boolean option)
1101   Specifies that the driver cannot rotate/shear images by CTM.
1102
1103 nopdftoopvpMiterLimit (Boolean option)
1104   Specifies that the driver does not support miter limit.
1105   If the driver does not prepare the opvpSetMiterLimit function entry,
1106   this option setting is ignored, and also miter limit is ignored.
1107
1108 pdftoopvpIgnoreMiterLimit (Boolean option)
1109   When nopdftoopvpMiterLimit option is set, pdftoopvp automatically
1110   replace paths to multiple lines or drawing images. This option
1111   specifies to avoid the path replacement even when nopdftoopvpMiterLimit
1112   option is set.
1113
1114 pdftoopvpMaxClipPathLength=<int>
1115   Specifies the maximum number of clipping path points that the driver
1116   supports. Default value is 2000 points.
1117
1118 pdftoopvpMaxFillPathLength=<int>
1119   Specifies the maximum number of fill path points that the driver supports.
1120   Default value is 4000 points.
1121
1122 nopdftoopvpLineStyle (Boolean option)
1123   Specifies that the driver ignores the line style settings in PDF.
1124   If the driver does not prepare the SetLineStyle , SetLineDash or
1125   SetLineDashOffset function entry, this option setting is ignored, and
1126   also line style, line dash and line dash offset are ignored.
1127
1128 nopdftoopvpClipPath (Boolean option)
1129   Specifies that the driver does not support clipping path.
1130   If the driver does not prepare the opvpSetClipPath function entry, this
1131   option is ignored, and also clip path setting is ignored.
1132
1133 nopdftoopvpBitmapChar (Boolean option)
1134   Specifies that the driver does not output characters as images.
1135   Default setting is that "pdftoopvp" outputs small characters as images.
1136
1137 pdftoopvpBitmapCharThreshold=<int>
1138   Specifies the threshold value that "pdftoopvp" outputs characters as
1139   images. Threshold value is defined as W x H where character's width
1140   is given by W pixels and height is given by H pixels.
1141   Default threshold value is 2000 points.
1142
1143 nopdftoopvpImageMask (Boolean option)
1144   Specifies that the driver does not support image mask.
1145   If this option is set, "pdftoopvp" treats as the nopdftoopvpBitmapChar
1146   option is given.
1147
1148 6. PPD OPTIONS
1149
1150 Following options can be defined in a PPD.
1151
1152 Resolution=<int>
1153 PageSize=<string>
1154 opvpDriver=<string>
1155 opvpModel=<string>
1156 opvpJobInfo=<string>
1157 opvpDocInfo=<string>
1158 opvpPageInfo=<string>
1159 pdftoopvpClipPathNotSaved=True
1160 pdftoopvpShearImage=False
1161 pdftoopvpMiterLimit=False
1162 pdftoopvpIgnoreMiterLimit=True
1163 pdftoopvpMaxClipPathLength=<int>
1164 pdftoopvpMaxFillPathLength=<int>
1165 pdftoopvpLineStyle=False
1166 pdftoopvpClipPath=False
1167 pdftoopvpBitmapChar=False
1168 pdftoopvpBitmapCharThreshold=<int>
1169 pdftoopvpImageMask=False
1170
1171 7. OPTIONS OVERRIDING RULE
1172
1173 "jobInfo" printing options in a PPD is used as a initial "jobInfo" printing
1174 options. If opvpJobInfo option is given in the command line, precedent
1175 "jobInfo" printing options are overridden by the opvpJobInfo options.
1176
1177 After the "jobInfo" printing options are overridden by the opvpJobInfo
1178 options, if JCL options are given, precedent "jobInfo" printing options are
1179 overridden by the options given by JCL options.
1180
1181 8. INFORMATION FOR CUPS 1.1
1182
1183 To use this program under CUPS 1.1, following lines must be defined
1184 in the CUPS's "mime.types" file.
1185
1186 application/vnd.cups-pdf
1187
1188 9. KNOWN PROBLEMS
1189
1190 Problem:
1191   When a page is rotated and a character is small, character might not be
1192   rotated correctly. This problem is caused by free type library.
1193 Solution:
1194   Define the nopdftoopvpBitmapChar to inhibit characters output as images.
1195