path: root/doc/kbruch/index.docbook

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

<book lang="&language;">

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

<authorgroup>
<author>
<firstname>Sebastian</firstname>
<surname>Stein</surname>
<affiliation>
<address><email>seb.kde@hpfsc.de</email></address>
</affiliation>
</author>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>

<copyright>
<year>2001-2005</year>
<holder>Sebastian Stein</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2004-07-09</date>
<releaseinfo>3.4</releaseinfo>

<abstract>
<para>&kbruch; is a small program to practice calculating with fractions.
Different exercises are provided for this purpose. The program checks user's
input and gives feedback.
</para>
	
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>education</keyword>
<keyword>fraction</keyword>
<keyword>mathematics</keyword>
<keyword>denominator</keyword>
<keyword>kbruch</keyword>
</keywordset>

</bookinfo>

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

<para>
&kbruch; is a small program to practice calculating with fractions. Therefore
4 different exercises are offered.
</para>

<itemizedlist>
	<listitem><para>
		Fraction Task - in this exercise you have to solve a given fraction task.
You have to enter numerator and denominator. This is the main exercise.
	</para></listitem>
	<listitem><para>
		Comparison - in this exercise you have to compare the size of 2 given
fractions.
	</para></listitem>
	<listitem><para>
		Conversion - in this exercise you have to convert a given number into a
fraction.
	</para></listitem>
	<listitem><para>
		Factorization - in this exercise you have to factorize a given number into its prime factors.
	</para></listitem>
</itemizedlist>

<para>
In all different exercises &kbruch; will generate a task and the user has to
solve it. The program checks the input and gives a feedback about it.
</para>

<para>
&kbruch; counts how many tasks were solved at all and how many tasks were
solved correctly. The statistics are shown to the user, but this part of the
main window can be hidden. The user can reset the statistics at any point.
</para>

<para>
&kbruch; is very compact and focuses on the core idea of a task generator. An
online help system provides context-sensitive help for the different
situations. 
</para>
<para>
&kbruch; is free and licensed under the &GNU; Public License.
</para>
</chapter>


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

<sect1 id="overview">
<title>Main screen</title>

<para>Here is a screenshot of &kbruch;'s main screen:</para>

<screenshot>
	<screeninfo>&kbruch; main screen, directly after the start</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="gui_main.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>&kbruch; main screen</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<para>
All action takes place in this screen. This ensures that &kbruch; is
easy to use even for young users! The main screen is separated into 5
parts:

<itemizedlist>
	<listitem><para>
		the menubar with the 3 menus <guimenu>Task</guimenu>,
<guimenu>Settings</guimenu> and <guimenu>Help</guimenu>
	</para></listitem>
	<listitem><para>
		the toolbar, where you can set the difficulty for the tasks given in the
		<guimenu>Fraction Task</guimenu> exercise
	</para></listitem>
	<listitem><para>
		the exercise chooser, where you can switch between the different exercises
	</para></listitem>
	<listitem><para>
		the task part, where you have to enter the result of the given task
	</para></listitem>
	<listitem><para>
		the statistical part, where you can see how many tasks have been solved
		correctly or attempted
	</para></listitem>
</itemizedlist>
</para>
<para>
First you have to choose an exercise in the exercise chooser on the left side
of the window. The task part will change according to the chosen task. The
settings in the toolbar will be enabled, if you have chosen the exercise
<guimenu>Fraction Task</guimenu>.
</para>
<para>
You will find an icon to generate a new task in the toolbar as well. This
action is also available in the menu
<menuchoice><guimenu>Task</guimenu><guimenuitem>New
Task</guimenuitem></menuchoice>. This action is always enabled. If you have not
solved the currently given task, a new task is generated and the given task is
counted as not correctly solved.
</para>
<para>
You can hide the statistic part by dragging the vertical separator to the
right.
</para>
<para>
If you terminate &kbruch; the currently chosen exercise will be saved and
restored on next startup.
</para>
</sect1>

<sect1 id="statistics">
<title>Statistical Part</title>
<para>
In this part of the main screen you can see:	
<itemizedlist>
	<listitem><para>
		how many tasks have been solved
	</para></listitem>
	<listitem><para>
		how many tasks have been solved correctly
	</para></listitem>
	<listitem><para>
		how many tasks have been solved incorrectly
	</para></listitem>
</itemizedlist>
</para>
<para>
You can reset the statistics by clicking on the <guimenu>Reset</guimenu> button
under the figures.
</para>
<para>
The statistics will be saved on &kbruch;'s termination and restored on next
startup.
</para>
</sect1>

<sect1 id="settings">
<title>Settings Window</title>
<para>
In this part of the main screen you can adjust some general settings for
task display. To open this dialog use
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
&kbruch;</guimenuitem></menuchoice>.
</para>

<screenshot>
	<screeninfo>&kbruch; settings dialog</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="settings.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>&kbruch; settings dialog</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<para>
In the top part of the dialog you can choose a font for displaying. In the
lower part you can choose colors for the different parts of a mathematical
expression. You can set wether to show the mixed number notation in the result.
This notation is not known everywhere and can be disabled therefore. 
</para>
<para>
The settings will be saved on &kbruch;'s termination and restored on the next
startup.
</para>
</sect1>

</chapter>

<chapter id="exercises">
<title>Exercises</title>

<sect1 id="exer_fraction">
<title>Exercise Fraction Task</title>

<para>In this exercise you have to solve a given task. Therefor you have to
enter numerator and denominator. The difficulty of the generated task can be
adjusted by the task parameters described below.
</para>

<sect2 id="task_paras">
<title>Task Parameters</title>
<para>
There are 3 parameters which influence the difficulty of the generated
tasks:</para>

<variablelist>
<varlistentry>
<term><guilabel>Terms</guilabel></term>
<listitem><para>The number of terms (separate fractions) given in each
task. From 2 to 5, inclusive.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Max. main denominator</guilabel></term>
<listitem><para>The highest number &kbruch; will use as the main denominator in the
tasks it sets. From a minimum of 10 to a maximum of 50.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Operations</guilabel></term>
<listitem><para>Operations which should be used in the
task: <guilabel>Addition/Subtraction</guilabel>,
<guilabel>Multiplication/Division</guilabel> or <guilabel>All Operations Mixed</guilabel>.</para></listitem>
</varlistentry>
</variablelist>

<para>
After you have changed the parameters you have to click on the <guimenu>New
Task</guimenu> button in the toolbar to generate a task which uses the new
parameters. You can also call this action from the menubar with
<menuchoice><guimenu>Task</guimenu><guimenuitem>New
Task</guimenuitem></menuchoice>.
</para>
<note>
<para>
Your selection of the maximum main denominator will be reset to a default
value every time you change the number of terms. So you should change the 
number of terms first and then select the maximum main denominator.
</para>
</note>
<para>
If you have not solved the current task and call the <guimenu>New
Task</guimenu> action, the task will be counted as not solved correctly. To
prevent this you have to change the parameters after you solved the task but
before generating a new one.
</para>
<para>
The chosen parameters will be saved on &kbruch;'s termination and restored
on next startup.
</para>
</sect2>

<sect2 id="exer_fraction_solve_task">
<title>Solving Tasks</title>
<para>
After you have solved a given task, you need to enter the result into the two
input boxes. In the upper box you enter the numerator and in the lower
box the denominator.
</para>
<para>
If the result is negative, you can enter a minus sign in front of the numerator
or denominator. If the result is 0, just type a 0 in the numerator input field.
If the result has a denominator of 1, you can leave the lower box empty.
</para>
<para>
After you have entered the result you should click the <guibutton>Check
Task</guibutton> button below the input boxes. &kbruch; will check your input
and present the correct result. Therefore the screen changes a little, as
you can see in the screenshot:
</para>
<screenshot>
<screeninfo>Checked Task</screeninfo>
<mediaobject>
  <imageobject>
		<imagedata fileref="checked.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase>Checked Task</phrase>
  </textobject>
</mediaobject>
</screenshot>
<para>
This task was solved correctly. The correct value is shown in 2 different
forms. The second form just in front of the word <guilabel>CORRECT</guilabel>
is only used in some countries and must be read as 2 + 1/5 in the given case.
</para>
<note>
<para>
You always have to enter the result reduced, because most teachers only
give all points to reduced results. &kbruch; will show you a short message
like the one in the screenshot below, if you enter the correct result
unreduced.
</para>
</note>
<screenshot>
<screeninfo>Unreduced Result</screeninfo>
<mediaobject>
  <imageobject>
		<imagedata fileref="reduced.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase>Unreduced Result</phrase>
  </textobject>
</mediaobject>
</screenshot>

<para>
To continue with the next task, click on the <guimenu>Next Task</guimenu>
button. If you want to change the parameters for the next task please do this
before clicking on the <guimenu>Next Task</guimenu> button.
</para>
</sect2>
</sect1>

<sect1 id="exer_compare">
<title>Exercise Comparison</title>

<para>In this exercise you have to compare 2 given fractions. You have to choose
the bigger fraction of both by selecting the correct comparison sign.
</para>

<screenshot>
<screeninfo>Exercise Comparison</screeninfo>
<mediaobject>
  <imageobject>
		<imagedata fileref="compare.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase>Exercise Comparison</phrase>
  </textobject>
</mediaobject>
</screenshot>

<para>First choose the correct comparison sign. To toggle the comparison sign,
you have to click on the button showing the comparison sign. After you have
chosen the comparison sign click on the <guimenu>Check Task</guimenu> button.
&kbruch; will check your input and present the correct result. After this step
you will get to the next task by clicking on the <guimenu>Next Task</guimenu>
button.
</para>
</sect1>

<sect1 id="exer_convert">
<title>Exercise Conversion</title>

<para>In this exercise you have to convert a given number into a fraction. You
have to enter numerator and denominator.
</para>

<screenshot>
<screeninfo>Exercise Conversion</screeninfo>
<mediaobject>
  <imageobject>
		<imagedata fileref="convert.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase>Exercise Conversion</phrase>
  </textobject>
</mediaobject>
</screenshot>

<para>On the left side of the equal sign in the screenshot above you can see a
recurring decimal. This means, that the fraction shown as a decimal has a
repeating part. The repeating part is marked with the small bar above the
numbers. Those numbers repeat ad infinitum.
</para>

<para>After you have entered the numerator and denominator click on the
<guimenu>Check Task</guimenu> button. &kbruch; will check your input and
present the correct result. After this step you will get to the next task by
clicking on the <guimenu>Next Task</guimenu> button.
</para>

<note>
<para>
Do not forget to enter the result reduced. Unreduced results will be counted as
solved not correctly.
</para>
</note>
</sect1>

<sect1 id="exer_factorize">
<title>Exercise Factorization</title>

<para>In this exercise you have to factorize a given number into its prime
factors. You have to enter all prime factors of the number.
</para>

<screenshot>
<screeninfo>Exercise Factorization</screeninfo>
<mediaobject>
  <imageobject>
		<imagedata fileref="factorize.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase>Exercise Factorization</phrase>
  </textobject>
</mediaobject>
</screenshot>

<para>You can enter a factor by clicking on the prime <guimenu>factor
buttons</guimenu>. The currently entered prime factors will be shown in the
field next to the number to be factorized. You can remove the last entered
prime factor by clicking on the <guimenu>Remove Last Factor</guimenu> button.
</para>
<para>
After you have entered all prime factors click on the
<guimenu>Check Task</guimenu> button. &kbruch; will check your input and
present the correct result. After this step you will get to the next task by
clicking on the <guimenu>Next Task</guimenu> button.
</para>

<para>In the screenshot at the top of this page you can see a <quote>*</quote>
between the prime factors. This is the multiplication sign. The product of all
prime factors must be the number you try to factorize.
</para>

<note>
<para>
You have to enter all prime factors even when a prime factor repeats several
times. Example: As prime factors of number 18 you have to enter 2, 3 and 3.
</para>
</note>
</sect1>

</chapter>

<chapter id="credits">

<title>Credits and License</title>
<para>&kbruch;</para>
<para>
Program and documentation Copyright, 2001-2004 Sebastian Stein
 <email>seb.kde@hpfsc.de</email>
</para>

<para>Thank you goes to:</para>

<itemizedlist>
	<listitem><para>&Anne-Marie.Mahfouf; for managing the &kde;-edu project</para></listitem>
	<listitem><para>Klas Kalass for helping design the interface</para></listitem>
	<listitem><para>Eva Brucherseifer for writing <application>KMath</application> (&kbruch;'s &GUI; is based on this work)</para></listitem>
	<listitem><para>Dominique Devriese for bug fixing</para></listitem>
	<listitem><para><ulink url="http://www.net-tex.de/">Stefan Schumacher</ulink> for testing a very early version</para></listitem>
	<listitem><para><ulink url="http://www.guckes.net/">Sven Guckes</ulink> for testing the text interface (which has been removed)</para></listitem>
	<listitem><para>&David.Faure; for helping with &kde; <acronym>CVS</acronym> and &kde; Bugzilla</para></listitem>
	<listitem><para>&Robert.Gogolok; for helping with &kde; <acronym>CVS</acronym></para></listitem>
	<listitem><para>John Kesson for proof reading the handbook</para></listitem>
</itemizedlist>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

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

</chapter>

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

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

&install.intro.documentation;

</sect1>

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

<para>
In order to successfully use &kbruch;, you need &kde; > 3.1 .
</para>

<para>
&kbruch; itself can be found
on <ulink url="http://edu.kde.org/kbruch/">the &kbruch; home page</ulink>
and it is part of the &kde;-edu project</para>

<para>You can find a list of changes in the <acronym>CVS</acronym> commit
messages.</para>

</sect1>

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

&install.compile.documentation;

</sect1>

</appendix>

&documentation.index;
</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=2:sw=2:tw=78:noet
-->