Commit ed257511 authored by Philip Rodrigues's avatar Philip Rodrigues

Some updates by Frederik Edemar, which I've proofread. Some more

proofreading needed.

svn path=/trunk/kdeedu/doc/kmplot/; revision=328366
parent e91c445e
......@@ -147,23 +147,136 @@ Settings</guilabel> dialog box. See <xref linkend="configuration"/>.
</sect1>
<sect1 id="a-functions-menu">
<title>The <guimenu>Functions</guimenu> Menu</title>
<title>The <guimenu>Plot</guimenu> Menu</title>
<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu>Functions</guimenu>
<guimenuitem>Functions</guimenuitem>
<guimenuitem>New Function Plot...</guimenuitem>
</menuchoice>
</term>
<listitem><para>Displays the functions dialog. See <xref
<listitem><para>Opens the dialog for creating a new function plot. See <xref
linkend="using-kmplot"/>.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<menuchoice>
<guimenu>Functions</guimenu>
<guimenuitem>New Parametric Plot...</guimenuitem>
</menuchoice>
</term>
<listitem><para>Opens the dialog for creating a new parametric plot. See <xref
linkend="using-kmplot"/>.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<menuchoice>
<guimenu>Functions</guimenu>
<guimenuitem>New Polar Plot...</guimenuitem>
</menuchoice>
</term>
<listitem><para>Opens the dialog for creating a new polar plot. See <xref
linkend="using-kmplot"/>.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<menuchoice>
<guimenu>Functions</guimenu>
<guimenuitem>Edit Plots...</guimenuitem>
</menuchoice>
</term>
<listitem><para>Displays the functions dialog. There you can add, edit and remove functions. See <xref
linkend="using-kmplot"/>.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="a-zoom-menu">
<title>The <guimenu>Zoom</guimenu> Menu</title>
<para>The first five items in the menu change zoom-mode.</para>
<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu>Zoom</guimenu>
<guimenuitem>No Zoom</guimenuitem>
</menuchoice>
</term>
<listitem><para>Disable the zoom-mode.</para></listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu>Zoom</guimenu>
<guimenuitem>Zoom rectangular</guimenuitem>
</menuchoice>
</term>
<listitem><para>Let the user draw a rectangle. The minimum and maximum values will be set to the cordinates of the rectangle.</para></listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu>Zoom</guimenu>
<guimenuitem>Zoom in</guimenuitem>
</menuchoice>
</term>
<listitem><para>The minimum and maximum values will come closer to eachother and the selected point in the graph will be centered.</para></listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu>Zoom</guimenu>
<guimenuitem>Zoom out</guimenuitem>
</menuchoice>
</term>
<listitem><para>The minimum and maximum values will be more seperated from eachother and the selected point in the graph will be centered.</para></listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu>Zoom</guimenu>
<guimenuitem>Center a point</guimenuitem>
</menuchoice>
</term>
<listitem><para>The selected point in the graph will be centered.</para></listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu>Zoom</guimenu>
<guimenuitem>Fit widget to trigonometric functions</guimenuitem>
</menuchoice>
</term>
<listitem><para>The scale will be adapted to trigometric functions. This works both for radians and degrees.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="a-settings-menu">
<title>The <guimenu>Settings</guimenu> Menu</title>
......@@ -243,6 +356,27 @@ that &kmplot; knows.</para>
</sect1>
<sect1 id="a-tools-menu">
<title>The <guimenu>Tools</guimenu> Menu</title>
<para>This menu constains some tools for the functions that can be useful:</para>
<variablelist>
<varlistentry>
<term><menuchoice><guimenu>Tools</guimenu>
<guimenuitem>Get y-value</guimenuitem>
</menuchoice></term>
<listitem>
<para>Let the user get the y-value from a specific x-value. At the moment, only plot functions are supported. Type a value or expression in the textbox under "X:". In the list below all the available functions are shown. Press the "Calculate" button to find the function's y-value. The result will be shown in the y-value box.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The standard &kde; <guimenu>Help</guimenu> entries are:</para>
&help.menu.documentation;
</sect1>
</chapter>
<!--
......
......@@ -3,12 +3,12 @@
<para>To access the &kmplot; configuration
dialog, select <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
KmPlot...</guimenuitem></menuchoice>. A number of settings can also be changed
from options in the <guimenu>View</guimenu> menu, as well. </para>
from options in the <guimenu>Edit</guimenu> menu, as well. </para>
<note>
<para>Settings changed in the &kmplot; configuration dialog become the
default for &kmplot;, and only take effect when a new plot is started. Settings
changed in the <guimenu>View</guimenu> menu take effect immediately, but do not
changed in the <guimenu>Edit</guimenu> menu take effect immediately, but do not
persist after &kmplot; is exited.</para>
</note>
......
......@@ -5,37 +5,56 @@
<title>Simple Function Plot</title>
<para>
In the main toolbar there is a simple edit line to enter a function expression. Simply enter:
<screen><userinput>x^2</userinput></screen>
This will draw the plot of y=x^2 in the coordinate system. Enter another expression in the edit line like
<screen><userinput>5*sin(x)</userinput></screen>
and another plot will be added.
In the main toolbar there is a simple text box in which you can enter
a function expression. Simply enter:
<screen><userinput>x^2</userinput></screen> and press &Enter;. This
will draw the plot of y=x^2 in the coordinate system. Enter another
expression in the text box like
<screen><userinput>5*sin(x)</userinput></screen> and another plot will
be added.
</para>
<para>Click onto the plot. Now the cross hair gets the color of the plot and is attached to the plot.
You can use the mouse to move the crosshair along the plot.
In the status bar at the bottom of the window the coordinates of the current position is displayed. Note that if the plot touches the x-axis the root will be displayed in the status bar, too.</para>
<para>Click on one of the lines you have just plotted. Now the cross
hair gets the color of the plot and is attached to the plot. You can
use the mouse to move the cross hair along the plot. In the status
bar at the bottom of the window the coordinates of the current
position is displayed. Note that if the plot touches the x-axis the
root will be displayed in the status bar, too.</para>
<para>Click the mouse again and the crosshair will be detached from the plot.</para>
<para>Click the mouse again and the cross hair will be detached from
the plot.</para>
</sect1>
<sect1 id="edit-properties">
<title>Edit Propertiest</title>
<title>Edit Properties</title>
<para>Let us make some changes to the function and change the color of the plot.</para>
<para>Let's make some changes to the function and change the color of
the plot.</para>
<para>You can edit all functions with the <guimenu>Edit Plots...</guimenu> menu entry. A dialog appears which lists all functions.
&kmplot; automatically found a unique function name for your expressions and completed the expression to a function equation.</para>
<para>You can edit all functions with the
<menuchoice><guimenu>Plot</guimenu><guimenuitem>Edit
Plots...</guimenuitem> </menuchoice> menu entry. A dialog appears
which lists all the functions that you have plotted. Notice that
&kmplot; has automatically found a unique function name for your
expressions and completed the expression to a function
equation.</para>
<para>Select <guilabel>f(x)=x^2</guilabel> in the list. A double click or pressing the <guibutton>Edit</guibutton> button
will show you a dialog window. Here you have access to a lot of options. Let us rename the function and move the plot 5 units down. Change the function equation to
<screen><userinput>parabola(x)=x^2-5</userinput></screen>
<para>Select <guilabel>f(x)=x^2</guilabel> in the list. A double click
or pressing the <guibutton>Edit</guibutton> button will show you a
dialog window. Here you have access to a lot of options. Let us rename
the function and move the plot 5 units down. Change the function
equation to <screen><userinput>parabola(x)=x^2-5</userinput></screen>
</para>
<para>Select another color for the plot using the <guibutton>Color</guibutton> button. Finally press <guibutton>Ok</guibutton>
and your changes take effect in the coordinate system.</para>
<para>Select another color for the plot using the
<guibutton>Color</guibutton> button. Finally press
<guibutton>OK</guibutton> and your changes take effect in the
coordinate system.</para>
<para>Note: All changes can be undone until you press <guibutton>Ok</guibutton> in the <guilabel>Edit Plots</guilabel> dialog.</para>
<note><para>All changes can be undone until you press
<guibutton>OK</guibutton> in the <guilabel>Edit Plots</guilabel>
dialog.</para>
</note>
</sect1>
</chapter>
......
......@@ -22,9 +22,24 @@ functions.</para>
polar coordinates. Several grid modes are supported. Plots may be
printed with high precision in the correct scale.</para>
<para>Some numerical an visual features like filling and calculating the area between the plot
and the first axis, finding maximum and minumum values, changing function parameters dynamically,
and plotting derivatives and integal functions helps educating and learning the realtionship between mathematical functions and their graphical representation in a coordinate system.</para>
<para>&kmplot; also provides some numerical an visual features like:
<itemizedlist>
<listitem><para>Filling and calculating
the area between the plot and the first axis</para>
</listitem>
<listitem><para>Finding maximum and
minimum values</para>
</listitem>
<listitem><para>Changing function parameters dynamically</para>
</listitem>
<listitem><para>Plotting
derivatives and integral functions.</para>
</listitem>
</itemizedlist>
These features help in learning the
relationship between mathematical functions and their graphical
representation in a coordinate system.</para>
</chapter>
......
......@@ -47,8 +47,7 @@ parser expects a second function with a leading <quote>y</quote> (here
<term>var2</term>
<listitem><para> The function <quote>group parameter</quote>. It must be
separated from the function's variable by a comma. You can use the group
parameter to, for example, plot a number of graphs from one function. See the P
option under <xref linkend="func-extension"/>.</para></listitem>
parameter to, for example, plot a number of graphs from one function. The parameter values can be selected manually or you can choose to have a slider bar than control one parameter.</para></listitem>
</varlistentry>
<varlistentry>
<term>term</term>
......@@ -166,76 +165,6 @@ be used to determine the axes settings as well. See <xref linkend="the-axes-tab"
</sect1>
<sect1 id="func-extension">
<title>Extensions</title>
<para>An extension for a function is specified by entering a semicolon,
followed by the extension, after the function definition. For example:
<screen>
<userinput>
f(x)=x^2; A1
</userinput>
</screen>
will show the graph y=x<superscript>2</superscript> with its first
derivative. Supported extensions are described below:
<variablelist>
<varlistentry>
<term>N</term>
<listitem>
<para>
The function will be stored but not be drawn.
So it can be used like any other user defined or predefined function.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A1</term>
<listitem>
<para>
The graph of the derivative of the function will be drawn
additionally with the same color but less line width.
This extension has no effect on functions defined in
parametric form.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A2</term>
<listitem>
<para>
The graph of the second derivative of the function will be
drawn additionally with the same color but less line width.
This extension has no effect on functions defined in
parametric form.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>D[a,b]</term>
<listitem>
<para>
Sets the domain for which the function will be displayed. For parametric
functions, this is the domain that the parameter takes, and only needs to be
specified for the x function.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>P[a{,b...}]</term>
<listitem>
<para>
Give a set of values of a group parameter for which the function should be
displayed. For example: <userinput>f(x,k)=k*x;P[1,2,3]</userinput> will plot
the functions f(x)=x, f(x)=2*x and f(x)=3*x. You can also use functions as the
arguments to the P option.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1 id="math-syntax">
<title>Mathematical Syntax</title>
<para>&kmplot; uses a common way of expressing mathematical functions, so you
......@@ -304,34 +233,29 @@ not, say 144. To override this, use parentheses. To use the above example,
<sect1 id="coord-area"><title>Plotting Area</title>
<para>
By default, explicitly given functions are plotted for the whole of the visible part of the
x-axis. (See <xref linkend="func-extension"/> to change this for individual
functions.) For every pixel on the x-axis &kmplot; calculates a function value.
x-axis. You can specify an other range in the edit-dialog for the function. For every pixel on the x-axis &kmplot; calculates a function value.
If the plotting area contains the resulting point it is connected to the last
drawn point by a line.
</para>
<para>
Parametric functions are plotted for parameter values from 0 upto 2&pgr;.
This range can also be set using the D extension (see <xref linkend="func-extension"/>).
You can set the plotting range in the dialog for the function too.
</para>
</sect1>
<sect1 id="coord-cross">
<title>Cross Hair Cursor</title>
<para>
While the mouse cursor is over the plotting area the cursor changes to a
cross hair. The current coordinates can be seen at the intersections with the
coordinate axes and also in the status bar at the bottom of the main window.
While the mouse cursor is over the plotting area the cursor changes to a cross hair. The current coordinates can be seen at the intersections with the coordinate axes and also in the status bar at the bottom of the main window.
</para>
<para>
You can trace a function's values more precisely by clicking onto or next to a
graph. The cross hair then will be caught and be colored in the same color as
the graph. A second click anywhere in the window will leave this trace mode.
You can trace a function's values more precisely by clicking onto or next to a graph. The selected function is shown in the statusbar in the right column. The cross hair then will be caught and be colored in the same color as the graph. If the graph has the same color as the background color, the cross hair will have the inverted color of the background. When moving the mouse or pressing the keys Left or Right the cross hair will follow the function and you see the current x- and y-value. If the cross hair is close to y-axis, the root-value is shown in the statusbar. You can switch function with the Up and Down keys. A second click anywhere in the window or pressing any non-navigating key will leave this trace mode.
</para>
<para>
Note that tracing is only possible with explicitly given functions.
The coordinates are always displayed according to a cartesian system of
coordinates. Neither parametric functions, nor functions given in polar
coordinates, nor derivatives can be traced in this way.
coordinates. Neither non-single-points parametric functions nor functions given in polar
coordinates can be traced in this way.
</para>
</sect1>
......
<chapter id="using-kmplot">
<title>Using &kmplot;</title>
<para>&kmplot; deals with named functions, which can be specified in terms of
Cartesian coordinates (called <quote>explicit functions</quote>), polar coordinates or as parametric functions. To enter a
function, choose
<menuchoice><guimenu>Functions</guimenu><guimenuitem>Functions</guimenuitem>
</menuchoice> or click on the Functions button on the toolbar. You can enter
new functions in the <guilabel>Function equation</guilabel> text box. Each
function you enter must have a unique name (&ie;, a name that is not taken by
any of the existing functions displayed in the list box).</para>
<para>&kmplot; deals with named functions, which can be specified in
terms of Cartesian coordinates (called <quote>explicit
functions</quote>), polar coordinates or as parametric functions. To
enter a function, choose
<menuchoice><guimenu>Plot</guimenu><guimenuitem>Edit
Plots...</guimenuitem> </menuchoice>. You can also enter new functions
in the <guilabel>Function equation</guilabel> text box in the main
&kmplot; window. The text box can handle explicit and polar
functions. Each function you enter must have a unique name (&ie;, a
name that is not taken by any of the existing functions displayed in
the list box). A function name will be automatically generated if you
don't specify one.</para>
<para>For more information on &kmplot; functions, see <xref
linkend="reference"/>.
......@@ -50,57 +54,100 @@ given in appropriate syntax for &kmplot;. See <xref linkend="math-syntax"/>.
<para>As an example, to draw the graph of y=x<superscript>2</superscript>+2x,
enter the following into the functions dialog of &kmplot;:
<screen>
f(x)=x^2+2
f(x)=x^2+2*x
</screen>
</para>
</sect2>
<sect2 id="parametric-functions">
<title>Parametric Functions</title>
<para>Parametric functions are those in which the x and y coordinates are
defined by separate functions of another variable, often called t. To enter a
parametric function in &kmplot;, follow the procedure as for an explicit
function, but prefix the name of the function describing the x-coordinate with
the letter x, and the function describing the y-coordinate with the letter
y. As with explicit functions, you may use any variable name you wish for the
parameter.</para>
<title>Parametric Functions</title> <para>Parametric functions are
those in which the x and y coordinates are defined by separate
functions of another variable, often called t. To draw a parametric
function, use <menuchoice><guimenu>Plot</guimenu><guimenuitem>New
Parametric Plot...</guimenuitem> </menuchoice>.</para>
<para>As an example, suppose you want to draw a circle, which has parametric
equations x=sin(t), y=cos(t). In the &kmplot; functions dialog, do the
following:
<orderedlist>
<listitem><para>Enter the function for the x-coordinate, then press &Enter;:
<screen>
<userinput>
xcircle=sin(t)
</userinput></screen>
</para>
<listitem><para>Open the parametric plot dialog with
<menuchoice><guimenu>Plot</guimenu><guimenuitem>New Parametric Plot...</guimenuitem>
</menuchoice>.</para>
</listitem>
<listitem><para>&kmplot; automatically changes the function name for you to
enter the y-coordinate function. Enter the function you want:
<screen>
<userinput>
ycircle=cos(t)
</userinput></screen>
</para>
<listitem><para>Enter a name for the function, say,
<userinput>circle</userinput>, in the <guilabel>Name</guilabel>
box. The names of the x and y functions change to match this name: the
x function becomes <guilabel>xcircle(t)</guilabel> and the y function
becomes <guilabel>ycircle(t)</guilabel>.</para>
</listitem>
<listitem>
<para>In the x and y boxes, enter the appropriate equations, &ie;,
<guilabel>xcircle(t)=</guilabel><userinput>sin(t)</userinput> and
<guilabel>ycircle(t)=</guilabel><userinput>cos(t)</userinput>.</para>
</listitem>
</orderedlist>
Click on <guibutton>OK</guibutton> and the function will be drawn.
</para>
<para>You can set some further options for the plot in this dialog:
<variablelist>
<varlistentry>
<term><guilabel>Hide</guilabel></term>
<listitem>
<para>If this option is selected, the plot is not drawn, but &kmplot;
remembers the function definition, so you can use it to define other
functions.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Custom Plot Range</guilabel></term>
<listitem>
<para>If this option is selected, you can change the maximum and
minimum values of the parameter t for which the function is plotted
using the <guilabel>min</guilabel> and <guilabel>max</guilabel>
boxes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Line width</guilabel></term>
<listitem>
<para>With this option you can set the width of the line drawn on the
plot area, in units of 0.1mm.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Color</guilabel></term>
<listitem>
<para>Click on the color box and pick a color in the dialog that
appears. The line on the plot will be drawn in this color.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="polar-functions">
<title>Entering Functions in Polar Coordinates</title>
<title>Entering Functions in Polar Coordinates</title>
<para>Polar coordinates represent a point by its distance from the origin
(usually called r), and the angle a line from the origin to the point makes
with the x-axis (usually represented by the Greek letter theta). To enter
functions in polar coordinates, prefix the function name with the letter r. The
dummy variable is now the angle, theta.</para>
<para>For example, to draw the Archimedes' spiral r=theta, enter:
functions in polar coordinates, use the menu entry
<menuchoice><guimenu>Plot</guimenu><guimenuitem>New Polar Plot...</guimenuitem>
</menuchoice>. In the box labeled <guilabel>r</guilabel>, complete the
function definition, including the name of the theta variable you want
to use, &eg;, to draw the Archimedes' spiral r=theta, enter:
<screen>
<userinput>
rspiral(theta)=theta
(theta)=theta
</userinput>
</screen>
so that the whole line reads <quote>r(theta)=theta</quote>. Note that
you can use any name for the theta variable, so
<quote>r(foo)=foo</quote> would have produced exactly the same output.
</para>
</sect2>
......@@ -125,18 +172,108 @@ explicit function cannot be combined with a polar function.</para>
<sect1 id="function-appearance">
<title>Changing the appearance of functions</title>
<para>To change the appearance of a function's graph on the main plot window,
select the function in the functions dialog, and click on the
<guibutton>Attributes</guibutton> button. In the dialog which appears, you can
change the line width in the text box, and the color of the function's graph by
clicking on the color button on the right hand side. If you select
<guilabel>Save as default</guilabel>, then the line width and color you select
will be used as the default for the <replaceable>n</replaceable>th function in
the list. &eg;, if the function for which you are changing the attributes is
the first in the list, the settings will be saved as the default for the first
function entered in the &kmplot; list.</para>
<para>To change the appearance of a function's graph on the main plot
window, select the function in the <guilabel>Edit Plots</guilabel>
dialog, and click on the <guibutton>Edit</guibutton> button. In the
dialog which appears, you can change the line width in the text box,
and the color of the function's graph by clicking on the color button
at the bottom. If you are editing an explicit function, you will see a
dialog with three tabs. In the first one you specify the equation of
the function. The <guilabel>Derivatives</guilabel> tab lets you draw
the first and second derivative to the function. With the
<guilabel>Integral</guilabel> tab you can draw the integral of the
function which is calculated using Euler's method. </para>
<para>Another way to edit a function is to right click on the
graph. In the popup menu that appears, choose
<guibutton>Edit</guibutton></para>
<para>For more information on the popup menu, see <xref
linkend="popupmenu"/>.
</para>
</sect1>
<sect1 id="popupmenu">
<title>Popup menu</title>
<para>When right-clicking on a plot function or a single-point parametric plot function a popup menu will appear.
In the menu there are seven items available:</para>
<variablelist>
<varlistentry>
<term><menuchoice><guimenuitem>Hide</guimenuitem>
</menuchoice></term>
<listitem>
<para>Hides the selected graph. Other plots of the graph's function will still be shown.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenuitem>Remove</guimenuitem>
</menuchoice></term>
<listitem>
<para>Removes the function. All its graphs will disappear.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenuitem>Edit</guimenuitem>
</menuchoice></term>
<listitem>
<para>Shows the editor dialog for the selected function.</para>
</listitem>
</varlistentry>
</variablelist>
<para>For plot functions the following four items are also available:</para>
<variablelist>
<varlistentry>
<term><menuchoice><guimenuitem>Get y-value</guimenuitem>
</menuchoice></term>
<listitem>
<para>Opens a dialog in which you can find the y-value corresponding to
a specific x-value. The selected graph will be highlighted in the
dialog. Enter an x value in the <guilabel>X</guilabel> box, and click
on <guibutton>Find</guibutton> (or press &Enter;). The corresponding y
value will be shown under <guilabel>Y</guilabel>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenuitem>Search for Minimum Value</guimenuitem>
</menuchoice></term>
<listitem>