Second part of prior commit

1 files changed, 154 insertions, 0 deletions

diff --git a/tde-i18n-en_GB/docs/tdeedu/kstars/scriptbuilder.docbook b/tde-i18n-en_GB/docs/tdeedu/kstars/scriptbuilder.docbook
new file mode 100644
index 00000000000..35e08cfb438
--- /dev/null
+++ b/tde-i18n-en_GB/docs/tdeedu/kstars/scriptbuilder.docbook
@@ -0,0 +1,154 @@
+<sect1 id="tool-scriptbuilder">
+<title
+>The Script Builder Tool</title>
+<indexterm
+><primary
+>Tools</primary>
+<secondary
+>Script Builder</secondary>
+</indexterm>
+
+<para
+>KDE applications can be controlled externally from another program, from a console prompt, or from a shell script using the Desktop COmmunication Protocol (<abbrev
+>DCOP</abbrev
+>). KStars takes advantage of this feature to allow rather complex behaviours to be scripted and played back at any time. This can be used, for example, to create a classroom demo to illustrate an astronomical concept. </para>
+<para
+>The problem with DCOP scripts is, writing them is a bit like programming, and can seem a daunting task to those who do not have programming experience. The Script Builder Tool provides a <abbrev
+>GUI</abbrev
+> point-and-click interface for constructing KStars DCOP scripts, making it very easy to create complex scripts. </para>
+
+<sect2 id="sb-intro">
+<title
+>Introduction to the Script Builder</title>
+
+<para
+>Before explaining how to use the Script Builder, I provide a very brief introduction to all of the <abbrev
+>GUI</abbrev
+> components; for more infomation, use the "What's This?" function. </para>
+
+<screenshot>
+<screeninfo
+>The Script Builder Tool </screeninfo>
+<mediaobject>
+  <imageobject>
+    <imagedata fileref="scriptbuilder.png" format="PNG"/>
+  </imageobject>
+  <textobject>
+    <phrase
+>Script Builder Tool</phrase>
+  </textobject>
+</mediaobject>
+</screenshot>
+
+<para
+>The Script Builder is shown in the above screenshot. The box on the left is the <firstterm
+>Current Script box</firstterm
+>; it shows the list of commands that comprise the current working script. The box on the right is the <firstterm
+>Function Browser</firstterm
+>; it displays the list of all available script functions. Below the Function Browser, there is a small panel which will display short documentation about the script function highlighted in the Function Browser. The panel below the Current Script box is the <firstterm
+>Function Arguments panel</firstterm
+>; when a function is highlighted in the Current Script box, this panel will contain items for specifying values for any arguments that the highlighted function requires. </para
+><para
+>Along the top of the window, there is a row of buttons which operate on the script as a whole. From left to right, they are: <guibutton
+>New Script</guibutton
+>, <guibutton
+>Open Script</guibutton
+>, <guibutton
+>Save Script</guibutton
+>, <guibutton
+>Save Script As...</guibutton
+>, and <guibutton
+>Test Script</guibutton
+>. The function of these buttons should be obvious, except perhaps the last button. Pressing <guibutton
+>Test Script</guibutton
+> will attempt to run the current script in the main KStars window. You should move the Script Builder window out of the way before pressing this, so you can see the results. </para
+><para
+>In the centre of the window, there is a column of buttons which operate on individual script functions. From top to bottom, they are: <guibutton
+>Add Function</guibutton
+>, <guibutton
+>Remove Function</guibutton
+>, <guibutton
+>Copy Function</guibutton
+>, <guibutton
+>Move Up</guibutton
+>, and <guibutton
+>Move Down</guibutton
+>. <guibutton
+>Add Function</guibutton
+> adds the currently-highlighted function in the Function Browser to the Current Script box (you can also add a function by double-clicking on it). The rest of the buttons operate on the function highlighted in the Current Script box, either removing it, duplicating it, or changing its position in the current script. </para>
+</sect2>
+
+<sect2 id="sb-using">
+<title
+>Using the Script Builder</title>
+<para
+>In order to illustrate using the Script Builder, we present a small tutorial example where we make a script that tracks the Moon while the clock runs at an accelerated rate. </para
+><para
+>If we are going to track the Moon, we will need to point the display at it first. The <firstterm
+>lookToward</firstterm
+> function is used to do this. Highlight this function in the Function Browser, and note the documentation displayed in the panel below the Browser. Press the <guibutton
+>Add Function</guibutton
+> button to add this function to the Current Script box. The Function Arguments panel will now contain a combobox labelled <quote
+>dir</quote
+>, short for direction. This is the direction in which the display should be pointed. The combobox contains only the cardinal compass points, not the Moon or any other objects. You can either enter <quote
+>Moon</quote
+> in the box manually, or press the <guibutton
+>Object</guibutton
+> button to use the <guilabel
+>Find Object</guilabel
+> window to select the Moon from the list of named objects. Note that, as usual, centring on an object automatically engages object-tracking mode, so there is no need to add the <firstterm
+>setTracking</firstterm
+> function after lookToward. </para
+><para
+>Now that we have taken care of pointing at the Moon, we next want to make time pass at an accelerated rate. Use the <firstterm
+>setClockScale</firstterm
+> function for this. Add it to the script by double-clicking on it in the Function Browser. The Function Arguments panel contains a timestep spinbox for setting the desired time step for the simulation clock. Change the timestep to 3 hours. </para
+><para
+>OK, we have pointed at the Moon and accelerated the clock. Now we just want the script to wait for several seconds while the display tracks on the Moon. Add the <firstterm
+>waitFor</firstterm
+> function to the script, and use the Function Arguments panel to specify that it should wait for 20 seconds before continuing. </para
+><para
+>To finish up, let us reset the clock's timestep to the normal value of 1 second. Add another instance of setClockScale, and set its value to 1 sec. </para
+><para
+>Actually, we are not quite done yet. We should probably make sure that the display is using Equatorial coordinates before the script tracks the Moon with an accelerated time step. Otherwise, if the display is using Horizontal coordinates, it will rotate very quickly through large angles as the Moon rises and sets. This can be very confusing, and is avoided by setting the View Option <firstterm
+>UseAltAz</firstterm
+> to <quote
+>false</quote
+>. To change any View Option, use the <firstterm
+>changeViewOption</firstterm
+> function. Add this function to the script, and examine the Function Arguments panel. There is a combobox which contains the list of all options which can be adjusted by changeViewOption. Since we know we want the UseAltAz option, we could simply select it from the combobox. However, the list is quite long, and there is no explanation of what each item is for. It therefore may be easier to press the <guibutton
+>Browse Tree</guibutton
+> button, which will open a window containing a tree view of the available options, organised by topic. In addition, each item has a short explanation of what the option does, and the data type of the option's value. We find UseAltAz under the <guilabel
+>Skymap options</guilabel
+> category. Just highlight this item and press <guibutton
+>OK</guibutton
+>, and it will be selected in the combobox of the Function Arguments panel. Finally, make its value <quote
+>false</quote
+> or <quote
+>0</quote
+>. </para
+><para
+>One more step: changing UseAltAz at the end of the script does us no good; we need this to be changed before anything else happens. So, make sure this function is highlighted in the Current Script box, and press the <guibutton
+>Move Up</guibutton
+> button until it is the first function. </para
+><para
+>Now that we have finished the script, we should save it to disk. Press the <guibutton
+>Save Script</guibutton
+> button. This will first open a window in which you can provide a name for the script, and fill in your name as the author. Enter <quote
+>Tracking the Moon</quote
+> for a name, and your name as the author, and press <guibutton
+>OK</guibutton
+>. Next, you will see the standard &kde; Save File dialog. Specify a filename for the script and press <guibutton
+>OK</guibutton
+> to save the script. Note that if your filename does not end with <quote
+>.kstars</quote
+>, this suffix will be automatically attached. If you are curious, you can examine the script file with any text editor. </para
+><para
+>Now that we have a completed script, we can run it in a couple of ways. From a console prompt, you can simply execute the script as long as an instance of KStars is currently running. Alternatively, you can execute the script from within KStars using the <guimenuitem
+>Run Script</guimenuitem
+> item in the <guimenu
+>File</guimenu
+> menu. </para>
+</sect2>
+
+</sect1>