updated help

git-svn-id: http://sextante.googlecode.com/svn/trunk/soft/bindings/qgis-plugin@264 881b9c09-3ef8-f3c2-ec3d-21d735c97f4d

Author: volayaf

src/sextante/help/3rdParty.html

@@ -52,18 +52,16 @@ <h1>Configuring external applications<a class="headerlink" href="#configuring-ex
 <div class="section" id="introduction">
 <h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
 <p>SEXTANTE can be extended using additional applications, calling them
-from within SEXTANTE.</p>
-<p>By default, algorithms coming from external applications are not activated unless SEXTANTE has checked that the corresponding applications are installed in your system and can be executed. That means that there are probably many more algorithms available than those that you can see in the toolbox, but some extra configuration is needed to have them fully operational.</p>
-<p>This chapter will show you how to configure SEXTANTE to include these
+from within SEXTANTE. Currently, SAGA, GRASS, OTB(Orfeo Toolbox) and R are supported, along
+with some other command-line applications that provide spatial data
+analysis functionalities.
+This chapter will show you how to configure SEXTANTE to include these
 additional applications. Once you have correctly configured the system,
 you will be able to execute external algorithms from any SEXTANTE
 component like the toolbox or the graphical modeler, just like you do
 with any other SEXTANTE geoalgorithm.</p>
-<p>At the time of writing this manual, SEXTANTE has two external providers activated by default: GRASS and GDAL. This providers are activated because QGIS includes both the GRASS binaries and the GDAL library files, so there is no need for further configuration (QGIS developers have done that in advance for you). This might change in other versions, but for now it means that you need to manually install and configure those external programs. Do not worry, this is very easy to do. If you are running Linux, you just have to install the software yourself and then activate the corresponding algorithm provider. If you are running Windows, you should also tell SEXTANTE the path to the software.</p>
-<p>For each algorithm provider there is a group entry in the SEXTANTE configuration dialog, which contains at least an &#8220;Activate&#8221; item. Other parameters might appear if they are needed to configure the provider (mostly paths to executales and additional files). In the following sections, we will see how to set those parameters for the main providers currently available for SEXTANTE. But first, a couple of quick notes with important information about using algorithms based on external applications.</p>
 <div class="section" id="a-note-on-file-formats">
 <h3>A note on file formats<a class="headerlink" href="#a-note-on-file-formats" title="Permalink to this headline">¶</a></h3>
-<p>Algorithms provided by external applications have some differences when compared to &#8220;native&#8221; SEXTANTE algorithm. The main one of them is related to the file formats supported both for input and for output.</p>
 <p>When using an external software, opening a file in QGIS does not mean
 that it can be opened and processed as well on that other software. In
 most cases, it can read what you have opened in QGIS, but in some cases,
@@ -116,7 +114,7 @@ <h3>A note on vector layer selections<a class="headerlink" href="#a-note-on-vect
 <h2>SAGA<a class="headerlink" href="#saga" title="Permalink to this headline">¶</a></h2>
 <p>SAGA algorithms can be run from SEXTANTE if you have SAGA installed in
 your system and you configure SEXTANTE properly so it can find SAGA
-executables. In particular, the SAGA command-line executable is needed
+executables. In particular, the SAGA command–line executable is needed
 to run SAGA algorithms. SAGA binaries are not included with SEXTANTE, so
 you have to download and install the software yourself. Please check the
 SAGA website at for more information. SAGA 2.0.8 is needed.</p>
@@ -189,7 +187,7 @@ <h2>R. Creating R scripts<a class="headerlink" href="#r-creating-r-scripts" titl
 the syntax to use to call those R commands from SEXTANTE and how to use
 SEXTANTE objects (layers, tables) in them.</p>
 <p>The first thing you have to do, as we saw in the case of SAGA, is to
-tell SEXTANTE where your R binaries are located. You can do so using the
+tell SEXTANTE where you R binaries are located. You can do so using the
 <em>R folder</em> entry in the SEXTANTE configuration dialog. Once you have set
 that parameter, you can start creating your own R scripts and executing
 them.</p>
@@ -267,9 +265,8 @@ <h2>R. Creating R scripts<a class="headerlink" href="#r-creating-r-scripts" titl
 console instead, you have to tell SEXTANTE that you want the console to
 be shown once the execution is finished. To do so, just start the
 command lines that produce the results you want to print with the
-“<span class="math">
-\(&gt;\)</span>
-” sign. The output of all other lines will not be shown. For
+“<math xmlns="http://www.w3.org/1998/Math/MathML">
+<mrow><mo>&gt;</mo></mrow></math>” sign. The output of all other lines will not be shown. For
 instance, here is the description file of an algorithms that performs a
 normality test on a given field (column) of the attributes of a vector
 layer:</p>

src/sextante/help/_sources/3rdParty.txt

@@ -5,26 +5,18 @@ Introduction
 ------------
 
 SEXTANTE can be extended using additional applications, calling them
-from within SEXTANTE. 
-
-By default, algorithms coming from external applications are not activated unless SEXTANTE has checked that the corresponding applications are installed in your system and can be executed. That means that there are probably many more algorithms available than those that you can see in the toolbox, but some extra configuration is needed to have them fully operational.
-
+from within SEXTANTE. Currently, SAGA, GRASS, OTB(Orfeo Toolbox) and R are supported, along 
+with some other command-line applications that provide spatial data 
+analysis functionalities. 
 This chapter will show you how to configure SEXTANTE to include these
 additional applications. Once you have correctly configured the system,
 you will be able to execute external algorithms from any SEXTANTE
 component like the toolbox or the graphical modeler, just like you do
 with any other SEXTANTE geoalgorithm.
 
-At the time of writing this manual, SEXTANTE has two external providers activated by default: GRASS and GDAL. This providers are activated because QGIS includes both the GRASS binaries and the GDAL library files, so there is no need for further configuration (QGIS developers have done that in advance for you). This might change in other versions, but for now it means that you need to manually install and configure those external programs. Do not worry, this is very easy to do. If you are running Linux, you just have to install the software yourself and then activate the corresponding algorithm provider. If you are running Windows, you should also tell SEXTANTE the path to the software.
-
-For each algorithm provider there is a group entry in the SEXTANTE configuration dialog, which contains at least an "Activate" item. Other parameters might appear if they are needed to configure the provider (mostly paths to executales and additional files). In the following sections, we will see how to set those parameters for the main providers currently available for SEXTANTE. But first, a couple of quick notes with important information about using algorithms based on external applications.
-
-
 A note on file formats
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Algorithms provided by external applications have some differences when compared to "native" SEXTANTE algorithm. The main one of them is related to the file formats supported both for input and for output.
-
 When using an external software, opening a file in QGIS does not mean
 that it can be opened and processed as well on that other software. In
 most cases, it can read what you have opened in QGIS, but in some cases,
@@ -84,7 +76,7 @@ SAGA
 
 SAGA algorithms can be run from SEXTANTE if you have SAGA installed in
 your system and you configure SEXTANTE properly so it can find SAGA
-executables. In particular, the SAGA command-line executable is needed
+executables. In particular, the SAGA command–line executable is needed
 to run SAGA algorithms. SAGA binaries are not included with SEXTANTE, so
 you have to download and install the software yourself. Please check the
 SAGA website at for more information. SAGA 2.0.8 is needed.
@@ -168,7 +160,7 @@ the syntax to use to call those R commands from SEXTANTE and how to use
 SEXTANTE objects (layers, tables) in them.
 
 The first thing you have to do, as we saw in the case of SAGA, is to
-tell SEXTANTE where your R binaries are located. You can do so using the
+tell SEXTANTE where you R binaries are located. You can do so using the
 *R folder* entry in the SEXTANTE configuration dialog. Once you have set
 that parameter, you can start creating your own R scripts and executing
 them.

src/sextante/help/_sources/console.txt

@@ -336,6 +336,13 @@ real examples of how to create algorithms using this feature of
 SEXTANTE. You can right-click on any script algorithm and select *Edit
 script* to edit its code or just to see it.
 
+Documenting your scripts
+--------------------------
+
+As in the case of models, you can create additional documentation for your script, to explain what they do and how to use them. In the script editing dialog you will find a *Edit script help* button. Click on it and it will take you to the help editing dialog. Check the chapter about the graphical modeler to know more about this dialog and how to use it.
+
+Help files are saved in the same folder as the script itself, adding the *.help* extension to the filename. Notice that you can edit your script's help before saving it for the first time. If you later close the script editing dialog without saving the script (i.e. you discard it), the help content you wrote will be lost. If your script was already saved and is associated to a filename, saving is done automatically.
+
 Communicating with the user
 ----------------------------
 

src/sextante/help/console.html

@@ -329,6 +329,11 @@ <h2>Creating scripts and running them from the toolbox<a class="headerlink" href
 SEXTANTE. You can right-click on any script algorithm and select <em>Edit
 script</em> to edit its code or just to see it.</p>
 </div>
+<div class="section" id="documenting-your-scripts">
+<h2>Documenting your scripts<a class="headerlink" href="#documenting-your-scripts" title="Permalink to this headline">¶</a></h2>
+<p>As in the case of models, you can create additional documentation for your script, to explain what they do and how to use them. In the script editing dialog you will find a <em>Edit script help</em> button. Click on it and it will take you to the help editing dialog. Check the chapter about the graphical modeler to know more about this dialog and how to use it.</p>
+<p>Help files are saved in the same folder as the script itself, adding the <em>.help</em> extension to the filename. Notice that you can edit your script&#8217;s help before saving it for the first time. If you later close the script editing dialog without saving the script (i.e. you discard it), the help content you wrote will be lost. If your script was already saved and is associated to a filename, saving is done automatically.</p>
+</div>
 <div class="section" id="communicating-with-the-user">
 <h2>Communicating with the user<a class="headerlink" href="#communicating-with-the-user" title="Permalink to this headline">¶</a></h2>
 <p>You can send messages to the user to inform about the progress of the algorithm. To do so, just print whatever information you want to show in the textbox above the progress bar in the algorithm dialog, using the <tt class="docutils literal"><span class="pre">print</span></tt> command. For instance, just use <tt class="docutils literal"><span class="pre">print</span> <span class="pre">&quot;Processing</span> <span class="pre">polygon</span> <span class="pre">layer&quot;</span></tt> and the text will be redirected to that textbox.</p>
@@ -348,6 +353,7 @@ <h3><a href="index.html">Table Of Contents</a></h3>
 <li><a class="reference internal" href="#introduction">Introduction</a></li>
 <li><a class="reference internal" href="#calling-sextante-from-the-python-console">Calling SEXTANTE from the Python console</a></li>
 <li><a class="reference internal" href="#creating-scripts-and-running-them-from-the-toolbox">Creating scripts and running them from the toolbox</a></li>
+<li><a class="reference internal" href="#documenting-your-scripts">Documenting your scripts</a></li>
 <li><a class="reference internal" href="#communicating-with-the-user">Communicating with the user</a></li>
 </ul>
 </li>

src/sextante/help/index.html

@@ -89,6 +89,7 @@ <h1>SEXTANTE for QGIS&#8217;s documentation<a class="headerlink" href="#sextante
 <li class="toctree-l2"><a class="reference internal" href="console.html#introduction">Introduction</a></li>
 <li class="toctree-l2"><a class="reference internal" href="console.html#calling-sextante-from-the-python-console">Calling SEXTANTE from the Python console</a></li>
 <li class="toctree-l2"><a class="reference internal" href="console.html#creating-scripts-and-running-them-from-the-toolbox">Creating scripts and running them from the toolbox</a></li>
+<li class="toctree-l2"><a class="reference internal" href="console.html#documenting-your-scripts">Documenting your scripts</a></li>
 <li class="toctree-l2"><a class="reference internal" href="console.html#communicating-with-the-user">Communicating with the user</a></li>
 </ul>
 </li>