<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
"dtd/kdex.dtd" [

  <!ENTITY kappname "&cantor;">
  <!ENTITY package "kdeedu">
  <!ENTITY latex "L<superscript>A</superscript>T<subscript>E</subscript>X">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
]>
<book id="cantor" lang="&language;">

<bookinfo>
<title>The &cantor; Handbook</title>

<authorgroup>
<author>
<personname>
<firstname>Alexander</firstname>
<surname>Rieder</surname>
</personname>
<email>alexanderrieder@gmail.com</email>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>2009</year>
<holder>Alexander Rieder</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>

<date>2013-10-27</date>
<releaseinfo>0.5 (&kde; 4.12)</releaseinfo>

<abstract>
<para>
&cantor; is an application, aimed at providing a
nice worksheet view to other Free Software Math packages.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdeedu</keyword>
<keyword>mathematics</keyword>
<keyword>math</keyword>
<keyword>Cantor</keyword>
<keyword>Sage</keyword>
<keyword>Python</keyword>
<keyword>Scilab</keyword>
<keyword>R</keyword>
<keyword>Maxima</keyword>
</keywordset>

</bookinfo>

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

<para>
&cantor; is an application to allow you to you use your favorite
mathematical applications from within an elegant &kde;-integrated
Worksheet Interface. It provides dialogs to assist with common tasks
and allows you to share your worksheets with others.
</para>
</chapter>

<chapter id="using-kapp">
<title>Using &cantor;</title>

<para>
Screenshot:
<screenshot>
<screeninfo>Here is a screenshot of &cantor;</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="screenshot.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>Screenshot</phrase>
	  </textobject>
	</mediaobject>
</screenshot>
</para>


<sect1 id="kapp-features">
<title>&cantor; features</title>
<itemizedlist>
  <listitem><para>Intuitive worksheet view for evaluating expressions.</para></listitem>
  <listitem><para>Results of graph plotting shown inside the worksheet.</para></listitem>
  <listitem><para>Easy plugin-based structure to allow different backends to be added.</para></listitem>
  <listitem><para>GetHotNewStuff integration to allow example worksheets to be downloaded (or uploaded.)</para></listitem>
  <listitem><para>Mathematical formula typesetting using &latex;.</para></listitem>
  <listitem><para>Backend-aware syntax highlighting.</para></listitem>
  <listitem><para>Plugin-based assistant dialogs to help with common tasks, such as integrating a function, or entering a matrix.</para></listitem>
</itemizedlist>
</sect1>

<sect1 id="backends">
<title>The &cantor; backends</title>
<para>
  &cantor; offers you several choices for the backends you wish to use with it.
  The choice to make depends on what you want to achieve.
</para>
<para>
  Currently the following backends are available:
  <variablelist>
    <varlistentry>
      <term>Sage:</term>
      <listitem>
	<para>
	  Sage is a free open-source mathematics software system licensed under the GPL.
	  It combines the power of many existing open-source packages, within a common Python-based interface.
	  See <ulink url="http://sagemath.org">http://sagemath.org</ulink> for more information.
	</para>
	</listitem>
    </varlistentry>
    <varlistentry>
      <term>Maxima:</term>
      <listitem>
	<para>
	  Maxima is a system for the manipulation of symbolic and numeric expressions,
	  including differentiation, integration, Taylor series, Laplace transforms,
	  ordinary differential equations, systems of linear equations, polynomials, sets,
	  lists, vectors, matrices, and tensors. Maxima yields high-precision numeric results
	  by using exact fractions, arbitrary precision integers, and variable precision
	  floating point numbers. Maxima can plot functions and data in two and three dimensions.
	  See <ulink url="http://maxima.sourceforge.net">http://maxima.sourceforge.net</ulink> for more information.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>R:</term>
      <listitem>
	<para>
	  R is a language and environment for statistical computing and graphics, similar to the S language and environment.
	  It provides a wide variety of statistical (linear and nonlinear modelling,
	  classical statistical tests, time-series analysis, classification, clustering, ...)
	  and graphical techniques, and is highly extensible. The S language is often the
	  vehicle of choice for research in statistical methodology,
	  and R provides an open-source route to this.
	  See <ulink url="http://www.r-project.org">http://www.r-project.org</ulink> for more information.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>&kalgebra;:</term>
      <listitem>
	<para>
	  &kalgebra; is a MathML-based graph calculator, that ships with &kde; Education project.
	  See <ulink url="http://edu.kde.org/kalgebra/">http://edu.kde.org/kalgebra/</ulink> for more information.
	  </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>Qalculate!:</term>
      <listitem>
  <para>
    Qalculate! is not your regular software replication of the cheapest
    available calculator. Qalculate! aims to make full use of the superior
    interface, power and flexibility of modern computers. The center of
    attention in Qalculate! is the expression entry. Instead of entering each
    number in a mathematical expression separately, you can directly write the
    whole expression and later modify it. The interpretation of expressions is
    flexible and fault tolerant, and if you nevertheless do something wrong,
    Qalculate! will tell you so. Not fully solvable expressions are however not
    errors. Qalculate! will simplify as far as it can and answer with an
    expression. In addition to numbers and arithmetic operators, an expression
    may contain any combination of variables, units, and functions.
    See <ulink url="http://qalculate.sourceforge.net/">http://qalculate.sourceforge.net/</ulink> for more information.
  </para>
  </listitem>
    </varlistentry>
    <varlistentry>
      <term>Python2:</term>
      <listitem>
  <para>
    Python is a remarkably powerful dynamic programming language that is used
in a wide variety of application domains. There are several Python packages
to scientific programming.
  </para>
  <para>Python is distributed under Python Software Foundation license (GPL compatible).
    See the <ulink url="http://www.python.org/">official website</ulink> for more information.
  </para>
  <note>
    <para>
      This backend adds an additional item to the &cantor;'s main menu, <guimenu>Package</guimenu>. The only item of this menu is <menuchoice><guimenu>Package</guimenu><guimenuitem>Import Package</guimenuitem></menuchoice>. This item can be used to import Python packages to the worksheet.
    </para>
  </note>
  <warning>
    <para>
      This backend supports Python 2 only.
    </para>
  </warning>
  </listitem>
    </varlistentry>
    <varlistentry>
      <term>Scilab:</term>
      <listitem>
  <para>
    Scilab is an free software, cross-platform numerical computational package
    and a high-level, numerically oriented programming language.
  </para>
  <para>Scilab is distributed under CeCILL license (GPL compatible).
    See <ulink url="http://www.scilab.org/">http://www.scilab.org/</ulink> for more information.
  </para>
  <warning>
    <para>
      You need Scilab version 5.5 or higher to be installed in your system to make this backend usable.
    </para>
  </warning>
  </listitem>
    </varlistentry>
    <varlistentry>
      <term>Octave:</term>
      <listitem>
  <para>
    &GNU; Octave is a high-level language, primarily intended for numerical
    computations. It provides a convenient command line interface for
    solving linear and nonlinear problems numerically, and for performing other
    numerical experiments using a language that is mostly compatible with <ulink url="http://www.mathworks.com/products/matlab/">MATLAB</ulink>.
    See <ulink url="http://www.gnu.org/software/octave/">http://www.gnu.org/software/octave/</ulink> for more information.
    </para>
      </listitem>
    </varlistentry>
  </variablelist>
</para>
</sect1>

<sect1 id="workspace">
<title>The &cantor; Workspace</title>
<para>
<screenshot>
  <screeninfo>Screenshot of the &cantor; Workspace</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="screenshot.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>Screenshot of the &cantor; Workspace</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>
<para>
  The Worksheet interface of &cantor; consists of three parts:
  <orderedlist>
    <listitem><para>The tab bar, where you can switch through the open worksheets.</para></listitem>
    <listitem><para>A help panel, where help for a specific command is displayed if you enter "? command".</para></listitem>
    <listitem><para>A Variable Manager panel where you can see the list of all available variables on the current worksheet. The Help and Variable Manager panels are shown as tabs on a sidebar of a &cantor; window. Variable manager can be used for Maxima (if enabled on <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &cantor;...</guimenuitem></menuchoice> <guilabel>Maxima</guilabel> page), &kalgebra;, Octave, Python2, Qalculate, and Scilab backends only.</para></listitem>
    <listitem><para>The worksheet itself.</para></listitem>
  </orderedlist>
</para>
<sect2 id="worksheet">
<title>The Worksheet</title>
<para>
  The worksheet is the basic area for working with &cantor;.  Using it, you can enter
  expressions, allow the backend to perform calculations, and look at the results.
  The commands the worksheets accept depend on the chosen backend, so you should
  learn the appropriate backend syntax (the Show Help button takes you there directly).
  If you know the command, but you need additional information, you can type "? <replaceable>command</replaceable>",
  and contextual help will appear on the right of the worksheet.
  If you want to see some example worksheets, you can go to <guimenuitem>Download Example Worksheets</guimenuitem>
  in the <guimenu>File</guimenu> menu, and download worksheets other users have published.
</para>
<para>
  To control each command entry of the worksheet you can use control buttons shown at the right part of the worksheet when hovering the entry field with a mouse cursor. There are three basic actions for each entry: <guilabel>Evaluate Entry</guilabel> to update the result of calculations for the entry, <guilabel>Drag Entry</guilabel> to move the entry at the other place of the current worksheet and <guilabel>Remove Entry</guilabel> to remove the entry from the current worksheet.
</para>
<para>
  Font settings and alignment of worksheet entries can be changed using a toolbar above the worksheet.
</para>
<sect3 id="worksheet-settings">
  <title>Settings</title>
  <para>
    The <guimenu>Settings</guimenu> menu allows you to change some settings of the appearance of your
    current worksheet.
  </para>
  <variablelist>
    <varlistentry>
      <term>Typesetting using &latex;</term>
      <listitem>
	<para>
	  This setting changes the way results are presented to you. If enabled, it passes the result through
	  the &latex; system, to produce visually appealing formulas. For example, <quote>3*x^2*sqrt(2)*x+2/3</quote> becomes
	  <inlinemediaobject>
	      <imageobject>
		<imagedata fileref="latex_formula.png" format="PNG"/>
	      </imageobject>
	      <textobject><phrase>3*x^2*sqrt(2)*x+2/3</phrase></textobject>
	  </inlinemediaobject>
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>Syntax Highlighting</term>
      <listitem>
	<para>
	  Syntax Highlighting increases the readability of code, by highlighting
	  keywords, or matching brackets in different colors.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>Completion</term>
      <listitem>
	<para>
	  When this is enabled, &cantor; will show you possible completions
	  for the command you are currently typing when you press the Tab-key. If there is only one choice
	  remaining, it will insert the rest of the command for you.
	</para>
      </listitem>
    </varlistentry>
  <varlistentry>
    <term>Line Numbers</term>
    <listitem>
      <para>
	This setting controls whether the different expressions should have a number in front.  This allows you
	to recall older results - in Maxima, for instance, this is done with the <quote>%O1</quote> command.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Animate Worksheet</term>
    <listitem>
      <para>
  This setting controls whether the different animations will be used to highlight changes on a worksheet.
      </para>
    </listitem>
  </varlistentry>
  </variablelist>
</sect3>
</sect2>
</sect1>
<!--
<sect1 id="assistant-dlgs">
<title>The assistant dialogs</title>
TODO add screenshots and descriptions of each assistant
</sect1>
-->
</chapter>
<chapter id="commands">
<title>Command Reference</title>

<sect1 id="kapp-mainwindow">
<title>The main &cantor; window</title>

<para>
&cantor; has the common &kde; menu items, for more information read the <ulink url="help:/fundamentals/ui.html#menus"
>Menu</ulink> chapter of the &kde; Fundamentals.
</para>

<para>Additional or special menu items in &cantor;:
</para>

<sect2 id="file-menu">
<title>The File Menu</title>
<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>New</guimenuitem>
</menuchoice></term>
<listitem><para><action>Creates a new worksheet with the default backend.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guisubmenu>New</guisubmenu>
<guimenuitem><replaceable>Backend</replaceable></guimenuitem>
</menuchoice></term>
<listitem><para><action>Creates a new worksheet with the chosen backend.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Download Example Worksheets</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens the dialog to download examples uploaded by other &cantor; users with
 <ulink url="http://userbase.kde.org/Special:MyLanguage/Glossary#Get_Hot_New_Stuff">GetHotNewStuff</ulink>.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Open Example</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens the dialog to choose an example to load.</action> The examples should be downloaded with <menuchoice><guimenu>File</guimenu>
<guimenuitem>Download Example Worksheets</guimenuitem></menuchoice> beforehand.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Save Plain Text</guimenuitem>
</menuchoice></term>
<listitem><para><action>Allows saving the current worksheet as a plain text document.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Export to LaTeX</guimenuitem>
</menuchoice></term>
<listitem><para><action>Allows saving the current worksheet as a &latex; document.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Publish Worksheet</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens the dialog to publish your current worksheet and make it available to other &cantor; users through
 <ulink url="http://userbase.kde.org/Special:MyLanguage/Glossary#Get_Hot_New_Stuff">GetHotNewStuff</ulink>.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Run Script</guimenuitem>
</menuchoice></term>
<listitem><para><action>Allows to load and run the batch scripts for the current backend.</action></para></listitem>
</varlistentry>
</variablelist>
</para>

</sect2>

<sect2 id="view-menu">
<title>The View Menu</title>
<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>+</keycap></keycombo>
</shortcut>
<guimenu>View</guimenu>
<guimenuitem>Zoom In</guimenuitem>
</menuchoice></term>
<listitem><para><action>Zoom in</action> the current worksheet by 10%.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>-</keycap></keycombo>
</shortcut>
<guimenu>View</guimenu>
<guimenuitem>Zoom Out</guimenuitem>
</menuchoice></term>
<listitem><para><action>Zoom out</action> the current worksheet by 10%.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>View</guimenu>
<guimenuitem>Show Script Editor</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens the batch script editor window for the current backend.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>View</guimenu>
<guisubmenu>Panels</guisubmenu>
<guimenuitem>Help</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggles</action> the visibility of the <guilabel>Help</guilabel> tab in the sidebar.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>View</guimenu>
<guisubmenu>Panels</guisubmenu>
<guimenuitem>Variable Manager</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggles</action> the visibility of the <guilabel>Variable Manager</guilabel> tab in the sidebar.</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>

<sect2 id="worsheet-menu">
<title>The Worksheet Menu</title>
<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<guimenu>Worksheet</guimenu>
<guimenuitem>Evaluate Worksheet</guimenuitem>
</menuchoice></term>
<listitem><para><action>Triggers</action> the evaluation of the whole worksheet.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Shift;<keycap>Return</keycap></keycombo>
</shortcut>
<guimenu>Worksheet</guimenu>
<guimenuitem>Evaluate Entry</guimenuitem>
</menuchoice></term>
<listitem><para><action>Triggers</action> the current entry evaluation.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>Return</keycap></keycombo>
</shortcut>
<guimenu>Worksheet</guimenu>
<guimenuitem>Insert Command Entry</guimenuitem>
</menuchoice></term>
<listitem><para><action>Inserts a new command entry below the current cursor position.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Worksheet</guimenu>
<guimenuitem>Insert Text Entry</guimenuitem>
</menuchoice></term>
<listitem><para><action>Inserts a new text entry below the current cursor position.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Worksheet</guimenu>
<guimenuitem>Insert Image</guimenuitem>
</menuchoice></term>
<listitem><para><action>Inserts the image template below the current cursor position.</action> You will need to click with &RMB; at the template to configure the image details.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Worksheet</guimenu>
<guimenuitem>Insert Page Break</guimenuitem>
</menuchoice></term>
<listitem><para><action>Inserts the page break below the current cursor position.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Shift;<keycap>Del</keycap></keycombo>
</shortcut>
<guimenu>Worksheet</guimenu>
<guimenuitem>Remove current Entry</guimenuitem>
</menuchoice></term>
<listitem><para><action>Removes</action> current entry from the worksheet.</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>

<sect2 id="settings-menu">
<title>The Settings Menu</title>
<para>
This menu contains standard &kde; <guimenu>Settings</guimenu> items, as well as the items described in <link linkend="worksheet-settings">Settings section</link>.
</para>
</sect2>

<sect2 id="help-menu">
<title>The Help Menu</title>

&help.menu.documentation;

</sect2>

</sect1>
</chapter>

<chapter id="developers">
<title>Developer's Guide to &cantor;</title>

<para>
&cantor; is easily extendable by plugins. You can write
<variablelist>
  <varlistentry>
    <term>Backends:</term>
    <listitem>
      <para>
	A new backend enables you to use the &cantor; interface with a different program.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Assistants:</term>
    <listitem>
      <para>
	Assistants provide dialogs to allow common tasks to be automated (such entering a matrix or running a script.)
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
At present, there are no special developer tutorials or API documentation, so if you want to write a plugin you will have to read through the sources.
All interface definitions are in the <filename role="directory">lib</filename> directory.  For some example implementations, look at the plugins shipped with &cantor;.
</para>

</chapter>

<chapter id="faq">
<title>Questions and Answers</title>

&reporting.bugs;
&updating.documentation;

<qandaset id="faqlist">
<qandaentry>
  <question><para>The Menu Item <guimenuitem>Typeset using LaTeX</guimenuitem> is not available</para></question>
  <answer><para>Not every backend supports every option. Current version supports &latex; output for Maxima, Qalculate! and Sage backends.</para></answer>
</qandaentry>
<qandaentry>
  <question><para>I have installed Sage/Maxima, but the appropriate backend does not appear.</para></question>
  <answer>
    <para>
      One possible explanation is that &cantor; did not correctly detect the location. Go to the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kappname;...</guimenuitem></menuchoice> dialog and change
      the <guilabel>Path</guilabel> to the appropriate application.
    </para>
  </answer>
</qandaentry>
<qandaentry>
  <question><para>What a peculiar name - what does it have to do with mathematics?</para></question>
  <answer><para>&cantor; is named after the German mathematician <ulink url="http://en.wikipedia.org/wiki/Georg_Cantor">Georg Cantor</ulink>, the creator of set theory.</para></answer>
</qandaentry>
</qandaset>
</chapter>

<chapter id="credits">

<title>Credits and License</title>

<para>
&cantor;
</para>
<para>
Program copyright 2009-2011 Alexander Rieder <email>alexanderrieder@gmail.com</email>
</para>

<para>
Documentation Copyright &copy; 2009-2011 Alexander Rieder <email>alexanderrieder@gmail.com</email>
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;               <!-- FDL: do not remove -->
&underGPL;        	 <!-- GPL License -->
</chapter>

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

<sect1 id="getting-kapp">
<title>How to obtain &cantor;</title>

&install.intro.documentation;

</sect1>

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

<para>
In order to successfully use &cantor;, you need &kde; 4.
If you want support for type-setting to be enabled, you need to install &latex; and LibSpectre.
To use the different Backends, the appropriate math package is required.
</para>

<!--
<para>
All required libraries as well as &cantor; itself can be found
on <ulink url="ftp://ftp.kapp.org">The &cantor; home page</ulink>.
</para>
-->


<!-- For a list of updates, you may refer to the application web site
or the ChangeLog file, or ... -->
<!--
<para>
You can find a list of changes at <ulink
url="http://apps.kde.org/kapp">http://apps.kde.org/kapp</ulink>.
</para>
-->
</sect1>

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

&install.compile.documentation;

</sect1>

<sect1 id="configuration">
<title>Configuration</title>

<para>
  Depending on your system, you may need to adjust the paths to the
  different applications used by &cantor;.
</para>

</sect1>

</appendix>

&documentation.index;
</book>

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

vim:tabstop=2:shiftwidth=2:expandtab
kate: space-indent on; indent-width 2; tab-width 2; indent-mode none;
-->
