"Fossies" - the Fresh Open Source Software Archive

Member "cups-filters-1.28.16/README" (24 Aug 2022, 64330 Bytes) of package /linux/misc/cups-filters-1.28.16.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 1.28.15_vs_1.28.16.

    1 README - OpenPrinting CUPS Filters v1.28.16 - 2022-08-24
    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
   11     by Apple Inc. for Mac OS® X and other UNIX®-like operating
   12     systems.  CUPS uses the Internet Printing Protocol ("IPP") and
   13     provides System V and Berkeley command-line interfaces, a web
   14     interface, and a C API to manage printers and print jobs.
   15 
   16     This package contains backends, filters, and other software that
   17     was once part of the core CUPS distribution but is no longer
   18     maintained by Apple Inc. In addition it contains additional
   19     filters and software developed independently of Apple, especially
   20     filters for the PDF-centric printing workflow introduced by
   21     OpenPrinting and a daemon to browse broadcasts of remote CUPS
   22     printers and IPP printers to make them available locally.
   23 
   24     From CUPS 1.6.0 on, this package is required for using printer
   25     drivers (and also driverless printing) with CUPS under Linux. With
   26     CUPS 1.5.x and 1.4.x this package can be used optionally to switch
   27     over to PDF-based printing. In that case some filters are provided
   28     by both CUPS and this package. Then the filters of this package
   29     should be used.
   30 
   31     For compiling and using this package CUPS, libqpdf (8.3.0 or
   32     newer), libjpeg, libpng, libtiff, freetype, fontconfig, liblcms
   33     (liblcms2 recommended), libavahi-common, libavahi-client, libdbus,
   34     and glib are needed. It is highly recommended, especially if
   35     non-PDF printers are used, to have at least one of Ghostscript,
   36     Poppler, or MuPDF.
   37 
   38     The Poppler-based pdftoraster filter needs a C++ compiler which
   39     supports C++11 and Poppler being built with the "./configure"
   40     option "-DENABLE_CPP=ON" for building the C++ support library
   41     libpoppler-cpp. This is the case for most modern Linux
   42     distributions.
   43 
   44     If you use MuPDF as PDF renderer make sure to use at least version
   45     1.15, as the older versions have bugs and so some files get not
   46     printed correctly.
   47 
   48     For Apple Raster output (used by AirPrint printers) at least CUPS
   49     2.2.2 is required.
   50 
   51     For Braille embosser support (see below) you will also need at
   52     least liblouis, ImageMagick, and poppler-utils. Recommended is to
   53     also have liblouisutdml, antiword, docx2txt for more sophisticated
   54     Braille generation representing also the formatting of the input
   55     text. None of these is needed for compiling cups-filters.
   56 
   57     CUPS, this package, and Ghostscript contain some rudimentary
   58     printer drivers and especially the filters needed for driverless
   59     printing (currently PWG Raster, Apple Raster, PCLm, and PDF output
   60     formats, for printers supporting IPP Everywhere, AirPrint, Wi-Fi
   61     Direct, and other standards), see
   62     http://www.openprinting.org/drivers/ for a more comprehensive set
   63     of printer drivers for Linux.
   64 
   65     See
   66     
   67     https://wiki.linuxfoundation.org/openprinting/pdf_as_standard_print_job_format
   68 
   69     for information about the PDF-based printing workflow.
   70 
   71     Report bugs to
   72 
   73     https://github.com/OpenPrinting/cups-filters/issues
   74 
   75     or alternatively to
   76 
   77     https://bugs.linuxfoundation.org/
   78 
   79     Choose "OpenPrinting" as the product and "cups-filters" as the component.
   80 
   81     See the "COPYING" files for legal information.
   82 
   83 IMAGE PRINTING DEFAULT CHANGED TO "SCALE TO FIT"
   84 
   85     Compared to the PostScript-based original CUPS filters there is a
   86     change of defaults: The imagetopdf and imagetoraster filters print
   87     in "scale-to-fit" mode (image is scaled to fill one page but
   88     nothing of the image being cut off) by default.
   89 
   90     This is done to support photo printing via AirPrint. The photo
   91     apps on Apple's iOS devices send print jobs as JPEG images and do
   92     not allow to set any options like "scaling" or the page size. With
   93     "scale-to-fit" mode set by default, the iOS photos come out on one
   94     page, as expected.
   95 
   96     To get back to the old behavior, supply one of the options
   97     "nofitplot" "filplot=Off", "nofit-to-page", or "fit-to-page=Off".
   98 
   99 GHOSTSCRIPT RENDERING OF FILLED PATHS
  100 
  101     When Ghostscript is rendering PostScript or PDF files into a
  102     raster format the filled paths are ususally rendered with the
  103     any-part-of-pixel method as it is PostScript standard. On
  104     low-resolution printers, like label printers with 203 dpi,
  105     graphics output can get inaccurate and so for example bar codes do
  106     not work any more. This problem can be solved by letting
  107     Ghostscript use the center-of-pixel method.
  108 
  109     This can be done by either supplying the option "-o
  110     center-of-pixel" or "-o CenterOfPixel" on the command line when
  111     printing or by adding a "CenterOfPixel" option to the PPD file and
  112     set it to "true", for example by adding the following lines to the
  113     PPD file of the print queue (usually in /etc/cups/ppd/):
  114 
  115         *OpenUI *CenterOfPixel/Center Of Pixel: PickOne
  116         *OrderDependency: 20 AnySetup *CenterOfPixel
  117         *DefaultCenterOfPixel: true
  118         *CenterOfPixel true/true: ""
  119         *CenterOfPixel false/false: ""
  120         *CloseUI: *CenterOfPixel
  121 
  122    This option can be used when the print queue uses the gstoraster
  123    filter.
  124 
  125 POSTSCRIPT PRINTING RENDERER AND RESOLUTION SELECTION
  126 
  127     If you use CUPS with this package and a PostScript printer then
  128     the included pdftops filter converts the print job data which is
  129     in PDF format into PostScript. By default, the PostScript is
  130     generated with Ghostscript's "ps2write" output device, which
  131     generates a DSC-conforming PostScript with compressed embedded
  132     fonts and compressed page content. This is resource-saving and
  133     leads to fast wire transfer of print jobs to the printer.
  134 
  135     Unfortunately, Ghostscript's PostScript output is not compatible
  136     with some printers due to interpreter bugs in the printer and in
  137     addition, processing (by Ghostscript or by the printer's
  138     interpreter) can get very slow with high printing resolutions when
  139     parts of the incoming PDF file are converted to bitmaps if they
  140     contain graphical structures which are not supported by
  141     PostScript. The bitmap problem especially occurs on input files
  142     with transparency, especially also the ones produced by Cairo
  143     (evince and many other GNOME/GTK applications) which unnecessarily
  144     introduces transparency even if the input PDF has no transparency.
  145 
  146     Therefore there are two possibilities to configure pdftops at
  147     runtime:
  148 
  149     1. Selection of the renderer: Ghostscript, Poppler, pdftocairo,
  150     Adobe Reader, or MuPDF
  151 
  152     Ghostscript has better color management and is generally optimized
  153     more for printing. Poppler produces a PostScript which is
  154     compatible with more buggy built-in PostScript interpreters of
  155     printers and it leads to a somewhat quicker workflow when
  156     graphical structures of the input PDF has to be turned into
  157     bitmaps. Adobe Reader is the PDF renderer from Adobe, the ones who
  158     created PDF and PostScript. pdftocairo is a good choice for the
  159     PDF output of Cairo (for example when printing from evince).  It
  160     is less resource-consuming when rasterizing graphical elements
  161     which cannot be represented in PostScript (like
  162     transparency). Note that pdftocairo only supports PDF input using
  163     DeviceRGB, DeviceGray, RGB or sGray and is not capable of
  164     generating PostScript level 1. So its support is only experimental
  165     and distributions should not choose it as default.
  166 
  167     The selection is done by the "pdftops-renderer" option, setting it
  168     to "gs", "pdftops", "pdftocairo", "acroread", "mupdf", or "hybrid":
  169 
  170     Per-job:           lpr -o pdftops-renderer=pdftops ...
  171     Per-queue default: lpadmin -p printer -o pdftops-renderer-default=gs
  172     Remove default:    lpadmin -p printer -R pdftops-renderer-default
  173 
  174     By default, pdftops uses Ghostscript if this does not get changed
  175     at compile time, for example by the Linux distribution vendor.
  176 
  177     Hybrid means Ghostscript for most printers, but Poppler's pdftops
  178     for Brother, Minolta, and Konica Minolta. Printer make and model
  179     information comes from the PPD or via the "make-and-model" option.
  180 
  181     2. Limitation of the image rendering resolution
  182 
  183     If graphical structures of the incoming PDF file have to be
  184     converted to bitmaps due to limitations of PostScript, the
  185     conversion of the file by pdftops or the rendering by the printer
  186     can get too slow if the bitmap resolution is too high or the
  187     printout quality can degrade if the bitmap resolution is too low.
  188 
  189     By default, pdftops tries to find out the actual printing
  190     resolution and sets the resolution for bitmap generation to the
  191     same value. If it cannot find the printing resolution, it uses 300
  192     dpi. It never goes higher than a limit of 1440 dpi. Note that this
  193     default limit can get changed at compile time, for example by the
  194     Linux distribution vendor.
  195 
  196     The resolution limit for bitmaps can be changed to a lower or
  197     higher value, or be set to unlimited. This is done by the option
  198     "pdftops-max-image-resolution", setting it to the desired value
  199     (in dpi) or to zero for unlimited. It can be used per-job or as
  200     per-queue default as the "pdftops-renderer" option described
  201     above.
  202 
  203     The "pdftops-max-image-resolution" option is ignored when Adobe
  204     Reader is selected as PDF renderer.
  205 
  206 POSTSCRIPT PRINTING DEBUG MODE
  207 
  208     Sometimes a PostScript printer's interpreter errors, crashes, or
  209     somehow else misbehaves on Ghostscript's output. To find
  210     workarounds (currently we have already workarounds for Brother and
  211     Kyocera) it is much easier to work with uncompressed PostScript.
  212     To get uncompressed PostScript as output, send a job with the
  213     "psdebug" option, with commands like the following:
  214 
  215       lpr -P <printer> -o psdebug <file>
  216       lp -d <printer> -o psdebug <file>
  217 
  218     If you want to send your job out of a desktop application, run
  219 
  220       lpoptions -p <printer> -o psdebug
  221 
  222     to make "psdebug" a personal default setting for you.
  223 
  224     To extract the PostScript output for a developer to analyse it,
  225     clone your print queue to a one which prints into a file:
  226 
  227       cupsctl FileDevice=yes
  228       lpadmin -p test -E -v file:/tmp/printout \
  229       -P /etc/cups/ppd/<name of original queue>.ppd
  230 
  231     and print into this queue as described above. The PostScript
  232     output is in /tmp/printout after the job has completed.
  233 
  234     This option does not change anything if Poppler's pdftops is used
  235     as renderer.
  236 
  237 HELPER DAEMON FOR BROWSING REMOTE CUPS PRINTERS AND IPP NETWORK PRINTERS
  238 
  239     From version 1.6.0 on in CUPS the CUPS broadcasting/browsing
  240     facility was dropped, in favour of Bonjour-based broadcasting of
  241     shared printers. This is done as Bonjour broadcasting of shared
  242     printers is a standard, established by the PWG (Printing Working
  243     Group, http://www.pwg.org/), and most other network services
  244     (shared file systems, shared media files/streams, remote desktop
  245     services, ...) are also broadcasted via Bonjour.
  246 
  247     Problem is that CUPS only broadcasts its shared printers but does
  248     not browse broadcasts of other CUPS servers to make the shared
  249     remote printers available locally without any configuration
  250     efforts. This is a regression compared to the old CUPS
  251     broadcasting/browsing. The intention of CUPS upstream is that the
  252     application's print dialogs browse the Bonjour broadcasts as an
  253     AirPrint-capable iPhone does, but it will take its time until all
  254     toolkit developers add the needed functionality, and programs
  255     using old toolkits or no toolkits at all, or the command line stay
  256     uncovered.
  257 
  258     The solution is cups-browsed, a helper daemon running in parallel
  259     to the CUPS daemon which listens to Bonjour broadcasts of shared
  260     CUPS printers on remote machines in the local network via Avahi,
  261     and can also listen for (and send) CUPS Browsing broadcasts. For
  262     each reported remote printer it creates a local raw queue pointing
  263     to the remote printer so that the printer appears in local print
  264     dialogs and is also available for printing via the command
  265     line. As with the former CUPS broadcasting/browsing with this
  266     queue the driver on the server is used and the local print dialogs
  267     give access to all options of the server-side printer driver.
  268 
  269     Note that CUPS broadcasting/browsing is available for legacy
  270     support, to let the local CUPS daemon work seamlessly together
  271     with remote CUPS daemons of version 1.5.x and older which only
  272     support CUPS broadcasting/browsing. In networks with only CUPS
  273     1.6.x servers (or Ubuntu or Fedora/Red Hat servers with CUPS
  274     1.5.x) please use the native Bonjour broadcasting of your servers
  275     and cups-browsed, configured for Bonjour browsing only on the
  276     clients.
  277 
  278     Also high availability with redundant print servers and load
  279     balancing is supported. If there is more than one server providing
  280     a shared print queue with the same name, cups-browsed forms a
  281     cluster locally with this name as queue name and printing through
  282     the "implicitclass" backend. Each job triggers cups-browsed to
  283     check which remote queue is suitable for the job, meaning that it
  284     is enabled, accepts jobs, and is not currently printing.  If none
  285     of the remote queues fulfills these criteria, we check again in 5
  286     seconds, until a printer gets free to accommodate the job. When we
  287     search for a free printer, we do not start at the first in the
  288     list, but always on the one after the last one used (as CUPS also
  289     does with classes), so that all printer get used, even if the
  290     frequency of jobs is low. This is also what CUPS formerly did with
  291     implicit classes. Optionally, jobs can be sent immediately into
  292     the remote queue with the lowest number of waiting jobs, so that
  293     no local queue of waiting jobs is built up.
  294 
  295     For maximum security cups-browsed uses IPPS (encrypted IPP)
  296     whenever possible.
  297 
  298     In addition, cups-browsed is also capable of discovering IPP
  299     network printers (native printers, not CUPS queues) with known
  300     page description languages (PWG Raster, Apple Raster, PDF,
  301     PostScript, PCL XL, PCL 5c/e) in the local network and auto-create
  302     print queues with auto-created PPD file or PPD-less for them (for
  303     the latter using a System V interface script to control the filter
  304     chain, only available for CUPS 2.1.0 and older, clients have to
  305     IPP-poll the capabilities of the printer and send option settings
  306     as standard IPP attributes then). This functionality is primarily
  307     for mobile devices running CUPS to not need a printer setup tool
  308     nor a collection of printer drivers and PPDs.
  309 
  310     cups-browsed can also be started on-demand, for example to save
  311     resources on mobile devices. For this, cups-browsed can be set
  312     into an auto shutdown mode so that it stops automatically when it
  313     has no remote printers to take care of any more, especially if an
  314     on-demand running avahi-daemon stops. Note that CUPS must stay
  315     running for cups-browsed removing its queues and so being able to
  316     shut down. Ideal is if CUPS stays running another 30 seconds after
  317     finishing its last job so that cups-browsed can take down the
  318     queue. For how to set up and control this mode via command line,
  319     configuration directives, or sending signals see the man pages
  320     cups-browsed(8) and cups-browsed.conf(5).
  321 
  322     The configuration file for cups-browsed is
  323     /etc/cups/cups-browsed.conf.  This file can include limited forms
  324     of the original CUPS BrowseRemoteProtocols, BrowseLocalProtocols,
  325     BrowsePoll, and BrowseAllow directives. It also can contain the
  326     new CreateIPPPrinterQueues to activate discovering of IPP network
  327     printers and creating PPD-less queues for them.
  328 
  329     Note that cups-browsed does not work with remote CUPS servers
  330     specified by a client.conf file. It always connects to the local
  331     CUPS daemon by setting the CUPS_SERVER environment variable and so
  332     overriding client.conf. If your local CUPS daemon uses a
  333     non-standard domain socket as only way of access, you need to
  334     specify it via the DomainSocket directive in
  335     /etc/cups/cups-browsed.conf.
  336 
  337     The "make install" process installs init scripts which make the
  338     daemon automatically started during boot. You can also manually
  339     start it with (as root):
  340 
  341     /usr/sbin/cups-browsed &
  342 
  343     or in debug mode with
  344 
  345     /usr/sbin/cups-browsed --debug
  346 
  347     Shut it down by sending signal 2 (SIGINT) or 15 (SIGTERM) to
  348     it. The queues which it has created get removed then (except a
  349     queue set as system default, to not loose its system default
  350     state).
  351 
  352     On systems using systemd use a
  353     /usr/lib/systemd/system/cups-browsed.service file like this:
  354 
  355         [Unit]
  356         Description=Make remote CUPS printers available locally
  357         After=cups.service avahi-daemon.service
  358         Wants=cups.service avahi-daemon.service
  359 
  360         [Service]
  361         ExecStart=/usr/sbin/cups-browsed
  362 
  363         [Install]
  364         WantedBy=multi-user.target
  365 
  366     On systems using Upstart use an /etc/init/cups-browsed.conf file like this:
  367 
  368         start on (filesystem
  369                   and (started cups or runlevel [2345]))
  370         stop on runlevel [016]
  371 
  372         respawn
  373         respawn limit 3 240
  374 
  375         pre-start script
  376             [ -x /usr/sbin/cups-browsed ]
  377         end script
  378 
  379         exec /usr/sbin/cups-browsed
  380 
  381     These files are included in the source distribution as
  382     utils/cups-browsed.service and utils/cups-browsed-upstart.conf.
  383 
  384     In the examples we start cups-browsed after starting
  385     avahi-daemon. This is not required. If cups-browsed starts first,
  386     then Bonjour/DNS-SD browsing kicks in as soon as avahi-daemon comes
  387     up. cups-browsed is also robust against any shutdown and restart
  388     of avahi-daemon.
  389 
  390     Here is some info on how cups-browsed works internally (first concept of a
  391     daemon which does only Bonjour browsing):
  392 
  393     - Daemon start
  394       o Wait for CUPS daemon if it is not running
  395       o Read out all CUPS queues created by this daemon (in former sessions)
  396       o Mark them unconfirmed and set timeout 10 sec from now
  397     - Main loop (use avahi_simple_poll_iterate() to do queue list maintenance
  398                  regularly)
  399       o Event: New printer shows up
  400         + Queue for printer is already created by this daemon -> Mark list
  401           entry confirmed, if discovered printer is ipps but existing queue ipp,
  402 	  upgrade existing queue by setting URI to ipps. Set status to
  403 	  to-be-created and timeout to now-1 sec to make the CUPS queue be
  404 	  updated.
  405         + Queue does not yet exist -> Mark as to-be-created and set
  406 	  timeout to now-1 sec.
  407       o Event: A printer disappears
  408         + If we have listed a queue for it, mark the entry as disappeared, set
  409           timeout to now-1 sec
  410       o On any of the above events and every 2 sec
  411         + Check through list of our listed queues
  412           - If queue is unconfirmed and timeout has passed, mark it as
  413             disappeared, set timeout to now-1 sec
  414           - If queue is marked disappered and timeout has passed, check whether
  415 	    there are still jobs in it, if yes, set timeout to 10 sec from now,
  416 	    if no, remove the CUPS queue and the queue entry in our list. If
  417 	    removal fails, set timeout to 10 sec.
  418 	  - If queue is to-be-created, create it, if succeeded set to
  419 	    confirmed, if not, set timeout to 10 sec fron now. printer-is-shared
  420 	    must be set to false.
  421     - Daemon shutdown
  422       o Remove all CUPS queues in our list, as long as they do not have jobs.
  423 
  424     Do not overwrite existing queues which are not created by us If
  425     the simple <remote_printer> name is already taken, try to create a
  426     <remote_printer>@<server> name, if this is also taken, ignore the
  427     remote printer. Do not retry, to avoid polling CUPS all the time.
  428 
  429     Do not remove queues which are not created by us. We do this by
  430     listing only our queues and remove only listed queues.
  431 
  432     Queue names: Use the name of the remote queue. If a queue with the
  433     same name from another server already exists, mark the new queue
  434     as duplicate and when a queue disappears, check whether it has
  435     duplicates and change the URI of the disappeared queue to the URI
  436     of the first duplicate, mark the queue as to-be-created with
  437     timeout now-1 sec (to update the URI of the CUPS queue) and mark
  438     the duplicate disappeared with timeout now-1 sec. In terms of
  439     high availability we replace the old load balancing of the
  440     implicit class by a failover solution. Alternatively (not
  441     implemented), if queue with same name but from other server
  442     appears, create new queue as <original name>@<server name without
  443     .local>. When queue with simple name is removed, replace the first
  444     of the others by one with simple name (mark old queue disappeared
  445     with timeout now-1 sec and create new queue with simple name).
  446 
  447     Fill description of the created CUPS queue with the Bonjour
  448     service name (= original description) and location with the server
  449     name without .local.
  450 
  451     stderr messages only in debug mode (command line options:
  452     "--debug" or "-d" or "-v").
  453 
  454     Queue identified as from this daemon by doing the equivalent of
  455     "lpadmin -p printer -o cups-browsed-default", this generates a
  456     "cups-browsed" attribute in printers.conf with value "true".
  457 
  458 CUPS FILTERS FOR PDF AS STANDARD PRINT JOB FORMAT
  459 
  460     Here is documentation from the former CUPS add-on tarball with the filters
  461     for the PDF-based printing workflow: imagetopdf, texttopdf,
  462     pdftopdf, and pdftoraster
  463 
  464     The original filters are from http://sourceforge.jp/projects/opfc/
  465 
  466     NOTE: the texttops and imagetops filters shipping with this package
  467     are simple wrapper scripts for backward compatibility with third-party
  468     PPD files and custom configurations. There are not referred to in the
  469     cupsfilters.convs file and therefore not used by the default
  470     configuration. Direct conversion of text or images to PostScript is
  471     deprecated in the PDF-based printing workflow. So do not use these
  472     filters when creating new PPDs or custom configurations. The parameters
  473     for these filters are the same as for texttopdf and imagetopdf (see
  474     below) as the ...tops filter calls the ....topdf filter plus
  475     Ghostscript's pdf2ps.
  476 
  477 
  478 IMAGETOPDF
  479 ==========
  480 
  481 1. INTRODUCTION
  482 
  483 This program is "imagetopdf". "imagetopdf" is a CUPS filter which reads
  484 a single image file, converts it into a PDF file and outputs it to stdout.
  485 
  486 This program accepts the following image file format;
  487 
  488   gif, png, jpeg, tiff, photocd, portable-anymap, portable-bitmap,
  489   portable-graymap, portable-pixmap, sgi-rgb, sun-raster, xbitmap,
  490   xpixmap, xwindowdump
  491 
  492 xbitmap, xpixmap and xwindowdump images are converted into png images by
  493 the "convert" command. Other kinds of image file format can be supported
  494 if the "convert" command support them.
  495 
  496 Output PDF file format conforms to PDF version 1.3 specification, and
  497 input image is converted and contained in the output PDF file as a binary
  498 format non-compression image.
  499 
  500 "imagetopdf" may outputs multiple pages if the input image exceeds page
  501 printable area.
  502 
  503 2. LICENSE
  504 
  505 "imagetopdf.c" is under the CUPS license. See the "COPYING" file.
  506 For other files, see the copyright notice and license of each file.
  507 
  508 3. COMMAND LINE
  509 
  510 "imagetopdf" is a CUPS filter, and the command line arguments, environment
  511 variables and configuration files are in accordance with the CUPS filter
  512 interface.
  513 
  514 imagetopdf <job> <user> <title> <num-copies> <options> [<filename>]
  515 
  516 "imagetopdf" ignores <job> and <user>.
  517 <title> is appended into the PDF dictionary as /Title.
  518 <num-copies> specifies the number of document copies.
  519 <options> is a CUPS option list.
  520 <filename> is an input image file name.
  521 
  522 When omit the <filename>, "imagetopdf" reads an image file from stdin.
  523 
  524 4. ENVIRONMENT VARIABLES
  525 
  526 This program refers the following environment variable;
  527 
  528    PPD:  PPD file name of the printer.
  529 
  530 5. COMMAND OPTIONS
  531 
  532 "imagetopdf" accepts the following CUPS standard options;
  533 
  534 fitplot
  535 mirror
  536 PageSize
  537 page-left, page-right, page-bottom, page-top
  538 OutputOrder
  539 Collate
  540 sides
  541 cupsEvenDuplex
  542 position
  543 scaling
  544 ppi
  545 natural-scaling
  546 landscape
  547 orientation-requested
  548 
  549 See the CUPS documents for details of these options.
  550 
  551 6. KNOWN PROBLEMS
  552 
  553 Problem:
  554   PBM and SUN raster images can not be printed.
  555 Solution:
  556   Due to the CUPS libcupsimage library's bug. Update the CUPS on your system.
  557   
  558 7. INFORMATION FOR DEVELOPERS
  559 
  560 Following information is for developers, not for driver users.
  561 
  562 7.1 Options handled by a printer or "imagetopdf"
  563 
  564 Following options are handled by a printer or "imagetopdf".
  565   Collate, Copies, Duplex, OutputOrder
  566 
  567 Which handles these options depends on following options and attributes.
  568   Collate, Copies, Duplex, OutputOrder, cupsEvenDuplex, cupsManualCopies
  569 
  570 "imagetopdf" judges whether a printer can handle these options according to
  571 the followings option settings in a PPD file.
  572 
  573 Collate:
  574   If Collate is defined, "imagetopdf" judges the printer supports Collate.
  575 Copies:
  576   If cupsManualCopies is defined as True, "imagetopdf" judges the printer
  577   does not support Copies feature.
  578  
  579 Duplex:
  580   If Duplex is defined, "imagetopdf" judges the printer supports Duplex.
  581   If cupsEvenDuplex is True, Number of pages must be even.
  582 OutputOrder:
  583   If OutputOrder is defined, "imagetopdf" judges the printer supports
  584   OutputOrder.
  585 
  586 If the printer cannot handle these options, "imagetopdf" handles it.
  587 
  588 Following pseudo program describes how "imagetopdf" judges to handle
  589 these options.
  590 
  591 Variables
  592 
  593 Copies : specified Copies
  594 Duplex : specified Duplex 
  595 Collate : specified Collate
  596 OutputOrder : specified OutputOrder
  597 EvenDuplex : specified cupsEvenDuplex
  598 pages : number of pages
  599 number_up : specified number-up
  600 
  601 device_copies : Copies passed to the printer
  602 device_duplex : Duplex passed to the printer
  603 device_collate : Collate passed to the printer
  604 device_outputorder : OutputOrder passed to the printer
  605 
  606 soft_copies : copies by imagetopdf
  607 
  608 
  609 device_copies = 1;
  610 device_duplex = False;
  611 device_collate = False;
  612 device_outputorder = False;
  613 
  614 if (Copies == 1) {
  615   /* Collate is not needed. */
  616   Collate = False;
  617 }
  618 
  619 if (!Duplex) {
  620   /* EvenDuplex is not needed */
  621   EvenDuplex = False;
  622 }
  623 
  624 
  625 if (Copies > 1 && the printer can handle Copies) device_copies = Copies;
  626 if (Duplex && the printer can handle Duplex) {
  627        device_duplex = True;
  628 } else {
  629    /* imagetopdf cannot handle Duplex */
  630 }
  631 if (Collate && the printer can handle Collate) device_collate = True;
  632 if (OutputOrder == Reverse && the printer can handle OutputOrder)
  633              device_outputorder = True;
  634 
  635 if (Collate && !device_collate) {
  636    /* The printer cannot handle Collate.
  637       So imagetopdf handle Copies */
  638               device_copies = 1;
  639 }
  640 
  641 if (device_copies != Copies /* imagetopdf handle Copies */ && Duplex)
  642     /* Make imagetopdf handle Collate, otherwise both paper side may have
  643        same page */
  644               Collate = True;
  645               device_collate = False;
  646 }
  647 
  648 if (Duplex && Collate && !device_collate) {
  649    /* Handle EvenDuplex, otherwise the last page has
  650       the next copy's first page in the other side of the paper. */
  651    EvenDuplex = True;
  652 }
  653 
  654 if (Duplex && OutputOrder == Reverse && !device_outputorder) {
  655    /* Handle EvenDuplex, otherwise the first page's other side of paper
  656       is empty. */
  657    EvenDuplex = True;
  658 }
  659 
  660 soft_copies = device_copies > 1 ? 1 : Copies;
  661 
  662 7.2 JCL
  663 
  664 When you print PDF files to a PostScript(PS) printer, you can specify
  665 device options in PS. In this case, you can write PS commands in a PPD file
  666 like as follows.
  667 
  668 *OpenUI *Resolution/Resolution : PickOne
  669 *DefaultResolution: 600
  670 *Resolution 300/300 dpi: "<</HWResolution[300 300]>>setpagedevice"
  671 *Resolution 600/600 dpi: "<</HWResolution[600 600]>>setpagedevice"
  672 *CloseUI: *Resolution
  673 
  674 However, if options cannot be described in PS file, you can write JCLs
  675 as follows;
  676 
  677 *JCLOpenUI *JCLFrameBufferSize/Frame Buffer Size: PickOne
  678 *DefaultJCLFrameBufferSize: Letter
  679 *OrderDependency: 20 JCLSetup *JCLFrameBufferSize
  680 *JCLFrameBufferSize Off: '@PJL SET PAGEPROTECT = OFF<0A>'
  681 *JCLFrameBufferSize Letter: '@PJL SET PAGEPROTECT = LTR<0A>'
  682 *JCLFrameBufferSize Legal: '@PJL SET PAGEPROTECT = LGL<0A>'
  683 *JCLCloseUI: *JCLFrameBufferSize
  684 
  685 Because PDF cannot specify device options in a PDF file, you have to define
  686 all the device options as JCLs.
  687 
  688 When a printer does not support PS or PDF, you can use Ghostscript (GS).
  689 In this case, you can specify device options like a PS printer.
  690 If you want to use the same printer and same PPD file for both PDF and PS
  691 printing, when you print a PS file, you can specify that GS handles it,
  692 and when you print a PDF file, you can also specify that PDF filters handle
  693 it in the same PPD file. However in this case, previous methods is not
  694 appropriate to specify device options.
  695 
  696 So, "imagetopdf" handles this case as follows;
  697 (In following pseudo program, JCL option is an option specified with JCLOpenUI)
  698 
  699 if (Both JCLBegin and JCLToPSInterpreter are specified in the PPD file) {
  700     output JCLs that marked JCL options.
  701 }
  702 
  703 if (pdftopdfJCLBegin attribute is specified in the PPD file) {
  704     output it's value
  705 }
  706 
  707 if (Copies option is specified in the PPD file) {
  708     mark Number of copies specified
  709 } else if (pdftopdfJCLCopies is specified in the PPD file) {
  710     output JCL specified with JCLCopies
  711 }
  712 
  713 for (each marked options) {
  714     if (pdftopdfJCL<marked option's name> is specified in the PPD file) {
  715 	output it's value as a JCL
  716     } else if (pdftopdfJCLBegin attributes is specified in the PPD file) {
  717 	output "<option's name>=<marked choice>;" as a JCL
  718     }
  719 }
  720 output NEWLINE
  721 
  722 Thus, if you want to use both PDF filters and GS by single PPD file,
  723 what you should do is to add the following line in the PPD file;
  724 
  725 *pdftopdfJCLBegin: "pdfto... jobInfo:"
  726 
  727 Replace "pdfto..." by the name of the actual filter to be called after
  728 pdftopdf.
  729 
  730 Note:
  731   If you specify JCLBegin, you have to specify JCLToPSInterpreter as well.
  732 
  733 Note:
  734   When you need to specify the value which is different from the choosen
  735   value based on the PPD into the jobInfo, you have to specify the values
  736   with the key started by "pdftopdfJCL" string.
  737 
  738   For example, if the page size is defined in a PPD file as following;
  739 
  740   *OpenUI *PageSize/Page Size: PickOne
  741   *DefaultPageSize: A4
  742   *PageSize A4/A4:
  743   *PageSize Letter/US Letter:
  744   *CloseUI: *PageSize
  745 
  746   if you choose the page size "Letter", the string "PageSize=Letter;" is
  747   added to jobInfo. On the other hand, if the driver requires the different
  748   value for the "Letter" size, for instance driver requires "PS=LT;"
  749   instead of "PageSize=Letter;" as the jobInfo value, the PPD file has to
  750   be defined as following;
  751 
  752   *OpenUI *PageSize/Page Size: PickOne
  753   *DefaultPageSize: A4
  754   *PageSize A4/A4:
  755   *pdftopdfJCLPageSize A4/A4: "PS=A4;"
  756   *PageSize Letter/US Letter:
  757   *pdftopdfJCLPageSize Letter/US Letter: "PS=LT;"
  758   *CloseUI: *PageSize
  759 
  760 7.3 Temporally files location
  761 
  762 "imagetopdf" creates temporally files if needed. Temporary files are created
  763 in the location specified by TMPDIR environment variable. Default location
  764 is "/tmp".
  765 
  766 
  767 PDFTOPDF
  768 ========
  769 
  770 The pdftopdf filter depends on libqpdf to read and write PDF files.
  771 
  772 It replaces and imitates the pstops filter in the PDF-based workflow.
  773 A similar filter (which can serve as behavior reference)
  774 is called "cgpdftopdf" in OS X (not open source).
  775 
  776 Command line
  777 ------------
  778 
  779 pdftopdf follows the usual CUPS filter calling conventions, i.e.
  780 
  781   pdftopdf <job> <user> <title> <num-copies> <options> [<filename>]
  782 
  783 together with the environment variables "PPD" and "CLASSIFICATION".
  784 
  785 When omitting <filename>, "pdftopdf" reads a PDF file from stdin.
  786 Internally this will write the data to a temporary file, because
  787 the PDF format cannot be processed in a streaming fashion.
  788 
  789 <options> are delimited by space; boolean type CUPS options can be set
  790 by only adding the option key, other types are provided as
  791 pairs of key and value, <key>=<value>.
  792 
  793 pdftopdf processes the following standard command-line and/or PPD options:
  794 
  795 Copies      # ppd will only override, when commandline parameter was 1
  796 fitplot / fit-to-page / ipp-attribute-fidelity
  797 landscape / orientation-requested
  798 PageSize / page-size / MediaSize / media-size
  799 page-left / page-right / page-bottom / page-top
  800 media-top-margin / media-left-margin / media-right-margin / media-bottom-margin
  801 Duplex / JCLDuplex / EFDuplex / JD03Duplex / sides
  802 number-up / number-up-layout
  803 page-border
  804 OutputOrder / OutputBin / DefaultOutputOrder / page-delivery
  805 page-label
  806 page-set
  807 page-ranges
  808 MirrorPrint / mirror
  809 emit-jcl
  810 position
  811 Collate / multiple-document-handling / sheet-collate
  812 cupsEvenDuplex
  813 cupsManualCopies  # via ppd
  814 
  815 Additional (non-standard) options
  816 ---------------------------------
  817 
  818 1) Booklet printing
  819 
  820   booklet=Off/On/Shuffle-Only
  821 
  822 "On" also tries to set DuplexTumble (two-sided-short-edge) and forces number-up=2
  823 
  824   booklet-signature=(multiple of 4, or default: -1 to use "all pages")
  825 
  826 2) Page autorotate
  827 
  828 pdftopdf automatically rotates pages to the same orientation,
  829 instead of (e.g. fitplot) scaling them down unrotated.
  830 This behavier can be controlled by
  831 
  832   pdfAutorotate / nopdfAutorotate
  833 
  834 Specifically, if a PDF file contains pages with page width greater than
  835 page height (a landscape page), such pages are automatically rotated
  836 anticlockwise by 90 degrees, unless the PPD file specifies
  837 "*LandscapeOrientation: Minus90". In this case, clockwise rotation is used.
  838 To turn off the feature on a job-by-job basis use
  839 
  840   lp -d <print_queue_name> -o nopdfAutorotate <document>
  841 
  842 On a per-queue basis use
  843 
  844   -o nopdfAutorotate-default
  845 
  846 as an option to lpadmin.
  847 
  848 When the 'landscape' or 'orientation-requested=4' (or =5) option of CUPS is
  849 given, the pdfAutorotate processing will adjust and accordingly rotate the
  850 non-landscape pages are rotated instead.
  851 
  852 Note: Some pages might end up 180 degree rotated (instead of 0 degree).
  853 Those should probably be rotated manually before binding the pages together.
  854 
  855 3) Method of flattening interactive PDF forms and annotations.
  856 
  857 Some PDF files (like application forms) contain interactive forms
  858 which the user can fill in inside a PDF viewer like evince. The filled
  859 in data is not integrated in each page of the PDF file but stored in
  860 an extra layer. Due to this the data gets lost when applying
  861 manipulations like scaling or N-up to the pages. To prevent the loss
  862 of the data pdftopdf flattens the form before doing the
  863 manipulations. This means the PDF will be converted into a static PDF
  864 file with the data being integral part of the pages.
  865 
  866 The same flattening is needed for annotations in PDF files.
  867 
  868 By default the actual flattening work is done by QPDF, as QPDF is also
  869 doing everything else in pdftopdf. This way no external utilities need
  870 to be called and so extra piping between processes and extra PDF
  871 interpreter runs are avoided which makes the filtering process faster.
  872 
  873 As we did not test the new QPDF-based form-flattening with thousands
  874 of PDF files yet and it has not been available to actual users yet it
  875 is possible that there are still some bugs. To give users a
  876 possibility to work around possible bugs in QPDF's form flattening, we
  877 have introduced an option to get back to the old flattening by the
  878 external tools pdftocairo or Ghostscript.
  879 
  880 The selection of the method is done by the "pdftopdf-form-flattening"
  881 option, setting it to "auto", "qpdf", "pdftocairo", "ghostscript",
  882 "gs", "internal" or "external":
  883 
  884 Per-job:           lpr -o pdftopdf-form-flattening=pdftocairo ...
  885 Per-queue default: lpadmin -p printer -o pdftopdf-form-flattening-default=gs
  886 Remove default:    lpadmin -p printer -R pdftopdf-form-flattening-default
  887 
  888 By default, pdftopdf uses QPDF if the option is not supplied, also the
  889 settings "auto" and "internal" make QPDF being used. "external"
  890 auto-selects from the two external utilities, trying pdftocairo at
  891 first and on failure Ghostscript. If the selected utility fails, the
  892 form stays unflattened and so the filled in data will possibly not get
  893 printed.
  894 
  895 Native PDF Printer / JCL Support
  896 --------------------------------
  897 
  898 Note that for most modern native PDF printers JCL is not needed any
  899 more as they are controlled via IPP. For these the PPD files get
  900 auto-generated by the support of CUPS and cups-filters for driverless
  901 IPP printing.
  902 
  903 pdftopdf will emit JCL when provided with a PPD file that includes the
  904 "*JCLToPDFInterpreter:" keyword.
  905 
  906 This enables for hardware copy generation and device collate; e.g. with PJL:
  907 
  908 *JCLBegin:           "<1B>%-12345X@PJL JOB<0A>"
  909 *JCLToPDFInterpreter: "@PJL ENTER LANGUAGE = PDF <0A>"
  910 *JCLEnd:             "<1B>%-12345X@PJL EOJ <0A><1B>%-12345X"
  911 
  912 For each marked option, the prefixed "pdftopdfJCL<option name>" keywords
  913 can also be used to send raw JCL strings for that option.
  914 These keywords also include *pdftopdfJCLBegin and *pdftopdfJCLCopies,
  915 This allows the use of the same PPD for PDF- and PS-based workflows,
  916 as pdftopdfJCL... will not be read in the PS case.
  917 
  918 When the PPD contains the "Copies" keyword, pdftopdf will detect the use
  919 of PJL and has special code which adds "@PJL SET COPIES=...",
  920 or "@PJL SET QTY=...", respectively.
  921 
  922 Other JCL code can be injected via "*JCLOpenUI: ..." ... "*JCLCloseUI: ...".
  923 
  924 Special PDF comments
  925 --------------------
  926 
  927 pdftopdf adds comments to the pdf preamble that might esp. be of use
  928 to subsequent filters, e.g.
  929 
  930   % This file was generated by pdftopdf
  931   %%PDFTOPDFNumCopies : 1
  932   %%PDFTOPDFCollate : false
  933 
  934 The "NumCopies" and "Collate" values refer to the expected device/hardware
  935 copies, i.e. when pdftopdf's soft-copy generation did not handle this options.
  936 
  937 Limitations
  938 -----------
  939 
  940 pdftopdf does not support functions that are not related to printing
  941 features, including interactive features and document interchange features.
  942 Many of these operators and sections are just ignored.
  943 Some of these may be output, but those functions are not assured.
  944 
  945 Most notable is the use of AcroForms; their content will not be printed
  946 if any non-trivial processing by pdftopdf is involved (e.g. "fitplot").
  947 This only occurs when a file is printed directly, e.g. by "lpr".
  948 
  949 Usual PDF viewer applications (xpdf, evince, acroread, ghostscript, ...)
  950 will hardcopy the form content into printable pdf operations,
  951 when choosing to print such a document.
  952 
  953 Known issues
  954 ------------
  955 
  956 - Borders, esp. in the "number-up=1 fitplot=false"-case might be drawn
  957   at incorrect locations.
  958 
  959 - JCL documentation is sparse.
  960   The imagetopdf or old pdftopdf documentation contains a tad more information.
  961 
  962 - Missing AcroForm-content might surprise users printing PDF files directly /
  963   from the command-line (see the Limitations section, above).
  964 
  965 License
  966 -------
  967 
  968 pdftopdf is released under the MIT license.
  969 
  970 The required libqpdf is available under version 2.0 of the Apache License,
  971 e.g. here: https://github.com/qpdf/qpdf
  972 
  973 
  974 TEXTTOPDF
  975 =========
  976 
  977 This implements a texttopdf filter, and is derived from cups' texttops.
  978 
  979 To configure:
  980 -------------
  981 
  982 - texttopdf uses CUPS_DATADIR/charset/pdf.utf-8 for font configuration
  983   (when utf-8 was requested as charset). The font names given there are 
  984   used as fontconfig selectors; the best matching font, that is both 
  985   monospaced and in a supported format (TTC, TTF or OTF) will then be used.
  986 
  987 - As a special exception, all fontnames that start with a '.' or '/' are
  988   considered filenames, and fontconfig is skipped; the name is used directly
  989   for loading the font file.
  990 
  991 - Implementation note: TrueType Collections (.TTC) are internally handled
  992   by appending '/' and the index of the font inside the collection to 
  993   the filename (e.g. to use the second font of uming.ttc, the filename 
  994   uming.ttc/1 must be given to the fontembed-library).
  995   By appending the index-field returned from fontconfig, this is completely
  996   transparent to the user (but currently not widely tested).
  997 
  998 - You may look at the two examples: pdf.utf-8.simple and pdf.utf-8.heavy.
  999 
 1000 To use:
 1001 -------
 1002 
 1003 The filter is called just like any other cups filter. Have a
 1004 look at test.sh for example. 
 1005 
 1006 Known Issues
 1007 ------------
 1008 
 1009  - Text extraction does not work (at least for pdftotext from xpdf)
 1010    for the resulting pdfs.
 1011 
 1012  - OTF(CFF) embedding currently does not subset the fonts.
 1013 
 1014  - Text wrapping in pretty-printing mode does not respect double-wide
 1015    characters (CJK), and thus produce wrong results (wrap too late)
 1016    for lines where they occur.  The fix is not trivial, since all the
 1017    pretty-printing processing is done without knowledge of / prior to
 1018    the font configuration (which is where single or double width
 1019    code-ranges are specified).
 1020 
 1021  - The hebrew example in test5.pdf shows one of our limitations:
 1022    Compose glyphs are not composed with the primary glyph but printed
 1023    as separate glyphs.
 1024 
 1025 Further Infos
 1026 -------------
 1027 
 1028 Font embedding is handled by libfontembed in the filter/fontembed
 1029 subdirectory.
 1030 
 1031 Please report all bugs to
 1032 
 1033 https://github.com/OpenPrinting/cups-filters/issues
 1034 
 1035 or to
 1036 
 1037 https://bugs.linuxfoundation.org/
 1038 
 1039 (product "OpenPrinting", component "cups-filters").
 1040 
 1041 
 1042 PDFTORASTER
 1043 ===========
 1044 
 1045 1. INTRODUCTION
 1046 
 1047 "pdftoraster" is a filter for CUPS. It reads PDF files, convert it and
 1048 output CUPS raster.
 1049 
 1050 "pdftoraster" does not support functions that are not related to printing
 1051 features, including interactive features and document interchange features.
 1052 Many of these operators and sections are just ignored.
 1053 Some of these may be output, but those functions are not assured.
 1054 Encryption feature is not supported.
 1055 
 1056 2. LICENSE
 1057 
 1058 Almost all source files are under MIT like license. However,
 1059 "pdftoraster" links some "poppler" libraries, and these files are
 1060 under GNU public license.  See copyright notice of each file for
 1061 details.
 1062 
 1063 3. COMMAND LINE
 1064 
 1065 "pdftoraster" is a CUPS filter, and the command line arguments, environment
 1066 variables and configuration files are in accordance with the CUPS filter
 1067 interface.
 1068 
 1069 pdftoraster <job> <user> <title> <num-copies> <options> [<filename>]
 1070 
 1071 "pdftoraster" ignores <job> and <user>.
 1072 <title> is appended into the PDF dictionary as /Title.
 1073 <num-copies> specifies the number of document copies.
 1074 <options> is a CUPS option list.
 1075 <filename> is an input PDF file name.
 1076 
 1077 When omit the <filename>, "pdftoraster" reads a PDF file from the stdin,
 1078 and save it as a temporary file.
 1079 
 1080 4. ENVIRONMENT VARIABLES
 1081 
 1082 This program refers the following environment variable;
 1083    PPD:  PPD file name of the printer.
 1084 
 1085 5. COMMAND OPTIONS
 1086 
 1087 See CUPS documents for details.
 1088 
 1089 6. INFORMATION FOR DEVELOPERS
 1090 
 1091 Following information is for developers, not for driver users.
 1092 
 1093 6.1 Options handled by a printer or "pdftoraster"
 1094 
 1095 "pdftopdf" outputs the following special comments from the 4th line in the
 1096 created PDF data.
 1097 
 1098 %%PDFTOPDFNumCopies : <copies> --- <copies> specified Number of Copies
 1099 %%PDFTOPDFCollate : <collate> --- <collate> is true or false
 1100 
 1101 "pdftoraster" overrides the command line options by above two option's values.
 1102  
 1103 6.2 Temporally files location
 1104 
 1105 "pdftoraster" creates temporally files if needed. Temporary files are created
 1106 in the location specified by TMPDIR environment variable. Default location
 1107 is "/tmp".
 1108 
 1109 
 1110 URFTOPDF
 1111 ========
 1112 
 1113 "urftopdf" is a filter to convert Apple's proprietary URF raster
 1114 format into PDF. URF raster is generated by some iOS applications when
 1115 printing via Airprint, so this filter provides a more complete support
 1116 for AirPrint clients. Note that it is not clear whether nowadays all
 1117 iOS applications send PDF and not URF any more. Also the filter does
 1118 not support all variants of URF format so the URF support is most
 1119 probably incomplete.
 1120 
 1121 Apple does not provide any official documentation of the format but there is
 1122 already some reverse engineering done. A description of the format as far as it
 1123 got found out and two sample files can be found here:
 1124 
 1125 https://github.com/AlanQuatermain/unirast
 1126 
 1127 An actual implementation of an urftopdf filter is here:
 1128 
 1129 https://github.com/superna9999/urftopdf
 1130 
 1131 This original version uses libharu and to avoid an extra dependency
 1132 the filter coming with this package is converted to use libqpdf
 1133 instead (the same library as pdftopdf uses).
 1134 
 1135 License: GNU General Public License version 3 or any newer version
 1136 
 1137 
 1138 TEXTTOTEXT
 1139 ==========
 1140 
 1141 This is a special filter for text-only printers (e. g. line printers,
 1142 daisy-wheel printers, POS printers, ...) or for using printers in
 1143 their text mode (e. g. dot-matrix printers or otherwise unsupported
 1144 printers). It takes plain text (UTF-8-encoded as this is standard with
 1145 CUPS) and not PDF as input.
 1146 
 1147 The texttotext filter replaces the former textonly filter.
 1148 
 1149 It is for the following use cases:
 1150 
 1151 - Using text-only printers, like line printers or daisy-wheel
 1152   printers. Note that only text can get printed in the way the printer
 1153   is designed. No support for graphics printing tricks like ASCII art
 1154   or printing pixels with the period character.
 1155 
 1156 - Fast and less resource-consuming text printing with dot-matrix
 1157   printers using the printer's text mode instead of converting the
 1158   text to PDF and printing the PDF in the printer's graphics mode,
 1159   which is slow, loud, and consumes much more ink.
 1160 
 1161 - POS printing. POS printers often print only text on roll paper. This
 1162   filter has a non-paginated mode which prints continuously, ignoring
 1163   page height definitions.
 1164 
 1165 The filter has the following features:
 1166 
 1167 - Conversion of UTF-8 to most printer's encodings.
 1168 
 1169 - To each page size a number of lines and columns is assigned, after that
 1170   you only need to select the size of the paper in use.
 1171 
 1172 - At end of page you can optionally send a Form Feed or let the filter fill
 1173   up the rest of the page with blank lines.
 1174 
 1175 - New lines can be initiated by Line Feed, Carriage Return, or both.
 1176 
 1177 - Adjustable margins.
 1178 
 1179 - Adjustable width for tab stops.
 1180 
 1181 - Pagination can be turned off for roll paper or continuous printing in
 1182   general.
 1183 
 1184 - Wrapping or truncation of long lines
 1185 
 1186 - Support for most of CUPS' page management options (only with
 1187   pagination turned on): page-ranges, page-set, output-order, collate,
 1188   multiple copies.
 1189 
 1190 Setting up the printer
 1191 
 1192 In the printer setup tool select the "Generic Text-Only Printer" (with
 1193 lpadmin use "-m drv:///cupsfilters.drv/textonly.ppd"), then under the
 1194 "Installable Options" adjust the following:
 1195 
 1196 - Which page sizes to use and how many lines and columns the printer
 1197   is capable to print on them. The default setting for lines and
 1198   columns assume 6 lines per inch and 10 columns per inch.
 1199 
 1200 - Whether to send a Form Feed character after each page. Sending a
 1201   Form Feed is highly recommended to get the content of each page
 1202   exactly onto the desired sheet. If the printer does not support Form
 1203   Feed characters, turn them off and make sure that you have adjusted
 1204   the correct number of lines for each page size, as the printer is
 1205   advancing pages by filling up the rest of the paper with blank
 1206   lines.
 1207 
 1208 - How the printer advancs to a new line. Most printers require both
 1209   Crriage Return and Line Feed (the DOS/Windows standard), but some
 1210   would also work with either Carriage Return or Line Feed.
 1211 
 1212 - The printer's encoding: Most text and dot-matrix printers (usually
 1213   older devices) do not understand CUPS' standard encoding UTF-8 but
 1214   instead, the use a simpler encoding (where each character is
 1215   represented by one byte). ASCII should always work, but does not
 1216   support letters with accents. So check the printer's manual what is
 1217   supported. You cannot only use the encodings suggested by the PPD
 1218   file, but any one-byte-per-character encoding which the "iconv"
 1219   utility supports (see "iconv --list" for a list of encodings).
 1220 
 1221 Also note that text-only and dot-matrix printers often have a DIP
 1222 switch block which allows for some hardware configuration, like
 1223 newline characters, length of page, input encoding, ...
 1224 
 1225 Options of the texttotext filter:
 1226 
 1227 To be usually used when sending a job:
 1228 
 1229 PageSize: Paper format to be used. Make sure that the number of lines
 1230 and columns printable on each paper size are correctly adjusted with
 1231 the appropriate setup option. The page height is ignore when
 1232 pagination is turned off. Possible values: Letter, Legal, Tabloid,
 1233 Ledger, A4, A3, FanFoldGerman, FanFoldGermanLegal, 11x14Rotated,
 1234 LegalRotated, Custom1, Custom2, Custom3
 1235 
 1236 OverLongLines: What to do with lines longer that the width of the
 1237 page: Truncate: Simply drop the extra characters; WrapAtWidth
 1238 (default): Continue the line in the next line on the paper; WordWrap:
 1239 As WrapAtWidth, but do not cut in the middle of a word.
 1240 
 1241 TabWidth: Width of a tab stop. Can be any positive number.
 1242 
 1243 Pagination: On: Text is divided in pages depending on the page size
 1244 selection, with each page having the user-selected margins,
 1245 recommended for sheet paper; Off: Text is printed continuously,
 1246 ignoring page breaks and the height and upper and lower margins of the
 1247 destination page size, recommended for roll paper, POS, long lists on
 1248 continuous paper, ... Note that with pagination turned off, multiple
 1249 copies, collate, page-ranges, page-set, and output-order are not
 1250 supported and therefore ignored.
 1251 
 1252 page-left, page-right, page-top, page-bottom: Width of the margins
 1253 left blank, counted in lines or columns. Top and bottom margins are
 1254 ignored when pagination is turned off. Can be any positive number or
 1255 zero for no margin.
 1256 
 1257 To be usually used when setting up the printer:
 1258 
 1259 PrinterEncoding: The printer's character encoding (code page). Any
 1260 encoding which the iconv utility can generate (see "iconv --list") and
 1261 which uses only one byte per character can be used. This should
 1262 support practically any printer which is capable of printing
 1263 text. ASCII is the default setting. See the printer's manual for the
 1264 correct encoding to use.
 1265 
 1266 NewlineCharacters: The characters sent on the end of a line, LineFeed
 1267 (LF), Crriage Return (CR), or both Carriage Return and Line Feed
 1268 (CRLF). Default is CRLF as most printers require this.
 1269 
 1270 SendFF: On: Send a Form Feed after each page, so that printer changes
 1271 to the next sheet. Off: Do not send Form Feeds. To advance to the next
 1272 page blank lines are printed to fill up the page (requires the number
 1273 of limes for the selected page size correctly being set). When
 1274 pagination is off, Form Feeds are never sent.
 1275 
 1276 LetterAvailable, LegalAvailable, TabloidAvailable, LedgerAvailable,
 1277 A4Available, A3Available, FanFoldGermanAvailable,
 1278 FanFoldGermanLegalAvailable, 11x14RotatedAvailable,
 1279 LegalRotatedAvailable, Custom1Available, Custom2Available,
 1280 Custom3Available: On: Paper of this size is available; Off: This paper
 1281 size is not available.
 1282 
 1283 LetterNumLines, LegalNumLines, TabloidNumLines, LedgerNumLines,
 1284 A4NumLines, A3NumLines, FanFoldGermanNumLines,
 1285 FanFoldGermanLegalNumLines, 11x14RotatedNumLines,
 1286 LegalRotatedNumLines, Custom1NumLines, Custom2NumLines,
 1287 Custom3NumLines: Maximum number of text lines fitting on the paper
 1288 size. Default value is selected assuming 6 lines per inch. Can be any
 1289 positive number.
 1290 
 1291 LetterNumColumns, LegalNumColumns, TabloidNumColumns,
 1292 LedgerNumColumns, A4NumColumns, A3NumColumns, FanFoldGermanNumColumns,
 1293 FanFoldGermanLegalNumColumns, 11x14RotatedNumColumns,
 1294 LegalRotatedNumColumns, Custom1NumColumns, Custom2NumColumns,
 1295 Custom3NumColumns: Maximum number of columns (characters) fitting on
 1296 the paper size. Default value is selected assuming 10 characters per
 1297 inch. Can be any positive number.
 1298 
 1299 Standard CUPS options supported:
 1300 
 1301 page-ranges, page set, output-order, collate
 1302 
 1303 Note that these options and multiple copies are ignored when
 1304 pagination is turned off.
 1305 
 1306 
 1307 BEH - Backend Error Handler wrapper backend
 1308 ===========================================
 1309 
 1310 A wrapper for CUPS backends to make error handling more configurable
 1311 
 1312 Usually, if a CUPS backend exits with an error status other than zero
 1313 (for example if a printer is not turned on or not reachable on the
 1314 network), CUPS disables the print queue and one can only print again
 1315 if a system administrator re-enables the queue manually. Even
 1316 restarting CUPS (or rebooting) does not re-enable disabled queues.
 1317 
 1318 For system administrators this can get annoying, for newbie users who
 1319 are not aware of this problem it looks like that CUPS is severely
 1320 broken. They remove and re-install print queues, getting on the nerves
 1321 of distro install support, people, or even switch back to a
 1322 proprietary operating system.
 1323 
 1324 Nowadays CUPS allows some configurability to avoid this, setting the
 1325 Error Policy to "retry-job", but this does not allow to retry for
 1326 infinitely many times and generally does not allow to change the
 1327 number of repetitions. It is also not possible to simply drop the job
 1328 without disabling the queue when CUPS gives up repeating the job.
 1329 
 1330 This script makes the handling of such backend errors more
 1331 configurable, so that the problem can easily be worked around. The new
 1332 possibilities are:
 1333 
 1334  - Let queues simply not being disabled. Simple approach, but job gets
 1335    lost.
 1336 
 1337  - Repeat a given number of times.
 1338 
 1339  - Repeat infinitely often, until the job gets finally through. This
 1340    is the standard of LPRng, and it eliminates loss of the job.
 1341 
 1342  - The interval between two attempts to run the backend can also be
 1343    configured.
 1344 
 1345  - Configuration is done independently for each print queue. So local
 1346    printers and network printers can be treated differently.
 1347 
 1348 
 1349 Usage: 
 1350 
 1351 Activate "beh" for your print queue(s) with command(s) like this:
 1352 
 1353 lpadmin -p <queue name> -E -v beh:/<dd>/<att>/<delay>/<originaluri>
 1354 
 1355 with 
 1356   <queue name>:     The name of your print queue
 1357   <dd>:             Don't Disable, if "1", beh always exits with zero
 1358                     status, so the queue gets never disabled when the
 1359                     original backend exits with an error. "0" carries
 1360                     the error status of the last call of the backend
 1361                     (after <att> retries) on to CUPS, so the queue
 1362                     usually gets disabled.
 1363   <att>:            Attempts, number of attempts to recall the backend
 1364                     in case of an error. "0" means infinite retries. In
 1365                     this case <dd> gets meaningless.
 1366   <delay>:          Delay between two attempts to call the beckend, to
 1367                     be given in seconds and as an integer number.
 1368                     Meaningless if <att> is one.
 1369   <originaluri>:    The original URI, which your queue had before. Can 
 1370                     be determined with "lpstat -v".
 1371 
 1372 All parameters, especially, <dd>, <att>, and <delay> have always to be
 1373 specified, even if one of them is meaningless due to the setting of
 1374 the others.
 1375 
 1376 beh works with every backend except the "hp" backend of HPLIP, as the
 1377 "hp" backend repeats failed jobs by itself.
 1378 
 1379 Example URIs:
 1380 
 1381 beh:/1/3/5/socket://printer:9100
 1382 
 1383   On the network printer with host name "printer" it is tried to
 1384   access 3 times with 5 second delays between the attempts. If the job
 1385   still fails, the queue is not disabled (and the job discarded).
 1386 
 1387 beh:/0/10/60/socket://printer:9100
 1388 
 1389   Retry 10 times in one minute intervals, disable the queue when still
 1390   not succeeding.
 1391 
 1392 beh:/1/0/60/usb://Brother/HL-5040%20series
 1393 
 1394   On a Brother HL-5040 on the USB try infinitely often until the
 1395   printer comes back, in intervals of one minute. This way the job
 1396   does not get lost when the printer is turned off and one can
 1397   intendedly delay printing by simply switching off the printer. The
 1398   ideal configuration for desktop printers and/or home users.
 1399 
 1400 Originally this backend was written in Perl and part of the
 1401 foomatic-filters package. It was not overtaken into cups-filters
 1402 together with foomatic-rip to avoid the introduction of a dependency
 1403 on Perl. Now it has been re-written in C and so it can be part of
 1404 cups-filters without introducing new dependencies.
 1405 
 1406 
 1407 BRAILLE EMBOSSING
 1408 =================
 1409 
 1410 cups-filters also provides filters and drivers for braille
 1411 embossers. It supports:
 1412 
 1413 - Text on all kinds of embossers with generic support
 1414 - Text and graphics on the Index V3 embossers and above.
 1415 
 1416 This is configured in CUPS just like any printer. Options can then be configured
 1417 in the standard printer panel, or passed as -o options to the lp command.
 1418 
 1419 
 1420 ------------
 1421 Text support
 1422 ------------
 1423 
 1424 Text can be embossed either with no translation on the computer side (the
 1425 embosser will translate), or with translation on the computer side (thanks to
 1426 liblouis). It is a matter of running
 1427 
 1428 lp file.txt
 1429 
 1430 or even
 1431 
 1432 lp file.html
 1433 lp file.odt
 1434 lp file.doc
 1435 lp file.rtf
 1436 lp file.docx
 1437 lp file.pdf
 1438 
 1439 Important: it is really preferrable to directly print the document files
 1440 themselves, and not a pdf output, or printing from the application (which
 1441 would first convert to pdf). That way, the braille conversion will have the
 1442 proper document structure (paragraphs, titles, footnotes, etc.) to produce good
 1443 quality.
 1444 
 1445 
 1446 --------------------
 1447 Vector Image support
 1448 --------------------
 1449 
 1450 Vector images can be embossed by converting them to braille dots.
 1451 
 1452 This needs the inkscape package installed. Various input formats are then
 1453 supported: .svg, .fig, .wmf, .emf, .cgm, .cmx
 1454 
 1455 The conversion assumes that the input is black-on-white. If it is
 1456 white-on-black, the -o Negate option can be used.
 1457 
 1458 This image support is preferred over the generic image support described below,
 1459 which has to reconstruct lines to be embossed.
 1460 
 1461 
 1462 -------------
 1463 Image support
 1464 -------------
 1465 
 1466 Images can be embossed by converting them to braille dots.
 1467 
 1468 The orientation of the image can be controlled. By default it will be rotate to
 1469 fit the image orientation, i.e. it will be rotate by 90 degree if it is wider
 1470 than high and the paper is higher than wide, or if vice-versa. Other rotation
 1471 modes are provided.
 1472 
 1473 By default, the image will be resized to fit the size of the paper. Disabling
 1474 the resize (fitplot set to No) will crop the image to the paper size. This is
 1475 useful for instance when a carefully-drawn image was designed especially for
 1476 embossing, and thus its pixels should exactly match with braille dots. In such
 1477 case, edge detection should very probably be disabled too.
 1478 
 1479 The image can be processed for edge detection. When no processing is done (edge
 1480 detection is configured to "None"), the dark pixels are embossed if the Negate
 1481 option is off, or the light pixels are embossed if the Negate option is on. When
 1482 edge processing is done, only the edges of the images will be embossed. The
 1483 Basic and the Canny algorithms bring differing results. The Basic algorithm
 1484 can be tuned thanks to the edge factor only. The Canny algorithm can also be
 1485 tuned: increasing the Upper value will reduce the amount of detected edges (and
 1486 vice-versa), increasing the Lower value will reduce the lengths of the detected
 1487 edges (and vice-versa). The Radius and Sigma parameter control the blurring
 1488 performed before edge detection, to improve the result; the Radius parameter
 1489 controls how large blurring should be performed, setting it to zero requests
 1490 autodetection; the Sigma parameter determines how strongly blurring should be
 1491 performed.
 1492 
 1493 A lot of images formats are support, so one can just run
 1494 
 1495 lp file.png
 1496 lp file.gif
 1497 lp file.jpg
 1498 ...
 1499 
 1500 Here are complete examples for controlling the processing (all options can be
 1501 omitted, the default values are shown here):
 1502 
 1503 Emboss the image without edge detection, as black on white or white on black:
 1504 
 1505 lp -o "Edge=None" file.png
 1506 lp -o "Edge=None Negate" file.png
 1507 
 1508 Emboss the image with edge detection, the default tuning parameters are set
 1509 here:
 1510 
 1511 lp -o "Edge=Edge EdgeFactor=1" file.png
 1512 lp -o "Edge=Canny CannyRadius=0 CannySigma=1 CannyLower=10 CannyUpper=30" file.png
 1513 
 1514 Emboss the image as it is, without any resize or edge detection, as black on
 1515 white or white on black:
 1516 
 1517 lp -o "nofitplot Edge=None" file.png
 1518 lp -o "nofitplot Edge=None Negate" file.png
 1519 
 1520 ------------------------
 1521 Generic embosser support
 1522 ------------------------
 1523 
 1524 It should be possible to make all embossers use the generic driver. For this to
 1525 work, one has to:
 1526 
 1527 - configure the embosser itself so that it uses an MIT/NABCC/BRF braille table
 1528 - add in CUPS a printer with the "Generic" manufacturer and "Braille embosser"
 1529   model
 1530 - configure CUPS options according to the embosser settings, so that CUPS knows
 1531   the page size, braille spacing, etc.
 1532 
 1533 The generic driver can emboss text, as well as images, but images will probably
 1534 be distorted by the Braille interline spacing.
 1535 
 1536 
 1537 -----------------------
 1538 Index embossers support
 1539 -----------------------
 1540 
 1541 Supported models:
 1542 
 1543 Basic-S V3/4
 1544 Basic-D V3/4
 1545 Everest-D V3/4
 1546 4-Waves PRO V3
 1547 4X4 PRO V3
 1548 Braille Box V4
 1549 
 1550 Index V3 embosser support has been well tested. It supports both text and
 1551 graphics mode.  Embossers with firmware 10.30 and above can be easily configured
 1552 from CUPS (paper dimension, braille spacing, etc.).
 1553 
 1554 Index V4 embosser support has not been tested, but is very close to V3 support,
 1555 so it is probably working fine already.  Feedback would be very welcome.
 1556 
 1557 To connect an Index embosser through Ethernet, gather its IP adress, select the
 1558 "AppSocket/HP JetDirect" network printer protocol, and set
 1559 socket://the.embosser.IP.address:9100 as Connection URL.
 1560 
 1561 The density of dots for images can easily be chosen from the command line, for
 1562 instance:
 1563 
 1564 lp -o "GraphicDotDistance=160" file.png
 1565 
 1566 to select 1.6mm dots spacing
 1567 
 1568 Troubleshooting: if your embosser starts every document with spurious
 1569 "TM0,BM0,IM0,OM0" or "TM0,BI0", your embosser is most probably still using an
 1570 old 10.20 firmware.  Please either reflash the embosser with a firmware version
 1571 10.30 or above, or select the 10.20 firmware version in the "index" panel of the
 1572 cups printer options.
 1573 
 1574 ----------------------
 1575 Braille output options
 1576 ----------------------
 1577 
 1578 The output can be finely tuned from the standard printing panel, or from the
 1579 command-line, the following example selects translation tables for French and
 1580 Greek, with 2.5mm dot spacing and 5mm line spacing. All options can be omitted,
 1581 the default values are shown here.
 1582 
 1583 lp -o "LibLouis=fr-fr-g1 LibLouis2=gr-gr-g1 TextDotDistance=250 LineSpacing=500" file.txt
 1584 
 1585 
 1586 ---------------------------------
 1587 Reworking output before embossing
 1588 ---------------------------------
 1589 
 1590 One may want to check and modify the .brf or .ubrl output before sending it to
 1591 the embosser.  This can be achieved by first generating the .brf file:
 1592 
 1593     /usr/sbin/cupsfilter -m application/vnd.cups-brf -p /etc/cups/ppd/yourprinter.ppd yourdocument.txt > ~/test.brf
 1594 
 1595 One can choose a ppd file and additionally pass -o options to control the
 1596 generated output. One can then modify the .brf file with a text editor. One can
 1597 then emboss it:
 1598 
 1599     lp -o document-format=application/vnd.cups-brf ~/test.brf
 1600 
 1601 
 1602 The same can be achieved for images:
 1603 
 1604     /usr/sbin/cupsfilter -m image/vnd.cups-ubrl -p /etc/cups/ppd/yourprinter.ppd yourimage.png > ~/test.ubrl
 1605 
 1606     lp -o document-format=image/vnd.cups-ubrl ~/test.ubrl
 1607 
 1608 
 1609 ---------------
 1610 BRF file output
 1611 ---------------
 1612 
 1613 One can generate BRF files by adding a virtual BRF printer.
 1614 
 1615 When creating it in the cups interface, choose the CUPS-BRF local printer,
 1616 select the Generic maker, and choose the Generic Braille embosser model.
 1617 
 1618 Printing to the resulting printer will generate a .brf file in a BRF
 1619 subdirectory of the home directory.
 1620 
 1621 
 1622 ----------------
 1623 UBRL file output
 1624 ----------------
 1625 
 1626 One can generate Unicode braille files, not useful for embossing, but which can
 1627 be easily looked at by sighted people to check for the output.
 1628 
 1629 In the cups interface, create a printer with the CUPS-BRF local printer,
 1630 the Generic maker, and choose the Generic UBRL generator model.
 1631 
 1632 Printing to the resulting printer will generate a .brf file in a BRF
 1633 subdirectory of the home directory.
 1634 
 1635 
 1636 ----------------------------
 1637 Remark about the source code
 1638 ----------------------------
 1639 
 1640 The file filter/braille/drivers/index/ubrlto4dot.c is used to generate
 1641 the translation table in
 1642 filter/braille/drivers/index/imageubrltoindexv[34]. It is included as
 1643 "source code" for these two files, even if actually running the
 1644 generation in the Makefile is more tedious than really useful.
 1645 
 1646 
 1647 ----
 1648 TODO
 1649 ----
 1650 
 1651 - Test whether one wants to negate, e.g. to emboss as few dots as possible
 1652 - textubrltoindex when liblouis tools will be able to emit 8dot braille
 1653