<!DOCTYPE book PUBLIC  "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
  <!ENTITY kappname "&kljettool;" -- this only *seems* redundant -->
  <!ENTITY pjl "<filename>PJL</filename>">
  <!ENTITY % English "INCLUDE">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % ents PUBLIC "-//KDE//ENTITIES Documentation V1.0//EN">
  %ents;
]>

<book lang="&language;">
<bookinfo>
<title>The &kljettool; Handbook</title>
<authorgroup>
<author>
<firstname>Mike</firstname>
<surname>McBride</surname>
<affiliation><address><email>mpmcbride7@yahoo.com</email></address></affiliation>
</author>

<othercredit role="developer">
<firstname>Bernd Johannes</firstname>
<surname>Wuebben</surname>
<affiliation>
<address><email>wuebben@kde.org</email></address>
</affiliation>
<contrib>Developer</contrib>
</othercredit>
<othercredit role="developer">
<firstname>Espen</firstname>
<surname>Sand</surname>
<affiliation>
<address><email>espen@kde.org</email></address>
</affiliation>
<contrib>Developer</contrib>
</othercredit>
<othercredit role="reviewer">
<firstname>Lauri</firstname>
<surname>Watts</surname>
<affiliation>
<address><email>vampyr@atconnex.net</email></address></affiliation>
<contrib>Reviewer</contrib>
</othercredit>
</authorgroup>

<copyright>
<year>2000</year>
<holder>Mike McBride</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>21/10/2000</date>
<releaseinfo>1.01.00</releaseinfo>

<abstract><para>This Handbook describes &kljettool; Version 1.1</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>KLJetTool</keyword>
<keyword>laserjet</keyword>
</keywordset>
</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>&kljettool; is a program that lets you adjust your Hewlett Packard Laserjet
operating parameters. Some of Hewlet Packards printers such as the 5L or the 6L
do no longer have a hardware control panel and the printer is controlled
completely by software. However this software is often available only for the
Windows platform. &kljettool; seeks to fill the need for such software on the Unix
platform. It should work with any printer that understands Hewlet Packarts PJL (
Printer Job Language). However some features may have no effect on your
particular model.</para>

<para>I hope you will enjoy this little tool.</para>

<para>Bernd Johannes Wuebben <email>wuebben@kde.org</email></para>
</chapter>

<chapter id="installation">
<title>Installation</title>

<sect1 id="how-to-obtain-kljettool">
<title>How to obtain &kljettool;</title>

<para>&kljettool; is part of the KDE project <ulink
url="http://www.kde.org">http://www.kde.org</ulink>.  &kljettool; can be found on
<ulink url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>, the
main ftp site of the KDE project.</para>

</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>In order to successfully compile &kljettool;, you need the latest versions of
libkdecore and libkfm. All required libraries as well as &kljettool; itself can be
found on <ulink
url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>. </para>
</sect1>

<sect1 id="compilation-and-installation">
<title>Compilation and installation</title>

<para>In order to compile and install &kljettool; on your system, type the following
in the base directory of the KDE distribution:</para>

<screen>
<prompt>%</prompt> <userinput>cd kdeutils</userinput>
<prompt>%</prompt> <userinput>./configure</userinput>
<prompt>%</prompt> <userinput>make</userinput>
<prompt>%</prompt> <userinput>make install</userinput>
</screen>

<para>Since &kljettool; uses <application>autoconf</application> you should have not
trouble compiling it.  Should you run into problems please report them to the
KDE mailing lists.</para>

</sect1>
</chapter>

<chapter id="getting-kljettool-to-work">
<title>Getting &kljettool; to work</title>

<para>Some Linux distributions have an overly eager printing subsystem that
doesn't respect the <filename>PJL</filename> files generated by LJetTool.  The printing subsystem on
these systems does not recognize a <filename>PJL</filename> file as such and tries to transform it
using its filters.  This will cause &kljettool; to malfunction.</para>

<para>This section describes the steps necessary to get LJetTool to work on pre
5.0 RedHat Linux systems (&kljettool; should work out of the box on RedHat linux 5.0
based distributions ). I assume similar steps might be necessary on other
systems. However, the steps which need to be undertaken are not difficult. All
that needs to be done is to make sure that the printing subsystem sends <filename>PJL</filename>
files unmodified to the printer.</para>
    
<para>A RedHat Linux system does not recognize <abbrev>PJL</abbrev> out of the
box, and tries to do weird things with it rather then sending it unmodified to
the printer, so we have to teach it how to deal with a <filename>PJL</filename> file. However
before you make the changes suggested here to your system, be sure that &kljettool;
really doesn't work on your system. RedHat and other distributions might well
have updated its printing subsystem by the time you read this.</para>
    
<para>I assume other distributions with an equally 'sophisticated' printer
subsytem such as the RedHat system might also need to be taught how to deal with
<abbrev>PJL</abbrev> ( Printer Job Language ) files that are send to the printer.</para>

<para>On a redhat system the script
<filename>/var/spool/lpd/lp/filter</filename> is invoked from
<filename>/etc/printcap</filename>, each time something is printed using the
command '<command>lpr</command>'. The filter runs the program
'<application>file</application>' on the file to be printed and
'<application>file</application>' will tell the
'<application>filter</application>' script what sort of document we are dealing
with.  Then depending on the type of the document the right program is run to
produce output in a format that the printer can understand. The program
'<application>file</application>' uses the file <filename>/etc/magic</filename>
to determine the type of the document to be printed ( <abbrev>e.g.</abbrev>
PostScript, dvi, text <abbrev>etc</abbrev> )</para>
    
<para>For example, if I print a postscript document,
<filename>myfile.ps</filename>, file tells the
'<application>filter</application>' script that we are dealing with a postscript
file and '<application>filter</application>' will run
<application>ghostscript</application> first to convert
<filename>myfile.ps</filename> into pcl 5, a language my laserjet understands,
before sending the file to the printer. </para>

<para>Unfortunately a RedHat system doesn't recognize a <filename>PJL</filename> file and tries to do
wrong things with the <filename>PJL</filename> file rather than sending it out to the printer
unmodified. </para>

<para>In order to get &kljettool; to work on a RedHat system we only need to do two
things:</para>

<itemizedlist>
<listitem>
<para> Add a line to the <filename>/etc/magic</filename> file so that the
program '<application>file</application>' will correctly recognize a <filename>PJL</filename> file as
a <filename>PJL</filename> file.</para>

<para>Simply add the following two lines to your <filename>/etc/magic</filename>
file.  Where in the file <filename>/etc/magic</filename> add these lines doesn't
really matter.</para>

<screen>
# HP Printer Job Language, Bernd Wuebben (wuebben@math.cornell.edu)
0	string		\033%-12345X	 HP PJL printer commands
</screen>

</listitem>
<listitem><para>Teach the <filename>/var/spool/lpd/lp/filter</filename> script
what to do with <filename>PJL</filename> files. This can be done by adding the following two lines to
the 'filter' script</para>

<screen>
   *pjl* )
                                             startpnt="INPUT-to-prdata";;
</screen>
		
<para>If you have a look at the filter script it will be clear where to add it (
at about line 220 in the version I have ). These lines simply tell the script to
leave a <filename>PJL</filename> file alone and to send it unmodified to the printer.</para>

</listitem>
</itemizedlist>

<para>I have included a copy of my <filename>filter</filename> script as well as
my <filename>/etc/magic</filename>. You can use them if you have trouble making
the above outlined modifications. You should be able to find them in the same
directory where you found &kljettool; documentation.</para>

<para>I would love to received instructions for what ( if anything ) needs to be
done to get &kljettool; to work on other systems who use an elaborate printing filter
subsystem. </para>

</chapter>

<chapter id="usage">
<title>Usage</title>

<para>&kljettool; is very simply to use. In fact most of its functions should be
self-explanatory. </para>
    
<sect1 id="screen">
<title>&kljettool; Screen</title>

<para>When you start &kljettool;, you are presented with a small window with 5 tabs
labled: <link linkend="printer"><guilabel>Printer</guilabel></link>, <link
linkend="paper"><guilabel>Paper</guilabel></link>, <link
linkend="operations"><guilabel>Operations</guilabel></link>, <link
linkend="fonts"><guilabel>Fonts</guilabel></link> and <link
linkend="about-tab"><guilabel>About</guilabel></link>.</para>

<screenshot>
<screeninfo>&kljettool; screenshot.</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="screenshot.png" format="png">
	  </imageobject>
	  <textobject>
	    <phrase>Screenshot</phrase>
	  </textobject>
	</mediaobject>
</screenshot>

<para>Along the bottom are 4 buttons:</para>

<variablelist>
<varlistentry><term><guibutton>Help</guibutton></term>
<listitem><para>This button opens this document in the help
browser.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>OK</guibutton></term>
<listitem><para>This button makes your changes permenant, and closes
&kljettool;.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Apply</guibutton></term>
<listitem><para>This button makes your changes permenant, but it does not close
&kljettool; so you can test your settings and adjust them some
more.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Close</guibutton></term>
<listitem><para>Exits the program without saving the changes.</para></listitem>
</varlistentry>
</variablelist>

<sect2 id="printer">
<title><guilabel>Printer</guilabel> tab</title>
<variablelist>

<varlistentry><term><guilabel>Mode</guilabel></term>
<listitem><para>You should choose between Economy Mode and Presentation Mode.
Economy mode is suitible for everyday printing, and requires less toner.  The
Presentation Mode produces the highest quality output, but requires more
toner.</para></listitem>
</varlistentry>
<varlistentry><term><guilabel>Resolution</guilabel></term>
<listitem><para>Choose between 300dpi and 600dpi for your
printer.</para></listitem>
</varlistentry>
<varlistentry><term><guilabel>Printer</guilabel></term>
<listitem><para>You can choose from a list of printers.  If your printer does
not appear in the list provided, see the section on <link
linkend="getting-kljettool-to-work">"Getting &kljettool; to
work"</link></para></listitem>
</varlistentry>
<varlistentry><term><guilabel>Density</guilabel></term>
<listitem><para>This will help determine how dark the print is on your final
output.</para></listitem>
</varlistentry>
<varlistentry><term><guilabel>Resolution Enhancement</guilabel></term>
<listitem><para>Determines the resolution enhancement mode.</para></listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="paper">
<title><guilabel>Paper</guilabel> tab</title>

<variablelist>
<varlistentry><term><guilabel>Format</guilabel></term>
<listitem><para>This drop down box allows you to choose your paper size, from a
variety of standard sizes.</para></listitem>
</varlistentry>
<varlistentry><term>Copies</term>
<listitem><para>Choose how many copies of each page you should print.</para>
<note><para>This will <emphasis>not</emphasis> override the settings of another
application.  This is in addition to the settings of all other
applications.</para>
<para>(You can think of the total number of copies as a multiplication
problem)</para>
<para>As an example:</para>
<para>If you tell <application>KWord</application> to print 2 copies of a
letter, but you tell &kljettool; to print one copy of the letter, 2 copies will still
be printed. (<application>KWord</application> says "print copy one of the
letter.  Now print copy 2 of the letter.".  (2 multiplied by 1 = 2
copies)</para>
<para>On the other hand, if you tell <application>KWord</application> to print 1
copy of a letter, and you tell &kljettool; to print 2 copies of the letter, 2 copies
will still be printed. (in this case, <application>KWord</application> says
"Print the letter".  &kljettool; then says, OK, now I need to print 2 of everything,
so you get 2 copies of the letter. (1 multiplied by 2 = 2 copies)</para>
<para>Finally, if you tell <application>KWord</application> to print 2 copies of
the letter, and you tell &kljettool; to print 2 copies of the letter, you will get 4
copies of the letter. (2 multiplied by 2 = 4 copies.)</para></note></listitem>
</varlistentry>
<varlistentry><term><guilabel>Lines</guilabel></term>
<listitem><para>This determines the number of printed lines on a
page.</para></listitem>
</varlistentry>
<varlistentry><term><guilabel>Orientation</guilabel></term>
<listitem><para>You can choose to have &kljettool; force a page to fit across
(landscape) or up and down a page (portrait).</para></listitem>
</varlistentry>
<varlistentry><term><guilabel>Miscellaneous</guilabel></term>
<listitem><para>Has two options:</para>
<variablelist>
<varlistentry>
<term><guilabel>Manual feed</guilabel></term>
<listitem><para>Used to tell the printer to take paper from the manual feed
slot, rather than the normal paper tray.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Autocontinue</guilabel></term>
<listitem><para>If selected, and if the requested paper size or type is not
available in the printer, the printer will override paper format, and pull paper
from the default tray.  If not selected, the printer will wait for the correct
paper size to be inserted.</para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="operations">
<title><guilabel>Operations</guilabel> Tab</title>

<variablelist>
<varlistentry><term><guilabel>End of Line Mode</guilabel></term>
<listitem><para>Determines how end of lines are sent to the printer.  If you are
not having problems, do not change this.</para></listitem>
</varlistentry>
<varlistentry><term><guilabel>Page Protect</guilabel></term>
<listitem><para>Sets the Page Protect option on your printer.  Refer to your
printer manual for an explanation of this feature.</para></listitem>
</varlistentry>
<varlistentry><term><guilabel>Power Save Time</guilabel></term>
<listitem><para>Determine the time of inactivity before the printer enters
Powersave mode.</para></listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="fonts">
<title><guilabel>Fonts</guilabel> Tab</title>

<para>This box lets you determine the language, Symbol Set and font sizes to use
for printing.</para>

</sect2>

<sect2 id="about-tab">
<title><guilabel>About</guilabel> Tab</title>

<para>This provides program and copyright information.</para>

</sect2>
</sect1>
</chapter>

<chapter id="credits">
<title>Credits and License</title>
<para>
&kljettool;
</para>
<para>
Program copyright 1997-2000 Bernd Johannes Wuebben <email>wuebben@kde.org</email> </para>
<para>Contributors:</para>
<itemizedlist><listitem><para>Espen Sand <email>espen@kde.org</email>
</para></listitem></itemizedlist>
<para>Documentation copyright 2000 Mike McBride<email>mpmcbride7@yahoo.com</email> and Bernd Johannes Wuebben <email>wuebben@kde.org</email>
</para>

&underFDL;
&underGPL;

</chapter>

<![ %addindex; [ &kdedocindex; ]]>
</book>
<!--
Local Variables:
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-omittag:t
sgml-shorttag:t
End:
-->
