Bug Fix #12431 - Updated %helps help page 48/18548/5
Nicolas [Thu, 15 Sep 2016 13:18:10 +0000 (15:18 +0200)]
Change-Id: If132adcbc0c5841479fa212e5e9d3af89fd420ae

scilab/CHANGES.md
scilab/modules/helptools/help/en_US/percenthelps.xml
scilab/modules/helptools/help/fr_FR/percenthelps.xml
scilab/modules/helptools/help/pt_BR/percenthelps.xml

index 9a807ac..9786f4f 100644 (file)
@@ -13,7 +13,7 @@ This file is intended for the specific needs of advanced users, and describes:
 - Bug fixes.
 
 This changelog is most likely incomplete, as an enormous amount of code has changed between 5.5.2 and 6.
-Please report any thing we could have missed, on the [mailing lists][1] or on the [bug tracker][2], 
+Please report any thing we could have missed, on the [mailing lists][1] or on the [bug tracker][2],
 and we will correct it before the final Scilab 6.0.0 release.
 
 [1]: http://mailinglists.scilab.org
@@ -23,8 +23,8 @@ and we will correct it before the final Scilab 6.0.0 release.
 Main new features
 -----------------
 
-For high-level description of the main new features of this release, please 
-consult the [embedded help](modules/helptools/data/pages/homepage-en_US.html). It is also available 
+For high-level description of the main new features of this release, please
+consult the [embedded help](modules/helptools/data/pages/homepage-en_US.html). It is also available
 as the "What's new" page of the help, by simply typing `help` in Scilab console.
 
 In summary, the main new features are:
@@ -100,7 +100,7 @@ Language changes
 
 Some small changes have been done to the language syntax, aiming at more clarity and less
 ambiguity. Some changes are not compatible with 5.5; code written for Scilab 5.x
-has to be modified in order to work in Scilab 6.0. 
+has to be modified in order to work in Scilab 6.0.
 
 See [the wiki page on porting code from 5.5 to 6.0](https://wiki.scilab.org/FromScilab5ToScilab6)
 for details and examples.
@@ -111,10 +111,10 @@ for details and examples.
 * Declaring strings using non-homogenous delimiters ("string' or 'string") is no longer allowed.
 * `(a=b)` executed as `a == b` is now deprecated and returns an error.
 * Function definitions can finish with `end` instead of `endfunction`.
-* `{}` and `[]` are now distinct operators. Matrices can no longer be defined usind `{}` operators. 
+* `{}` and `[]` are now distinct operators. Matrices can no longer be defined usind `{}` operators.
 These are reserved for cell definition.
 * Shortcut and element-wise boolean operators are now distinct. `&&` and `||` are new shortcut boolean AND and OR,
-while `&` and `|` are element-wise operations and will not shortcut one of the operand. 
+while `&` and `|` are element-wise operations and will not shortcut one of the operand.
 Both shortcut and element-wise operators are evaluated from left to right.
 * Syntax `%i:10` is now deprecated (only real scalars can be used).
 * `while ... else ... end` control instruction is not supported anymore.
@@ -150,12 +150,12 @@ Feature changes and additions
 * `sign` can now handle a sparse matrix.
 * `sleep(..,'s')` allows now to specify the duration in seconds.
 * `real`, `imag`, `conj` and `isreal` now accept rational fractions.
-* A call stack limit has been introduced. Default maximum depth is setup to 1000 
+* A call stack limit has been introduced. Default maximum depth is setup to 1000
 and can be changed by `recursionlimit` or through the Preferences interface.
-* The floating point exception mode `ieee` is now set to `2` by default: floating 
+* The floating point exception mode `ieee` is now set to `2` by default: floating
 point exceptions now produce `Inf` or `Nan`, and do not cause any error.
 The previous behavior can be recalled by simply calling: `ieee(0)`.
-* The graphics entity "Datatip" has its property `z_component = 'on|off'` changed to 
+* The graphics entity "Datatip" has its property `z_component = 'on|off'` changed to
 `display_components = 'xyz'`; it is now possible to choose which components to display,
 and in which order. Loading old `*.scg` files containing datatips with "z_component"
 property may not display the z component.
@@ -163,7 +163,7 @@ property may not display the z component.
 * `amell` now:
   - checks if its parameters are real numbers,
   - throws an error if the second parameter is not a scalar.
-* The use of I/O console is now allowed with the following functions: `mget`, 
+* The use of I/O console is now allowed with the following functions: `mget`,
 `mgetl`, `mgetstr`, `mput`, `mputl` and `mputstr`.
 * `mclearerr` now returns a flag indicating the file identifier validity.
 * `fileinfo` can now take a row vector as input.
@@ -192,9 +192,9 @@ input and output arguments.
    - `bitxor` is now vectorized and fast.
 * The zoom rubber box now can start/finish from points lying outside the axes bounds.
 * The zoom rubber box now can select multiple and overlying axes at once. Changed behavior of scroll zoom,
-scrolling over overlying axes will zoom all of them together, using the CTRL key while scrolling 
+scrolling over overlying axes will zoom all of them together, using the CTRL key while scrolling
 will zoom all axes in the current figure.
-* The graphics entity "Datatip" has a new property `detached_position` which accepts `[]` 
+* The graphics entity "Datatip" has a new property `detached_position` which accepts `[]`
 or a 3-components vector to set the position in axes coordinates to draw the datatip text box.
 * `MPI_Create_comm` create a new communicator from MPI_COMM_WORLD using MPI world ranks.
 
@@ -202,7 +202,7 @@ Help pages:
 -----------
 
 * fixed / improved:  `members`, `part`, `ode`, `ode_optional_output`, `ode_roots`, `roots`,
-  `printf`, `sprintf`, `iconvert`, `stdev`, `xlabel`, `and_op`, `or_op`
+  `printf`, `sprintf`, `iconvert`, `stdev`, `xlabel`, `and_op`, `or_op`, `%helps`
 * rewritten: `consolebox`, `double`, `isoview`, `householder`, `or`, `and`, `format`, `typeof`,
 `brackets`, `setlanguage`, `sleep`, `isinf`, `bitor`, `bitxor`, `bitand`
 * reorganized:
@@ -235,9 +235,9 @@ Xcos
 
 * Major rewrite of the data structures, huge models should load and save faster.
 The memory usage on diagram edition is also slightly reduced.
-* ZCOS and XCOS file formats have evolved to reduce the duplicated information. 
+* ZCOS and XCOS file formats have evolved to reduce the duplicated information.
 Scilab 5.5.2 is able to open the newly saved files, but the ports have to be repositioned manually.
-* Implicit fixed-size step ODE solver added: Crank-Nicolson 2(3). 
+* Implicit fixed-size step ODE solver added: Crank-Nicolson 2(3).
 Added to the CVode package, it also benefits from the CVode rootfinding feature.
 * Block modifications :
   - `INVBLK`: add a divide by zero parameter to ignore the error
@@ -247,13 +247,13 @@ Added to the CVode package, it also benefits from the CVode rootfinding feature.
 API modification
 ----------------
 
-A new set of C APIs to write C or C++ extensions (toolboxes) to Scilab. 
+A new set of C APIs to write C or C++ extensions (toolboxes) to Scilab.
 It allows defining native functions (commonly called "gateways"), getting input parameters
 for such functions, setting return parameters, accessing local variables, using common helper
-functions for accessing environment information (such as warning level), generate errors... 
+functions for accessing environment information (such as warning level), generate errors...
 
 It also includes ways to overload existing Scilab functions to support additional parameter
-types (see `help scilab_overload`). Finally, you can call back Scilab functions 
+types (see `help scilab_overload`). Finally, you can call back Scilab functions
 (macros and built-in functions) from your gateway (see `help scilab_call`).
 
 User-defined functions written in C or C++ (gateways) must now use a `void* pvApiCtx` name
@@ -302,7 +302,7 @@ Known issues
 
 * Scilab 6 is still in a beta stage and likely to contain a number of known or unknown bugs.
 Do not hesitate to [report](https://bugzilla.scilab.org) them.
-* Toolboxes rebuild is in progress. Do not hesitate to submit patch or feature upgrade to 
+* Toolboxes rebuild is in progress. Do not hesitate to submit patch or feature upgrade to
 the [development mailing list](dev@lists.scilab.org) for a particular toolbox.
 
 
@@ -328,6 +328,7 @@ Bug Fixes
 * [#11692](http://bugzilla.scilab.org/show_bug.cgi?id=11692): The summary of a help section built from both default en_US and localized files was never sorted overall.
 * [#11959](http://bugzilla.scilab.org/show_bug.cgi?id=11959): Allow "Zoom Area" to be clicked out of axes
 * [#12110](http://bugzilla.scilab.org/show_bug.cgi?id=12110): Unable to zoom multiple axes at once
+* [#12431](http://bugzilla.scilab.org/show_bug.cgi?id=12431): The page describing the `%helps` variable needed clarification.
 * [#13166](http://bugzilla.scilab.org/show_bug.cgi?id=13166): `l` and `b` endian flags used with `mget` and `mgeti` were sticky
 * [#13375](http://bugzilla.scilab.org/show_bug.cgi?id=13375): If (Max - Min) == 1, then the multiple selection is not allowed.
 * [#13583](http://bugzilla.scilab.org/show_bug.cgi?id=13583): `getd` loading a script including a `clear` instruction yielded an error
index 69b8f52..8a07b57 100644 (file)
 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="percenthelps">
     <refnamediv>
         <refname>%helps</refname>
-        <refpurpose>Variable defining the path of help directories</refpurpose>
+        <refpurpose>
+            global variable: paths to help directories of loaded external modules
+        </refpurpose>
     </refnamediv>
-    <refsection>
+    <refsection role="description">
         <title>Description</title>
-        <para>BEWARE: This variable must NOT be modified by users.</para>
         <para>
             The global variable <literal>%helps</literal> is an N x 2 matrix of strings.
-            The kth row of <literal>%helps</literal>, <literal>%helps(k,:)</literal> represents
-            the kth chapter of the manual and is made of two strings:
-        </para>
-        <para>
-            <literal>%helps(k,1)</literal> is the absolute pathname for a help directory.
-        </para>
-        <para>
-            <literal>%helps(k,2)</literal> is a title for this help directory.
-        </para>
-        <para>
-            To add a new help directory, the user should use <literal>add_help_chapter</literal>.
+            Each row refers to the help chapter of a loaded external module:
+            <itemizedlist>
+               <listitem>
+                   <literal>%helps(k,1)</literal> is the absolute pathname to its help directory.
+               </listitem>
+               <listitem>
+                   <literal>%helps(k,2)</literal> is the title of its help chapter.
+               </listitem>
+            </itemizedlist>
         </para>
+        <warning>
+          This variable must NOT be modified by hand. <literal>add_help_chapter</literal>
+          must be used to add a new help chapter and update <literal>%helps</literal>.
+        </warning>
+    </refsection>
+    <refsection role="examples">
+       <title>Examples</title>
+        <programlisting role="example"><![CDATA[
+global %helps  // This instruction creates a local %helps variable connected to the global one
+%helps
+if %helps==[]                    // No help chapter is registered for any external module
+    if atomsGetInstalled()==[]   // If no external module is installed
+        atomsInstall uman;       //  we install the "uman" one (available for all plateforms)
+    end
+    atomsLoad(atomsGetInstalled()(1));  // We load the first module, included its help pages
+    %helps                       // Now the external chapter should be registered
+end
+      ]]></programlisting>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
index 1aef6aa..00c3ec3 100644 (file)
 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="fr" xml:id="percenthelps">
     <refnamediv>
         <refname>%helps</refname>
-        <refpurpose>variable contenant les noms des répertoires des chapitres d'aide  </refpurpose>
+        <refpurpose>
+            variable globale : chemins des répertoires d'aide des modules externes chargés en session
+        </refpurpose>
     </refnamediv>
-    <refsection>
+    <refsection role="description">
         <title>Description</title>
-        <para>ATTENTION: Cette variable ne doit pas être modifiée manuellement par l'utilisateur.</para>
         <para>
-            <literal>%helps</literal> est une matrice de chaînes de caractères à deux colonnes. Chaque ligne est formée comme ceci
-        </para>
-        <programlisting role="no-scilab-exec"><![CDATA[
-répertoire_du_chapitre    titre_du_chapitre
- ]]></programlisting>
-        <para>
-            Pour ajouter de nouveaux chapitres d'aide, il faut utiliser la fonction <literal>add_help_chapter</literal>.
+            La variable globale <literal>%helps</literal> est une matrice texte à 2 colonnes.
+            Chaque ligne référence le chapitre d'aide d'un module externe chargé en session :
+            <itemizedlist>
+               <listitem>
+                   <literal>%helps(k,1)</literal> est le chemin absolu du répertoire d'aide du module.
+               </listitem>
+               <listitem>
+                   <literal>%helps(k,2)</literal> est le titre du chapitre d'aide.
+               </listitem>
+            </itemizedlist>
         </para>
+        <warning>
+          Cette variable ne doit PAS être modifiée manuellement. <literal>add_help_chapter</literal>
+          doit être utilisée pour ajouter au navigateur d'aide (à redémarrer) le chapitre relatif
+          à un module externe chargé, et pour actualiser <literal>%helps</literal>.
+        </warning>
+    </refsection>
+    <refsection role="examples">
+       <title>Exemples</title>
+        <programlisting role="example"><![CDATA[
+global %helps  // Création de la variable locale %helps connectée à sa version globale
+%helps
+if %helps==[]                    // Aucun chapitre d'aide n'est déclaré pour aucun module externe
+    if atomsGetInstalled()==[]   // Si aucun module externe n'est installé,
+        atomsInstall uman;       //  on installe le module "uman" (disponible pour Windows, Linux et MacOS)
+    end
+    atomsLoad(atomsGetInstalled()(1));  // On charge le 1er module installé, pages d'aide incluses
+    %helps                       // Le chapitre d'aide correspondant est maintenant indexé dans %helps
+end
+      ]]></programlisting>
     </refsection>
     <refsection role="see also">
         <title>Voir aussi</title>
@@ -38,6 +61,9 @@ répertoire_du_chapitre    titre_du_chapitre
             <member>
                 <link linkend="add_help_chapter">add_help_chapter</link>
             </member>
+            <member>
+                <link linkend="help">help</link>
+            </member>
         </simplelist>
     </refsection>
 </refentry>
index f5361f7..877b766 100644 (file)
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2008 - INRIA
  * along with this program.
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="percenthelps" xml:lang="pt">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:id="percenthelps" xml:lang="pt">
     <refnamediv>
         <refname>%helps</refname>
-        <refpurpose>variável definindo o endereço dos diretórios de
-            ajuda
+        <refpurpose>variável definindo o endereço dos diretórios de ajuda
         </refpurpose>
     </refnamediv>
-    <refsection>
-        <title>Descrição</title>
+    <refsection role="description">
+        <title>Descrição</title>
         <para>
-            A variável global <literal>%helps</literal> é uma matriz N x 2 de
-            strings. A k-ésima linha de <literal>%helps</literal>,
-            <literal>%helps(k,:)</literal> representa o k-ésimo capítulo do manual e é
+            A variável global <literal>%helps</literal> é uma matriz N x 2 de
+            strings. A k-ésima linha de <literal>%helps</literal>,
+            <literal>%helps(k,:)</literal> representa o k-ésimo capítulo do manual e é
             feita de dois strings:
         </para>
         <para>
-            <literal>%helps(k,1)</literal> é o nome de endereço absoluto de um
-            diretório.
+            <literal>%helps(k,1)</literal> é o nome de endereço absoluto de um
+            diretório.
         </para>
         <para>
-            <literal>%helps(k,2)</literal> é um título para este diretório. Por
-            exemplo, para k=2, nós temos o capítulo de gráficos
+            <literal>%helps(k,2)</literal> é um título para este diretório. Por
+            exemplo, para k=2, nós temos o capítulo de gráficos
             <literal>%helps(2,:)</literal>.
         </para>
         <para>
-            A variável <literal>%helps</literal> é definida no arquivo de
-            inicialização do Scilab <literal>SCI+"/scilab.start"</literal>.
+            A variável <literal>%helps</literal> é definida no arquivo de
+            inicialização do Scilab <literal>SCI+"/scilab.start"</literal>.
         </para>
-        <para>Para adicionar um novo diretório de ajuda, o usuário deve adicionar
+        <para>Para adicionar um novo diretório de ajuda, o usuário deve adicionar
             uma linha a <literal>%helps</literal>. (Uma linha para cada
-            diretório).
+            diretório).
         </para>
         <para>
             Por exemplo, <literal>%helps=[%helps;
                 "Path-Of-My-Help-Dir","My-Title"];
             </literal>
             habilita o navegador de ajuda
-            do Scilab a procurar por itens do manual de ajuda no diretório com
-            endereço "Path-Of-My-Help-Dir".
+            do Scilab a procurar por itens do manual de ajuda no diretório com
+            endereço "Path-Of-My-Help-Dir".
         </para>
-        <para>"My-Title" é, então, o título do novo capítulo de ajuda.</para>
-        <para>Um diretório válido deve conter:</para>
+        <para>"My-Title" é, então, o título do novo capítulo de ajuda.</para>
+        <para>Um diretório válido deve conter:</para>
         <para>
             1- Um conjunto de arquivos<literal>.html</literal> (ex.:
             <literal>item1.html, item2.html</literal> etc). Os arquivos
-            <literal>.html</literal> são geralmente construídos de arquivos
+            <literal>.html</literal> são geralmente construídos de arquivos
             XML.
         </para>
         <para>
@@ -70,8 +72,8 @@
 <BR><A HREF="item.html">item</A> - rápida descrição
  ]]></programlisting>
         <para>
-            <literal>item</literal> é o item da ajuda, i.e. o comando
-            <literal>help item</literal> exibe o conteúdo do arquivo
+            <literal>item</literal> é o item da ajuda, i.e. o comando
+            <literal>help item</literal> exibe o conteúdo do arquivo
             <literal>item.html</literal>.
         </para>
         <para>
             todos os arquivos <literal>whatis.html</literal> nos quais a palavra-chave
             keyword aparece.
         </para>
-        <para>Em plataformas Linux, o Scilab provê um Makefile para transformar
-            páginas <literal>.xml</literal> pages em páginas <literal>.html</literal>
+        <para>Em plataformas Linux, o Scilab provê um Makefile para transformar
+            páginas <literal>.xml</literal> pages em páginas <literal>.html</literal>
             (ver SCIDIR/examples/man-examples).
         </para>
     </refsection>
+    <refsection role="examples">
+       <title>Exemplos</title>
+        <programlisting role="example"><![CDATA[
+global %helps  // This instruction creates a local %helps variable connected to the global one
+%helps
+if %helps==[]                    // No help chapter is registered for any external module
+    if atomsGetInstalled()==[]   // If no external module is installed
+        atomsInstall uman;       //  we install the "uman" one (available for all plateforms)
+    end
+    atomsLoad(atomsGetInstalled()(1));  // We load the first module, included its help pages
+    %helps                       // Now the external chapter should be registered
+end
+      ]]></programlisting>
+    </refsection>
     <refsection role="see also">
-        <title>Ver Também</title>
+        <title>Ver Também</title>
         <simplelist type="inline">
             <member>
                 <link linkend="apropos">apropos</link>
             <member>
                 <link linkend="help">help</link>
             </member>
-            <member>
-                <link linkend="man">man</link>
-            </member>
         </simplelist>
     </refsection>
 </refentry>