[Ktutorial-commits] SF.net SVN: ktutorial:[186] trunk/ktutorial/ktutorial-editor
Status: Alpha
Brought to you by:
danxuliu
Menu
▾
▴
[Ktutorial-commits] SF.net SVN: ktutorial:[186] trunk/ktutorial/ktutorial-editor
|
From: <dan...@us...> - 2010-03-23 22:22:11
|
Revision: 186
http://ktutorial.svn.sourceforge.net/ktutorial/?rev=186&view=rev
Author: danxuliu
Date: 2010-03-23 22:22:03 +0000 (Tue, 23 Mar 2010)
Log Message:
-----------
Add KTutorial editor English handbook
Modified Paths:
--------------
trunk/ktutorial/ktutorial-editor/CMakeLists.txt
Added Paths:
-----------
trunk/ktutorial/ktutorial-editor/doc/
trunk/ktutorial/ktutorial-editor/doc/CMakeLists.txt
trunk/ktutorial/ktutorial-editor/doc/en/
trunk/ktutorial/ktutorial-editor/doc/en/CMakeLists.txt
trunk/ktutorial/ktutorial-editor/doc/en/commands.docbook
trunk/ktutorial/ktutorial-editor/doc/en/index.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-reaction-data.png
trunk/ktutorial/ktutorial-editor/doc/en/set-step-data.png
trunk/ktutorial/ktutorial-editor/doc/en/set-tutorial-information.png
trunk/ktutorial/ktutorial-editor/doc/en/using.docbook
Modified: trunk/ktutorial/ktutorial-editor/CMakeLists.txt
===================================================================
--- trunk/ktutorial/ktutorial-editor/CMakeLists.txt 2010-03-23 08:02:59 UTC (rev 185)
+++ trunk/ktutorial/ktutorial-editor/CMakeLists.txt 2010-03-23 22:22:03 UTC (rev 186)
@@ -4,6 +4,7 @@
include(KDE4Defaults)
+add_subdirectory(doc)
add_subdirectory(po)
add_subdirectory(src)
add_subdirectory(tests)
Added: trunk/ktutorial/ktutorial-editor/doc/CMakeLists.txt
===================================================================
--- trunk/ktutorial/ktutorial-editor/doc/CMakeLists.txt (rev 0)
+++ trunk/ktutorial/ktutorial-editor/doc/CMakeLists.txt 2010-03-23 22:22:03 UTC (rev 186)
@@ -0,0 +1 @@
+add_subdirectory(en)
Property changes on: trunk/ktutorial/ktutorial-editor/doc/CMakeLists.txt
___________________________________________________________________
Added: svn:eol-style
+ native
Added: trunk/ktutorial/ktutorial-editor/doc/en/CMakeLists.txt
===================================================================
--- trunk/ktutorial/ktutorial-editor/doc/en/CMakeLists.txt (rev 0)
+++ trunk/ktutorial/ktutorial-editor/doc/en/CMakeLists.txt 2010-03-23 22:22:03 UTC (rev 186)
@@ -0,0 +1,3 @@
+########### install files ################
+
+kde4_create_handbook(index.docbook INSTALL_DESTINATION ${HTML_INSTALL_DIR}/en SUBDIR ktutorial-editor)
Property changes on: trunk/ktutorial/ktutorial-editor/doc/en/CMakeLists.txt
___________________________________________________________________
Added: svn:eol-style
+ native
Added: trunk/ktutorial/ktutorial-editor/doc/en/commands.docbook
===================================================================
--- trunk/ktutorial/ktutorial-editor/doc/en/commands.docbook (rev 0)
+++ trunk/ktutorial/ktutorial-editor/doc/en/commands.docbook 2010-03-23 22:22:03 UTC (rev 186)
@@ -0,0 +1,356 @@
+<!--<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> -->
+<!-- Uncomment the previous two lines to validate this document -->
+<!-- standalone. Be sure to recomment them before attempting to -->
+<!-- process index.docbook -->
+
+<chapter id="commands">
+ <title>Command Reference</title>
+
+ <sect1 id="commands-mainwindow">
+ <title>The main &ktutorial-editor; window</title>
+
+ <sect2>
+ <title>The <guimenu>File</guimenu> Menu</title>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>File</guimenu>
+ <guimenuitem>Export...</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Exports the tutorial to a script.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <shortcut>
+ <keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
+ </shortcut>
+ <guimenu>File</guimenu>
+ <guimenuitem>Quit</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Quits &ktutorial-editor;.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>The <guimenu>Edit</guimenu> Menu</title>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Edit</guimenu>
+ <guimenu>Tutorial</guimenu>
+ <guimenuitem>Set information...</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Opens the dialog to set the name and description of the tutorial.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Edit</guimenu>
+ <guimenu>Tutorial</guimenu>
+ <guimenuitem>Set license...</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Opens the dialog to set the license text of the tutorial.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Edit</guimenu>
+ <guimenu>Tutorial</guimenu>
+ <guimenuitem>Set setup code...</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Opens the dialog to set the custom code to be executed when the tutorial starts.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Edit</guimenu>
+ <guimenu>Tutorial</guimenu>
+ <guimenuitem>Set tear down code...</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Opens the dialog to set the custom code to be executed when the tutorial finishes.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Edit</guimenu>
+ <guimenu>Step</guimenu>
+ <guimenuitem>Add step...</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Opens the dialog to add a new step to the tutorial</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Edit</guimenu>
+ <guimenu>Step</guimenu>
+ <guimenuitem>Set data...</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Opens the dialog to set the name and text of the currently selected step.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Edit</guimenu>
+ <guimenu>Step</guimenu>
+ <guimenuitem>Set setup code...</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Opens the dialog to set the custom code to be executed when the tutorial passes to the currently selected step.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Edit</guimenu>
+ <guimenu>Step</guimenu>
+ <guimenuitem>Set tear down code...</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Opens the dialog to set the custom code to be executed when the tutorial changes from the currently selected step to another step.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Edit</guimenu>
+ <guimenu>Step</guimenu>
+ <guimenuitem>Remove step</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Removes the currently selected step from the tutorial.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Edit</guimenu>
+ <guimenu>Reaction</guimenu>
+ <guimenuitem>Add reaction...</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Opens the dialog to add a new reaction to the selected step.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Edit</guimenu>
+ <guimenu>Reaction</guimenu>
+ <guimenuitem>Set data...</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Opens the dialog to set the trigger and response of the currently selected reaction.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Edit</guimenu>
+ <guimenu>Reaction</guimenu>
+ <guimenuitem>Remove reaction</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Removes the currently selected reaction from its step.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>The <guimenu>View</guimenu> Menu</title>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>View</guimenu>
+ <guimenuitem>Panels</guimenuitem>
+ <guimenuitem>Edit tutorial</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Shows or hides the panel with the shorcuts to tutorial edition actions.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>View</guimenu>
+ <guimenuitem>Panels</guimenuitem>
+ <guimenuitem>Edit step</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Shows or hides the panel with the shorcuts to step edition actions.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>View</guimenu>
+ <guimenuitem>Panels</guimenuitem>
+ <guimenuitem>Edit reaction</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Shows or hides the panel with the shorcuts to reaction edition actions.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>The <guimenu>Settings</guimenu> Menu</title>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Settings</guimenu>
+ <guimenuitem>Show Toolbar</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Shows or hides the main toolbar.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Settings</guimenu>
+ <guimenuitem>Show Statusbar</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Shows or hides the statusbar.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Settings</guimenu>
+ <guimenuitem>Configure Shortcuts...</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Opens a configure dialog for binding keys to actions.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <menuchoice>
+ <guimenu>Settings</guimenu>
+ <guimenuitem>Configure Toolbars...</guimenuitem>
+ </menuchoice>
+ </term>
+ <listitem>
+ <para>
+ <action>Opens a configure dialog for selecting the actions to show in the toolbar.</action>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>The <guimenu>Help</guimenu> Menu</title>
+
+ &help.menu.documentation;
+
+ </sect2>
+ </sect1>
+</chapter>
+
+<!--
+Local Variables:
+mode: xml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+vim:tabstop=4:shiftwidth=4:expandtab
+kate: space-indent on; indent-width 4; tab-width 4; indent-mode none;
+-->
Added: trunk/ktutorial/ktutorial-editor/doc/en/index.docbook
===================================================================
--- trunk/ktutorial/ktutorial-editor/doc/en/index.docbook (rev 0)
+++ trunk/ktutorial/ktutorial-editor/doc/en/index.docbook 2010-03-23 22:22:03 UTC (rev 186)
@@ -0,0 +1,125 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+ <!ENTITY ktutorial-editor "<application>KTutorial editor</application>">
+ <!ENTITY kappname "&ktutorial-editor;">
+ <!ENTITY package "kde-module">
+ <!ENTITY % addindex "IGNORE">
+ <!ENTITY % English "INCLUDE">
+
+ <!ENTITY using SYSTEM "using.docbook">
+ <!ENTITY commands SYSTEM "commands.docbook">
+ <!ENTITY installation SYSTEM "installation.docbook">
+]>
+
+<!-- ................................................................ -->
+
+<book lang="&language;">
+
+<!-- This header contains all of the meta-information for the document such
+as Authors, publish date, the abstract, and Keywords -->
+
+<bookinfo>
+ <title>The &ktutorial-editor; Handbook</title>
+
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Daniel</firstname>
+ <surname>Calviño Sánchez</surname>
+ </personname>
+ <email>dan...@gm...</email>
+ </author>
+ </authorgroup>
+
+ <!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+ <copyright>
+ <year>2010</year>
+ <holder>Daniel Calviño Sánchez</holder>
+ </copyright>
+ <!-- Translators: put here the copyright notice of the translation -->
+ <!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook
+ and in the FDL itself on how to use it. -->
+ <legalnotice>&FDLNotice;</legalnotice>
+
+ <!-- Date and version information of the documentation
+ Don't forget to include this last date and this last revision number, we
+ need them for translation coordination !
+ Please respect the format of the date (YYYY-MM-DD) and of the version
+ (V.MM.LL), it could be used by automation scripts.
+ Do NOT change these in the translation. -->
+
+ <date>2010-03-23</date>
+ <releaseinfo>0.1</releaseinfo>
+
+ <!-- Abstract about this handbook -->
+
+ <abstract>
+ <para>&ktutorial-editor; is a graphical editor for KTutorial tutorials.</para>
+ </abstract>
+
+ <keywordset>
+ <keyword>KDE</keyword>
+ <keyword>KTutorial editor</keyword>
+ <keyword>KTutorial</keyword>
+ <keyword>tutorial</keyword>
+ <keyword>editor</keyword>
+ </keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+ <title>Introduction</title>
+
+ <para>&ktutorial-editor; is a graphical editor for KTutorial tutorials.</para>
+ <para>KTutorial is a interactive tutorial system for KDE 4. You can get more information about KTutorial in its webpage: <ulink url="http://ktutorial.sourceforge.net">http://ktutorial.sourceforge.net</ulink>.</para>
+ <para>Using &ktutorial-editor; you can design a tutorial for some application specifying the steps that it will be composed of. For each step, you can specify how the tutorial will react, for example, when the user selects an option, closes a dialog, writes some text...</para>
+ <para>Once the tutorial has been designed, it can be exported by &ktutorial-editor; to a scripted tutorial. Once the scripted tutorial is placed in the appropriate directory, it can be read by KTutorial library and started by the user of the application. </para>
+ <para>Tutorials created by &ktutorial-editor; are not as powerful as fully hand made tutorials. However, they are way easier to create and the generated source code can be used as a skeleton to be manually completed if the tutorial requires something not supported by &ktutorial-editor;.</para>
+</chapter>
+
+&using;
+&commands;
+
+<chapter id="credits">
+
+ <!-- Include credits for the programmers, documentation writers, and
+ contributors here. -->
+
+ <title>Credits and License</title>
+
+ <para>
+ &ktutorial-editor;
+ </para>
+ <para>
+ Program Copyright 2010 Daniel Calviño Sánchez <email>dan...@gm...</email>
+ </para>
+
+ <para>
+ Documentation Copyright 2010 Daniel Calviño Sánchez <email>dan...@gm...</email>
+ </para>
+
+ <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+ &underFDL;
+ &underGPL;
+
+</chapter>
+
+&installation;
+
+&documentation.index;
+</book>
+
+<!--
+Local Variables:
+mode: xml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+vim:tabstop=4:shiftwidth=4:expandtab
+kate: space-indent on; indent-width 4; tab-width 4; indent-mode none;
+-->
Added: trunk/ktutorial/ktutorial-editor/doc/en/installation.docbook
===================================================================
--- trunk/ktutorial/ktutorial-editor/doc/en/installation.docbook (rev 0)
+++ trunk/ktutorial/ktutorial-editor/doc/en/installation.docbook 2010-03-23 22:22:03 UTC (rev 186)
@@ -0,0 +1,97 @@
+<!--<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> -->
+<!-- Uncomment the previous two lines to validate this document -->
+<!-- standalone. Be sure to recomment them before attempting to -->
+<!-- process index.docbook -->
+
+<appendix id="installation">
+ <title>Installation</title>
+
+ <sect1 id="getting-klusi">
+ <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>
+
+ <para>KTutorial can be downloaded from the <ulink url="http://sourceforge.net/projects/ktutorial/files/">files section</ulink> of the <ulink url="http://sourceforge.net/projects/ktutorial/">KTutorial project in SourceForge.net</ulink>.</para>
+
+ <para>You are encouraged to visit, however, the <ulink url="http://ktutorial.sourceforge.net/download.html">download section</ulink> of the <ulink url="http://ktutorial.sourceforge.net/">webpage</ulink>, as a lot more information can be found there apart of only the files.</para>
+
+ <para>If you are brave enough, in the download section you will also find instructions to install KTutorial from <acronym>SVN</acronym>. However, this is only recommended for developers.</para>
+ </sect1>
+
+ <sect1 id="requirements">
+ <title>Requirements</title>
+
+ <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>Also, <application>CMake</application> build system is required to build KTutorial, as required to build any other &kde; application.</para>
+ </sect1>
+
+ <sect1 id="compilation">
+ <title>Compilation and Installation</title>
+
+ <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 && <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>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>
+
+ <tip>
+ <title>Installing &ktutorial-editor; in <filename class="directory">/usr/local/</filename></title>
+
+ <para>In order to keep a proper organization of your system and not mess up the packages installed by your distribution package manager and those installed manually by you, you are encouraged to install KTutorial in <filename class="directory">/usr/local/</filename>.</para>
+
+ <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>
+ </tip>
+ </sect1>
+
+ <sect1 id="configuration">
+ <title>Configuration</title>
+
+ <para>Depending on your distribution and where KTutorial was installed (if you installed it from sourcecode), you may need a last step before being able to make KTutorial run properly.</para>
+
+ <para>To check this, launch &ktutorial-editor; and take a look to the help. If &ktutorial-editor; manual cannot be found, go on reading to know what must be configured. If the manual is shown, congratulations, just enjoy! :)</para>
+
+ <para>If the manual wasn't found, you must configure your &kde; prefixes. To do this, create the file <filename>/etc/kderc</filename> and add the following content:</para>
+
+<programlisting>
+[Directories]
+prefixes=/the/prefix/where/ktutorial/was/installed/
+</programlisting>
+
+ <para>If <filename>/etc/kderc</filename> already existed and had a prefixes rule, add the prefix of KTutorial separating it from the previous prefixes with a "," like this:</para>
+
+<programlisting>
+[Directories]
+prefixes=/previous/prefixes/,/the/prefix/where/ktutorial/was/installed/
+</programlisting>
+ </sect1>
+</appendix>
+
+<!--
+Local Variables:
+mode: xml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+vim:tabstop=4:shiftwidth=4:expandtab
+kate: space-indent on; indent-width 4; tab-width 4; indent-mode none;
+-->
+
Added: trunk/ktutorial/ktutorial-editor/doc/en/main-window.png
===================================================================
(Binary files differ)
Property changes on: trunk/ktutorial/ktutorial-editor/doc/en/main-window.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Added: trunk/ktutorial/ktutorial-editor/doc/en/new-condition.png
===================================================================
(Binary files differ)
Property changes on: trunk/ktutorial/ktutorial-editor/doc/en/new-condition.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Added: trunk/ktutorial/ktutorial-editor/doc/en/set-reaction-data.png
===================================================================
(Binary files differ)
Property changes on: trunk/ktutorial/ktutorial-editor/doc/en/set-reaction-data.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Added: trunk/ktutorial/ktutorial-editor/doc/en/set-step-data.png
===================================================================
(Binary files differ)
Property changes on: trunk/ktutorial/ktutorial-editor/doc/en/set-step-data.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Added: trunk/ktutorial/ktutorial-editor/doc/en/set-tutorial-information.png
===================================================================
(Binary files differ)
Property changes on: trunk/ktutorial/ktutorial-editor/doc/en/set-tutorial-information.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Added: trunk/ktutorial/ktutorial-editor/doc/en/using.docbook
===================================================================
--- trunk/ktutorial/ktutorial-editor/doc/en/using.docbook (rev 0)
+++ trunk/ktutorial/ktutorial-editor/doc/en/using.docbook 2010-03-23 22:22:03 UTC (rev 186)
@@ -0,0 +1,279 @@
+<!--<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> -->
+<!-- Uncomment the previous two lines to validate this document -->
+<!-- standalone. Be sure to recomment them before attempting to -->
+<!-- process index.docbook -->
+
+<chapter id="using">
+ <title>Using &ktutorial-editor;</title>
+
+ <para>In this chapter you should find all the information you need to use &ktutorial-editor;. However, some general information about KTutorial is also given here, as it is needed to fully understand the purpose of &ktutorial-editor;.</para>
+
+ <tip>
+ <title>Getting extended information</title>
+
+ <para>You can also get extended information about a lot of widgets throughout &ktutorial-editor; using the <emphasis>What's This?</emphasis> help. <emphasis>What's This?</emphasis> help can be shown with the keyboard shortcut <keycombo action="simul">&Shift;<keycap>F1</keycap></keycombo>, selecting <guimenuitem>What's This?</guimenuitem> from the <guimenu>Help</guimenu> menu or, with some window decorations, clicking on the What's This? button in the window's titlebar (usually a question mark), and then clicking on the widget to get its extended help.</para>
+ </tip>
+
+ <sect1 id="understanding-ktutorial">
+ <title>Understanding KTutorial</title>
+
+ <para>&ktutorial-editor; is just a graphical editor to create tutorials to be used by KTutorial. That is why you should at least have some little notions of how KTutorial works to fully understand the purpose of &ktutorial-editor;.</para>
+
+ <para>A tutorial is a little guide to help the user to learn how to use an application. For example, it shows the user how some feature works, or how to accomplish some task. A tutorial is composed of several steps, each one containing a bit of information.</para>
+
+ <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 also two types of responses: changing to another step, or executing some custom code.</para>
+
+ <para>Finally, KTutorial provides a system to execute some actions when a tutorial starts or finishes, or when the tutorial enters or exists from a step.</para>
+
+ <para>All this abstract concepts are fine but, how do you tell KTutorial all those things? KTutorial is a software package, how does it know that it has to wait for something to happen, or show the user some text, or whatever? KTutorial tutorials are specified as source code, be it C++ or a script language.</para>
+
+ <para>C++ tutorials must be embedded in the application source code itself, and they have to be compiled with it when the application is compiled.</para>
+
+ <para>On the other hand, scripted tutorials are external data to the application. When an application that supports KTutorial starts, it looks for scripted tutorials in some specific directories and loads those found. If you add new scripted tutorials to the directories, the next time the application starts they will be available. You don't have to compile again the application, not even to reinstall it.</para>
+
+ <para>Scripted tutorials are looked for in the <filename>tutorials/</filename> subdirectory of the application data directory. The application data directory is <filename>KDE_PREFIX/share/apps/applicationName/</filename>. Special cases aside, the <emphasis>KDE_PREFIX</emphasis> can be the KDE installation prefix (usually <filename>/usr/</filename>) or the user KDE4 configuration directory (<filename>/home/userName/.kde4/</filename>).</para>
+
+ <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>
+ </sect1>
+
+ <sect1 id="main-window">
+ <title>Main Window</title>
+
+ <para>&ktutorial-editor; main window shows the tutorial being worked on, and provides actions to modify it.</para>
+
+ <para>A tutorial can be seen as a hierarchical structure: a tutorial contains several steps, each step may contain several reactions, and each reaction may contain a composed condition. Also, tutorial, step and reactions contain other properties, like the name in a tutorial or the response code in a reaction, that can be seen as children of their element. With all this, a tutorial is shown as a tree in the main window.</para>
+
+ <para>The tree only shows properties already set. For example, if there is no custom setup code for a step, no item is shown, not even to say that there is no setup code. The exception to this behavior happens when a property is mandatory, for example, the id of a step. In that case, if the property is not set, an item with a warning is shown.</para>
+
+ <para>The actions to modify the tutorial and its elements can be always accessed from the <guimenu>Edit</guimenu> menu. Most actions will open a edition dialog to edit the desired element, which means that, in some cases, you have to select an element before being able to use an action. For example, to use <action>Set reaction data</action>, you first have to select the reaction to edit in the tutorial. Otherwise, the action will be disabled and it could not be executed (which is logical, as it will not know which reaction to edit).</para>
+
+ <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>
+
+ <screenshot>
+ <screeninfo>The main window of &ktutorial-editor; with a tutorial being worked on</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="main-window.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>&ktutorial-editor; Main Window</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </sect1>
+
+ <sect1 id="edition-dialogs">
+ <title>Edition dialogs</title>
+
+ <para>There are several edition dialogs, each one to set some property or properties of an element.</para>
+
+ <sect2 id="edition-dialogs-tutorial">
+ <title>Tutorial edition</title>
+
+ <para>The tutorial information dialog is used to set the name and description of a tutorial. The name and description are mandatory properties, as through the name the user can identify a tutorial and with the description he can know the purpose of the tutorial.</para>
+
+ <screenshot>
+ <screeninfo>The dialog to set the name and description of a tutorial</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="set-tutorial-information.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Tutorial information edition dialog</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>The license text dialog is used to set a license for the tutorial, for example, if the exported scripted tutorial is going to be distributed with its application. When the tutorial is exported, the license text is automatically wrapped in comments appropriate for the script language. For example, the following license text:
+<programlisting>The license text, which should be
+wrapped
+</programlisting> is exported to Javascript as:
+<programlisting>/*****************************************
+ * The license text, which should be *
+ * wrapped *
+ *****************************************/
+</programlisting>
+ </para>
+
+ <para>The setup and tear down code dialogs just provide a text editor to write the custom code to be executed when the tutorial starts or finishes. Note that you have to provide just the body of the function, as the signature is automatically written when exported. For example, the following setup code:
+<programlisting>alert("Hello world!");</programlisting> is exported to Javascript as:
+<programlisting>function tutorialSetup(tutorial) {
+ alert("Hello world!");
+}
+</programlisting>
+ </para>
+ </sect2>
+
+ <sect2 id="edition-dialogs-step">
+ <title>Step edition</title>
+
+ <para>The step data dialog is used to set the id and text of a tutorial. 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>
+ <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>
+
+ <screenshot>
+ <screeninfo>The dialog to set the id and text of a step</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="set-step-data.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Step data edition dialog</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>The setup and tear down code dialogs behave like the tutorial ones. The only difference is that the code is executed when the tutorial changes to the step or when the tutorial changes from this step to another one.</para>
+ <para>Also note that the exported scripted tutorial creates all the reactions in the setup method of a step. The custom setup code is added after that code.</para>
+ </sect2>
+
+ <sect2 id="edition-dialogs-reaction">
+ <title>Reaction edition</title>
+
+ <para>The reaction dialog is used to set the trigger and response of a step. The trigger and response are mandatory properties, as they define how the reaction behaves.</para>
+ <para>The trigger can be either an option selected or a condition met, but not both. If the trigger type is the option, its name will be shown to the user in the step and the response will be executed when the user selects it. If the type is the condition, the response will be executed when the condition is met.</para>
+ <para>Likely, the response can be changing to another step or executing some custom code, but not both. If the response type is the custom code, it will be used as the body of a function called when the reaction is triggered. Again, the signature of the function is automatically provided and you have to set only the body.</para>
+
+ <screenshot>
+ <screeninfo>The dialog to set the trigger and response of a reaction</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="set-reaction-data.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Set reaction data edition dialog</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <sect3 id="edition-dialogs-reaction-condition">
+ <title>Condition edition</title>
+
+ <para>The condition that acts as a trigger of a reaction can be a simple condition or a composed condition. Simple conditions wait for something to happen, like a signal emitted by an object. Composed conditions wait for its child conditions. For example, waiting until a signal is emitted by an object or an event is received in another object, whatever comes first.</para>
+ <para>Due to this, conditions are represented in a tree, and it also affects how they are edited.</para>
+ <para>A condition can be added as the root condition when there are no other conditions set, or as a child of the selected composed condition, but not when a simple condition is selected. When a new condition is added, you must select its type. Note that the type of the condition can not be changed later, you will have to remove the condition.</para>
+
+ <screenshot>
+ <screeninfo>The dialog to select the type of the new condition to add</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="new-condition.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>New condition dialog</phrase>
+ </textobject>
+ </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>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>
+ </sect3>
+ </sect2>
+ </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 FTP, SSH, etc), although it will be very strange that you need to use that.</para>
+ </sect1>
+
+ <sect1 id="command-line-options">
+ <title>Command Line Options</title>
+
+ <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>
+
+ <sect2 id="other-command-line-options">
+ <title>Default KDE4 Command Line Options</title>
+
+ <para>The following command line help options are available:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <command>ktutorial-editor <option>--help</option></command>
+ </term>
+ <listitem>
+ <para>This lists the most basic options available at the command line.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <command>ktutorial-editor <option>--help-qt</option></command>
+ </term>
+ <listitem>
+ <para>This lists the options available for changing the way &ktutorial-editor; interacts with &Qt;.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <command>ktutorial-editor <option>--help-kde</option></command>
+ </term>
+ <listitem>
+ <para>This lists the options available for changing the way &ktutorial-editor; interacts with &kde;.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <command>ktutorial-editor <option>--help-all</option></command>
+ </term>
+ <listitem>
+ <para>This lists all of the command line options.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <command>ktutorial-editor <option>--author</option></command>
+ </term>
+ <listitem>
+ <para>Lists &ktutorial-editor;'s author in the terminal window.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <command>ktutorial-editor <option>--version</option></command>
+ </term>
+ <listitem>
+ <para>Lists version information for &Qt;, &kde;, and &ktutorial-editor;. Also available through <command>ktutorial-editor <option>-v</option></command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <command>ktutorial-editor <option>--license</option></command>
+ </term>
+ <listitem>
+ <para>Shows &ktutorial-editor;'s license text in the terminal window.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+ </sect1>
+</chapter>
+
+<!--
+Local Variables:
+mode: xml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+vim:tabstop=4:shiftwidth=4:expandtab
+kate: space-indent on; indent-width 4; tab-width 4; indent-mode none;
+-->
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
