Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdeedu@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 553 insertions, 0 deletions

diff --git a/doc/kbruch/index.docbook b/doc/kbruch/index.docbook
new file mode 100644
index 00000000..dd7343b2
--- /dev/null
+++ b/doc/kbruch/index.docbook
@@ -0,0 +1,553 @@
+<?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>[email protected]</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>[email protected]</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
+-->