<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
  <!ENTITY kappname "&kcalc;" > <!-- replace kapp here. This only *seems* redundant -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

<book lang="&language;">
<bookinfo>
<title>The &kcalc; Handbook</title>

<authorgroup>
<author>
<firstname>Bernd Johannes</firstname>
<surname>Wuebben</surname>
<affiliation><address><email>wuebben@kde.org</email></address></affiliation>
</author>

<author>
<firstname>Pamela</firstname>
<surname>Roberts</surname>
<affiliation>
<address><email>pam.roberts@btinternet.com</email></address>
</affiliation>
</author>

<othercredit role="reviewer">
<firstname>Lauri</firstname>
<surname>Watts</surname>
<affiliation>
<address><email>lauri@kde.org</email></address>
</affiliation>
<contrib>Reviewer</contrib>
</othercredit>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>2001</year>
<holder>Bernd Johannes Wuebben, Pamela Roberts</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2001-03-11</date>
<releaseinfo>1.03.01</releaseinfo>

<abstract><para>&kcalc; is a scientific calculator for &kde;</para></abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>KCalc</keyword>
<keyword>calculator</keyword>
</keywordset>
</bookinfo>

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

<para>This document describes &kcalc; version 1.3.0.</para>

<para>&kcalc; offers many more mathematical functions than meet the eye
on a first glance. Please study the section on keyboard accelerators and
modes in this handbook to learn more about the many functions
available.</para>

<para>In addition to the usual functionality offered by most scientific
calculators, &kcalc; offers a number of features, which I think are
worthwhile pointing out:</para>

<itemizedlist>
<listitem>
<para>&kcalc; has a trigonometric and a statistics mode.</para>
</listitem>
<listitem>
<para>&kcalc; allows you to cut and paste numbers
from/into its display.</para>
</listitem>
<listitem>
<para>&kcalc; features a <quote>results-stack</quote> which let's
you conveniently recall previous results. </para>
</listitem>
<listitem>
<para>You can
configure &kcalc;'s display colors and font.</para>
</listitem>
<listitem>
<para>You can configure &kcalc;'s  precision and the number
of digits after the period.</para>
</listitem>
<listitem>
<para> &kcalc; offers a great number of useful key-bindings, which make using &kcalc;
without using a pointing device easy.</para>
</listitem>
</itemizedlist>

<para>Have fun with &kcalc;!</para>

<para>Bernd Johannes Wuebben</para>

</chapter>


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

<para>General usage is straight forward and similar to the way most
simple scientific calculators operate, but take note of the following
special &kcalc; features:</para>

<variablelist>
<varlistentry>
<term>Result Stack</term>
<listitem><para>Each time you &LMB; click on the
<guibutton>=</guibutton> button or press your keyboard's
<keycap>Enter</keycap> or <keysym>=</keysym> keys, the display result is
written to &kcalc;'s result stack. You can navigate through the result
stack with your keyboard's <keysym>Up</keysym> and <keysym>Down</keysym>
arrow keys.</para> 
</listitem>
</varlistentry> 

<varlistentry>
<term>Percent Function</term>
<listitem>
<para>The percent function works somewhat differently to that on most
calculators. However, once understood, its enhanced functionality proves
quite useful. See the section about the <link
linkend="percent">percent</link> function for further details.</para>
</listitem></varlistentry>
      
<varlistentry>
<term>Cut and Paste</term>
<listitem>
<para><itemizedlist>
<listitem>
<para>Pressing the &LMB; on &kcalc;'s display will place the displayed
number on to the clipboard.</para>
</listitem>
<listitem>
<para>Pressing the <mousebutton>right</mousebutton> or &MMB; on
&kcalc;'s display will paste the clipboard content into the display if
the content of the clipboard is a valid floating point number.</para>
</listitem>
</itemizedlist>
</para></listitem></varlistentry>

<varlistentry>
<term>Statistical and Trigonometric Modes</term>
<listitem>
<para>&kcalc; can run in <link
linkend="statistical-mode">Statistical</link> or <link
linkend="trigonometric-mode">Trigonometric</link> mode. Pressing
<keycap>F3</keycap> will toggle between the modes or you can set the
mode with the <guilabel>Configuration</guilabel> dialog brought up by
pressing the <guibutton>Configure</guibutton> button or with
<keycap>F2</keycap>.</para> 
</listitem>
</varlistentry>
</variablelist>

<sect1 id="statistical-mode">
<title>Statistical Mode</title>

<para>In this mode the left column of buttons is allocated to statistical
functions:</para>

<informaltable><tgroup cols="2">
<thead>
<row><entry>Buttons</entry>
<entry>Function</entry></row></thead>

<tbody>
<row><entry><guibutton>N</guibutton></entry>
<entry>Recall the number of data items entered</entry></row>

<row><entry><guibutton>Inv</guibutton> <guibutton>N</guibutton></entry>
<entry>Display the sum of all data items entered</entry></row>

<row><entry><guibutton>Mea</guibutton></entry>
<entry>Display the mean of the data items entered</entry></row>

<row><entry><guibutton>Inv</guibutton> <guibutton>Mea</guibutton></entry>
<entry>Display the sum of the square of all data items entered</entry></row>

<row><entry><guibutton>Std</guibutton></entry>
<entry>Display the standard deviation (n)</entry></row>

<row><entry><guibutton>Inv</guibutton> <guibutton>Std</guibutton></entry>
<entry>Display the population standard deviation (n-1)</entry></row>

<row><entry><guibutton>Med</guibutton></entry>
<entry>Display the median</entry></row>

<row><entry><guibutton>Dat</guibutton></entry>
<entry>Enter a data item</entry></row>

<row><entry><guibutton>Inv</guibutton> <guibutton>Dat</guibutton></entry>
<entry>Clear last data item entered</entry></row>

<row><entry><guibutton>Cst</guibutton></entry>
<entry>Clear the store of all data item entered</entry></row>

</tbody></tgroup></informaltable>


</sect1>

<sect1 id="trigonometric-mode">
<title>Trigonometric Mode</title>

<para>In this mode the left column of buttons is allocated to trigonometric
functions:</para>

<informaltable><tgroup cols="2">
<thead>
<row><entry>Buttons</entry>
<entry>Function</entry></row>
</thead>
<tbody>
<row><entry><guibutton>Hyp</guibutton></entry>
<entry>Enter Hyperbolic sub mode. Hyp Sin for example is the hyperbolic sine:
sinh(x)</entry></row>

<row><entry><guibutton>Sin</guibutton></entry>
<entry>Compute the sine</entry></row>

<row><entry><guibutton>Inv</guibutton> <guibutton>Sin</guibutton></entry>
<entry>Compute the inverse sine</entry></row>

<row><entry><guibutton>Cos</guibutton></entry>
<entry>Compute the cosine</entry></row>

<row><entry><guibutton>Inv</guibutton> <guibutton>Cos</guibutton></entry>
<entry>Compute the inverse cosine</entry></row>

<row><entry><guibutton>Tan</guibutton></entry>
<entry>Compute the tangent</entry></row>

<row><entry><guibutton>Inv</guibutton> <guibutton>Tan</guibutton></entry>
<entry>Compute the inverse tangent</entry></row>

<row><entry><guibutton>Log</guibutton></entry>
<entry>Compute the Log base 10</entry></row>

<row><entry><guibutton>Inv</guibutton> <guibutton>Log</guibutton></entry>
<entry>Compute 10 to the power of x</entry></row>

<row><entry><guibutton>Ln</guibutton></entry>
<entry>Compute the natural logarithm. That is the log to base e</entry></row>

<row><entry><guibutton>Inv</guibutton> <guibutton>Ln</guibutton></entry>
<entry>Compute e to the power of x</entry></row>

</tbody></tgroup></informaltable>

</sect1>

<sect1 id="key-accels">
<title>Single Key Accelerators</title>

<para>To simplify entering calculations from the keyboard &kcalc; has single key
accelerators for most functions. For example entering <userinput>7R</userinput>
or <userinput>7r</userinput> will calculate the reciprocal of 7 (1/7).</para>

<informaltable><tgroup cols="3">
<thead>
<row><entry>Key</entry><entry>Function</entry><entry>Notes</entry></row>
</thead>
<tbody>
<row><entry><keycap>H</keycap></entry>
<entry>Hyp</entry>
<entry>Hyperbolic as in <guibutton>Hyp</guibutton> <guibutton>Sin</guibutton> ,
the sinh(x)</entry></row>
<row><entry><keycap>S</keycap></entry>
<entry><guibutton>Sin</guibutton></entry>
<entry></entry></row>
<row><entry><keycap>C</keycap></entry>
<entry><guibutton>Cos</guibutton></entry>
<entry></entry></row>
<row><entry><keycap>T</keycap></entry>
<entry><guibutton>Tan</guibutton></entry>
<entry></entry></row>
<row><entry><keycap>N</keycap></entry>
<entry><guibutton>Ln</guibutton></entry>
<entry>log base e</entry></row>
<row><entry><keycap>L</keycap></entry>
<entry><guibutton>Log</guibutton></entry>
<entry>log base 10</entry></row>
<row><entry><keycap>I</keycap></entry>
<entry> <guibutton>Inv</guibutton></entry>
<entry>Inverse, &eg; if
you want arcsin(x) type <userinput>i s </userinput></entry></row>
<row><entry><keysym>\</keysym></entry>
<entry><guibutton>+/-</guibutton></entry>
<entry>Change sign</entry></row>
<row><entry><keysym>[</keysym></entry>
<entry><guibutton>x^2</guibutton></entry>
<entry></entry></row>
<row><entry><keysym>^</keysym></entry>
<entry><guibutton>x^y</guibutton></entry>
<entry></entry></row>
<row><entry><keysym>!</keysym></entry>
<entry><guibutton>x!</guibutton></entry>
<entry>Factorial</entry></row>
<row><entry><keysym>&lt;</keysym></entry>
<entry><guibutton>Lsh</guibutton></entry>
<entry>Left shift. Note: <guibutton>Inv</guibutton>
<guibutton>Lsh</guibutton> is Right shift</entry></row>

<row><entry><keysym>&amp;</keysym></entry>
<entry><guibutton>And</guibutton></entry>
<entry>Logical AND</entry></row>
<row><entry><keysym>*</keysym></entry>
<entry>*</entry>
<entry>Multiply</entry></row>
<row><entry><keysym>/</keysym></entry>
<entry>/</entry>
<entry>Divide</entry></row>
<row><entry><keycap>D</keycap></entry>
<entry>Dat</entry>
<entry>Enter data item in statistical mode</entry></row>
<row><entry><keycap>O</keycap></entry>
<entry>Or</entry>
<entry>Logical OR. Note: <guibutton>Inv</guibutton>
<guibutton>Or</guibutton> is XOR</entry></row>
<row><entry><keycap>R</keycap></entry>
<entry>1/x</entry>
<entry>Reciprocal</entry></row>

<row><entry><keysym>=</keysym></entry>
<entry><guibutton>=</guibutton></entry>
<entry></entry></row>
<row><entry><keycap>Enter</keycap></entry>
<entry><guibutton>=</guibutton></entry>
<entry></entry></row>
<row><entry><keycap>Return</keycap></entry>
<entry><guibutton>=</guibutton></entry>
<entry></entry></row>

<row><entry><keycap>Page Up</keycap></entry>
<entry>C</entry>
<entry>Clear</entry></row>
<row><entry><keycap>Esc</keycap></entry>
<entry>C</entry>
<entry>Clear</entry></row>
<row><entry><keycap>Prior</keycap></entry>
<entry>C</entry>
<entry>Clear</entry></row>

<row><entry><keycap>Page Down</keycap></entry>
<entry>AC</entry>
<entry>Clear all</entry></row>
<row><entry><keycap>Next</keycap></entry>
<entry>AC</entry>
<entry>Clear all</entry></row>
<row><entry><keycap>Del</keycap></entry>
<entry>AC</entry>
<entry>Clear all</entry></row>

<row><entry><keycap>F1</keycap></entry>
<entry>?</entry>
<entry>Help, brings up this manual</entry></row>

<row><entry><keycap>F2</keycap></entry>
<entry>Configure</entry>
<entry>Bring up the configure dialog</entry></row>

<row><entry><keycap>F3</keycap></entry>
<entry></entry>
<entry>Switch between Trigonometric and Statistical modes</entry></row>

</tbody></tgroup></informaltable>

</sect1>
</chapter>

<chapter id="comments-on-specific-functions">
<title>Comments on Specific Functions</title>

<sect1 id="mod">
<title>Mod and Inv Mod</title>

<variablelist>
<varlistentry>
<term><guibutton>Mod</guibutton> gives the remainder of dividing the displayed
number by the next input number.</term>
<listitem><para><userinput>22 Mod 8 = </userinput> will give the result
<emphasis>6</emphasis></para>
<para><userinput>22.345 Mod 8 = </userinput> will give the result
<emphasis>6.345</emphasis></para>
</listitem></varlistentry>

<varlistentry>
<term><guibutton>Inv</guibutton> <guibutton>Mod</guibutton> does integer
divison of the displayed number by the next input number.</term>
<listitem><para><userinput>22 Inv Mod 8 = </userinput> will give the result
<emphasis>2</emphasis></para>
<para><userinput>22.345 Mod 8 = </userinput> also gives <emphasis>2.</emphasis>
</para></listitem></varlistentry>
</variablelist>

</sect1>


<sect1 id="percent">
<title>&percnt;</title>

<para>Used instead of the <guibutton>=</guibutton> key,
<guibutton>%</guibutton> interprets the final operation carried out in  the
current calculation as follows:</para>

<para><itemizedlist>
<listitem>
<para>If the final operator is + or - show the result as a percentage of the final operand.
</para>
</listitem>
<listitem>
<para>If the final operator is * divide the result of the multiplication by 100.
</para>
</listitem>
<listitem>
<para>If the final operator is / give the left operand
as a percentage of the right operand.
</para>
</listitem>
<listitem>
<para>If the final operator is x^y give the left operand 
raised to the power of the (right operand / 100).
</para>
</listitem>
<listitem>
<para> In all other cases the &percnt; key gives identical results to the = key.
</para>
</listitem>
</itemizedlist></para>

<variablelist>
<varlistentry>
<term>Examples:</term>
<listitem>
<para><userinput>11 + 89 %</userinput> gives <emphasis>112.35..</emphasis> (89 +
11 = 100, and 100 is 112.35 percent of 89)</para>
<para><userinput>42 * 3 %</userinput> gives
<emphasis>1.26</emphasis>  (42 * 3 / 100)</para>
<para><userinput>45 / 55 %</userinput> gives
<emphasis>81.81...</emphasis> (45 is 81.81.. percent of 55)</para>
<para><userinput>2 / 300 %</userinput> gives
<emphasis>8</emphasis>  (2 to the power (300/100))</para>
 </listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="lsh-rsh">
<title>Lsh and Inv Lsh</title>
<variablelist>
<varlistentry>
<term><guibutton>Lsh</guibutton> left shifts the integer part of the displayed
value (multiplies it by 2) n times, where n is the next input number, and
gives an integer result:</term>
<listitem><para><userinput>10 Lsh 3 =</userinput> gives <emphasis>80</emphasis>
(10 multiplied by 2 three times).</para>
<para><userinput>10.345 Lsh 3 =</userinput> also gives
<emphasis>80</emphasis>.</para></listitem>
</varlistentry>

<varlistentry>
<term><guibutton>Inv</guibutton> <guibutton>Lsh</guibutton> right shifts the
value (performs an integer divide by 2) n times.</term>
<listitem><para><userinput>16 Inv Lsh 2 =</userinput> gives
<emphasis>4</emphasis> (16 divided by 2 twice).</para>
<para><userinput>16.999 Inv Lsh 2 =</userinput> also gives
<emphasis>4</emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="and-or-xor">
<title>Cmp, And, Or and Inv Or</title>

<para>The <guibutton>Cmp</guibutton>, <guibutton>And</guibutton> and 
<guibutton>Or</guibutton> functions perform bitwise logical operations and
therefore appear more meaningful if the <guilabel>Base</guilabel> is set to
<guilabel>Hex</guilabel>, <guilabel>Oct</guilabel> or <guilabel>Bin</guilabel>
rather than <guilabel>Dec</guilabel>. In the following
examples <guilabel>Base</guilabel> is set to <guilabel>Bin</guilabel>.</para>

<variablelist>
<varlistentry>
<term><guibutton>Cmp</guibutton> performs a 1's complement (inverts the
bits).</term>
<listitem><para><userinput>101 Cmp</userinput> gives
<emphasis>111...111010</emphasis></para> </listitem>
</varlistentry>

<varlistentry>
<term><guibutton>And</guibutton> does a logical AND.</term>
<listitem><para><userinput>101 And 110 =</userinput> gives
<emphasis>100</emphasis></para> </listitem>
</varlistentry>

<varlistentry>
<term><guibutton>Or</guibutton> does the logical OR.</term>
<listitem><para><userinput>101 Or 110 =</userinput> gives
<emphasis>111</emphasis></para> </listitem>
</varlistentry>

<varlistentry>
<term><guibutton>Inv</guibutton> <guibutton>Or</guibutton> performs the logical
XOR (exclusive OR) operation.</term>
<listitem><para><userinput>101 Inv Or 110 =</userinput> gives
<emphasis>11</emphasis></para> </listitem>
</varlistentry>

</variablelist>
</sect1>
</chapter>


<chapter id="questions-and-answers">
<title>Questions and Answers</title>

<qandaset>

<qandaentry>
<question><para>How do I get pi=3.1415926...?</para></question>
<answer><para>Simply type <userinput>Inv EE</userinput>.</para></answer>
</qandaentry>

<qandaentry>
<question><para>How do I get e, the Euler number?</para></question>
<answer><para>Type <userinput>1 Inv Ln</userinput>.</para></answer>
</qandaentry>

<qandaentry>
<question><para>How do I get two fixed digits after the period?</para></question>
<answer><para>Click on the <guibutton>Configure</guibutton> button, this will
bring up the configuration dialog. Check <guilabel>Set fixed
precision</guilabel> and adjust the spin control so that it shows a
2.</para></answer> </qandaentry>

<qandaentry>
<question><para>What about Precision?</para></question>
<answer><para>The main factor determining the precision of &kcalc; is whether your libc and libmath
supports the C data type <type>long double</type>. If this is the case, &kcalc; will detect this
at compile time and use it as its fundamental data type to represent numbers.
Check &kcalc;'s <guilabel>About</guilabel> dialog (in the
<guibutton>Configure</guibutton> dialog box) in order to find out what the
fundamental data type for your copy of &kcalc; is.</para>

<para>Unless you have a libc and libmath of exceptionally high quality, you will
be able to observe some <quote>interesting</quote> results when trying
to execute computations such as: <userinput>123.22 - 123.21</userinput>,
<userinput>2.01 - 2</userinput>, <userinput>123.88 - 123.87</userinput> and
similar. However if you think this is bad I ask you to do the same computation
on the windows calculator.</para>

<para>Adjust the <guilabel>Precision</guilabel> in &kcalc;'s
<guibutton>Configure</guibutton> dialog so that the above computations
work correctly. I recommend a precision of 14 if the fundamental data type
for your copy of &kcalc; is long double, otherwise 8 or 10.</para>

<para>Higher precision doesn't necessarily lead to better results. Play with
the precision and you will see what I mean.</para>
</answer>
</qandaentry>

</qandaset>
</chapter>

<chapter id="copyright">
<title>Credits and License</title>

<para>&kcalc; Program copyright 1996-2001 Bernd Johannes
Wuebben.<email>wuebben@kde.org</email></para>
<para>Additions by Espen Sand. <email>espen@kde.org</email></para>

<para>&kcalc; was inspired by Martin Bartlett's xfrmcalc, whose stack
engine is still part of &kcalc;.</para>

<para>Documentation copyright 2001:</para>
<itemizedlist>
<listitem><para>Bernd Johannes
Wuebben. <email>wuebben@kde.org</email></para></listitem>
<listitem><para>Pamela Roberts
<email>pam.roberts@btinternet.com</email></para></listitem>
</itemizedlist>

&underFDL;
&underGPL;

</chapter>

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

<para>&kcalc; is part of the kdeutils package within the &kde; project and will
normally be provided as part of a &kde; installation. For more details about
&kde; visit <ulink url="http://www.kde.org">http://www.kde.org</ulink>.</para>

<!--
<para>&kcalc;'s home site is <ulink
url="http://math.cornell.edu/~wuebben/kde.html">
http://math.cornell.edu/~wuebben/kde.html</ulink></para>
-->

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

<para>If you wish to compile &kcalc; by itself, source code can be found at
<ulink url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>, the
main &FTP; site of the &kde; project.</para>

<para>Compile and install with the usual:</para>

<screen>
<prompt>%</prompt> <userinput><command>./configure</command></userinput>
<prompt>%</prompt> <userinput><command>make</command></userinput>
<prompt>%</prompt> <userinput><command>make</command> <option>install</option></userinput>
</screen>
</sect1>

<sect1 id="enable-long-double-precision">
<title>How to enable long double precision for &kcalc;</title>

<para>If your machine supports the C data type <type>long double</type>
and if you have a working libc you can enable <type>long double</type>
precison for &kcalc;.</para>

<para>Here is what to do:</para>

<procedure>
<step>
<para> Check <filename>../config.h</filename> and see whether
HAVE&lowbar;LONG&lowbar;DOUBLE is defined, &ie; you should be able to locate a
line saying:</para>

<screen>#define HAVE_LONG_DOUBLE 1</screen>

<para>If you can't find such a line your system doesn't support long
double IEEE precision. </para>
</step>
<step>
<para>Edit the file <filename class="headerfile">kcalctype.h</filename>
<filename>configdlg.cpp</filename> <filename>kcalc.cpp</filename> and
<filename>kcalc&lowbar;core.cpp</filename> and remove the lines: </para>

<screen>
#ifdef HAVE_LONG_DOUBLE
#undef HAVE_LONG_DOUBLE
#endif
</screen>

</step>
<step>
<para> Recompile &kcalc;.
</para>
</step>
</procedure>

</sect1>
</appendix>

</book>

<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

// vim:ts=0:sw=2:tw=78:noet
-->
