path: root/doc/en/index.docbook

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
<!ENTITY mathemagics "Mathemagics" > 
<!ENTITY package "kdenonbeta">
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

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

<authorgroup>
<author>
<firstname>Jason</firstname>
<surname>Katz-Brown</surname>
<affiliation>
<address><email>jason@katzbrown.com</email></address>
</affiliation>
</author>
</authorgroup>

<copyright>
<year>2002</year>
<holder>Jason Katz-Brown</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2002-05-25</date>
<releaseinfo>1.0</releaseinfo>

<abstract><para>&mathemagics; is a scientific RPN calculator for &tde;.</para></abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>Mathemagics</keyword>
<keyword>calculator</keyword>
<keyword>RPN</keyword>
</keywordset>
</bookinfo>

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

<para>This document describes &mathemagics; version 1.0.</para>

<para>&mathemagics; is a full-featured scientific calculator. It uses Reverse Polish Notation, or RPN. &mathemagics; can store and use user-defined functions and variables, and comes with large number of built-in functions.</para>

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

</chapter>


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

<para>This chapter describes usage of &mathemagics;'s features.</para>

<sect1 id="rpn">
<title>Reverse Polish Notation (RPN)</title>

<para>Most calculators use an algebraic system of input. In this system, one enters arguments to a function after entering the function itself. For example, to add 2 and 2, one would enter <userinput>2 + 2</userinput>.</para>

<para>&mathemagics; uses the <emphasis>Reverse Polish Notation</emphasis> system for input. With RPN, arguments are entered before the function. So to add 2 and 2, one would enter "2 2 +".</para>

<para>RPN is based around the <emphasis>stack</emphasis>. The stack stores numbers. When you execute a function, like <guibutton>x^y</guibutton>, the operation takes its arguments from the stack. If there are not enough numbers on the stack, &mathemagics; will tell you. In &mathemagics;, the stack is shown as a pile of line-entries. The first stack level is on the very bottom.</para>
</sect1>

<sect1 id="stack">
<title>Modifying the Stack</title>

<para>To enter something onto the stack, type it into the line-entry on the main toolbar. Then press the Return key. The number you entered will be pushed onto the stack. You can enter multiple numbers onto the stack at once by separating them with spaces. </para>

<para>To modify numbers already on the stack, click in the line-entry that represents the stack level. Then modify the displayed number by typing the new number you want into the line-entry. Finally, press return and the number will be saved onto that stack level. If you ever want to get rid of any stack changes you've made in this way, Choose the <guimenu>Edit</guimenu>-><guimenuitem>Revert Stack Changes</guimenuitem>.</para>

<para>To drop a stack level, replace the text in its line-entry with nothing. Then press return as you normall would in that line-entry.</para>

<para>To roll values on the stack upwards from a level, click the button to the right of the stack level you want to roll from. If the <guilabel>Inv</guilabel> button is checked, this will roll the values down; otherwise, it will roll them up.</para>
</sect1>

<sect1 id="functions">
<title>Using Functions</title>

<para>&mathemagics; comes with many built-in functions. You can access most of them from the <guilabel>Operations</guilabel> menu. The functions take their arguments from the numbers on the stack.</para>

<para>Alternatively, you can type the name of the function directly into the main line-entry.</para>

</sect1>

<sect1 id="variables">
<title>Variables</title>

<para>Variable syntax in &mathemagics; are slightly tricky to use.</para>

<variablelist>
<varlistentry>
<term>Assigning Variables</term>
<listitem>
<para><userinput>2 $example=</userinput> will create the variable <emphasis>example</emphasis> and assign the value <emphasis>2</emphasis> to it.</para>
<para><userinput>2 level $example=</userinput> will create the variable <emphasis>example</emphasis> and assign the value of the second stack level to it.</para>
<para>So, to assign the value on stack level 1 to a variable, write the variable name (prefaced by '$') followed immediately by '='.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Using Variables</term>
<listitem>
<para>To push the variable example on the stack, simply enter <userinput>$example</userinput>. In this way, using variables is the same as using any other number in equations. If you enter a variable that has no value assigned to it, nothing is pushed onto the stack.</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>
</chapter>

<chapter id="scripting">
<title>Scripting</title>

<para>&mathemagics; can be scripted by defining your own functions.</para>

<sect1 id="user-functions">
<title>Defining Your Own Functions</title>

<para>You can define your own functions in &mathemagics;.</para>

<variablelist>
<varlistentry>
<term>Creating Functions</term>
<listitem>
<para><userinput>example=2 *</userinput> will create the function <emphasis>example</emphasis>. As defined, this function multiplies the bottom stack level by two. Functions can use any variables, and even call other functions</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Using Functions</term>
<listitem>
<para>To use the function example, simply enter <userinput>example</userinput>. The function will be evaluated.</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="useful">
<title>Useful Functions for Scripting</title>

<para>There are a few useful built-in functions that you can use when scripting &mathemagics;. Of course, all other built-in functions are also available for use.</para>

<informaltable><tgroup cols="3">
<thead>
<row><entry>Function</entry><entry>Arguments</entry><entry>Result</entry></row></thead>

<tbody>

<row><entry><userinput>reqargs</userinput></entry>
<entry>1: number of required arguments</entry>
<entry>stops function execution if stack does not have enough arguments</entry></row>

<row><entry><userinput>stopif</userinput></entry>
<entry>1: whether or not to stop (1 for true ($true), anything else for false ($false))</entry>
<entry>stop function execution if specified</entry></row>

<row><entry><userinput>at</userinput></entry>
<entry>1: level number (0-indexed)</entry>
<entry>drops stack level 1; pushes value of stack level onto stack</entry></row>

<row><entry><userinput>level</userinput></entry>
<entry>1: level number (1-indexed)</entry>
<entry>drops stack level 1; pushes value of stack level onto stack</entry></row>

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

</sect1>

</chapter>

<chapter id="specific-functions">

<title>Notes on Specific Functions</title>

<para>Some built-in functions in &mathemagics; require extra explanation. This follows.</para>

<sect1 id="lsh-rsh">
<title>Left Shift (lsh) and Right Shift (rsh)</title>
<variablelist>
<varlistentry>
<term><userinput>lsh</userinput> 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 3 lsh</userinput> gives <emphasis>80</emphasis> (10 multiplied by 2 three times).</para>
<para><userinput>10.345 3 lsh</userinput> also gives <emphasis>80</emphasis>.</para></listitem>
</varlistentry>

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

</sect1>

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

<para>The <userinput>and</userinput>, <userinput>or</userinput> and <userinput>xor</userinput> functions perform bitwise logical operations and therefore appear more meaningful if the <guilabel>Base</guilabel> is set to <guilabel>Hexadecimal</guilabel>, <guilabel>Octal</guilabel> or <guilabel>Binary</guilabel> rather than <guilabel>Decmal</guilabel>. In the following examples <guilabel>Base</guilabel> is set to <guilabel>Binary</guilabel>.</para>

<variablelist>
<varlistentry>
<term><userinput>and</userinput> does a logical AND.</term>
<listitem><para><userinput>101 110 and</userinput> gives
<emphasis>100</emphasis></para> </listitem>
</varlistentry>

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

<varlistentry>
<term><userinput>xor</userinput> performs the logical
XOR (exclusive OR) operation.</term>
<listitem><para><userinput>101 110 xor</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>There is a predefined variable pi. To use it, enter <userinput>$pi</userinput>.</para></answer>
</qandaentry>

<qandaentry>
<question><para>How do I get e, the Euler number?</para></question>
<answer><para>There is a predefined variable e. To use it, enter <userinput>$e</userinput>.</para></answer>
</qandaentry>

</qandaset>
</chapter>

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

<para>&mathemagics; Program copyright 2001-2002 Jason Katz-Brown <email>jason@katzbrown.com</email>.</para>

<para>Documentation copyright 2002:</para>
<itemizedlist>
<listitem><para>Jason Katz-Brown <email>jason@katzbrown.com</email></para></listitem>
</itemizedlist>

&underFDL;
<!-- &underBSDLicence; -->

</chapter>

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

<para>&mathemagics; is part of the &tde; project. For more details about &tde; visit <ulink url="http://trinitydesktop.org">http://trinitydesktop.org</ulink>.</para>

<para>&mathemagics;'s website is <ulink
url="https://mirror.git.trinitydesktop.org/gitea/TDE/mathemagics">
https://mirror.git.trinitydesktop.org/gitea/TDE/mathemagics</ulink></para>

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

<para>
In order to compile and install &mathemagics; on your system, type the following in the base directory; distribution:
<screen width="40">
<prompt>%</prompt> <userinput>mkdir -p build</userinput>
<prompt>%</prompt> <userinput>cd build</userinput>
<prompt>%</prompt> <userinput>cmake ../</userinput>
<prompt>%</prompt> <userinput>make</userinput>
<prompt>%</prompt> <userinput>make install</userinput>
</screen>
</para>

<para>Since &mathemagics; uses cmake you should have not trouble compiling it. Default options for cmake build are available in the INSTALL file.</para>

</sect1>
</appendix>

</book>