README

README - OpenPrinting CUPS Filters v1.25.0 - 2019-06-06
-------------------------------------------------------

Looking for compile instructions?  Read the file "INSTALL.txt"
instead...


INTRODUCTION

    CUPS is a standards-based, open source printing system developed
    by Apple Inc. for Mac OS® X and other UNIX®-like operating
    systems.  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 is no longer
    maintained by Apple Inc. In addition it contains additional
    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.

    From CUPS 1.6.0 on, this package is required for using printer
    drivers (and also driverless printing) with CUPS under Linux. With
    CUPS 1.5.x and 1.4.x this package can be used optionally to switch
    over to PDF-based printing. In that case some filters are provided
    by both CUPS and this package. Then the filters of this package
    should be used.

    For compiling and using this package CUPS, libqpdf (8.3.0 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 Apple Raster output (used by AirPrint printers) at least CUPS
    2.2.2 is required.

    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 file or PPD-less for them (for
    the latter using a System V interface script to control the filter
    chain, only available for CUPS 2.1.0 and older, clients have to
    IPP-poll the capabilities of the printer and send option settings
    as standard IPP attributes then). 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
==========