Provided by: xorg-docs-core_1.4-5_all bug

NAME

       Xprint  -  The  "X  print  service"  -  a portable, network-transparent
       printing system based on the X11 protocol

SYNOPSIS

       Xprint is a very flexible, extensible, scaleable,  client/server  print
       system  based on ISO 10175 (and some other specs) and the X11 rendering
       protocol.  Using Xprint  an  application  can  search,  query  and  use
       devices like printers, FAX machines or create documents in formats like
       PDF.  In particular, an application can seek a printer, query supported
       attributes  (like paper size, trays, fonts etc.), configure the printer
       device to match it’s needs and print on it like on any other  X  device
       reusing parts of the code which is used for the video card Xserver.

OVERVIEW

       The  "X Print Service" technology allows X rendering to devices such as
       printers and  fax.  Most  of  the  service  is  available  in  the  X11
       technology  stack  as  Xp,  with the remainder in single toolkit stacks
       (e.g. DtPrint for CDE).  Modifications  have  also  been  made  to  the
       LessTif/Motif/Qt technology stacks to support Xprint.

       The Xp portion consists of:

       · Xp Extension for the X-Server (included in the X-Server Xprt)

       · Xp Extension API for the client side (libXp/libXprintUtils)

       · PCL ddx driver that converts core X to native PCL

       · PDF ddx driver that converts core X to native PDF

       · PostScript ddx driver that converts core X to native PostScript

       · Raster  ddx  driver that generates xwd rasters which can be converted
         to PCL, PDF or PostScript rasters

       From an X clients perspective, it can  attach  to  one  of  two  nearly
       identical  X-Servers,  a "Video" X-Server, and a "Print" X-Server which
       has the additional Xp capability but otherwise looks  and  behaves  the
       same.

HOW THE X PRINT SERVICE WORKS

       The  X Print Service expands on the traditional X-Server and Xlib world
       in four ways.

       1.  Most obvious is the use of "print ddx drivers"  instead  of  "video
           ddx  drivers".  While a video ddx driver modifies pixels in a video
           frame buffer,  a  print  ddx  driver  generates  "page  description
           language  (PDL)"  output  (such as PCL, PDF or PostScript) or sends
           the print rendering instructions to a platform-specific  print  API
           (like Win32/GDI).

           Once  a  print ddx driver generates PDL output, it can be sent to a
           spooler such as lp(1) or retrieved  by  the  client  (to  implement
           functionality like "print-to-file").

           Though not currently done, a single X-Server can support both print
           and video ddx drivers.

       2.  Since printers support "paged" output, unlike video, a  portion  of
           the  Xp  Extension  supports APIs to delineate printed output.  For
           example, XpStartPage  and  XpEndPage  tell  the  X-Server  where  a
           physical  page starts and ends in an otherwise continuous stream of
           X rendering primitives. Likewise, XpStartJob and XpEndJob determine
           when  a  collection  of  pages starts and ends.  XpEndJob typically
           causes the generated PDL to be submitted  to  a  spooler,  such  as
           lp(1).

       3.  Since  printers have extensive capabilities, another portion of the
           Xp Extension supports APIs to manipulate "print contexts".

           Once a printer is selected using the  Xp  Extension  API,  a  print
           context  to  represent  it can be created. A print context embodies
           the  printer  selected  -  it  contains   the   printer’s   default
           capabilities,  selectable range of capabilities, printer state, and
           generated output. Some "attributes" within the print context can be
           modified  by  the  user, and the X-Server and print ddx driver will
           react accordingly. For example, the attribute "content-orientation"
           can  be  set  to "landscape" or "portrait" (if the printer supports
           these values - which can be queried using the Xprint API as  well).

       4.  Since  printers  can have "built in" fonts, the Xp Extension in the
           X-Server works with the print ddx drivers to  make  available  (for
           printing only) additional fonts on a per print context basis.

           When  a print context is created and set for a given printer, the X
           font calls may be able to access additional printer  fonts.  To  do
           this  (typically), the X-Server must have access to "printer metric
           files" (.pmf) that describe at minimum the metrics of the built  in
           fonts.

USAGE

       There are three tasks to start the X Print Service:

       1.  configuring the X Print Server,

       2.  starting the X Print Service

       3.  configuring the user session so that clients can find the running X
           Print Service

       The tasks are described in detail below.

SERVER CONFIGURATION

       The X Print Server (Xprt) can read  a  number  of  configuration  files
       which  control  its  behavior  and  support  for  printers. Each vendor
       platform has a default location for this  information.  Xprt  can  also
       read   the   environment   variable  XPCONFIGDIR  to  locate  alternate
       configuration directories. Common settings include:

       export XPCONFIGDIR=/X11/lib/X11/XpConfig/

       export XPCONFIGDIR=/proj/x11/xc/programs/Xserver/XpConfig/

       Xprt has many built-in defaults, and lacking any  configuration  files,
       will immediately try to support all printers visible via lpstat(1).

       In order of importance for configuration by a system administrator, the
       configuration files for a "C" locale are as follows  (see  Xprt(1)  for
       more details (including support for non-"C" locales)):

       ${XPCONFIGDIR}/C/print/Xprinters
              ’Xprinters’  is  the  top most configuration file. It tells Xprt
              which specific printer names (e.g. mylaser) should be supported,
              and  whether  lpstat(1)  or  other  commands  should  be used to
              automatically supplement the list of printers.

       ${XPCONFIGDIR}/C/print/attributes/printer
              The ’printer’ file maps printer names  to  model  configurations
              (see  ’model-config’  below).  For  example,  "mylaser" could be
              mapped to a "HPDJ1600C", and all other arbitrary printers  could
              be  mapped  to  a  default, such as "HPLJ4SI". When depending on
              lpstat(1)  in  the  Xprinters  file,  setting  up  defaults   in
              ’printer’ becomes all the more important.

       ${XPCONFIGDIR}/C/print/attributes/document
              The  ’document’  file  specifies the initial document values for
              any print jobs. For example,  which  paper  tray  to  use,  what
              default resolution, etc.

       ${XPCONFIGDIR}/C/print/attributes/job
              The  ’job’  file  specifies the initial job values for any print
              jobs. For example, "notification-profile" can  be  set  so  that
              when  a  print  job is successfully sent to a printer, e-mail is
              sent to the user.

       ${XPCONFIGDIR}/C/print/models/PSdefault/model-config,
       ${XPCONFIGDIR}/C/print/models/PSdefault/fonts/fonts.dir,
       ${XPCONFIGDIR}/C/print/models/PSdefault/fonts/9nb00051.pmf,
       ${XPCONFIGDIR}/C/print/models/PSdefault/fonts/9nb00093.pmf
              The ’model-config’ file has attributes that describe the printer
              model’s  capabilities and default settings.  Printer model fonts
              may also be present. The model-config file also  identifies  the
              print  ddx driver to be used.  For each printer model supported,
              a complete hierarchy of files should exist. In most cases, these
              files do not need to be modified.

       ${XPCONFIGDIR}/C/print/ddx-config/raster/pcl,
       ${XPCONFIGDIR}/C/print/ddx-config/raster/pdf,
       ${XPCONFIGDIR}/C/print/ddx-config/raster/postscript
              The  print  ddx  drivers  can have highly specific configuration
              files to control their behavior. In most cases, these  files  do
              not need to be modified.

       More  information  in how to configure and customize the X print server
       can be found in the Xprt(1) manual page.

STARTING UP

       The summary checklist for starting the X Print Service is as follows:

       1.  Choose an execution model for the X  Print  Service.  The  X  Print
           Service  can be run on a per-user session basis, per machine basis,
           or can be run on a few machines globally available to a  number  of
           users.

       2.  If  print  jobs are to be submitted to a spooler (almost always the
           case), make sure all needed printers are available to  the  spooler
           subsystem  (most  often  lp(1))  on  the same machine running the X
           Print Service.

       3.  Configure the X Print Server. See ‘‘X Print Server Configuration’’.

       4.  Depending  on #1, start the X Print Server process "Xprt", and then
           the toolkit-specific Print Dialog Manager Daemon process  (such  as
           CDEnext’s   "dtpdmd")   at   the   appropriate  times.   Note  that
           libXprintUtils-based applications/toolkits  do  not  need  a  Print
           Dialog Manager Daemon process to use Xprint.

       The details are described below.

       Because  the  X  Print  Service  is  based  on  X,  it  can  be  easily
       distributed.  The most significant factors in which execution model  to
       choose will be driven by:

       · how many printers will be accessable through the printer subsystem on
         any given machine. A  system  administrator  may  choose  to  cluster
         printers  on  a  few  given  machines,  or  scatter  them  across  an
         organization and possibly make extensive use of  remote  spoolers  to
         make them globally available.

       · how   many   machines  will  need  a  copy  of  the  X  Print  Server
         configuration files. The files have  been  architected  so  that  one
         super-set version of them can be maintained and distributed (e.g. via
         NFS), and a per-machine or per-user version of the ‘Xprinters’ is all
         that  is  needed to have the appropriate information in them utilized
         or ignored.

       · how many users can demand services from a given X Print Service.

       With the above in mind, some obvious execution models include:

       · Global - in this model, the system administrator is choosing  to  run
         the  X  Print  Service  on  a  *few* select machines with appropriate
         printers configured, and allow clients access to the global resource.
         This  can centralize the administration of printers and configuration
         files, but may have to be monitored for performance loading.

         Startup  would  likely  be  done  by   boot-up   scripts   (such   as
         /etc/init.d/xprint).

       · Per-machine  -  every  machine  with  potential X Print Service users
         would run the service. Printer and configuration file  administration
         is  decentralized,  and  usage  would  be limited to the users on the
         machine.

         Startup  would  likely  be  done  by   boot-up   scripts   (such   as
         /etc/init.d/xprint).

       · Per-user session - every user would run an entire X Print Service for
         themselves. In the future, the Video X Server  normally  started  may
         contain  Print  X  Server  capability,  so  this  model  becomes very
         natural.

         Startup would likely be done at session login or by launching actions
         or  processes  manually  once  the  user  logs in. Note: Deamons like
         "dtpdmd" must be started after Xprt.

       Starting of the processes is straight forward. In strict order (example
       is for manually starting the X print server for CDEnext usage):

       1.
           [machineA] % Xprt [-XpFile <Xprinters file>] [:dispNum] &

           Note  that  Xprt  will  look  for  configuration  files in either a
           default location or where XPCONFIGDIR points.

           -XpFile specifies an alternate ‘Xprinters’ file,  rather  than  the
           default one or ‘${XPCONFIGDIR}/C/print/Xprinters’.

       2.
           [machineA] % dtpdmd -d machineA[:dispNum] [-l /tmp/dtpdmd.log] &

           The  dtpdmd  will maintain an X-Selection on the X-Server, and will
           start dtpdm’s as required to service requests.

       In all but the per-user session model, the machine running  the  dtpdmd
       (thus  dtpdm’s)  will  need  display  authorization  to the users video
       display.

CLIENT CONFIGURATION

       Once a X Print Server and dtpdmd have been started -- many of  them  in
       some  cases  --  clients  will need to find and use them. There are two
       mechanisms that allow clients to discover X Print Servers and printers.

       · "X Print Specifier" - assuming usage of the DtPrint/XprintUtils-based
         print applications, the following notation is understood:

         printer_name@machine[:dispNum]

         For example:

         colorlj7@printhub:2

         In the above example, the X Print Server running at  ‘printhub:2’  is
         assumed to support the printer named ‘colorlj7’.

       · ${XPSERVERLIST}  -  assuming  usage of the DtPrint print dialogs, the
         environment variable ${XPSERVERLIST} can contain a list  of  X  Print
         Servers. For example:

         XPSERVERLIST="printhub:2 printhub:3 otherdept:0"

         Then  in  the  dialogs, only a printer name needs to be entered.  The
         dialog will then search the X Print Servers in ${XPSERVERLIST} for  a
         server than supports the printer, and then establish contact.

END-USER SEQUENCE

       From  most  CDEnext  applications, printing is accomplished by bringing
       down the <File> menu and selecting <Print...>. This will result in  the
       DtPrintSetupBox  dialog,  which will request the name of a printer, and
       offer limited capability to configure print  options  (e.g.  number  of
       copies).  If  the  user  wishes, they can select <Setup...>, which will
       start a dtpdm capable of modifying additional print options.   Finally,
       the user should select <Print>.

ENVIRONMENT

       ${XPCONFIGDIR}
              This  environment  variable  points  to  the  root of the Xprint
              server configuration directory hierarchy.  If  the  variable  is
              not  defined,  the  default path is be assumed. The default path
              may   be   /usr/X11R6/lib/X11/xserver/,   /usr/lib/X11/xserver/,
              /usr/share/Xprint/xserver/  or /usr/openwin/server/etc/XpConfig,
              depending  on   the   system,   and   may   be   configured   in
              /etc/init.d/xprint.

       ${LANG}
              This  environment  variable  selects the locale settings used by
              the  Xprint  server.   Xprt  allows  language-specific  settings
              (stored  in  ${XPCONFIGDIR}/${LANG}/print/)  which will override
              the default settings (stored  in  ${XPCONFIGDIR}/C/print/).   If
              ${LANG} is not set "C" is assumed.

       ${XPSERVERLIST}
              The  environment  variable  ${XPSERVERLIST}  contains  a list of
              display identifiers (separated  by  whitespace)  which  tell  an
              application  where  it  can  find  the  Xprint  servers. Usually
              ${XPSERVERLIST} is set by  the  profile  startup  scripts  (e.g.
              /etc/profile  or  /etc/profile.d/xprint.sh)  using the output of
              /etc/init.d/xprint get_xpserverlist.

              Example:

                        export XPSERVERLIST="‘/etc/init.d/xprint get_xpserverlist‘"

              Alternatively ${XPSERVERLIST} can be set manually. Example:

                        export XPSERVERLIST="littlecat:80 bitdog:72"

              instructs an application to find an Xprint server at display  80
              on  the  machine  "littlecat"  and  at display 72 on the machine
              bigdog.

       ${XPRINTER}
              The environment variable ${XPRINTER} defines the default printer
              used  by print applications. The syntax is either printername or
              printername@display.

              Examples:

              XPRINTER=ps003
                     tells an application to look for the first printer  named
                     "ps003" on all Xprint servers.

              XPRINTER=hplaser19@littlecat:80
                     tells  an  application  to use the printer "hplaser19" on
                     the Xprint server at display "littlecat:80".

       If ${XPRINTER} is not set the applications will examine the  values  of
       the  ${PDPRINTER},  ${LPDEST}, and ${PRINTER} environment variables (in
       that order).

SEE ALSO

       X11(7),   xplsprinters(1),   xprehashprinterlist(1),   xphelloworld(1),
       xpxmhelloworld(1),         xpawhelloworld(1),        xpxthelloworld(1),
       xpsimplehelloworld(1), Xserver(1), Xprt(1), libXp(),  libXprintUtils(),
       libXprintAppUtils(),   XmPrintShell(),   XawPrintShell(),   Xprint  FAQ
       (http://xprint.mozdev.org/docs/Xprint_FAQ.html),   Xprint   main   site
       (http://xprint.mozdev.org/)

AUTHORS

       This manual page was written by Roland Mainz <roland.mainz@nrubsig.org>
       based on the original X11R6.6 xc/programs/Xserver/XpConfig/README.

                                8 October 2004                       Xprint(7)