[Ktutorial-commits] SF.net SVN: ktutorial:[282] trunk/ktutorial/ktutorial-editor/doc/en
Status: Alpha
Brought to you by:
danxuliu
Menu
▾
▴
[Ktutorial-commits] SF.net SVN: ktutorial:[282] trunk/ktutorial/ktutorial-editor/doc/en
|
From: <dan...@us...> - 2010-10-29 21:48:05
|
Revision: 282
http://ktutorial.svn.sourceforge.net/ktutorial/?rev=282&view=rev
Author: danxuliu
Date: 2010-10-29 21:47:59 +0000 (Fri, 29 Oct 2010)
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/main-window.png
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
Added Paths:
-----------
trunk/ktutorial/ktutorial-editor/doc/en/signal-name-completion.png
Modified: trunk/ktutorial/ktutorial-editor/doc/en/commands.docbook
===================================================================
--- trunk/ktutorial/ktutorial-editor/doc/en/commands.docbook 2010-10-29 21:43:09 UTC (rev 281)
+++ trunk/ktutorial/ktutorial-editor/doc/en/commands.docbook 2010-10-29 21:47:59 UTC (rev 282)
@@ -17,7 +17,81 @@
<varlistentry>
<term>
<menuchoice>
+ <shortcut>
+ <keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
+ </shortcut>
<guimenu>File</guimenu>
+ <guimenuitem>New</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Creates a new tutorial.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <shortcut>
+ <keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
+ </shortcut>
+ <guimenu>File</guimenu>
+ <guimenuitem>Open...</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Opens a saved tutorial.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>File</guimenu>
+ <guimenuitem>Open Recent</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Opens a tutorial from the list of the most recently used tutorials.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <shortcut>
+ <keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
+ </shortcut>
+ <guimenu>File</guimenu>
+ <guimenuitem>Save</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Saves the tutorial to the current file.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>File</guimenu>
+ <guimenuitem>Save As...</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Saves the tutorial to the selected file.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>File</guimenu>
<guimenuitem>Export...</guimenuitem>
</menuchoice>
</term>
@@ -54,7 +128,39 @@
<varlistentry>
<term>
<menuchoice>
+ <shortcut>
+ <keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo>
+ </shortcut>
<guimenu>Edit</guimenu>
+ <guimenuitem>Undo</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Undoes the last edition action not undone yet.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <shortcut>
+ <keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo>
+ </shortcut>
+ <guimenu>Edit</guimenu>
+ <guimenuitem>Redo</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Does again the last undone edition action not redone yet.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Edit</guimenu>
<guimenu>Tutorial</guimenu>
<guimenuitem>Set information...</guimenuitem>
</menuchoice>
@@ -219,6 +325,19 @@
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Edit</guimenu>
+ <guimenuitem>Test tutorial</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Starts the tutorial in the target application.</action>
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</para>
</sect2>
Modified: trunk/ktutorial/ktutorial-editor/doc/en/installation.docbook
===================================================================
--- trunk/ktutorial/ktutorial-editor/doc/en/installation.docbook 2010-10-29 21:43:09 UTC (rev 281)
+++ trunk/ktutorial/ktutorial-editor/doc/en/installation.docbook 2010-10-29 21:47:59 UTC (rev 282)
@@ -7,7 +7,7 @@
<appendix id="installation">
<title>Installation</title>
- <sect1 id="getting-klusi">
+ <sect1 id="getting-ktutorial">
<title>How to obtain &ktutorial-editor;</title>
<para>&ktutorial-editor; is part of KTutorial package, which is hosted at <ulink url="http://sourceforge.net/">SourceForge.net</ulink>.</para>
@@ -24,6 +24,8 @@
<para>In order to successfully build and use KTutorial, you need &kde; (at least version 4.3) and, therefore, &Qt; (at least version 4.5.3).</para>
+ <para>To use the full feature set of &ktutorial-editor; you will also need the QtDBus module of Qt, only available in Unix systems. Without that module &ktutorial-editor; can not talk to the target application, for example to know the name of its objects.</para>
+
<para>Also, <application>CMake</application> build system is required to build KTutorial, as required to build any other &kde; application.</para>
</sect1>
Modified: trunk/ktutorial/ktutorial-editor/doc/en/main-window.png
===================================================================
(Binary files differ)
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)
Added: trunk/ktutorial/ktutorial-editor/doc/en/signal-name-completion.png
===================================================================
(Binary files differ)
Property changes on: trunk/ktutorial/ktutorial-editor/doc/en/signal-name-completion.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Modified: trunk/ktutorial/ktutorial-editor/doc/en/using.docbook
===================================================================
--- trunk/ktutorial/ktutorial-editor/doc/en/using.docbook 2010-10-29 21:43:09 UTC (rev 281)
+++ trunk/ktutorial/ktutorial-editor/doc/en/using.docbook 2010-10-29 21:47:59 UTC (rev 282)
@@ -24,7 +24,7 @@
<para>The most interesting feature is that, with KTutorial, applications can explain to the user how to do something in an interactive way. Each step contains one or more reactions. A reaction is composed by a trigger and a response: when the reaction is triggered, the response is executed.</para>
- <para>There are two types of triggers: options and conditions to wait for. Options are shown to the user as buttons below the text of the step, and the response is executed when the user selects the option. Conditions to wait for are not show in any way to the user, and the response is executed when the condition is met. For example, when an object receives an event, or when an object emits a signal.</para>
+ <para>There are two types of triggers: options and conditions to wait for. Options are shown to the user as buttons below the text of the step, and the response is executed when the user selects the option. Conditions to wait for are not shown in any way to the user, and the response is executed when the condition is met. For example, when an object receives an event, or when an object emits a signal.</para>
<para>There are also two types of responses: changing to another step, or executing some custom code.</para>
@@ -40,7 +40,7 @@
<para>When the scripted tutorial is part of an application (it is installed with the rest of the application data when the application is installed), the strings in the scripted tutorial can be extracted to be localized before the installation like any other string in the C++ code, as explained in KTutorial documentation. Scripted tutorials that are added after the application was installed, however, can not be localized, as KTutorial uses the same translation file as the rest of the application where it is used.</para>
- <para>As you may have guessed already, &ktutorial-editor; creates scripted tutorials. Right now, only Javascript is supported, as &kde; libraries offer out of the box support for Javascript scripts. Python or Ruby, on the other hand, require some specific packages to be installed in the system.</para>
+ <para>As you may have guessed already, &ktutorial-editor; creates scripted tutorials. Right now, only Javascript is supported by &ktutorial-editor;, as &kde; libraries offer out of the box support for Javascript scripts. Python or Ruby, on the other hand, require some specific packages to be installed in the system.</para>
</sect1>
<sect1 id="main-window">
@@ -56,6 +56,8 @@
<para>As well as being shown in the <guimenu>Edit</guimenu> menu, the actions to edit a tutorial, a step and a reaction are shown in three panels provided for convenience. The panels can be shown or hidden from <guimenu>View</guimenu> menu, and can be docked to the top, bottom, right or left side of the main window. If desired, they can also be dragged out of the window to make them floating panels.</para>
+ <para>Every edition action can be undone and redone using the typical undo/redo system. Note, however, that the whole action is undone/redone, and not each tiny change that make up the action. That is, when an edition dialog is opened, several changes are made in the dialog, the dialog is accepted and then the action is undone, the tutorial will get back to the state it had before the edition dialog was opened, no matter what or how many changes were made while the dialog was opened.</para>
+
<screenshot>
<screeninfo>The main window of &ktutorial-editor; with a tutorial being worked on</screeninfo>
<mediaobject>
@@ -115,6 +117,11 @@
<title>Step edition</title>
<para>The step data dialog is used to set the id and text of a step. The id and text are mandatory properties, as the id is used by other steps to change to this step, and the text is shown to the user to explain him what must be done. Thus, the id must be unique for every step in the same tutorial.</para>
+ <tip>
+ <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><strong>Hello world!</strong></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><a href="widget:theWidgetObjectName">this is a link</a></emphasis> (if the HTML subset is used) or <emphasis><link url="widget:theWidgetObjectName">this is a link</link></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>
+ </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>
@@ -172,19 +179,90 @@
</mediaobject>
</screenshot>
- <para>Only simple conditions (waiting for an event and waiting for a signal) 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 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>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>
+
+ <important>
+ <title>Conditions and modal dialogs</title>
+ <para>Modal dialogs are those that block the interaction with the windows of the application under them (for example, an error message). When a modal dialog is shown by the application after the user clicks a button, the condition to wait for must be the dialog being shown, but never the button being clicked. The reason has to do with Qt's internals and it is out of the scope for this document.</para>
+ <para>Take, for example, an <emphasis>Open file</emphasis> dialog. If the condition to change to the next step is waiting for the <function>clicked()</function> signal to be emitted by the button that shows the dialog, the step will freeze until the <emphasis>Open file</emphasis> dialog is closed, and then it will change to the next step. Instead, the condition to change to the next step must be waiting for the <emphasis>Open file</emphasis> dialog to be shown.</para>
+ <para>The condition to wait for windows to be shown supports both windows and dialogs, so whenever a window or dialog is shown you can safely use that condition without worrying about whether it is a window, a modal dialog or a modeless dialog.</para>
+ </important>
</sect3>
</sect2>
</sect1>
+ <sect1 id="target-application">
+ <title>Interacting with the target application</title>
+
+ <para>When a tutorial is being designed it is usually necessary to know some internals about the target application of the tutorial. For example, in order to wait for a signal emitted by an object the name of the object must be known. However, it is very unlikely that even the developers of the application know those things by heart.</para>
+ <para>To help with this problem &ktutorial-editor; is able to "talk" with any application using KTutorial to provide the tutorial designer internal information about the target application. For example, it can provide a list with the names of all the objects accessible by KTutorial in the target application.</para>
+ <para>Note, however, that the intercommunication system between &ktutorial-editor; and KTutorial works only if they were built with D-Bus system support. Don't worry, though, as it would be very unlikely that the packages of your GNU/Linux distribution were not built with D-Bus support, and if you are building it yourself you probably know what all this means ;)</para>
+
+ <sect2 id="target-application-start">
+ <title>Starting the target application</title>
+
+ <para>&ktutorial-editor; requires an instance of the target application to be running in order to talk with it, although that instance must have been launched by &ktutorial-editor; itself.</para>
+ <para>So, how can the target application be started from &ktutorial-editor;? When you execute some action that requires &ktutorial-editor; to talk to the target application a dialog to choose the application is shown to you. The application can be selected from the proposed application list, or the full path to the application can be manually specified.</para>
+ <para>Note that the application list contains all the known KDE applications in the system, instead of just those that use KTutorial. &ktutorial-editor; will warn you after launching the application if it is not a valid application.</para>
+ <para>Once a valid target application has been specified it will be used automatically until the tutorial being designed is closed. If the target application instance is closed, &ktutorial-editor; will launch another instance automatically when it needs to talk again to the target application.</para>
+ </sect2>
+
+ <sect2 id="target-application-object-choosing">
+ <title>Choosing an object in the target application</title>
+
+ <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>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>
+ </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>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>
+
+ <sect2 id="target-application-other">
+ <title>Other less noticeable features</title>
+
+ <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 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>
+ <screeninfo>An example of text completion for a signal name</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="signal-name-completion.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Signal name completion</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </sect2>
+ </sect1>
+
+ <sect1 id="save-load-tutorial">
+ <title>Saving and loading again the tutorial</title>
+
+ <para>&ktutorial-editor; supports saving a tutorial being designed so it can be loaded later to continue working on it. To do this, just use the standard <menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice> and <menuchoice><guimenu>File</guimenu><guimenuitem>Open...</guimenuitem></menuchoice> menu entries.</para>
+ <para>Note that tutorials are saved in an XML format specific to &ktutorial-editor;. A tutorial saved by &ktutorial-editor; can not be used in KTutorial. The tutorial must be <link linkend="export-tutorial">exported</link> before KTutorial can understand it.</para>
+ <para>Also note that loading and saving a tutorial does not need to be done from or to a local file. Both the dialog to open a tutorial and the dialog to save it support remote directories (via <acronym>FTP</acronym>, <acronym>SSH</acronym>, etc).</para>
+ <para>When a tutorial is loaded or saved it is added to the recently used file list. <menuchoice><guimenu>File</guimenu><guimenuitem>Open Recent</guimenuitem></menuchoice> provides a quick way to load a recently used tutorial from that list.</para>
+ </sect1>
+
<sect1 id="export-tutorial">
<title>Exporting the tutorial</title>
<para>Once you have finished designing the tutorial you can export it to a scripted tutorial. To do this, just use <menuchoice><guimenu>File</guimenu><guimenuitem>Export...</guimenuitem></menuchoice>, select where to save the file and you are done. Remember that you have to export the file to some specific directory to be found by KTutorial, as explained in <xref linkend="understanding-ktutorial"/>.</para>
- <para>The export dialog supports exporting to remote directories (via <acronym>FTP</acronym>, <acronym>SSH</acronym>, etc), although it will be very strange that you need to use that.</para>
+ <para>The export dialog also supports exporting to remote directories, although it will be very strange that you need to use that.</para>
</sect1>
<sect1 id="command-line-options">
@@ -192,6 +270,10 @@
<para>Though &ktutorial-editor; will be usually started from the &kde; program menu, or a desktop icon, it can also be opened from the command line prompt of a terminal window. There are a few options that are available when doing this.</para>
+ <para>Apart from generic &kde; command line options, &ktutorial-editor; optionally accepts an URL to load a tutorial from it:</para>
+ <cmdsynopsis><command>ktutorial-editor</command> <arg choice="opt" rep="norepeat">URL</arg></cmdsynopsis>
+ <para>The URL does not need to be a local file; remote directories are also supported.</para>
+
<sect2 id="other-command-line-options">
<title>Default &kde; Command Line Options</title>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
