diff options
Diffstat (limited to 'man/Xprint.sgml')
| -rw-r--r-- | man/Xprint.sgml | 627 |
1 files changed, 627 insertions, 0 deletions
diff --git a/man/Xprint.sgml b/man/Xprint.sgml new file mode 100644 index 0000000..96af582 --- /dev/null +++ b/man/Xprint.sgml @@ -0,0 +1,627 @@ +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.3//EN" 'http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd'> + +<!-- Process this file with docbook-to-man to generate an nroff manual + page: 'docbook-to-man manpage.sgml > manpage.1'. You may view + the manual page with: 'docbook-to-man manpage.sgml | nroff -man | less'. + A typical entry in a Makefile or Makefile.am is: + +manpage.1: manpage.sgml + docbook-to-man $< > $@ + +HTML generation can be done like this: +% xsltproc ==docbook /usr/share/sgml/docbook/docbook-xsl-stylesheets-1.60.1/html/docbook.xsl Xprint.sgml >Xprint.html + --> + +<refentry id="Xprint"> + <refmeta> + <refentrytitle>Xprint</refentrytitle> + <manvolnum>__miscmansuffix__</manvolnum> + </refmeta> + <refnamediv> + <refname>Xprint</refname> + + <refpurpose>The "X print service" - a portable, network-transparent printing system based on the X11 protocol</refpurpose> + </refnamediv> + <refsynopsisdiv> + <para>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. + </para> + </refsynopsisdiv> + + <refsect1> + <title>OVERVIEW</title> + <para> + 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. + </para> + <para> + The Xp portion consists of: + <itemizedlist> + <listitem><para>Xp Extension for the X-Server (included in the X-Server Xprt)</para></listitem> + <listitem><para>Xp Extension API for the client side (libXp/libXprintUtils)</para></listitem> + <listitem><para>PCL ddx driver that converts core X to native PCL</para></listitem> + <listitem><para>PDF ddx driver that converts core X to native PDF</para></listitem> + <listitem><para>PostScript ddx driver that converts core X to native PostScript</para></listitem> + <listitem><para>Raster ddx driver that generates xwd rasters which can be converted to PCL, PDF or PostScript rasters</para></listitem> + </itemizedlist> + </para> + <para> + 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. + </para> + </refsect1> + + <refsect1> + <title>HOW THE X PRINT SERVICE WORKS</title> + <para> + The X Print Service expands on the traditional X-Server and Xlib world + in four ways. + + <orderedlist> + <listitem> + <para> + 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). + </para> + <para> + Once a print ddx driver generates PDL output, it can be sent to + a spooler such as <citerefentry><refentrytitle>lp</refentrytitle><manvolnum>1</manvolnum></citerefentry> + or retrieved by the client (to implement functionality like "print-to-file"). + </para> + <para> + Though not currently done, a single X-Server can support both + print and video ddx drivers. + <!-- FIXME: IBM/AIX people have integrated Xprt into their main Xserver (currently experimental) ... --> + </para> + </listitem> + <listitem> + <para> + Since printers support "paged" output, unlike video, a portion + of the Xp Extension supports APIs to delineate printed output. + For example, <function>XpStartPage</function> and <function>XpEndPage</function> tell the X-Server where + a physical page starts and ends in an otherwise continuous + stream of X rendering primitives. Likewise, <function>XpStartJob</function> and + <function>XpEndJob</function> determine when a collection of pages starts and ends. + <function>XpEndJob</function> typically causes the generated PDL to be submitted to + a spooler, such as <citerefentry><refentrytitle>lp</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + </listitem> + <listitem> + <para> + Since printers have extensive capabilities, another portion of + the Xp Extension supports APIs to manipulate "print contexts". + </para> + <para> + 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). + </para> + </listitem> + <listitem> + <para> + 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. + </para> + <para> + 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. + </para> + </listitem> + </orderedlist> + </para> + </refsect1> + + <refsect1> + <title>USAGE</title> + <para> + There are three tasks to start the X Print Service: + <orderedlist> + <listitem><para>configuring the X Print Server,</para></listitem> + <listitem><para>starting the X Print Service</para></listitem> + <listitem><para>configuring the user session so that clients can find the running X Print Service</para></listitem> + </orderedlist> + </para> + <para> + The tasks are described in detail below. + </para> + </refsect1> + + <refsect1> + <title>SERVER CONFIGURATION</title> + <para> + 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 <envar>XPCONFIGDIR</envar> to locate alternate configuration + directories. Common settings include: + + <simplelist type="vert"> + <member>export XPCONFIGDIR=/X11/lib/X11/XpConfig/</member> + <member>export XPCONFIGDIR=/proj/x11/xc/programs/Xserver/XpConfig/</member> + </simplelist> + </para> + <para> + Xprt has many built-in defaults, and lacking any configuration files, + will immediately try to support all printers visible via <citerefentry><refentrytitle>lpstat</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + <para> + In order of importance for configuration by a system administrator, the + configuration files for a "C" locale are as follows (see <citerefentry><refentrytitle>Xprt</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry> for more + details (including support for non-"C" locales)): + <variablelist> + <varlistentry> + <term><filename>${XPCONFIGDIR}/C/print/Xprinters</filename></term> + <listitem> + <para> + 'Xprinters' is the top most configuration file. It tells + Xprt which specific printer names (e.g. mylaser) should + be supported, and whether <citerefentry><refentrytitle>lpstat</refentrytitle><manvolnum>1</manvolnum></citerefentry> or other commands + should be used to automatically supplement the list of + printers. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>${XPCONFIGDIR}/C/print/attributes/printer</filename></term> + <listitem> + <para> + 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 <citerefentry><refentrytitle>lpstat</refentrytitle><manvolnum>1</manvolnum></citerefentry> in the Xprinters + file, setting up defaults in 'printer' becomes all the + more important. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>${XPCONFIGDIR}/C/print/attributes/document</filename></term> + <listitem> + <para> + The 'document' file specifies the initial document values + for any print jobs. For example, which paper tray to + use, what default resolution, etc. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>${XPCONFIGDIR}/C/print/attributes/job</filename></term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>${XPCONFIGDIR}/C/print/models/PSdefault/model-config</filename></term> + <term><filename>${XPCONFIGDIR}/C/print/models/PSdefault/fonts/fonts.dir</filename></term> + <term><filename>${XPCONFIGDIR}/C/print/models/PSdefault/fonts/9nb00051.pmf</filename></term> + <term><filename>${XPCONFIGDIR}/C/print/models/PSdefault/fonts/9nb00093.pmf</filename></term> + + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>${XPCONFIGDIR}/C/print/ddx-config/raster/pcl</filename></term> + <term><filename>${XPCONFIGDIR}/C/print/ddx-config/raster/pdf</filename></term> + <term><filename>${XPCONFIGDIR}/C/print/ddx-config/raster/postscript</filename></term> + + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + </variablelist> + + More information in how to configure and customize the X print server can be found in the + <citerefentry><refentrytitle>Xprt</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry> + manual page. + </para> + </refsect1> + + <refsect1> + <title>STARTING UP</title> + <para> + The summary checklist for starting the X Print Service is as follows: + + <orderedlist> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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 <citerefentry><refentrytitle>lp</refentrytitle><manvolnum>1</manvolnum></citerefentry>) + on the same machine running the X Print Service. + </para> + </listitem> + <listitem> + <para> + Configure the X Print Server. See ``X Print Server + Configuration''. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + </orderedlist> + The details are described below. + </para> + <para> + 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: + <itemizedlist> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + how many users can demand services from a given X Print + Service. + </para> + </listitem> + </itemizedlist> + + With the above in mind, some obvious execution models include: + <itemizedlist> + <listitem> + <para> + 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. + </para> + <para> + Startup would likely be done by boot-up scripts (such as <filename>/etc/init.d/xprint</filename>). + </para> + </listitem> + + <listitem> + <para> + 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. + </para> + <para> + Startup would likely be done by boot-up scripts (such as <filename>/etc/init.d/xprint</filename>). + </para> + </listitem> + + <listitem> + <para> + 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. + </para> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </para> + <para> + Starting of the processes is straight forward. In strict order (example is for manually starting the X print server for CDEnext usage): + <orderedlist> + <listitem> + <para> + <programlisting>[machineA] % Xprt [-XpFile <Xprinters file>] [:dispNum] &</programlisting> + </para> + <para> + Note that Xprt will look for configuration files in either + a default location or where <envar>XPCONFIGDIR</envar> points. + </para> + <para> + <option>-XpFile</option> specifies an alternate `Xprinters' file, rather + than the default one or `<filename>${XPCONFIGDIR}/C/print/Xprinters</filename>'. + </para> + </listitem> + <listitem> + <para> + <programlisting>[machineA] % dtpdmd -d machineA[:dispNum] [-l /tmp/dtpdmd.log] &</programlisting> + </para> + <para> + The dtpdmd will maintain an X-Selection on the X-Server, + and will start dtpdm's as required to service requests. + </para> + </listitem> + </orderedlist> + </para> + <para> + 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. + </para> + </refsect1> + + <refsect1> + <title>CLIENT CONFIGURATION</title> + <para> + 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. + + <itemizedlist> + <listitem> + <para> + "X Print Specifier" - assuming usage of the DtPrint/XprintUtils-based print + applications, the following notation is understood: + </para> + <para> + <programlisting>printer_name@machine[:dispNum]</programlisting> + </para> + <para> + For example: + </para> + <para> + <programlisting>colorlj7@printhub:2</programlisting> + </para> + <para> + In the above example, the X Print Server running at `printhub:2' + is assumed to support the printer named `colorlj7'. + </para> + </listitem> + <listitem> + <para> + <envar>${XPSERVERLIST}</envar> - assuming usage of the DtPrint print dialogs, + the environment variable <envar>${XPSERVERLIST}</envar> can contain a list + of X Print Servers. For example: + </para> + <para> + <programlisting>XPSERVERLIST="printhub:2 printhub:3 otherdept:0"</programlisting> + </para> + <para> + Then in the dialogs, only a printer name needs to be entered. + The dialog will then search the X Print Servers in <envar>${XPSERVERLIST}</envar> + for a server than supports the printer, and then establish + contact. + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + + <refsect1> + <title>END-USER SEQUENCE</title> + <para> + 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>. + </para> + </refsect1> + + <refsect1> + <title>ENVIRONMENT</title> + <variablelist> + <varlistentry> + <term><envar>${XPCONFIGDIR}</envar></term> + <listitem> + <para> 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 + <filename>/usr/X11R6/lib/X11/xserver/</filename>, + <filename>/usr/lib/X11/xserver/</filename>, + <filename>/usr/share/Xprint/xserver/</filename> or + <filename>/usr/openwin/server/etc/XpConfig</filename>, depending on the + system, and may be configured in <filename>/etc/init.d/xprint</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>${LANG}</envar></term> + <listitem> + <para> + This environment variable selects the locale settings used by the Xprint server. + Xprt allows language-specific settings (stored in <filename>${XPCONFIGDIR}/${LANG}/print/</filename>) + which will override the default settings (stored in <filename>${XPCONFIGDIR}/C/print/</filename>). + If <envar>${LANG}</envar> is not set "C" is assumed. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>${XPSERVERLIST}</envar></term> + <listitem> + <para>The environment variable <envar>${XPSERVERLIST}</envar> contains a list + of display identifiers (separated by whitespace) which tell an + application where it can find the Xprint servers. Usually + <envar>${XPSERVERLIST}</envar> is set by the profile startup scripts (e.g. + <filename>/etc/profile</filename> or <filename>/etc/profile.d/xprint.sh</filename>) using the output of + <userinput>/etc/init.d/xprint get_xpserverlist</userinput>.</para> + <para>Example: + <informalexample> + <programlisting> + export XPSERVERLIST="`/etc/init.d/xprint get_xpserverlist`"</programlisting> + </informalexample> + </para> + <para>Alternatively <envar>${XPSERVERLIST}</envar> can be set + manually. Example:</para> + <informalexample> + <programlisting> + export XPSERVERLIST="littlecat:80 bitdog:72"</programlisting> + </informalexample> + <para> + instructs an application to find an Xprint server at display + 80 on the machine "littlecat" and at display 72 on the + machine bigdog. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>${XPRINTER}</envar> + </term> + <listitem> + <para>The environment variable <envar>${XPRINTER}</envar> + defines the default printer used by print + applications. The syntax is either + <replaceable>printername</replaceable> or + <replaceable>printername</replaceable>@<replaceable>display</replaceable>.</para> + <para>Examples: + <variablelist> + <varlistentry> + <term><userinput>XPRINTER=ps003</userinput></term> + <listitem><para> + tells an application to look for the + first printer named "ps003" on all Xprint + servers.</para> + </listitem> + </varlistentry> + + <varlistentry> + <!-- brain dead <term> does not permit quote marks + (in XPRINTER="hplaser19@littlecat:80"), so omit them --> + <term><userinput>XPRINTER=hplaser19@littlecat:80</userinput></term> + <listitem><para> + tells an application to use the printer "hplaser19" + on the Xprint server at display + "littlecat:80".</para> + </listitem> + </varlistentry> + + </variablelist> + </para> + <para>If <envar>${XPRINTER}</envar> is not set the applications + will examine the values of the <envar>${PDPRINTER}</envar>, + <envar>${LPDEST}</envar>, and + <envar>${PRINTER}</envar> environment variables (in that order). + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>SEE ALSO</title> + <para> + <simplelist type="inline"> + <!-- specific references --> + <!-- none --> + + <!-- Xprint general references --> +<!-- + <member><citerefentry><refentrytitle>Xprint</refentrytitle><manvolnum>__miscmansuffix__</manvolnum></citerefentry></member> +--> + <member><citerefentry><refentrytitle>X11</refentrytitle><manvolnum>__miscmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>xplsprinters</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>xprehashprinterlist</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>xphelloworld</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>xpxmhelloworld</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>xpawhelloworld</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>xpxthelloworld</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>xpsimplehelloworld</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>Xserver</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>Xprt</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <!-- ToDO: Add manual pages for the single Xprint DDX implementations (PostScript/PDF/PCL/PCL-MONO/Raster/etc.) --> + <member><citerefentry><refentrytitle>libXp</refentrytitle><manvolnum>__libmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>libXprintUtils</refentrytitle><manvolnum>__libmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>libXprintAppUtils</refentrytitle><manvolnum>__libmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>XmPrintShell</refentrytitle><manvolnum>__libmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>XawPrintShell</refentrytitle><manvolnum>__libmansuffix__</manvolnum></citerefentry></member> + <member>Xprint FAQ (<ulink url="http://xprint.mozdev.org/docs/Xprint_FAQ.html">http://xprint.mozdev.org/docs/Xprint_FAQ.html</ulink>)</member> + <member>Xprint main site (<ulink url="http://xprint.mozdev.org/">http://xprint.mozdev.org/</ulink>)</member> + </simplelist> + </para> + </refsect1> + + <refsect1> + <title>AUTHORS</title> + <para> + This manual page was written by + Roland Mainz <email>roland.mainz@nrubsig.org</email> based on the original X11R6.6 + <filename>xc/programs/Xserver/XpConfig/README</filename>. + </para> + </refsect1> +</refentry> + |