[Ktutorial-commits] SF.net SVN: ktutorial:[327] trunk/ktutorial/ktutorial-editor/doc/en

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Revision: 327
          http://ktutorial.svn.sourceforge.net/ktutorial/?rev=327&view=rev
Author:   danxuliu
Date:     2011-06-17 01:49:37 +0000 (Fri, 17 Jun 2011)

Log Message:
-----------
Update English handbook.

Modified Paths:
--------------
    trunk/ktutorial/ktutorial-editor/doc/en/commands.docbook
    trunk/ktutorial/ktutorial-editor/doc/en/installation.docbook
    trunk/ktutorial/ktutorial-editor/doc/en/new-condition.png
    trunk/ktutorial/ktutorial-editor/doc/en/set-step-data.png
    trunk/ktutorial/ktutorial-editor/doc/en/using.docbook

Modified: trunk/ktutorial/ktutorial-editor/doc/en/commands.docbook
===================================================================

--- trunk/ktutorial/ktutorial-editor/doc/en/commands.docbook	2011-06-17 01:46:54 UTC (rev 326)
+++ trunk/ktutorial/ktutorial-editor/doc/en/commands.docbook	2011-06-17 01:49:37 UTC (rev 327)
@@ -338,6 +338,19 @@
                             </para>
                         </listitem>
                     </varlistentry>
+                    <varlistentry>
+                        <term>
+                            <menuchoice>
+                                <guimenu>Edit</guimenu>
+                                <guimenuitem>Test tutorial from current step</guimenuitem>
+                            </menuchoice>
+                        </term>
+                        <listitem>
+                            <para>
+                                <action>Starts the tutorial in the target application from the currently selected step.</action>
+                            </para>
+                        </listitem>
+                    </varlistentry>
                 </variablelist>
             </para>
         </sect2>

Modified: trunk/ktutorial/ktutorial-editor/doc/en/installation.docbook
===================================================================
--- trunk/ktutorial/ktutorial-editor/doc/en/installation.docbook	2011-06-17 01:46:54 UTC (rev 326)
+++ trunk/ktutorial/ktutorial-editor/doc/en/installation.docbook	2011-06-17 01:49:37 UTC (rev 327)
@@ -34,19 +34,15 @@
 
         <para>In order to compile KTutorial on your system, extract the KTutorial package you downloaded and type the following in the base directory of the extracted package:</para>
 
-        <screen>
-            <prompt>$</prompt> <userinput><command>mkdir</command> build &amp;&amp; <command>cd</command> build</userinput>
-            <prompt>$</prompt> <userinput><command>cmake</command> ..</userinput>
-            <prompt>$</prompt> <userinput><command>make</command></userinput>
-        </screen>
+        <screen><prompt>$</prompt> <userinput><command>mkdir</command> build &amp;&amp; <command>cd</command> build</userinput>
+<prompt>$</prompt> <userinput><command>cmake</command> ..</userinput>
+<prompt>$</prompt> <userinput><command>make</command></userinput></screen>
 
         <para>That will create a <filename class="directory">build</filename> directory, change to it, prepare the build directory to build KTutorial on it and finally build KTutorial. If <command>cmake</command> complains, you have to install the required dependencies asked in the error message.</para>
 
         <para>To install KTutorial, become root user and run:</para>
 
-        <screen>
-            <prompt>#</prompt> <userinput><command>make</command> install</userinput>
-        </screen>
+        <screen><prompt>#</prompt> <userinput><command>make</command> install</userinput></screen>
 
         <tip>
             <title>Installing &ktutorial-editor; in <filename class="directory">/usr/local/</filename></title>
@@ -55,9 +51,7 @@
 
             <para>This is the directory that should be used for manually installed packages. To do this, instead of executing <command>cmake</command> as stated before, execute this:</para>
 
-            <screen>
-            <prompt>$</prompt> <userinput><command>cmake</command> <parameter class="command">-DCMAKE_INSTALL_PREFIX=<filename class="directory">/usr/local/</filename></parameter></userinput>
-            </screen>
+            <screen><prompt>$</prompt> <userinput><command>cmake</command> <parameter class="command">-DCMAKE_INSTALL_PREFIX=<filename class="directory">/usr/local/</filename></parameter></userinput></screen>
         </tip>
     </sect1>
 

Modified: trunk/ktutorial/ktutorial-editor/doc/en/new-condition.png
===================================================================
(Binary files differ)

Modified: trunk/ktutorial/ktutorial-editor/doc/en/set-step-data.png
===================================================================
(Binary files differ)

Modified: trunk/ktutorial/ktutorial-editor/doc/en/using.docbook
===================================================================
--- trunk/ktutorial/ktutorial-editor/doc/en/using.docbook	2011-06-17 01:46:54 UTC (rev 326)
+++ trunk/ktutorial/ktutorial-editor/doc/en/using.docbook	2011-06-17 01:49:37 UTC (rev 327)
@@ -121,6 +121,7 @@
                 <title>Rich text and widget higlighting</title>
                 <para>When writing the text of a step you can use the <ulink url="http://doc.trolltech.com/richtext-html-subset.html">supported subset of HTML tags</ulink> or the <ulink url="http://techbase.kde.org/Development/Tutorials/Localization/i18n_Semantics#Semantic_Tags">KDE semantic markup tags</ulink> to enrich the text. For example, <emphasis>&lt;strong&gt;Hello world!&lt;/strong&gt;</emphasis> will appear as <emphasis role="strong">Hello world!</emphasis> when shown in the tutorial.</para>
                 <para>KTutorial also provides a special type of link that highlights the referenced widget in order to be found easily. For example, <emphasis>&lt;a href="widget:theWidgetObjectName"&gt;this is a link&lt;/a&gt;</emphasis> (if the HTML subset is used) or <emphasis>&lt;link url="widget:theWidgetObjectName"&gt;this is a link&lt;/link&gt;</emphasis> (if KDE semantic markup is used) will show <emphasis>this is a link</emphasis> with a link appearance (underlined and with some special color) and, when the link is clicked, the widget with the given object name will be highlighted. Clicking the link again will stop highlighting the widget.</para>
+                <para>To ease all these things, &ktutorial-editor; provides several buttons in the step data dialog that help writing KDE semantic markup tags. These buttons insert the start and end tags for an element as needed, and are enabled or disabled based on the position of the cursor in the text. For example, the button to insert a paragraph tag will be disabled if the cursor is inside a link, but the button to insert a link tag will be enabled if the cursor is inside a paragraph.</para>
             </tip>
             <para>The step data dialog is also shown when a new step is added. If the dialog is accepted, the step is added. If the dialog is cancelled, the step is not added.</para>
             <para>Also note that, in every tutorial, there must be one step with id <emphasis>start</emphasis>, so KTutorial knows where to start the tutorial.</para>
@@ -179,7 +180,7 @@
                     </mediaobject>
                 </screenshot>
 
-                <para>Only simple conditions (waiting for an event, waiting for a signal and waiting for a window to be shown) can be edited, showing specific dialogs for it. Composed conditions only group other conditions, so they don't have properties to be edited.</para>
+                <para>Only simple conditions (waiting for an event, waiting for a signal, waiting for a window to be shown and waiting for a property to have certain value) can be edited, showing specific dialogs for it. Composed conditions only group other conditions, so they don't have properties to be edited. The condition to wait for its step to be activated, despite being a simple condition, can not be edited either.</para>
                 <para>Any condition can be removed from its parent composed condition, or from the reaction if it is the root condition.</para>
 
                 <para>There is a special type of condition that verifies that its negated condition wasn't met which purpose is to be used only as a child of a composed condition that waits until all its child conditions were met. The idea is that, when the negated condition wasn't met, the special condition is met. When the negated condition is met, the special condition is no longer met. It can be used, for example, to make a reaction wait for the user to write something in a text line, provided he has not pressed a button before. Note that a fallback reaction should be added in cases like this one.</para>
@@ -216,14 +217,22 @@
             <para>When you want to choose an object from the target application a list with all the objects accessible by &ktutorial-editor; in the target application is shown. The name and class of each object is shown in their entry of the list. The list is an hierarchical structure, thus the parent-child relationship between objects is also shown.</para>
             <para>The list is updated when there are changes in the target application. For example, if a new dialog is shown in the target application, the dialog and all its children will be shown in the list.</para>
             <para>Usually, the objects used in tutorials are widgets, so when a widget is selected in the list it is highlighted in the target application. Plain objects obviously are not, as they do not have a graphical representation.</para>
+            <para>As widgets are the most used objects in tutorials, plain objects can be filtered from the list. In the same way, objects without name can also be filtered. However, some objects may appear in the list even if they should be hidden when they have any descendant that passes the enabled filters.</para>
             <para>When the list with the objects is shown, the rest of the &ktutorial-editor; windows are hidden. It is made to better view the widgets when they are highlighted in the target application. The &ktutorial-editor; windows are shown again once the selection list is closed.</para>
+            <tip>
+                <title>Objects with duplicated names</title>
+                <para>Usually, the name of an object in the target application will identify that and only that object. However, sometimes there could be two or more objects with the same name. For example, if there are two or more dialogs opened, there will probably be two or more objects named <literal>Ok button</literal>.</para>
+                <para>Therefore, when two or more objects have the same name, they can not be identified by their name alone. Instead, their name must be qualified with the name of one or more ancestor objects. For example, <literal>Configuration dialog/Ok button</literal>. When an object is chosen in the list, &ktutorial-editor; takes care of all this and gets a unique name for the object.</para>
+                <para>But note that a name and the object it represents depends on the state of the target application. For example, if there is a dialog named <literal>Configuration dialog</literal> with a button named <literal>Ok button</literal>, its unique name could be just <literal>Ok button</literal>. However, if another dialog named <literal>File information dialog</literal> were opened while the <literal>Configuration dialog</literal> was still opened, and <literal>File information dialog</literal> had a also button called <literal>Ok button</literal>, now the unique name of the first button would be <literal>Configuration dialog/Ok button</literal>. In this situation, <literal>Ok button</literal> would not represent a specific object in the target application.</para>
+                <para>All that means that, when choosing an object from the target application, the target application should be in the same state as it would be when following the tutorial and getting to the current step.</para>
+            </tip>
         </sect2>
 
         <sect2 id="target-application-tutorial-testing">
             <title>Testing a tutorial in the target application</title>
 
             <para>Designing a tutorial is not a failproof task. Maybe your custom code does not work as expected, or you are not waiting for the right signal to be emitted, or you forgot some step, or... so the tutorial will have to be tested at least once, but more likely several times.</para>
-            <para>Exporting the tutorial to the application data directory and then starting the target application each time you want to test the tutorial can be very tedious. To ease testing the tutorial, &ktutorial-editor; is able to start the tutorial being designed directly in the target application.</para>
+            <para>Exporting the tutorial to the application data directory and then starting the target application each time you want to test the tutorial can be very tedious. To ease testing the tutorial, &ktutorial-editor; is able to start the tutorial being designed directly in the target application. The tutorial can be started from the beginning or from the currently selected step.</para>
             <para>Note, however, that after closing the tutorial the target application will know nothing about it. You will have to use the test action in &ktutorial-editor; to start it again, or <link linkend="export-tutorial">export</link> it to a directory known by KTutorial if you want to start it from the application itself.</para>
         </sect2>
 
@@ -232,7 +241,8 @@
 
             <para>Besides those already mentioned, &ktutorial-editor; uses a running target application to provide other small yet useful features.</para>
             <para>The one-line text editors to set the name of an object have text completion, so if instead of choosing the object its name is written directly in the text editor it will suggest the name based on the objects in the target application.</para>
-            <para>The one-line text editor to set the name of a signal also has text completion, so when the object name was set, the text editor will suggest the signal name based on the signals that can be emitted by that object.</para>
+            <para>The one-line text editor to set the name of a signal also has text completion, so when the object name was set, the text editor will suggest the signal name based on the signals that can be emitted by that object. The same schema is used for the name of properties.</para>
+            <para>The one-line text editors for step ids in the step data and reaction dialogs have text completion too. The first one will suggest the ids not assigned yet (from the <emphasis>change to step</emphasis> field of the reactions), and the second one will suggest the ids already set in the steps.</para>
             <para>The text completion uses the standard KDE text completion system, so all the standard keyboard shortcuts can be used (like <keycombo action="simul">&Ctrl;<keycap>T</keycap></keycombo> to show all the available completions).</para>
 
             <screenshot>


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.


