Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 518 insertions, 0 deletions

diff --git a/doc/kdeprint/highlights.docbook b/doc/kdeprint/highlights.docbook
new file mode 100644
index 000000000..85e0e348f
--- /dev/null
+++ b/doc/kdeprint/highlights.docbook
@@ -0,0 +1,518 @@
+<chapter id="kdeprint-highlights">
+<title>&kdeprint;'s Highlights</title>
+
+<para>The new &kdeprint; system includes more than one highlight.
+Having worked in an environment in the past that is not exactly
+sophisticated, as far as printing is concerned, take a look at some of
+the benefits that come with &kdeprint;</para>
+
+<sect1 id="add-printer-wizard">
+<title>The <quote>Add Printer</quote> Wizard</title>
+
+<para>&kdeprint; has an <quote>Add Printer Wizard</quote>.  The Add
+Printer Wizard helps you with adding and configuring a new printer.  Of
+course, you may do this manually as well.</para>
+
+<para>&kdeprint; helps you <quote>discover</quote> printers. It is able
+to scan the environment for available devices and queues. This works for
+network connections using <acronym>TCP</acronym> (AppSocket,
+<acronym>aka</acronym> &HP; <trademark
+class="registered">JetDirect</trademark>, or <acronym>IPP</acronym>) or
+<acronym>SMB</acronym>/Samba (<quote>shared</quote> &Windows;) printers
+and partially for directly attached printers over parallel, serial, or
+<acronym>USB</acronym> connections.</para>
+
+<screenshot>
+<screeninfo>A screenshot of the new <quote>Add Printer
+Wizard</quote></screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="cupsaddprinterwizard1.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>Here's a screenshot of the <quote>Add Printer Wizard</quote>
+(this one is not very exciting yet; but...)</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>The wizard makes the installation and handling of the drivers
+<quote>a snap</quote>. Selecting, configuring and testing should be easy
+as never before on any &Linux;-like system.</para>
+
+<!-- LW: needs some info where to find it, or a pointer to where in this -->
+<!-- doc that is covered -->
+
+</sect1>
+
+<sect1 id="print-job-control">
+<title>Full Print Job Control</title>
+
+<para>The Print Job Viewer is automatically started by &kprinter;.  It
+may be docked into the &kde; panel (in the system tray).  The Print Job
+Viewer allows full job management, if supported by the print
+subsystem.</para>
+
+<para>You can:</para>
+
+<itemizedlist>
+<listitem>
+<para>Hold and release jobs,</para>
+</listitem>
+<listitem>
+<para>Move pending jobs to another printer,</para>
+</listitem>
+<listitem>
+<para>Cancel pending or processing jobs.</para>
+</listitem>
+</itemizedlist>
+
+<para>A screenshot of the &kdeprint; PrintJob Viewer shows the information
+you get: Job-ID, target printer, job name, job owner, job status and job
+size. In the next &kdeprint; release you will also see information about the
+number of pages (as &CUPS; calculates it; see chapter on page accounting
+for more information about its merits and limitations).</para>
+
+<screenshot>
+<screeninfo>A screenshot of the &kdeprint; PrintJob Viewer</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="kdeprint-jobviewer.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>Here's a screenshot of the &kdeprint; PrintJob Viewer.</phrase>
+</textobject>
+<caption><para>A screenshot of the &kdeprint; PrintJob
+Viewer.</para></caption>
+</mediaobject>
+</screenshot>
+
+<para>An alternative way to looking at the same information (and having the
+same amount of control is through the <inlinemediaobject><imageobject>
+<imagedata fileref="kcontrol-icon.png" format="PNG"/></imageobject>
+</inlinemediaobject> &kcontrolcenter; selecting
+<menuchoice><guilabel>System</guilabel><guilabel>Printing
+Manager</guilabel></menuchoice>. If you don't see the
+<guilabel>Printer Information</guilabel>,
+<mousebutton>right</mousebutton> click on the window
+background and select <guilabel>View Printer
+Information</guilabel>. Then go to the <guilabel>Jobs</guilabel> tab
+to see this:</para>
+
+<screenshot>
+<screeninfo></screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="kcontrolcenter-printmanager-jobcontrol-2.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>Here's a screenshot of the &kdeprint; PrintJob Viewer.</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+</sect1>
+
+<sect1 id="modules-for-different-subsystems">
+<title>Modules for different print subsystems</title>
+
+<para>&kdeprint; uses different modules to realize the interface to the
+possible print subsystems.  Not all the modules are yet developed fully,
+but you will have basic printing functionality with:</para>
+
+<itemizedlist>
+<listitem>
+<para><acronym>LPD</acronym> (<acronym>BSD</acronym> style)</para>
+</listitem>
+<listitem>
+<para><acronym>LPRng</acronym> (&RedHat;, if you just use it's
+<acronym>BSD</acronym> style subset),</para>
+</listitem>
+<listitem>
+<para><acronym>RLPR</acronym> (a command-line <acronym>LPR</acronym>
+utility, which doesn't need a <filename>printcap</filename> file.</para>
+</listitem>
+<listitem>
+<para><quote>external</quote> print commands (&Netscape; like).</para>
+</listitem>
+</itemizedlist>
+
+<para>Most importantly, full support for &CUPS; is already there.
+Modules for other print subsystems, such as <acronym>PLP</acronym>,
+<acronym>PPR</acronym> and <acronym>PDQ</acronym> may be available
+later.</para>
+
+<para>&kdeprint; makes &kde; much more flexible.  It gives freedom of
+choice to &kde; 2.2 users.  To use different available print subsystems,
+these must, of course, be installed independently from &kde;.  In
+former versions, users were stuck with the old <acronym>LPD</acronym>
+style print subsystems.  Now they can even use &CUPS;. In the future,
+there will be easy integration of new subsystems, as they
+appear on the scene.</para>
+
+</sect1>
+
+<sect1 id="kdeprint-goodies">
+<title>More &kdeprint; <quote>Goodies</quote></title>
+<subtitle>Benefitting all Print SubSystems.</subtitle>
+
+<para>Some specific features of &kdeprint; depend on the chosen print
+subsystem.  This dependency might exist because those features are only
+implemented there; remember, &kdeprint; is an intermediate layer between
+&kde; applications, and the print subsystem, but it's no replacement for
+any print subsystem by itself.  Such dependency may exist for another
+reason: that &kdeprint; has not yet implemented an interface to all the
+features of all the subsystems.</para>
+
+<para>Other features include benefits from &kdeprint; that are
+independent of the chosen print subsystem, and are available with all of
+them.  At present there are <quote>special</quote> or
+<quote>virtual</quote> printers, and some generic
+<quote>pre-filters</quote>.</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Print Preview</guilabel></term>
+<listitem>
+<para>From the Print Dialog, you can select to look at a preview.  For
+this, the print file is passed through filters which make it suitable for
+displaying on screen using &kghostview;.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Special Printers</guilabel></term>
+<listitem>
+<para>Amongst these additional &kdeprint; features are a few
+<quote>special</quote> or <quote>virtual</quote> printers:</para>
+
+<para>These special printers may:</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Print to PDF</guilabel></term>
+<listitem>
+<para>Convert your document into a <acronym>PDF</acronym> file with the
+help of an external program.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Print to email</guilabel></term>
+<listitem>
+<para>Send your document as an email attached <acronym>PDF</acronym>
+file.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Print to PS file</guilabel></term>
+<listitem>
+<para>Save your document as a &PostScript; file.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Print to Fax</guilabel></term>
+<listitem>
+<para>Send it through an available backend, such as
+<application>Hylafax</application> as a fax.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>These <quote>special</quote> printers appear in the user print
+dialog just like <quote>normal</quote> printers.  They are entirely
+configurable on a per-user basis.</para>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Generic Pre-Filtering</guilabel></term>
+<listitem>
+<para>&kdeprint; provides you with a framework to define and configure
+your own <quote>pre-filters</quote>.  These pre-filters may take effect
+<emphasis>before</emphasis> they are passed to your print subsystem for
+further processing, but <emphasis>after</emphasis> the (&PostScript;,
+plain text or other) print files have been generated by your
+application.</para>
+
+<para>There are a few useful filters already predefined. These
+are:</para>
+
+<itemizedlist>
+<listitem>
+<para>The <quote>multiple pages per sheet</quote> filter,</para>
+</listitem>
+
+<listitem>
+<para>the <quote>enscript</quote> text filter,</para>
+</listitem>
+
+<listitem>
+<para>and three filters to help print pamphlets.</para>
+</listitem>
+</itemizedlist>
+
+<para>You may create your own filters based on any third party program
+that is able to process &PostScript;, plain text or image files, and output
+any one of those formats.</para>
+
+<para>These filters are configured through <acronym>XML</acronym> files.
+This makes an extension of the concept very easy for experienced developers,
+but end-user configuration is also done through an intuitive graphical
+user interface.  So, fear not, you don't need to learn
+<acronym>XML</acronym> because of &kdeprint;!</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Multiple Pages Per Sheet Filter</guilabel></term>
+<listitem>
+<para>This is a predefined filter that installs with &kdeprint;.  It
+allows you to create a modified &PostScript; output, from &PostScript;
+input, that prints 1, 2, or 4 logical pages on a single sheet of
+paper.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Enscript Text Filter</guilabel></term>
+<listitem>
+<para>This is a predefined filter that installs with &kdeprint;.  It
+allows you to create &PostScript; output from any text file input, that
+includes syntax highlighting for program listings, pretty-printing, and
+nice configurable page frames and headers.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Pamphlet Printing Filters</guilabel></term>
+<listitem>
+<para>If your printer is able to produce duplex output, using either
+one-pass or two-pass technology, you may be able to use one, or a
+combination, of the <quote>pamphlet</quote> filters.</para>
+
+<para>For duplexing printers, make sure you use the duplex option that
+<quote>turns</quote> the output along the short paper edge.  Folding the
+printed paper along the middle turns your document into a nice pamphlet.</para>
+
+<para>If you are stuck with using a simplex-only device, you can do the
+same, using two different filters and a few additional steps.</para>
+
+<para>Depending on your model, first use the filter for printing the
+<quote>odd</quote> pages, then insert the paper in the correct order
+back into the paper tray to get the even pages printed on the reverse
+side.  These can then be folded to make a pamphlet.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+<sect1 id="cups-plugin">
+<title>&CUPS; Support: the Most Important Module in &kdeprint;</title>
+
+<para>&kdeprint; contains a module for &CUPS;.  &CUPS;, the
+<quote>Common &UNIX; Printing System</quote> (<ulink
+url="http://www.cups.org">http://www.cups.org/</ulink>), is the most
+advanced, powerful and flexible of all print subsystems on &UNIX; and
+other &UNIX;-like operating systems.  It is still quite new on the
+horizon, but is based on <acronym>IPP</acronym>, the Internet Printing
+Protocol, the newly emerging standard for the future of network
+printing. &CUPS; is clearly the print system of choice for Michael
+Goffioul, the principal &kdeprint; developer.</para>
+
+<para>Experienced &kde; users may already be familiar with Michael's
+utilities <application>qtcups</application> and
+<application>kups</application> (co-developed with Jean-Eric Cuendet).
+These were, up until now, the graphical
+&GUI; front ends for &CUPS; with a strong relation to &kde;.</para>
+
+<sect2>
+<title><application>qtcups</application> and
+<application>kups</application> &mdash; The Predecessors</title>
+
+<para>Both utilities are probably still widely used. For those
+not familiar with them,
+here are brief explanations.</para>
+
+<para><application>qtcups</application> was a graphical front end for
+the <command>lp</command> or <command>lpr</command> print commands as
+installed by &CUPS;. Using <application>qtcups</application> opened a
+dialog.  This dialog let you comfortably select your printer and the
+print job options. <application>qtcups</application>
+worked from the command line, or from
+within applications, when the application in question had a configurable
+print command.</para>
+
+<para><application>kups</application> was a graphical wrapper to do the
+administration tasks for your &CUPS; server, and the &CUPS; daemon at
+the heart of it.  You could add, delete, modify, configure, start, and
+stop printers.  You could cancel, delete, move, stop and restart print
+jobs, and you could change the settings of the daemon, start, stop, and
+restart it.</para>
+
+</sect2>
+
+<sect2>
+<title>&kdeprint; &mdash; The Heir</title>
+
+<para>The &CUPS; Module in &kdeprint; now contains all (and more)
+functions that were provided by <application>qtcups</application> and
+<application>kups</application> in former &kde; versions.</para>
+
+<para>Instead of <command>qtcups</command> you can now use the
+<command>kprinter</command> command.  And in place of
+<command>kups</command> you will probably use
+<command>kcmshell printers</command> from now on.
+</para>
+
+<para>The &kdeprint; module for &CUPS; also lets you fully administer
+the print subsystem, just like <application>kups</application> did
+before. It can start, stop and configure your &CUPS; daemon. It can also
+start, stop, add and delete <quote>printers</quote> (&ie; printer
+queues) and printer <quote>instances</quote>.  Printer instances are
+printer queues that point to the same physical output device but with a
+different default setting of print options.</para>
+
+</sect2>
+
+<sect2>
+<title>&kprinter; &mdash; Graphical Print Command</title>
+
+<para>&kdeprint;'s &CUPS; module gives you access to a <quote>graphical
+print command</quote>, like <application>qtcups</application> did
+before.</para>
+
+<para>Use &kprinter; in any application, even a non-&kde;
+application, that lets you configure your print command.  Examples of
+these are &Netscape; and <application>StarOffice</application>, but
+<emphasis>not</emphasis> most pre-&kde; 2.2 programs.</para>
+
+<para>A screenshot how to use the new <command>kprinter</command>
+print command instead of the old-fashioned <command>lpr</command>...
+Of course you need to have <command>kprinter</command> in your
+$<envar>PATH</envar>, or give the full path in the dialog; &eg;
+<userinput><filename>/opt/kde/bin/kprinter</filename></userinput>.
+&Netscape; will remember this and with further print jobs you will get
+the <command>kprinter</command> dialog to configure your printouts.</para>
+
+<screenshot>
+<screeninfo>A screenshot of the <command>kprinter</command> print
+command in action.</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="kprinter-as-netscape-printcommand.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>Here's a screenshot showing how to use the new
+<command>kprinter</command> print command
+instead of the old-fashioned <command>lp</command> or
+<command>lpr</command> in &Netscape;.</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>You can also use <command>&kprinter;</command> from the
+command line and see the resulting dialog box pop up:</para>
+
+<screenshot>
+<screeninfo>Screenshot of the <command>kprinter</command> command</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="kprinter.png"
+format="PNG"/></imageobject>
+<textobject>
+<phrase>Screenshot showing use of the <command>kprinter</command> command
+from the command line.</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+<note><para>Just make sure you give at least the file to be printed
+from the command line as well: <userinput><command>kprinter</command>
+<option>/usr/share/doc/packages/cups/sam.pdf</option></userinput>.
+This will hand over the &CUPS; Software Administrator Manual to the
+<command>kprinter</command> dialog, which will then pop up with the
+default printer pre-selected.</para>
+
+<para>To pre-select a specific printer from the command line, use the
+<option>-d</option> option, &eg;:
+<userinput><command>kprinter</command> <option>-d
+DANKAcolorC2000</option>
+<option>/home/kurt/linuxtag2001-paper.ps</option></userinput>.  You
+can still de-select the printer <option>DANKAcolorC2000</option> and
+choose a different one.</para>
+
+<para> You <emphasis>cannot</emphasis> however call
+<userinput><command>kprinter</command></userinput> 
+without a print file and hope to open a file selection
+dialog box from the &kprinter; window. This is a feature that will be
+implemented only in the next version.</para>
+</note>
+
+<para>Using <command>kprinter</command> you are able to <quote>ring
+all the bells and blow all the whistles</quote> of your printer.  You
+will need a device-specific so-called &PPD; (&PostScript; Printer
+Description) to enable &CUPS; to make this nice tandem team do this
+for you.  Read more about this in <xref linkend="ppd-files"/>.</para>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="future-plans">
+<title>Plans for Future Development</title>
+
+<para>What you have now is the first, already very feature-rich
+version of &kdeprint;. This version is, of course, fully usable for
+printing. You might even think that <quote>it was never so
+easy</quote> (not even back in the days when you had to use
+&Microsoft; &Windows;).</para>
+
+<para> In the future, &kdeprint; will become even better. It will do a
+better job of <quote>detecting</quote> your installed print subsystem
+itself. Already &kdeprint; is doing quite well in automatically
+sensing if you have &CUPS; on your system. But in many cases you will
+have to tell &kdeprint; what you are using, if you want to keep a
+legacy print system.</para>
+
+<para>The most important improvement in the near future will be a
+completion of the <application>LPRng</application> plugin.  This at
+present is still very basic.  It is restricted to the pure classical
+<acronym>LPD</acronym> part of
+<application>LPRng</application>.</para>
+
+<para>Also, you may be able to add printers directly from the print
+dialog to your system <quote>just in time</quote>, without going to
+&kcontrol; first.</para>
+
+<para>Some smaller improvements already planned are:</para>
+
+<itemizedlist>
+<listitem><para>add a file selection dialog from the &kprinter; window
+to allow combining of additional files to the present
+printjob</para></listitem> <listitem><para>add a
+<quote>history</quote> button to the
+<application>KJobViewer</application> window and also a column to show
+the number of pages &CUPS; calculates for the job.</para></listitem>
+</itemizedlist>
+
+<para>Finally, there will be an <quote>IO slave</quote> that will give
+you access to your print subsystem, via &konqueror; for example.  With
+this you will soon be able to browse your print subsystem from
+&konqueror; through a &URL; like shortcut such as
+<userinput>print://printers/printername</userinput>.  A KPart will add
+a virtual folder to the services section of the &konqueror; navigation
+panel, giving a nice integrated way to browse and manage your print
+system via the &URL; <userinput>print:/manager</userinput>.</para>
+
+<para>Please contact Michael Goffioul at <email>kdeprint@swing.be</email>
+with any further user or developer suggestions.</para>
+
+</sect1>
+</chapter>