[education/step] doc: Documentation improves
Antoni Bella Pérez
null at kde.org
Sun Oct 24 18:19:24 BST 2021
Git commit fd62a9eecf9b167d4963dced15d7a30498427dbd by Antoni Bella Pérez.
Committed on 24/10/2021 at 17:18.
Pushed by bellaperez into branch 'master'.
Documentation improves
* Update date and version numbers
* Remove final whitespaces
* Remove unused kappname entity
* Use suitable tags, add empty lines and re-indent some sections (more readable)
* Use a suitable capitalization, tagging and punctuation
* Use more entities
* Change http: to https:
* Add GUI icons and renew a screenshot
M +135 -135 doc/examples.docbook
M +61 -81 doc/index.docbook
M +- -- doc/mainwindow.png
A +- -- doc/media-playback-start.png
A +- -- doc/step_object_CircularMotor.png
A +- -- doc/step_object_Particle.png
A +- -- doc/step_object_Stick.png
M +115 -89 doc/tutorials.docbook
https://invent.kde.org/education/step/commit/fd62a9eecf9b167d4963dced15d7a30498427dbd
diff --git a/doc/examples.docbook b/doc/examples.docbook
index dfbb223..f4bb4a7 100644
--- a/doc/examples.docbook
+++ b/doc/examples.docbook
@@ -1,145 +1,145 @@
<chapter id="examples">
-<title>&step; examples</title>
-<para>
- &step; package contains several instructive examples to help you understand the principles of the application work. To open an example from the default set choose <menuchoice><guimenu>File</guimenu> <guisubmenu>Examples</guisubmenu> <guimenuitem>Open Example...</guimenuitem></menuchoice> from the main window menu.
-</para>
-
-<para>
- You can share your own examples with <menuchoice><guimenu>File</guimenu> <guisubmenu>Examples</guisubmenu> <guimenuitem>Share Current Experiment...</guimenuitem></menuchoice> or download examples shared by other users with <menuchoice><guimenu>File</guimenu> <guisubmenu>Examples</guisubmenu> <guimenuitem>Download New Experiments...</guimenuitem></menuchoice>. Downloaded examples can be opened using <menuchoice><guimenu>File</guimenu> <guisubmenu>Examples</guisubmenu> <guimenuitem>Open Downloaded Example...</guimenuitem></menuchoice> menu item.
-</para>
+<title>&step; examples</title>
-<para>
- You can find the descriptions of the default example files below.
+<para>&step; package contains several instructive examples to help you understand the principles of the application work:
</para>
<variablelist>
-<varlistentry id="brownian">
-<term>brownian.step</term>
-<listitem><para>Plots trajectory of the rigid disk interacting with 40 particles that randomly drifting in a box. This example simulates <ulink url="http://en.wikipedia.org/wiki/Brownian_motion">Brownian motion</ulink> of ideal gas particles.</para></listitem>
-</varlistentry>
-
-<varlistentry id="pendulum">
-<term>doublependulum.step</term>
-<listitem><para>This example simulates <ulink url="http://en.wikipedia.org/wiki/Double_pendulum">double pendulum motion</ulink> using 2 massive particles and two sticks.</para></listitem>
-</varlistentry>
-
-<varlistentry id="eightpendulum">
-<term>eightpendulum.step</term>
-<listitem><para>This example is a simple demonstration of the famous <ulink url="http://en.wikipedia.org/wiki/Newton%27s_cradle">Newton's cradle</ulink>. It is done in &step; using sticks, 8 discs and a box. The six balls in the middle are not moving because they just transfer momentum and energy, not a motion.</para></listitem>
-</varlistentry>
-
-<varlistentry id="first">
-<term>first.step: First example</term>
-<listitem><para>This example has two parts. The first part contains two particles connected
-by a spring and the second part contains two charged particles.</para>
-
-<variablelist>
-<varlistentry id="first-two-particles">
-<term>Two particles connected by a spring</term>
-<listitem>
- <para>
- In this example two particles are added to the scene and spring is connected
- between them. The properties of both the particles such as velocity, momentum,
- position &etc; has been set in the properties browser. The properties of the
- spring such as stiffness, restLength, damping &etc; also has been set in the
- properties browser.
- </para>
- <para>
- <emphasis>Explanation of the simulation:</emphasis>
- </para>
- <para>
- This is good example of a simple harmonic motion. Here the acceleration of the
- one particle is set in direction of positive x-axis and the acceleration of
- the other particle is set along negative x-axis. As a result both the particles
- pulls the spring in opposite directions, where as spring tries to bring the
- two particles back to their original positions. Thus the system executes
- simple harmonic motion. The simulation of the particles and spring under these
- conditions can be seen on the scene.
- </para>
-</listitem>
-</varlistentry>
-
-<varlistentry id="first-two-charged">
-<term>Two charged particles</term>
-<listitem>
- <para>
- Velocity of the each charged particle is set in some direction so, the charged
- particles moves in respective direction of their velocity but each particle
- has been given a equal and opposite charge so the particles try to attract
- each other. As a result the simulation of the charged particles under these
- conditions can be seen on the scene.
- </para>
-</listitem>
-</varlistentry>
+ <varlistentry>
+ <term><menuchoice>
+ <guimenu>File</guimenu>
+ <guisubmenu>Examples</guisubmenu></menuchoice></term>
+ <listitem><para><action>Opens a submenu</action> with different action items.</para>
+ <variablelist>
+ <varlistentry>
+ <term><guimenuitem>Open Example...</guimenuitem></term>
+ <listitem><para><action>Opens an example</action> from the default set</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><guimenuitem>Open Downloaded Example...</guimenuitem></term>
+ <listitem><para><action>Opens the downloaded examples.</action></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><guimenuitem>Download New Experiments...</guimenuitem></term>
+ <listitem><para><action>Download examples</action> shared by other users.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><guimenuitem>Share Current Experiment...</guimenuitem></term>
+ <listitem><para><action>You can share your own examples.</action></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
</variablelist>
-</listitem>
-</varlistentry>
-
-<varlistentry id="fourpendula">
-<term>fourpendula.step</term>
-<listitem><para>This example is a correct demonstration of the <ulink url="http://en.wikipedia.org/wiki/Newton%27s_cradle">Newton's cradle</ulink>. As the system is imperfect two disks in the middle get visual movement with time.</para></listitem>
-</varlistentry>
-
-<varlistentry id="gas">
-<term>gas.step</term>
-<listitem><para>This example simulates ideal gas pressure caused by <ulink url="http://en.wikipedia.org/wiki/Brownian_motion">Brownian motion</ulink>.</para></listitem>
-</varlistentry>
-
-<varlistentry id="graph">
-<term>graph.step</term>
-<listitem><para>Plots velocity vs. position graph for particle1 in the system of two particles connected with a spring.</para></listitem>
-</varlistentry>
-
-<varlistentry id="liquid">
-<term>liquid.step</term>
-<listitem><para>This example simulates monoatomic liquid.</para></listitem>
-</varlistentry>
-
-<varlistentry id="lissajous">
-<term>lissajous.step</term>
-<listitem><para>This example simulates <ulink url="http://en.wikipedia.org/wiki/Lissajous_curve">Lissajous curve</ulink> using two-particle model. The parameters on the model can be changed using the controller at the center of the world.</para></listitem>
-</varlistentry>
-
-<varlistentry id="motor1">
-<term>motor1.step</term>
-<listitem><para>Simulates triangular rigid body under the loading of the three linear motors.</para></listitem>
-</varlistentry>
-
-<varlistentry id="motor-example">
-<term>motor.step</term>
-<listitem><para>Simulates interaction of the linear motor with a rigid rectangular body on a spring.</para></listitem>
-</varlistentry>
-
-<varlistentry id="note-example">
-<term>note.step</term>
-<listitem><para>Example with LaTeX formula (<ulink url="http://en.wikipedia.org/wiki/Divergence_theorem">divergence theorem</ulink>) and embedded image.</para></listitem>
-</varlistentry>
-
-<varlistentry id="resonance">
-<term>resonance.step</term>
-<listitem><para>This example simulates resonance in the system with angular motor.</para></listitem>
-</varlistentry>
-
-<varlistentry id="softbody">
-<term>softbody.step</term>
-<listitem><para>This example simulates interaction of two rigid bodies with a soft body between them.</para></listitem>
-</varlistentry>
-
-<varlistentry id="solar">
-<term>solar.step</term>
-<listitem><para>This example simulates the motion of Solar system major bodies (Sun and the planets).</para></listitem>
-</varlistentry>
-
-<varlistentry id="springs">
-<term>springs.step</term>
-<listitem><para>This example simulates the motion of the planar system of five particles connected with four springs.</para></listitem>
-</varlistentry>
-
-<varlistentry id="wave">
-<term>wave.step</term>
-<listitem><para>The graph on the scene shows oscillations of the green particle. When you start simulation the wave starts to travel from the red particle. The blue particle will reflect the wave and it will travel in reverse direction until the red particle reflects in again. After some time the wave will vanish because springs have damping.</para></listitem>
-</varlistentry>
+<para>You can find the descriptions of the default example files below.
+</para>
+
+<variablelist>
+ <varlistentry id="brownian">
+ <term><filename>brownian.step</filename></term>
+ <listitem><para>Plots trajectory of the rigid disk interacting with 40 particles that randomly drifting in a box. This example simulates <ulink url="https://en.wikipedia.org/wiki/Brownian_motion">Brownian motion</ulink> of ideal gas particles.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="pendulum">
+ <term><filename>doublependulum.step</filename></term>
+ <listitem><para>This example simulates <ulink url="https://en.wikipedia.org/wiki/Double_pendulum">double pendulum motion</ulink> using 2 massive particles and two sticks.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="eightpendulum">
+ <term><filename>eightpendulum.step</filename></term>
+ <listitem><para>This example is a simple demonstration of the famous <ulink url="https://en.wikipedia.org/wiki/Newton%27s_cradle">Newton's cradle</ulink>. It is done in &step; using sticks, 8 discs and a box. The six balls in the middle are not moving because they just transfer momentum and energy, not a motion.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="first">
+ <term><filename>first.step</filename>: First example</term>
+ <listitem><para>This example has two parts. The first part contains two particles connected by a spring and the second part contains two charged particles.
+ </para>
+ <variablelist>
+ <varlistentry id="first-two-particles">
+ <term>Two particles connected by a spring</term>
+ <listitem><para>In this example two particles are added to the scene and spring is connected between them. The properties of both the particles such as velocity, momentum, position &etc; has been set in the properties browser. The properties of the spring such as stiffness, restLength, damping &etc; also has been set in the properties browser.
+ </para>
+
+ <para><emphasis>Explanation of the simulation:</emphasis>
+ </para>
+
+ <para>This is good example of a simple harmonic motion. Here the acceleration of the one particle is set in direction of positive x-axis and the acceleration of the other particle is set along negative x-axis. As a result both the particles pulls the spring in opposite directions, where as spring tries to bring the two particles back to their original positions. Thus the system executes simple harmonic motion. The simulation of the particles and spring under these conditions can be seen on the scene.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry id="first-two-charged">
+ <term>Two charged particles</term>
+ <listitem><para>Velocity of the each charged particle is set in some direction so, the charged particles moves in respective direction of their velocity but each particle has been given a equal and opposite charge so the particles try to attract each other. As a result the simulation of the charged particles under these conditions can be seen on the scene.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="fourpendula">
+ <term><filename>fourpendula.step</filename></term>
+ <listitem><para>This example is a correct demonstration of the <ulink url="https://en.wikipedia.org/wiki/Newton%27s_cradle">Newton's cradle</ulink>. As the system is imperfect two disks in the middle get visual movement with time.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="gas">
+ <term><filename>gas.step</filename></term>
+ <listitem><para>This example simulates ideal gas pressure caused by <ulink url="https://en.wikipedia.org/wiki/Brownian_motion">Brownian motion</ulink>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="graph">
+ <term><filename>graph.step</filename></term>
+ <listitem><para>Plots velocity vs. position graph for particle1 in the system of two particles connected with a spring.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="liquid">
+ <term><filename>liquid.step</filename></term>
+ <listitem><para>This example simulates monoatomic liquid.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="lissajous">
+ <term><filename>lissajous.step</filename></term>
+ <listitem><para>This example simulates <ulink url="https://en.wikipedia.org/wiki/Lissajous_curve">Lissajous curve</ulink> using two-particle model. The parameters on the model can be changed using the controller at the center of the world.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="motor1">
+ <term><filename>motor1.step</filename></term>
+ <listitem><para>Simulates triangular rigid body under the loading of the three linear motors.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="motor-example">
+ <term><filename>motor.step</filename></term>
+ <listitem><para>Simulates interaction of the linear motor with a rigid rectangular body on a spring.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="note-example">
+ <term><filename>note.step</filename></term>
+ <listitem><para>Example with &latex; formula (<ulink url="https://en.wikipedia.org/wiki/Divergence_theorem">divergence theorem</ulink>) and embedded image.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="resonance">
+ <term><filename>resonance.step</filename></term>
+ <listitem><para>This example simulates resonance in the system with angular motor.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="softbody">
+ <term><filename>softbody.step</filename></term>
+ <listitem><para>This example simulates interaction of two rigid bodies with a soft body between them.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="solar">
+ <term><filename>solar.step</filename></term>
+ <listitem><para>This example simulates the motion of Solar system major bodies (Sun and the planets).</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="springs">
+ <term><filename>springs.step</filename></term>
+ <listitem><para>This example simulates the motion of the planar system of five particles connected with four springs.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="wave">
+ <term><filename>wave.step</filename></term>
+ <listitem><para>The graph on the scene shows oscillations of the green particle. When you start simulation the wave starts to travel from the red particle. The blue particle will reflect the wave and it will travel in reverse direction until the red particle reflects in again. After some time the wave will vanish because springs have damping.</para></listitem>
+ </varlistentry>
</variablelist>
</chapter>
diff --git a/doc/index.docbook b/doc/index.docbook
index 8c72088..38d06eb 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -1,6 +1,5 @@
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
- <!ENTITY kappname "&step;">
<!ENTITY tutorials SYSTEM "tutorials.docbook">
<!ENTITY examples SYSTEM "examples.docbook">
<!ENTITY % addindex "IGNORE">
@@ -30,21 +29,21 @@
<legalnotice>&FDLNotice;</legalnotice>
-<date>2016-05-07</date>
-<releaseinfo>0.1.0 (Applications 16.04)</releaseinfo>
+<date>2021-10-24</date>
+<releaseinfo>KDE Gear 21.08</releaseinfo>
<abstract>
-<para>
-&step; is an interactive physical simulator. It allows you to explore the physical world through simulations. It works like this: you place some bodies on the scene, add some forces such as gravity or springs, then click <guibutton>Simulate</guibutton> and &step; shows you how your scene will evolve according to the laws of physics. You can change every property of the bodies/forces in your experiment (even during simulation) and see how this will change evolution of the experiment. With &step; you cannot only learn but feel how physics works!
+<para>&step; is an interactive physical simulator. It allows you to explore the physical world through simulations. It works like this: you place some bodies on the scene, add some forces such as gravity or springs, then press the <inlinemediaobject><imageobject><imagedata fileref="media-playback-start.png" format="PNG"/></imageobject></inlinemediaobject> <guiicon>Simulate</guiicon> icon in the toolbar and &step; shows you how your scene will evolve according to the laws of physics. You can change every property of the bodies/forces in your experiment (even during simulation) and see how this will change evolution of the experiment. With &step; you cannot only learn but feel how physics works!
</para>
</abstract>
<keywordset>
-<keyword>KDE</keyword>
-<keyword>kdeedu</keyword>
-<keyword>physics</keyword>
-<keyword>simulator</keyword>
-<keyword>forces</keyword>
+ <keyword>KDE</keyword>
+ <keyword>kdeedu</keyword>
+ <keyword>physics</keyword>
+ <keyword>simulator</keyword>
+ <keyword>forces</keyword>
+ <keyword>Step</keyword>
</keywordset>
</bookinfo>
@@ -52,108 +51,89 @@
<chapter id="introduction">
<title>Introduction</title>
<para>&step; is an interactive physical simulator.</para>
-
+
<para>
&step; features:
+
<itemizedlist>
-<listitem><para>
-Classical mechanical simulation in two dimensions
-</para></listitem>
-<listitem><para>
-Particles, springs with damping, gravitational and coulomb forces
-</para></listitem>
-<listitem><para>
-Rigid bodies
-</para></listitem>
-<listitem><para>
-Collision detection (currently only discrete) and handling
-</para></listitem>
-<listitem><para>
-Soft (deformable) bodies simulated as user-editable particles-springs system, sound waves
-</para></listitem>
-<listitem><para>
-Molecular dynamics (currently using Lennard-Jones potential): gas and liquid, condensation and evaporation, calculation of macroscopic quantities and their variances
-</para></listitem>
-<listitem><para>
-Units conversion and expression calculation: you can enter something like "(2 days + 3 hours) * 80 km/h" and it will be accepted as distance value (requires libqalculate)
-</para></listitem>
-<listitem><para>
-Errors calculation and propagation: you can enter values like "1.3 ± 0.2" for any property and errors for all dependent properties will be calculated using statistical formulas
-</para></listitem>
-<listitem><para>
-Solver error estimation: errors introduced by the solver is calculated and added to user-entered errors
-</para></listitem>
-<listitem><para>
-Several different solvers: up to 8th order, explicit and implicit, with or without adaptive timestep (most of the solvers require GSL library)
-</para></listitem>
-<listitem><para>
-Controller tool to easily control properties during simulation (even with custom keyboard shortcuts)
-</para></listitem>
-<listitem><para>
-Tools to visualize results: graph, meter, tracer
-</para></listitem>
-<listitem><para>
-Context information for all objects, integrated wikipedia browser
-</para></listitem>
-<listitem><para>
-Collection of example experiments, more can be downloaded with KNewStuff2
-</para></listitem>
-<listitem><para>
-Integrated tutorials
-</para></listitem>
+ <listitem><para>Classical mechanical simulation in two dimensions</para></listitem>
+
+ <listitem><para>Particles, springs with damping, gravitational and coulomb forces</para></listitem>
+
+ <listitem><para>Rigid bodies</para></listitem>
+
+ <listitem><para>Collision detection (currently only discrete) and handling</para></listitem>
+
+ <listitem><para>Soft (deformable) bodies simulated as user-editable particles-springs system, sound waves</para></listitem>
+
+ <listitem><para>Molecular dynamics (currently using Lennard-Jones potential): gas and liquid, condensation and evaporation, calculation of macroscopic quantities and their variances</para></listitem>
+
+ <listitem><para>Units conversion and expression calculation: you can enter something like <quote>(2 days + 3 hours) * 80 km/h</quote> and it will be accepted as distance value (requires libqalculate)</para></listitem>
+
+ <listitem><para>Errors calculation and propagation: you can enter values like <quote>1.3 ± 0.2</quote> for any property and errors for all dependent properties will be calculated using statistical formulas</para></listitem>
+
+ <listitem><para>Solver error estimation: errors introduced by the solver is calculated and added to user-entered errors</para></listitem>
+
+ <listitem><para>Several different solvers: up to 8th order, explicit and implicit, with or without adaptive timestep (most of the solvers require GSL library)</para></listitem>
+
+ <listitem><para>Controller tool to easily control properties during simulation (even with custom keyboard shortcuts)</para></listitem>
+
+ <listitem><para>Tools to visualize results: graph, meter, tracer</para></listitem>
+
+ <listitem><para>Context information for all objects, integrated wikipedia browser</para></listitem>
+
+ <listitem><para>Collection of example experiments, more can be downloaded with &knewstuff;3</para></listitem>
+
+ <listitem><para>Integrated tutorials</para></listitem>
</itemizedlist>
</para>
</chapter>
<chapter id="using-step">
<title>Using &step;</title>
-<para>&step; simulates a physical world. The main part of &step; (1) is the world scene in the center of &step; main window where you first place physical objects and where you see the simulation. On the left of this scene a palette (2) let you choose your physical objects. You can freely move this palette anywhere on your desktop by dragging the title bar. On the right of the scene you can see the current world description (3), its properties (4), some help to explain some words (5) and the history of the current world (6). Each of those panels can be placed elsewhere on your screen by dragging the title bar.</para>
+
+<para>&step; simulates a physical world. The main part of &step; (1) is the world scene in the center of &step; main window where you first place physical objects and where you see the simulation. On the left of this scene a palette (2) let you choose your physical objects. You can freely move this palette anywhere on your desktop by dragging the title bar. On the right of the scene you can see the current world description (3), its properties (4), some help to explain some words (5) and the history of the current world (6). Each of those panels can be placed elsewhere on your screen by dragging the title bar.
+</para>
+
<screenshot>
- <screeninfo>Here's a screenshot of &step; when you start it for the first time</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="mainwindow.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Step Main Window</phrase>
- </textobject>
- </mediaobject>
+ <screeninfo>Here's a screenshot of &step; when you start it for the first time</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="mainwindow.png" format="PNG"/></imageobject>
+ <textobject><phrase>&step; Main Window</phrase></textobject>
+ </mediaobject>
</screenshot>
-<para>To help you get started, &step; integrates a series of tutorials which easily teach you how to build an experiment. Please see step by step to start with the first tutorial.</para>
+<para>To help you get started, &step; integrates a series of tutorials which easily teach you how to build an experiment. Please see step by step to start with the first tutorial.
+</para>
</chapter>
-&tutorials;
+&tutorials;
&examples;
<chapter id="credits">
<title>Credits and License</title>
-<para>
-&step;
+<para>&step;
</para>
-<para>
-Program copyright 2007 &Vladimir.Kuznetsov; &Vladimir.Kuznetsov.mail;
+
+<para>Program copyright 2007 &Vladimir.Kuznetsov; &Vladimir.Kuznetsov.mail;
</para>
-<para>
-Contributors:
+
+<para>Contributors:
+
<itemizedlist>
-<listitem><para>Author: &Vladimir.Kuznetsov; &Vladimir.Kuznetsov.mail;</para>
-</listitem>
-<listitem><para>Contributor: &Carsten.Niehaus; &Carsten.Niehaus.mail;</para>
-</listitem>
+ <listitem><para>Author: &Vladimir.Kuznetsov; &Vladimir.Kuznetsov.mail;</para></listitem>
+ <listitem><para>Contributor: &Carsten.Niehaus; &Carsten.Niehaus.mail;</para></listitem>
</itemizedlist>
</para>
-<para>
-Documentation copyright 2007 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;
+<para>Documentation copyright 2007 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;
</para>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;
-
&underGPL; <!-- GPL License -->
</chapter>
diff --git a/doc/mainwindow.png b/doc/mainwindow.png
index 805a341..ec3e843 100644
Binary files a/doc/mainwindow.png and b/doc/mainwindow.png differ
diff --git a/doc/media-playback-start.png b/doc/media-playback-start.png
new file mode 100644
index 0000000..e730813
Binary files /dev/null and b/doc/media-playback-start.png differ
diff --git a/doc/step_object_CircularMotor.png b/doc/step_object_CircularMotor.png
new file mode 100644
index 0000000..e92e159
Binary files /dev/null and b/doc/step_object_CircularMotor.png differ
diff --git a/doc/step_object_Particle.png b/doc/step_object_Particle.png
new file mode 100644
index 0000000..8781468
Binary files /dev/null and b/doc/step_object_Particle.png differ
diff --git a/doc/step_object_Stick.png b/doc/step_object_Stick.png
new file mode 100644
index 0000000..96622c6
Binary files /dev/null and b/doc/step_object_Stick.png differ
diff --git a/doc/tutorials.docbook b/doc/tutorials.docbook
index df7bad0..9b7b277 100644
--- a/doc/tutorials.docbook
+++ b/doc/tutorials.docbook
@@ -1,130 +1,156 @@
<chapter id="tutorials">
-<title>Getting familiar with &step;: the tutorials</title>
-<para>The <menuchoice><guimenu>File</guimenu><guimenuitem>Open Tutorial...</guimenuitem></menuchoice> menu action brings you a file dialog where you can load &step; built-in tutorials. There are five tutorials and you will progressively learn how to interact with each of &step; element. The best is to start with the first tutorial by clicking on the file <filename>tutorial1.step</filename>. This will display Tutorial 1 in &step;.</para>
+<title>Getting familiar with &step;: the tutorials</title>
+
+<para>The <menuchoice><guimenu>File</guimenu><guimenuitem>Open Tutorial...</guimenuitem></menuchoice> menu item brings you a file dialog where you can load &step; built-in tutorials. There are five tutorials and you will progressively learn how to interact with each of &step; element. The best is to start with the first tutorial by clicking on the file <filename>tutorial1.step</filename>. This will display Tutorial 1 in &step;.
+</para>
+
<note><para>If you do not see the tutorial properly you can try to zoom in to display it better.</para></note>
-<para>The <guilabel>World</guilabel> panel on the right lists all the objects you have on your scene. By clicking on an object here, the <guilabel>Properties</guilabel> panel below displays this object properties. You can change the properties here by clicking on the one you want to modify.</para>
+<para>The <guilabel>World</guilabel> panel on the right lists all the objects you have on your scene. By clicking on an object here, the <guilabel>Properties</guilabel> panel below displays this object properties. You can change the properties here by clicking on the one you want to modify.
+</para>
-<para>Each tutorial consists in some text presenting the new elements and explaining their properties. Then you are asked to change some properties of the elements in order to achieve a new result of the experiment. </para>
+<para>Each tutorial consists in some text presenting the new elements and explaining their properties. Then you are asked to change some properties of the elements in order to achieve a new result of the experiment.
+</para>
<sect1 id="tutorial1">
<title>Tutorial 1: Bodies and springs</title>
-<para>This tutorial presents you bodies and springs and how to start your first simulation.</para>
-<para>A physical body or body for short is an object which can be described by the theories of classical mechanics, or quantum mechanics, and experimented upon with physical instruments. This includes the determination of position, and in some cases the orientation in space, as well as means to change these, by exerting forces.</para>
-<para>A spring is a flexible elastic object used to store mechanical energy.</para>
+
+<para>This tutorial presents you bodies and springs and how to start your first simulation.
+</para>
+
+<para>A physical body or body for short is an object which can be described by the theories of classical mechanics, or quantum mechanics, and experimented upon with physical instruments. This includes the determination of position, and in some cases the orientation in space, as well as means to change these, by exerting forces.
+</para>
+
+<para>A spring is a flexible elastic object used to store mechanical energy.
+</para>
+
<screenshot>
- <screeninfo>Tutorial 1 experiment</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="tutorial1.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Tutorial 1 experiment</phrase>
- </textobject>
- </mediaobject>
+ <screeninfo>Tutorial 1 experiment</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="tutorial1.png" format="PNG"/></imageobject>
+ <textobject><phrase>Tutorial 1 experiment</phrase></textobject>
+ </mediaobject>
</screenshot>
-<para>The physical experiment in this tutorial represents two disks linked by a spring. Disks have an initial velocity in a tangential direction (the little blue arrow) and an acceleration (the red arrow) and springs have a stiffness and the length can be changed. Running the experiment you can see the disks being pulled and pushed by the spring. The tutorial invites you to modify the spring stiffness and also to try to change the system experiment.</para>
-<para>At the end of this tutorial you should be more familiar with &step; interface and you should also be able to easily change bodies properties.</para>
+
+<para>The physical experiment in this tutorial represents two disks linked by a spring. Disks have an initial velocity in a tangential direction (the little blue arrow) and an acceleration (the red arrow) and springs have a stiffness and the length can be changed. Running the experiment you can see the disks being pulled and pushed by the spring. The tutorial invites you to modify the spring stiffness and also to try to change the system experiment.
+</para>
+
+<para>At the end of this tutorial you should be more familiar with &step; interface and you should also be able to easily change bodies properties.
+</para>
</sect1>
<sect1 id="tutorial2">
<title>Tutorial 2: Controllers and graphs</title>
-<para>You will learn more about controllers and graphs in this tutorial.</para>
-<para>A controller is a device which allows you to graphically modify a property of a body or a spring. In the tutorial, the controller allows you to change the stiffness of the spring "spring1". By moving the slider to the right or using the W key you can increase spring1 stiffness value and by moving the slider to the left or using the Q key you can decrease it. Right-clicking on the controller brings you several context actions and the <guilabel>Configure Controller...</guilabel> dialog allows you to change each property of the controller.</para>
+
+<para>You will learn more about controllers and graphs in this tutorial.
+</para>
+
+<para>A controller is a device which allows you to graphically modify a property of a body or a spring. In the tutorial, the controller allows you to change the stiffness of the spring <quote>spring1</quote>. By moving the slider to the right or using the <keycap>W</keycap> key you can increase spring1 stiffness value and by moving the slider to the left or using the <keycap>Q</keycap> key you can decrease it. Right-clicking on the controller brings you several context actions and the <guimenuitem>Configure Controller...</guimenuitem> item shows a dialog allows you to change each property of the controller.
+</para>
+
<screenshot>
- <screeninfo>Tutorial 2 experiment</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="tutorial2.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Tutorial 2 experiment</phrase>
- </textobject>
- </mediaobject>
+ <screeninfo>Tutorial 2 experiment</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="tutorial2.png" format="PNG"/></imageobject>
+ <textobject><phrase>Tutorial 2 experiment</phrase></textobject>
+ </mediaobject>
</screenshot>
-<para>Graphs allow you to graphically visualize the relationship between two variables. The example in the tutorial prints the evolution of the position of particle1 while time advances in world1. With a right click on a graph you can clear or delete the graph as well as edit the configuration dialog and change here all the properties for this graph.</para>
-<para>At the end of this tutorial you are able to use controllers to act on your bodies properties and graphs to monitor specific properties in your experiment.</para>
+
+<para>Graphs allow you to graphically visualize the relationship between two variables. The example in the tutorial prints the evolution of the position of particle1 while time advances in world1. With a right click on a graph you can clear or delete the graph as well as edit the configuration dialog and change here all the properties for this graph.
+</para>
+
+<para>At the end of this tutorial you are able to use controllers to act on your bodies properties and graphs to monitor specific properties in your experiment.
+</para>
</sect1>
<sect1 id="tutorial3">
<title>Tutorial 3: Rigid bodies and tracers</title>
-<para>Tutorial 3 presents you rigid bodies and tracers.</para>
-<para>A rigid body is an idealization of a solid body of finite size in which deformation is neglected. In other words, the distance between any two given points of a rigid body remains constant in time regardless of external forces exerted on it.</para>
-<para>A tracer is a tool which shows the trajectory of a given point on a rigid body.</para>
+
+<para>Tutorial 3 presents you rigid bodies and tracers.
+</para>
+
+<para>A rigid body is an idealization of a solid body of finite size in which deformation is neglected. In other words, the distance between any two given points of a rigid body remains constant in time regardless of external forces exerted on it.
+</para>
+
+<para>A tracer is a tool which shows the trajectory of a given point on a rigid body.
+</para>
+
<screenshot>
- <screeninfo>Disk properties</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="disk-properties.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Disk properties</phrase>
- </textobject>
- </mediaobject>
+ <screeninfo>Disk properties</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="disk-properties.png" format="PNG"/></imageobject>
+ <textobject><phrase>Disk properties</phrase></textobject>
+ </mediaobject>
</screenshot>
-<para>When a rigid body (here a disk) is selected you see three grey handlers on it. Using them by clicking on them and moving them, you can change the velocity, the angle and the angular velocity of the body.</para>
+
+<para>When a rigid body (here a disk) is selected you see three grey handlers on it. Using them by clicking on them and moving them, you can change the velocity, the angle and the angular velocity of the body.
+</para>
+
<screenshot>
- <screeninfo>Tutorial 3: 2 tracers</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="tutorial3.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Tutorial 3: 2 tracers</phrase>
- </textobject>
- </mediaobject>
+ <screeninfo>Tutorial 3: 2 tracers</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="tutorial3.png" format="PNG"/></imageobject>
+ <textobject><phrase>Tutorial 3: 2 tracers</phrase></textobject>
+ </mediaobject>
</screenshot>
-<para>The experiment in Tutorial 3 shows a disk and a box linked by a spring. A tracer (the blue one) is already on the box. You can add a second one: select <guilabel>Tracer</guilabel> in the <guilabel>Palette</guilabel> panel then click on the box on the point where you want the tracer to be. In the <guilabel>Properties</guilabel> panel, click on the <guilabel>color</guilabel> line and on the right of this line you can click on the blue square and a color palette appears: you can choose a new color for the tracer. The screenshot above shows two tracers after the simulation is run for a few seconds.</para>
+
+<para>The experiment in Tutorial 3 shows a disk and a box linked by a spring. A tracer (the blue one) is already on the box. You can add a second one: select the <guibutton>Tracer</guibutton> button in the <guilabel>Palette</guilabel> panel then click on the box on the point where you want the tracer to be. In the <guilabel>Properties</guilabel> panel, click on the <guilabel>color</guilabel> line and on the right of this line you can click on the blue square and a color palette appears: you can choose a new color for the tracer. The screenshot above shows two tracers after the simulation is run for a few seconds.
+</para>
</sect1>
<sect1 id="tutorial4">
<title>Tutorial 4: Motors and forces</title>
-<para>You have two sorts of motors available in &step;: linear motors and circular motors. A linear motor applies a constant force to a given point on a body while a circular motor applies a constant angular momentum to a body.</para>
-<para>Three different forces can be added to bodies: the weight force, the gravitation force and the Coulomb force. By default all forces are turned off in &step;. Coulomb force is a force which existed intrinsically between two charges.</para>
+
+<para>You have two sorts of motors available in &step;: linear motors and circular motors. A linear motor applies a constant force to a given point on a body while a circular motor applies a constant angular momentum to a body.
+</para>
+
+<para>Three different forces can be added to bodies: the weight force, the gravitation force and the Coulomb force. By default all forces are turned off in &step;. Coulomb force is a force which existed intrinsically between two charges.
+</para>
+
<screenshot>
- <screeninfo>Tutorial 4: Motors</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="tutorial4.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Tutorial 4: Motors</phrase>
- </textobject>
- </mediaobject>
+ <screeninfo>Tutorial 4: Motors</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="tutorial4.png" format="PNG"/></imageobject>
+ <textobject><phrase>Tutorial 4: Motors</phrase></textobject>
+ </mediaobject>
</screenshot>
-<para>In the experiment you have a disk and a box linked by a spring. A flat box at the bottom will make a boundary. The disk and the box both have a linear motor applied to them. Two controllers allow you to change the force value of each motor. Start the simulation and play with the controllers. Then stop the simulation and add a weight force in the world (forces are global and apply to the whole world). Restart the simulation and analyze the difference.</para>
-<para>You can also remove the linear motor on the box and add a circular motor instead. Click on <guilabel>CircularMotor</guilabel> in the <guilabel>Palette</guilabel> panel and then click on the box. The circular motor is applied to the box. You then need to set the torque value by clicking and moving the grey handler of the motor.</para>
+
+<para>In the experiment you have a disk and a box linked by a spring. A flat box at the bottom will make a boundary. The disk and the box both have a linear motor applied to them. Two controllers allow you to change the force value of each motor. Start the simulation and play with the controllers. Then stop the simulation and add a weight force in the world (forces are global and apply to the whole world). Restart the simulation and analyze the difference.
+</para>
+
+<para>You can also remove the linear motor on the box and add a circular motor instead. Press on the <inlinemediaobject><imageobject><imagedata fileref="step_object_CircularMotor.png" format="PNG"/></imageobject></inlinemediaobject> <guibutton>CircularMotor</guibutton> button in the <guilabel>Palette</guilabel> panel and then click on the box. The circular motor is applied to the box. You then need to set the torque value by clicking and moving the grey handler of the motor.
+</para>
+
<screenshot>
- <screeninfo>Circular motor</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="circular-motor.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Circular motor</phrase>
- </textobject>
- </mediaobject>
+ <screeninfo>Circular motor</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="circular-motor.png" format="PNG"/></imageobject>
+ <textobject><phrase>Circular motor</phrase></textobject>
+ </mediaobject>
</screenshot>
+
<para>This tutorial introduced you with motors and forces and you should now be able to add those to bodies.</para>
</sect1>
<sect1 id="tutorial5">
<title>Tutorial 5: Joints</title>
-<para>Joints are objects that attaches bodies to each other or to the background. You have a the following joints in &step;: anchors, pins and sticks. An anchor is a joint that
-fixes position of the body. The body cannot move when it has an anchor. A pin is a joint that fixes one point of the body, the body can still move around the pin. A stick is a joint that fixes the distance between two points on two bodies.</para>
+
+<para>Joints are objects that attaches bodies to each other or to the background. You have a the following joints in &step;: anchors, pins and sticks. An anchor is a joint that fixes position of the body. The body cannot move when it has an anchor. A pin is a joint that fixes one point of the body, the body can still move around the pin. A stick is a joint that fixes the distance between two points on two bodies.
+</para>
+
<screenshot>
- <screeninfo>Tutorial 5: double pendulum</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="tutorial5.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Tutorial 5: double pendulum</phrase>
- </textobject>
- </mediaobject>
+ <screeninfo>Tutorial 5: double pendulum</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="tutorial5.png" format="PNG"/></imageobject>
+ <textobject><phrase>Tutorial 5: double pendulum</phrase></textobject>
+ </mediaobject>
</screenshot>
-<para>Tutorial 5 describes a double pendulum.</para>
-<para>Add a <guilabel>Particle</guilabel> to the scene then join this particle to Particle2 with a stick. Click on Stick on the <guilabel>Palette</guilabel> panel. You then need to select the first object attached to the stick (particle2) with the left mouse button then drag the mouse to the second object (particle3) and release the mouse button on particle3. You now have a triple pendulum!</para>
+
+<para>Tutorial 5 describes a double pendulum.
+</para>
+
+<para>Add a <inlinemediaobject><imageobject><imagedata fileref="step_object_Particle.png" format="PNG"/></imageobject></inlinemediaobject> <guibutton>Particle</guibutton> to the scene then join this particle to Particle2 with a stick. Press the <inlinemediaobject><imageobject><imagedata fileref="step_object_Stick.png" format="PNG"/></imageobject></inlinemediaobject> <guibutton>Stick</guibutton> button on the <guilabel>Palette</guilabel> panel. You then need to select the first object attached to the stick (particle2) with the left mouse button then drag the mouse to the second object (particle3) and release the mouse button on particle3. You now have a triple pendulum!
+</para>
</sect1>
</chapter>
More information about the kde-doc-english
mailing list