forked from OpenPrinting/cups-filters
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
1692 lines (1249 loc) · 63.7 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
README - OpenPrinting CUPS Filters v1.27.5 - 2020-06-05
-------------------------------------------------------
Looking for compile instructions? Read the file "INSTALL.txt"
instead...
INTRODUCTION
CUPS is a standards-based, open source printing system used by
Apple's Mac OS® X and other UNIX®-like operating systems,
especially also Linux. CUPS uses the Internet Printing Protocol
("IPP") and provides System V and Berkeley command-line
interfaces, a web interface, and a C API to manage printers and
print jobs.
This package contains backends, filters, and other software that
was once part of the core CUPS distribution, but during the time
when CUPS was developed at Apple, Apple stopped maintining these
parts as they were not needed by Mac OS.
In addition it contains more filters and software developed
independently of Apple, especially filters for the PDF-centric
printing workflow introduced by OpenPrinting and a daemon to
browse broadcasts of remote CUPS printers and IPP printers to make
them available locally.
Since CUPS 1.6.0 cups-filters is required for using printer
drivers (and also driverless printing) with CUPS under Linux. This
version of cups-filters is only for CUPS 2.2.2 or newer. Please
use the cups-filters 1.x line for older CUPS versions.
For compiling and using this package CUPS (2.2.2 or newer),
libqpdf (10.3.2 or newer), libjpeg, libpng, libtiff, freetype,
fontconfig, liblcms (liblcms2 recommended), libavahi-common,
libavahi-client, libdbus, and glib are needed. It is highly
recommended, especially if non-PDF printers are used, to have at
least one of Ghostscript, Poppler, or MuPDF.
The Poppler-based pdftoraster filter needs a C++ compiler which
supports C++11 and Poppler being built with the "./configure"
option "-DENABLE_CPP=ON" for building the C++ support library
libpoppler-cpp. This is the case for most modern Linux
distributions.
If you use MuPDF as PDF renderer make sure to use at least version
1.15, as the older versions have bugs and so some files get not
printed correctly.
For Braille embosser support (see below) you will also need at
least liblouis, ImageMagick, and poppler-utils. Recommended is to
also have liblouisutdml, antiword, docx2txt for more sophisticated
Braille generation representing also the formatting of the input
text. None of these is needed for compiling cups-filters.
CUPS, this package, and Ghostscript contain some rudimentary
printer drivers and especially the filters needed for driverless
printing (currently PWG Raster, Apple Raster, PCLm, and PDF output
formats, for printers supporting IPP Everywhere, AirPrint, Wi-Fi
Direct, and other standards). See
http://www.openprinting.org/drivers/ for a more comprehensive set
of printer drivers for Linux.
See
https://wiki.linuxfoundation.org/openprinting/pdf_as_standard_print_job_format
for information about the PDF-based printing workflow.
Report bugs to
https://github.com/OpenPrinting/cups-filters/issues
or alternatively to
https://bugs.linuxfoundation.org/
Choose "OpenPrinting" as the product and "cups-filters" as the component.
See the "COPYING" files for legal information.
IMAGE PRINTING DEFAULT CHANGED TO "SCALE TO FIT"
Compared to the PostScript-based original CUPS filters there is a
change of defaults: The imagetopdf and imagetoraster filters print
in "scale-to-fit" mode (image is scaled to fill one page but
nothing of the image being cut off) by default.
This is done to support photo printing via AirPrint. The photo
apps on Apple's iOS devices send print jobs as JPEG images and do
not allow to set any options like "scaling" or the page size. With
"scale-to-fit" mode set by default, the iOS photos come out on one
page, as expected.
To get back to the old behavior, supply one of the options
"nofitplot" "filplot=Off", "nofit-to-page", or "fit-to-page=Off".
GHOSTSCRIPT RENDERING OF FILLED PATHS
When Ghostscript is rendering PostScript or PDF files into a
raster format the filled paths are ususally rendered with the
any-part-of-pixel method as it is PostScript standard. On
low-resolution printers, like label printers with 203 dpi,
graphics output can get inaccurate and so for example bar codes do
not work any more. This problem can be solved by letting
Ghostscript use the center-of-pixel method.
This can be done by either supplying the option "-o
center-of-pixel" or "-o CenterOfPixel" on the command line when
printing or by adding a "CenterOfPixel" option to the PPD file and
set it to "true", for example by adding the following lines to the
PPD file of the print queue (usually in /etc/cups/ppd/):
*OpenUI *CenterOfPixel/Center Of Pixel: PickOne
*OrderDependency: 20 AnySetup *CenterOfPixel
*DefaultCenterOfPixel: true
*CenterOfPixel true/true: ""
*CenterOfPixel false/false: ""
*CloseUI: *CenterOfPixel
This option can be used when the print queue uses the gstoraster
filter.
POSTSCRIPT PRINTING RENDERER AND RESOLUTION SELECTION
If you use CUPS with this package and a PostScript printer then
the included pdftops filter converts the print job data which is
in PDF format into PostScript. By default, the PostScript is
generated with Ghostscript's "ps2write" output device, which
generates a DSC-conforming PostScript with compressed embedded
fonts and compressed page content. This is resource-saving and
leads to fast wire transfer of print jobs to the printer.
Unfortunately, Ghostscript's PostScript output is not compatible
with some printers due to interpreter bugs in the printer and in
addition, processing (by Ghostscript or by the printer's
interpreter) can get very slow with high printing resolutions when
parts of the incoming PDF file are converted to bitmaps if they
contain graphical structures which are not supported by
PostScript. The bitmap problem especially occurs on input files
with transparency, especially also the ones produced by Cairo
(evince and many other GNOME/GTK applications) which unnecessarily
introduces transparency even if the input PDF has no transparency.
Therefore there are two possibilities to configure pdftops at
runtime:
1. Selection of the renderer: Ghostscript, Poppler, pdftocairo,
Adobe Reader, or MuPDF
Ghostscript has better color management and is generally optimized
more for printing. Poppler produces a PostScript which is
compatible with more buggy built-in PostScript interpreters of
printers and it leads to a somewhat quicker workflow when
graphical structures of the input PDF has to be turned into
bitmaps. Adobe Reader is the PDF renderer from Adobe, the ones who
created PDF and PostScript. pdftocairo is a good choice for the
PDF output of Cairo (for example when printing from evince). It
is less resource-consuming when rasterizing graphical elements
which cannot be represented in PostScript (like
transparency). Note that pdftocairo only supports PDF input using
DeviceRGB, DeviceGray, RGB or sGray and is not capable of
generating PostScript level 1. So its support is only experimental
and distributions should not choose it as default.
The selection is done by the "pdftops-renderer" option, setting it
to "gs", "pdftops", "pdftocairo", "acroread", "mupdf", or "hybrid":
Per-job: lpr -o pdftops-renderer=pdftops ...
Per-queue default: lpadmin -p printer -o pdftops-renderer-default=gs
Remove default: lpadmin -p printer -R pdftops-renderer-default
By default, pdftops uses Ghostscript if this does not get changed
at compile time, for example by the Linux distribution vendor.
Hybrid means Ghostscript for most printers, but Poppler's pdftops
for Brother, Minolta, and Konica Minolta. Printer make and model
information comes from the PPD or via the "make-and-model" option.
2. Limitation of the image rendering resolution
If graphical structures of the incoming PDF file have to be
converted to bitmaps due to limitations of PostScript, the
conversion of the file by pdftops or the rendering by the printer
can get too slow if the bitmap resolution is too high or the
printout quality can degrade if the bitmap resolution is too low.
By default, pdftops tries to find out the actual printing
resolution and sets the resolution for bitmap generation to the
same value. If it cannot find the printing resolution, it uses 300
dpi. It never goes higher than a limit of 1440 dpi. Note that this
default limit can get changed at compile time, for example by the
Linux distribution vendor.
The resolution limit for bitmaps can be changed to a lower or
higher value, or be set to unlimited. This is done by the option
"pdftops-max-image-resolution", setting it to the desired value
(in dpi) or to zero for unlimited. It can be used per-job or as
per-queue default as the "pdftops-renderer" option described
above.
The "pdftops-max-image-resolution" option is ignored when Adobe
Reader is selected as PDF renderer.
POSTSCRIPT PRINTING DEBUG MODE
Sometimes a PostScript printer's interpreter errors, crashes, or
somehow else misbehaves on Ghostscript's output. To find
workarounds (currently we have already workarounds for Brother and
Kyocera) it is much easier to work with uncompressed PostScript.
To get uncompressed PostScript as output, send a job with the
"psdebug" option, with commands like the following:
lpr -P <printer> -o psdebug <file>
lp -d <printer> -o psdebug <file>
If you want to send your job out of a desktop application, run
lpoptions -p <printer> -o psdebug
to make "psdebug" a personal default setting for you.
To extract the PostScript output for a developer to analyse it,
clone your print queue to a one which prints into a file:
cupsctl FileDevice=yes
lpadmin -p test -E -v file:/tmp/printout \
-P /etc/cups/ppd/<name of original queue>.ppd
and print into this queue as described above. The PostScript
output is in /tmp/printout after the job has completed.
This option does not change anything if Poppler's pdftops is used
as renderer.
HELPER DAEMON FOR BROWSING REMOTE CUPS PRINTERS AND IPP NETWORK PRINTERS
From version 1.6.0 on in CUPS the CUPS broadcasting/browsing
facility was dropped, in favour of Bonjour-based broadcasting of
shared printers. This is done as Bonjour broadcasting of shared
printers is a standard, established by the PWG (Printing Working
Group, http://www.pwg.org/), and most other network services
(shared file systems, shared media files/streams, remote desktop
services, ...) are also broadcasted via Bonjour.
Problem is that CUPS only broadcasts its shared printers but does
not browse broadcasts of other CUPS servers to make the shared
remote printers available locally without any configuration
efforts. This is a regression compared to the old CUPS
broadcasting/browsing. The intention of CUPS upstream is that the
application's print dialogs browse the Bonjour broadcasts as an
AirPrint-capable iPhone does, but it will take its time until all
toolkit developers add the needed functionality, and programs
using old toolkits or no toolkits at all, or the command line stay
uncovered.
The solution is cups-browsed, a helper daemon running in parallel
to the CUPS daemon which listens to Bonjour broadcasts of shared
CUPS printers on remote machines in the local network via Avahi,
and can also listen for (and send) CUPS Browsing broadcasts. For
each reported remote printer it creates a local raw queue pointing
to the remote printer so that the printer appears in local print
dialogs and is also available for printing via the command
line. As with the former CUPS broadcasting/browsing with this
queue the driver on the server is used and the local print dialogs
give access to all options of the server-side printer driver.
Note that CUPS broadcasting/browsing is available for legacy
support, to let the local CUPS daemon work seamlessly together
with remote CUPS daemons of version 1.5.x and older which only
support CUPS broadcasting/browsing. In networks with only CUPS
1.6.x servers (or Ubuntu or Fedora/Red Hat servers with CUPS
1.5.x) please use the native Bonjour broadcasting of your servers
and cups-browsed, configured for Bonjour browsing only on the
clients.
Also high availability with redundant print servers and load
balancing is supported. If there is more than one server providing
a shared print queue with the same name, cups-browsed forms a
cluster locally with this name as queue name and printing through
the "implicitclass" backend. Each job triggers cups-browsed to
check which remote queue is suitable for the job, meaning that it
is enabled, accepts jobs, and is not currently printing. If none
of the remote queues fulfills these criteria, we check again in 5
seconds, until a printer gets free to accommodate the job. When we
search for a free printer, we do not start at the first in the
list, but always on the one after the last one used (as CUPS also
does with classes), so that all printer get used, even if the
frequency of jobs is low. This is also what CUPS formerly did with
implicit classes. Optionally, jobs can be sent immediately into
the remote queue with the lowest number of waiting jobs, so that
no local queue of waiting jobs is built up.
For maximum security cups-browsed uses IPPS (encrypted IPP)
whenever possible.
In addition, cups-browsed is also capable of discovering IPP
network printers (native printers, not CUPS queues) with known
page description languages (PWG Raster, Apple Raster, PDF,
PostScript, PCL XL, PCL 5c/e) in the local network and auto-create
print queues with auto-created PPD files. This functionality is
primarily for mobile devices running CUPS to not need a printer
setup tool nor a collection of printer drivers and PPDs.
cups-browsed can also be started on-demand, for example to save
resources on mobile devices. For this, cups-browsed can be set
into an auto shutdown mode so that it stops automatically when it
has no remote printers to take care of any more, especially if an
on-demand running avahi-daemon stops. Note that CUPS must stay
running for cups-browsed removing its queues and so being able to
shut down. Ideal is if CUPS stays running another 30 seconds after
finishing its last job so that cups-browsed can take down the
queue. For how to set up and control this mode via command line,
configuration directives, or sending signals see the man pages
cups-browsed(8) and cups-browsed.conf(5).
The configuration file for cups-browsed is
/etc/cups/cups-browsed.conf. This file can include limited forms
of the original CUPS BrowseRemoteProtocols, BrowseLocalProtocols,
BrowsePoll, and BrowseAllow directives. It also can contain the
new CreateIPPPrinterQueues to activate discovering of IPP network
printers and creating PPD-less queues for them.
Note that cups-browsed does not work with remote CUPS servers
specified by a client.conf file. It always connects to the local
CUPS daemon by setting the CUPS_SERVER environment variable and so
overriding client.conf. If your local CUPS daemon uses a
non-standard domain socket as only way of access, you need to
specify it via the DomainSocket directive in
/etc/cups/cups-browsed.conf.
The "make install" process installs init scripts which make the
daemon automatically started during boot. You can also manually
start it with (as root):
/usr/sbin/cups-browsed &
or in debug mode with
/usr/sbin/cups-browsed --debug
Shut it down by sending signal 2 (SIGINT) or 15 (SIGTERM) to
it. The queues which it has created get removed then (except a
queue set as system default, to not loose its system default
state).
On systems using systemd use a
/usr/lib/systemd/system/cups-browsed.service file like this:
[Unit]
Description=Make remote CUPS printers available locally
After=cups.service avahi-daemon.service
Wants=cups.service avahi-daemon.service
[Service]
ExecStart=/usr/sbin/cups-browsed
[Install]
WantedBy=multi-user.target
On systems using Upstart use an /etc/init/cups-browsed.conf file like this:
start on (filesystem
and (started cups or runlevel [2345]))
stop on runlevel [016]
respawn
respawn limit 3 240
pre-start script
[ -x /usr/sbin/cups-browsed ]
end script
exec /usr/sbin/cups-browsed
These files are included in the source distribution as
utils/cups-browsed.service and utils/cups-browsed-upstart.conf.
In the examples we start cups-browsed after starting
avahi-daemon. This is not required. If cups-browsed starts first,
then Bonjour/DNS-SD browsing kicks in as soon as avahi-daemon comes
up. cups-browsed is also robust against any shutdown and restart
of avahi-daemon.
Here is some info on how cups-browsed works internally (first concept of a
daemon which does only Bonjour browsing):
- Daemon start
o Wait for CUPS daemon if it is not running
o Read out all CUPS queues created by this daemon (in former sessions)
o Mark them unconfirmed and set timeout 10 sec from now
- Main loop (use avahi_simple_poll_iterate() to do queue list maintenance
regularly)
o Event: New printer shows up
+ Queue for printer is already created by this daemon -> Mark list
entry confirmed, if discovered printer is ipps but existing queue ipp,
upgrade existing queue by setting URI to ipps. Set status to
to-be-created and timeout to now-1 sec to make the CUPS queue be
updated.
+ Queue does not yet exist -> Mark as to-be-created and set
timeout to now-1 sec.
o Event: A printer disappears
+ If we have listed a queue for it, mark the entry as disappeared, set
timeout to now-1 sec
o On any of the above events and every 2 sec
+ Check through list of our listed queues
- If queue is unconfirmed and timeout has passed, mark it as
disappeared, set timeout to now-1 sec
- If queue is marked disappered and timeout has passed, check whether
there are still jobs in it, if yes, set timeout to 10 sec from now,
if no, remove the CUPS queue and the queue entry in our list. If
removal fails, set timeout to 10 sec.
- If queue is to-be-created, create it, if succeeded set to
confirmed, if not, set timeout to 10 sec fron now. printer-is-shared
must be set to false.
- Daemon shutdown
o Remove all CUPS queues in our list, as long as they do not have jobs.
Do not overwrite existing queues which are not created by us If
the simple <remote_printer> name is already taken, try to create a
<remote_printer>@<server> name, if this is also taken, ignore the
remote printer. Do not retry, to avoid polling CUPS all the time.
Do not remove queues which are not created by us. We do this by
listing only our queues and remove only listed queues.
Queue names: Use the name of the remote queue. If a queue with the
same name from another server already exists, mark the new queue
as duplicate and when a queue disappears, check whether it has
duplicates and change the URI of the disappeared queue to the URI
of the first duplicate, mark the queue as to-be-created with
timeout now-1 sec (to update the URI of the CUPS queue) and mark
the duplicate disappeared with timeout now-1 sec. In terms of
high availability we replace the old load balancing of the
implicit class by a failover solution. Alternatively (not
implemented), if queue with same name but from other server
appears, create new queue as <original name>@<server name without
.local>. When queue with simple name is removed, replace the first
of the others by one with simple name (mark old queue disappeared
with timeout now-1 sec and create new queue with simple name).
Fill description of the created CUPS queue with the Bonjour
service name (= original description) and location with the server
name without .local.
stderr messages only in debug mode (command line options:
"--debug" or "-d" or "-v").
Queue identified as from this daemon by doing the equivalent of
"lpadmin -p printer -o cups-browsed-default", this generates a
"cups-browsed" attribute in printers.conf with value "true".
CUPS FILTERS FOR PDF AS STANDARD PRINT JOB FORMAT
Here is documentation from the former CUPS add-on tarball with the filters
for the PDF-based printing workflow: imagetopdf, texttopdf,
pdftopdf, and pdftoraster
The original filters are from http://sourceforge.jp/projects/opfc/
NOTE: the texttops and imagetops filters shipping with this package
are simple wrapper scripts for backward compatibility with third-party
PPD files and custom configurations. There are not referred to in the
cupsfilters.convs file and therefore not used by the default
configuration. Direct conversion of text or images to PostScript is
deprecated in the PDF-based printing workflow. So do not use these
filters when creating new PPDs or custom configurations. The parameters
for these filters are the same as for texttopdf and imagetopdf (see
below) as the ...tops filter calls the ....topdf filter plus
Ghostscript's pdf2ps.
IMAGETOPDF
==========
1. INTRODUCTION
This program is "imagetopdf". "imagetopdf" is a CUPS filter which reads
a single image file, converts it into a PDF file and outputs it to stdout.
This program accepts the following image file format;
gif, png, jpeg, tiff, photocd, portable-anymap, portable-bitmap,
portable-graymap, portable-pixmap, sgi-rgb, sun-raster, xbitmap,
xpixmap, xwindowdump
xbitmap, xpixmap and xwindowdump images are converted into png images by
the "convert" command. Other kinds of image file format can be supported
if the "convert" command support them.
Output PDF file format conforms to PDF version 1.3 specification, and
input image is converted and contained in the output PDF file as a binary
format non-compression image.
"imagetopdf" may outputs multiple pages if the input image exceeds page
printable area.
2. LICENSE
"imagetopdf.c" is under the CUPS license. See the "COPYING" file.
For other files, see the copyright notice and license of each file.
3. COMMAND LINE
"imagetopdf" is a CUPS filter, and the command line arguments, environment
variables and configuration files are in accordance with the CUPS filter
interface.
imagetopdf <job> <user> <title> <num-copies> <options> [<filename>]
"imagetopdf" ignores <job> and <user>.
<title> is appended into the PDF dictionary as /Title.
<num-copies> specifies the number of document copies.
<options> is a CUPS option list.
<filename> is an input image file name.
When omit the <filename>, "imagetopdf" reads an image file from stdin.
4. ENVIRONMENT VARIABLES
This program refers the following environment variable;
PPD: PPD file name of the printer.
5. COMMAND OPTIONS
"imagetopdf" accepts the following CUPS standard options;
fitplot
mirror
PageSize
page-left, page-right, page-bottom, page-top
OutputOrder
Collate
sides
cupsEvenDuplex
position
scaling
ppi
natural-scaling
landscape
orientation-requested
See the CUPS documents for details of these options.
6. KNOWN PROBLEMS
Problem:
PBM and SUN raster images can not be printed.
Solution:
Due to the CUPS libcupsimage library's bug. Update the CUPS on your system.
7. INFORMATION FOR DEVELOPERS
Following information is for developers, not for driver users.
7.1 Options handled by a printer or "imagetopdf"
Following options are handled by a printer or "imagetopdf".
Collate, Copies, Duplex, OutputOrder
Which handles these options depends on following options and attributes.
Collate, Copies, Duplex, OutputOrder, cupsEvenDuplex, cupsManualCopies
"imagetopdf" judges whether a printer can handle these options according to
the followings option settings in a PPD file.
Collate:
If Collate is defined, "imagetopdf" judges the printer supports Collate.
Copies:
If cupsManualCopies is defined as True, "imagetopdf" judges the printer
does not support Copies feature.
Duplex:
If Duplex is defined, "imagetopdf" judges the printer supports Duplex.
If cupsEvenDuplex is True, Number of pages must be even.
OutputOrder:
If OutputOrder is defined, "imagetopdf" judges the printer supports
OutputOrder.
If the printer cannot handle these options, "imagetopdf" handles it.
Following pseudo program describes how "imagetopdf" judges to handle
these options.
Variables
Copies : specified Copies
Duplex : specified Duplex
Collate : specified Collate
OutputOrder : specified OutputOrder
EvenDuplex : specified cupsEvenDuplex
pages : number of pages
number_up : specified number-up
device_copies : Copies passed to the printer
device_duplex : Duplex passed to the printer
device_collate : Collate passed to the printer
device_outputorder : OutputOrder passed to the printer
soft_copies : copies by imagetopdf
device_copies = 1;
device_duplex = False;
device_collate = False;
device_outputorder = False;
if (Copies == 1) {
/* Collate is not needed. */
Collate = False;
}
if (!Duplex) {
/* EvenDuplex is not needed */
EvenDuplex = False;
}
if (Copies > 1 && the printer can handle Copies) device_copies = Copies;
if (Duplex && the printer can handle Duplex) {
device_duplex = True;
} else {
/* imagetopdf cannot handle Duplex */
}
if (Collate && the printer can handle Collate) device_collate = True;
if (OutputOrder == Reverse && the printer can handle OutputOrder)
device_outputorder = True;
if (Collate && !device_collate) {
/* The printer cannot handle Collate.
So imagetopdf handle Copies */
device_copies = 1;
}
if (device_copies != Copies /* imagetopdf handle Copies */ && Duplex)
/* Make imagetopdf handle Collate, otherwise both paper side may have
same page */
Collate = True;
device_collate = False;
}
if (Duplex && Collate && !device_collate) {
/* Handle EvenDuplex, otherwise the last page has
the next copy's first page in the other side of the paper. */
EvenDuplex = True;
}
if (Duplex && OutputOrder == Reverse && !device_outputorder) {
/* Handle EvenDuplex, otherwise the first page's other side of paper
is empty. */
EvenDuplex = True;
}
soft_copies = device_copies > 1 ? 1 : Copies;
7.2 JCL
When you print PDF files to a PostScript(PS) printer, you can specify
device options in PS. In this case, you can write PS commands in a PPD file
like as follows.
*OpenUI *Resolution/Resolution : PickOne
*DefaultResolution: 600
*Resolution 300/300 dpi: "<</HWResolution[300 300]>>setpagedevice"
*Resolution 600/600 dpi: "<</HWResolution[600 600]>>setpagedevice"
*CloseUI: *Resolution
However, if options cannot be described in PS file, you can write JCLs
as follows;
*JCLOpenUI *JCLFrameBufferSize/Frame Buffer Size: PickOne
*DefaultJCLFrameBufferSize: Letter
*OrderDependency: 20 JCLSetup *JCLFrameBufferSize
*JCLFrameBufferSize Off: '@PJL SET PAGEPROTECT = OFF<0A>'
*JCLFrameBufferSize Letter: '@PJL SET PAGEPROTECT = LTR<0A>'
*JCLFrameBufferSize Legal: '@PJL SET PAGEPROTECT = LGL<0A>'
*JCLCloseUI: *JCLFrameBufferSize
Because PDF cannot specify device options in a PDF file, you have to define
all the device options as JCLs.
When a printer does not support PS or PDF, you can use Ghostscript (GS).
In this case, you can specify device options like a PS printer.
If you want to use the same printer and same PPD file for both PDF and PS
printing, when you print a PS file, you can specify that GS handles it,
and when you print a PDF file, you can also specify that PDF filters handle
it in the same PPD file. However in this case, previous methods is not
appropriate to specify device options.
So, "imagetopdf" handles this case as follows;
(In following pseudo program, JCL option is an option specified with JCLOpenUI)
if (Both JCLBegin and JCLToPSInterpreter are specified in the PPD file) {
output JCLs that marked JCL options.
}
if (pdftopdfJCLBegin attribute is specified in the PPD file) {
output it's value
}
if (Copies option is specified in the PPD file) {
mark Number of copies specified
} else if (pdftopdfJCLCopies is specified in the PPD file) {
output JCL specified with JCLCopies
}
for (each marked options) {
if (pdftopdfJCL<marked option's name> is specified in the PPD file) {
output it's value as a JCL
} else if (pdftopdfJCLBegin attributes is specified in the PPD file) {
output "<option's name>=<marked choice>;" as a JCL
}
}
output NEWLINE
Thus, if you want to use both PDF filters and GS by single PPD file,
what you should do is to add the following line in the PPD file;
*pdftopdfJCLBegin: "pdfto... jobInfo:"
Replace "pdfto..." by the name of the actual filter to be called after
pdftopdf.
Note:
If you specify JCLBegin, you have to specify JCLToPSInterpreter as well.
Note:
When you need to specify the value which is different from the choosen
value based on the PPD into the jobInfo, you have to specify the values
with the key started by "pdftopdfJCL" string.
For example, if the page size is defined in a PPD file as following;
*OpenUI *PageSize/Page Size: PickOne
*DefaultPageSize: A4
*PageSize A4/A4:
*PageSize Letter/US Letter:
*CloseUI: *PageSize
if you choose the page size "Letter", the string "PageSize=Letter;" is
added to jobInfo. On the other hand, if the driver requires the different
value for the "Letter" size, for instance driver requires "PS=LT;"
instead of "PageSize=Letter;" as the jobInfo value, the PPD file has to
be defined as following;
*OpenUI *PageSize/Page Size: PickOne
*DefaultPageSize: A4
*PageSize A4/A4:
*pdftopdfJCLPageSize A4/A4: "PS=A4;"
*PageSize Letter/US Letter:
*pdftopdfJCLPageSize Letter/US Letter: "PS=LT;"
*CloseUI: *PageSize
7.3 Temporally files location
"imagetopdf" creates temporally files if needed. Temporary files are created
in the location specified by TMPDIR environment variable. Default location
is "/tmp".
PDFTOPDF
========
The pdftopdf filter depends on libqpdf to read and write PDF files.
It replaces and imitates the pstops filter in the PDF-based workflow.
A similar filter (which can serve as behavior reference)
is called "cgpdftopdf" in OS X (not open source).
Command line
------------
pdftopdf follows the usual CUPS filter calling conventions, i.e.
pdftopdf <job> <user> <title> <num-copies> <options> [<filename>]
together with the environment variables "PPD" and "CLASSIFICATION".
When omitting <filename>, "pdftopdf" reads a PDF file from stdin.
Internally this will write the data to a temporary file, because
the PDF format cannot be processed in a streaming fashion.
<options> are delimited by space; boolean type CUPS options can be set
by only adding the option key, other types are provided as
pairs of key and value, <key>=<value>.
pdftopdf processes the following standard command-line and/or PPD options:
Copies # ppd will only override, when commandline parameter was 1
fitplot / fit-to-page / ipp-attribute-fidelity
landscape / orientation-requested
PageSize / page-size / MediaSize / media-size
page-left / page-right / page-bottom / page-top
media-top-margin / media-left-margin / media-right-margin / media-bottom-margin
Duplex / JCLDuplex / EFDuplex / JD03Duplex / sides
number-up / number-up-layout
page-border
OutputOrder / OutputBin / DefaultOutputOrder / page-delivery
page-label
page-set
page-ranges
MirrorPrint / mirror
emit-jcl
position
Collate / multiple-document-handling / sheet-collate
cupsEvenDuplex
cupsManualCopies # via ppd
Additional (non-standard) options
---------------------------------
1) Booklet printing
booklet=Off/On/Shuffle-Only
"On" also tries to set DuplexTumble (two-sided-short-edge) and forces number-up=2
booklet-signature=(multiple of 4, or default: -1 to use "all pages")
2) Page autorotate
pdftopdf automatically rotates pages to the same orientation,
instead of (e.g. fitplot) scaling them down unrotated.
This behavier can be controlled by
pdfAutorotate / nopdfAutorotate
Specifically, if a PDF file contains pages with page width greater than
page height (a landscape page), such pages are automatically rotated
anticlockwise by 90 degrees, unless the PPD file specifies
"*LandscapeOrientation: Minus90". In this case, clockwise rotation is used.
To turn off the feature on a job-by-job basis use
lp -d <print_queue_name> -o nopdfAutorotate <document>
On a per-queue basis use
-o nopdfAutorotate-default
as an option to lpadmin.
When the 'landscape' or 'orientation-requested=4' (or =5) option of CUPS is
given, the pdfAutorotate processing will adjust and accordingly rotate the
non-landscape pages are rotated instead.
Note: Some pages might end up 180 degree rotated (instead of 0 degree).
Those should probably be rotated manually before binding the pages together.
3) Method of flattening interactive PDF forms and annotations.
Some PDF files (like application forms) contain interactive forms
which the user can fill in inside a PDF viewer like evince. The filled
in data is not integrated in each page of the PDF file but stored in
an extra layer. Due to this the data gets lost when applying
manipulations like scaling or N-up to the pages. To prevent the loss
of the data pdftopdf flattens the form before doing the
manipulations. This means the PDF will be converted into a static PDF
file with the data being integral part of the pages.
The same flattening is needed for annotations in PDF files.
By default the actual flattening work is done by QPDF, as QPDF is also
doing everything else in pdftopdf. This way no external utilities need
to be called and so extra piping between processes and extra PDF
interpreter runs are avoided which makes the filtering process faster.
As we did not test the new QPDF-based form-flattening with thousands
of PDF files yet and it has not been available to actual users yet it
is possible that there are still some bugs. To give users a
possibility to work around possible bugs in QPDF's form flattening, we
have introduced an option to get back to the old flattening by the
external tools pdftocairo or Ghostscript.
The selection of the method is done by the "pdftopdf-form-flattening"
option, setting it to "auto", "qpdf", "pdftocairo", "ghostscript",
"gs", "internal" or "external":
Per-job: lpr -o pdftopdf-form-flattening=pdftocairo ...
Per-queue default: lpadmin -p printer -o pdftopdf-form-flattening-default=gs
Remove default: lpadmin -p printer -R pdftopdf-form-flattening-default
By default, pdftopdf uses QPDF if the option is not supplied, also the
settings "auto" and "internal" make QPDF being used. "external"
auto-selects from the two external utilities, trying pdftocairo at
first and on failure Ghostscript. If the selected utility fails, the
form stays unflattened and so the filled in data will possibly not get
printed.
Native PDF Printer / JCL Support
--------------------------------
Note that for most modern native PDF printers JCL is not needed any
more as they are controlled via IPP. For these the PPD files get
auto-generated by the support of CUPS and cups-filters for driverless
IPP printing.
pdftopdf will emit JCL when provided with a PPD file that includes the
"*JCLToPDFInterpreter:" keyword.
This enables for hardware copy generation and device collate; e.g. with PJL:
*JCLBegin: "<1B>%-12345X@PJL JOB<0A>"
*JCLToPDFInterpreter: "@PJL ENTER LANGUAGE = PDF <0A>"
*JCLEnd: "<1B>%-12345X@PJL EOJ <0A><1B>%-12345X"
For each marked option, the prefixed "pdftopdfJCL<option name>" keywords
can also be used to send raw JCL strings for that option.
These keywords also include *pdftopdfJCLBegin and *pdftopdfJCLCopies,
This allows the use of the same PPD for PDF- and PS-based workflows,
as pdftopdfJCL... will not be read in the PS case.
When the PPD contains the "Copies" keyword, pdftopdf will detect the use
of PJL and has special code which adds "@PJL SET COPIES=...",
or "@PJL SET QTY=...", respectively.
Other JCL code can be injected via "*JCLOpenUI: ..." ... "*JCLCloseUI: ...".
Special PDF comments
--------------------
pdftopdf adds comments to the pdf preamble that might esp. be of use
to subsequent filters, e.g.
% This file was generated by pdftopdf
%%PDFTOPDFNumCopies : 1
%%PDFTOPDFCollate : false
The "NumCopies" and "Collate" values refer to the expected device/hardware
copies, i.e. when pdftopdf's soft-copy generation did not handle this options.
Limitations
-----------
pdftopdf does not support functions that are not related to printing
features, including interactive features and document interchange features.
Many of these operators and sections are just ignored.
Some of these may be output, but those functions are not assured.
Most notable is the use of AcroForms; their content will not be printed
if any non-trivial processing by pdftopdf is involved (e.g. "fitplot").
This only occurs when a file is printed directly, e.g. by "lpr".
Usual PDF viewer applications (xpdf, evince, acroread, ghostscript, ...)
will hardcopy the form content into printable pdf operations,
when choosing to print such a document.
Known issues
------------
- Borders, esp. in the "number-up=1 fitplot=false"-case might be drawn
at incorrect locations.
- JCL documentation is sparse.
The imagetopdf or old pdftopdf documentation contains a tad more information.
- Missing AcroForm-content might surprise users printing PDF files directly /
from the command-line (see the Limitations section, above).
License
-------
pdftopdf is released under the MIT license.
The required libqpdf is available under version 2.0 of the Apache License,
e.g. here: https://github.com/qpdf/qpdf
TEXTTOPDF
=========
This implements a texttopdf filter, and is derived from cups' texttops.
To configure:
-------------
- texttopdf uses CUPS_DATADIR/charset/pdf.utf-8 for font configuration
(when utf-8 was requested as charset). The font names given there are
used as fontconfig selectors; the best matching font, that is both
monospaced and in a supported format (TTC, TTF or OTF) will then be used.
- As a special exception, all fontnames that start with a '.' or '/' are
considered filenames, and fontconfig is skipped; the name is used directly
for loading the font file.
- Implementation note: TrueType Collections (.TTC) are internally handled
by appending '/' and the index of the font inside the collection to
the filename (e.g. to use the second font of uming.ttc, the filename
uming.ttc/1 must be given to the fontembed-library).
By appending the index-field returned from fontconfig, this is completely
transparent to the user (but currently not widely tested).
- You may look at the two examples: pdf.utf-8.simple and pdf.utf-8.heavy.
To use:
-------
The filter is called just like any other cups filter. Have a
look at test.sh for example.