* Bug 15236 fixed: isglobal() page was inaccurate + wrong examples 63/19363/5
Samuel GOUGEON [Tue, 8 Aug 2017 10:04:53 +0000 (12:04 +0200)]
  * http://bugzilla.scilab.org/15236
  * page overhauled => easier to retranslate from scratch rather than
    to detect and pick up many cookies to retranslate
    => other languages deleted

Change-Id: I0cd3c9d3594303376f521e675157561bc8f048ab

scilab/CHANGES.md
scilab/modules/core/help/en_US/variables/isglobal.xml
scilab/modules/core/help/fr_FR/variables/isglobal.xml [deleted file]
scilab/modules/core/help/ja_JP/variables/isglobal.xml [deleted file]
scilab/modules/core/help/pt_BR/variables/isglobal.xml [deleted file]
scilab/modules/core/help/ru_RU/variables/isglobal.xml

index b86b0f0..a3b59b8 100644 (file)
@@ -222,7 +222,7 @@ Help pages:
   `scilab|scilex`, `flipdim`, `Matplot_properties`, `meshgrid`, `ismatrix`, `xget`, `xset`, `ieee`
 * rewritten: `consolebox`, `double`, `isoview`, `pixel_drawing_mode`, `householder`, `or`, `|,||`,
 `and`, `&,&&`, `format`, `typeof`, `brackets`, `setlanguage`, `sleep`, `isinf`,
-`bitor`, `bitxor`, `bitand`, `macr2tree`, `geomean`, `clf`, `getPreferencesValue`, `gcd`
+`bitor`, `bitxor`, `bitand`, `macr2tree`, `geomean`, `clf`, `getPreferencesValue`, `gcd`, `isglobal`
 * reorganized:
   - `else`, `elseif`, `end`, `try`, `sciargs`, `global`, `halt`, `empty`, `power`, `numderivative`
   - `pixel_drawing_mode`, `show_window`, `twinkle`, `uigetcolor`, `winsid`, `xdel`, `xgrid`, `xname`, `xnumb`
@@ -403,6 +403,7 @@ the [development mailing list](dev@lists.scilab.org) for a particular toolbox.
 * [#15199](http://bugzilla.scilab.org/show_bug.cgi?id=15199): Scilab crash when using fsolve for functions containing other functions.
 * [#15205](http://bugzilla.scilab.org/show_bug.cgi?id=15205): `get_scicos_version` returned the previous version.
 * [#15207](http://bugzilla.scilab.org/show_bug.cgi?id=15207): `xcos(scs_m)` did not work for sub-systems.
+* [#15236](http://bugzilla.scilab.org/show_bug.cgi?id=15236): The `isglobal` help page was inaccurate. Examples were erroneous.
 * [#15266](http://bugzilla.scilab.org/show_bug.cgi?id=15266): Wrong default out_mode in `linear_interpn`.
 
 ### Bugs fixed in 6.0.0:
index 83182fb..200341a 100644 (file)
@@ -1,20 +1,39 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<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="isglobal">
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2017 - Samuel GOUGEON
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * 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: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="isglobal">
     <refnamediv>
         <refname>isglobal</refname>
-        <refpurpose>check if a variable is global</refpurpose>
+        <refpurpose>checks if a local variable has a global counterpart</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>t = isglobal(x)</synopsis>
+        <synopsis>t = isglobal(varname)</synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
         <variablelist>
             <varlistentry>
-                <term>x</term>
+                <term>varname</term>
                 <listitem>
-                    <para>any variable</para>
+                    <para>
+                        text: name of any single local variable. This is not the variable itself
+                        (that provides its content), but its name.
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
     <refsection>
         <title>Description</title>
         <para>
-            <code>isglobal(x)</code> returns <emphasis>true</emphasis> if <varname>x</varname> has been declared to be a global
-            variable and <emphasis>false</emphasis> otherwise.
+            <literal>isglobal("x")</literal> returns <literal>%T</literal> if the variable
+            <varname>x</varname> is defined locally and points to a global counterpart. It returns
+            <literal>%F</literal> otherwise.
         </para>
+        <important>
+            <itemizedlist>
+                <listitem>
+                    If <literal>x</literal> is defined in the global space but not in the local
+                    one, <literal>isglobal("x")</literal> will return <literal>%F</literal>
+                    (as <literal>isdef("x")</literal>).
+                </listitem>
+                <listitem>
+                    If <varname>varname</varname> is a text not corresponding to the name of any
+                    variable, no error occurs and <literal>%F</literal> is returned.
+                </listitem>
+            </itemizedlist>
+        </important>
+        <note>
+            The list of all variables defined in the global space (but not necessarily in the local
+            one) can be retrieved with <literal>who("global")</literal>.
+        </note>
     </refsection>
     <refsection>
         <title>Examples</title>
+        <para>
+            <emphasis role="bold">Example #1</emphasis> with a predefined global variable:
+        </para>
         <programlisting role="example"><![CDATA[
-isglobal(1)
-global a
-isglobal(a)
+mprintf("%s\n", who("global")) // demolist has a global definition...
+isdef("demolist")       // %F: ... but no local one (not yet)
+demolist(1)             // => "Undefined variable"
+isglobal("demolist")    // => %F, since it has no local definition
+
+global demolist         // We define a local demolist and make it pointing to the existing global one
+demolist($,:)           // Here is the last row of the existing global content
+isglobal("demolist")    // => now %T
+ ]]></programlisting>
+    <screen><![CDATA[
+--> mprintf("%s\n", who("global")) // demolist has a global definition...
+%helps
+%modalWarning
+%toolboxes
+%toolboxes_dir
+demolist
+
+--> isdef("demolist")     // ... but no local one (not yet)
+ ans  =
+  F
+
+--> demolist(1)           // So: => "Undefined variable"
+Undefined variable: demolist
+
+--> isglobal("demolist")  // => %F, since it has no local definition
+ ans  =
+  F
+
+--> global demolist       // We define a local demolist and make it pointing to the existing global one
+--> demolist($,:)         // Here is the last row of the existing global content
+ ans  =
+!Xcos  SCI\modules\xcos\demos\xcos.dem.gateway.sce  !
+
+--> isglobal("demolist")  // => now %T
+ ans  =
+  T
+ ]]></screen>
+
+    <para>
+        <emphasis role="bold">Example #2</emphasis> with a custom variable:
+    </para>
+    <programlisting role="example"><![CDATA[
+// In the list hereabove, "abc" does not exist. Let's create it locally and globally:
+global abc              // initialized with []
+isdef("abc")            // => %T
+isglobal("abc")         // => %T
+
+abc = %pi;              // Writes simultaneously in the local AND global spaces
+clear abc               // We delete the local definition, but not the global one
+abc                     // => "undefined variable"
+isglobal("abc")         // => %F, since there is no longer any local alias
+
+global abc              // We redefine abc connected to its global counterpart. What is it?
+abc
  ]]></programlisting>
+    <screen><![CDATA[
+--> // In the list hereabove, "abc" does not exist. Let's create it locally and globally:
+--> global abc              // initialized with []
+--> isdef("abc")
+ ans  =
+  T
+
+--> isglobal("abc")
+ ans  =
+  T
+
+--> abc = %pi;              // Writes simultaneously in the local AND global spaces
+--> clear abc               // We delete the local definition, but not the global one
+--> abc                     // => "undefined variable"
+Undefined variable: abc
+
+--> isglobal("abc")         // => %F, since without local alias
+ ans  =
+  F
+
+--> global abc              // We redefine abc connected to its global counterpart. What is it?
+--> abc
+ abc  =
+   3.1415927
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
@@ -52,6 +168,9 @@ isglobal(a)
             <member>
                 <link linkend="who">who</link>
             </member>
+            <member>
+                <link linkend="isdef">isdef</link>
+            </member>
         </simplelist>
     </refsection>
 </refentry>
diff --git a/scilab/modules/core/help/fr_FR/variables/isglobal.xml b/scilab/modules/core/help/fr_FR/variables/isglobal.xml
deleted file mode 100644 (file)
index f261542..0000000
+++ /dev/null
@@ -1,58 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<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="isglobal">
-    <refnamediv>
-        <refname>isglobal</refname>
-        <refpurpose>vérifie si une variable est globale  </refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Séquence d'appel</title>
-        <synopsis>t=isglobal(x)</synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>Paramètres</title>
-        <variablelist>
-            <varlistentry>
-                <term>x  </term>
-                <listitem>
-                    <para>une variable
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>t  </term>
-                <listitem>
-                    <para>un booléen
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Description</title>
-        <para>
-            <literal>isglobal(x)</literal> renvoie %T (vrai) si x a été déclarée en tant que variable globale et %F (faux) sinon.
-        </para>
-    </refsection>
-    <refsection>
-        <title>Exemples</title>
-        <programlisting role="example"><![CDATA[
-isglobal(1)
-global a
-isglobal(a)
- ]]></programlisting>
-    </refsection>
-    <refsection role="see also">
-        <title>Voir aussi</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="global">global</link>
-            </member>
-            <member>
-                <link linkend="clearglobal">clearglobal</link>
-            </member>
-            <member>
-                <link linkend="who">who</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>
diff --git a/scilab/modules/core/help/ja_JP/variables/isglobal.xml b/scilab/modules/core/help/ja_JP/variables/isglobal.xml
deleted file mode 100644 (file)
index af10b2d..0000000
+++ /dev/null
@@ -1,58 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<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="ja" xml:id="isglobal">
-    <refnamediv>
-        <refname>isglobal</refname>
-        <refpurpose>変数がグローバルかどうかを確認</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>呼出し手順</title>
-        <synopsis>t = isglobal(x)</synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>引数</title>
-        <variablelist>
-            <varlistentry>
-                <term>x</term>
-                <listitem>
-                    <para>任意の変数</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>t</term>
-                <listitem>
-                    <para>論理値</para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>説明</title>
-        <para>
-            <literal>isglobal(x)</literal> は, <varname>x</varname> がグローバル変数として
-            宣言されている場合に <emphasis>true</emphasis>,
-            それ以外の場合に <emphasis>false</emphasis> を返します.
-        </para>
-    </refsection>
-    <refsection>
-        <title>例</title>
-        <programlisting role="example"><![CDATA[
-isglobal(1)
-global a
-isglobal(a)
- ]]></programlisting>
-    </refsection>
-    <refsection role="see also">
-        <title>参照</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="global">global</link>
-            </member>
-            <member>
-                <link linkend="clearglobal">clearglobal</link>
-            </member>
-            <member>
-                <link linkend="who">who</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>
diff --git a/scilab/modules/core/help/pt_BR/variables/isglobal.xml b/scilab/modules/core/help/pt_BR/variables/isglobal.xml
deleted file mode 100644 (file)
index 8607b8c..0000000
+++ /dev/null
@@ -1,58 +0,0 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<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="isglobal" xml:lang="pt">
-    <refnamediv>
-        <refname>isglobal</refname>
-        <refpurpose>verifica se uma variável é global</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Seqüência de Chamamento</title>
-        <synopsis>t=isglobal(x)</synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>Parâmetros</title>
-        <variablelist>
-            <varlistentry>
-                <term>x</term>
-                <listitem>
-                    <para>qualquer variável</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>t</term>
-                <listitem>
-                    <para>um valor booleano</para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Descrição</title>
-        <para>
-            <literal>isglobal(x)</literal> retorna "true" ("verdadeiro"), se x
-            tiver sido declarada como variável global e "false" ("falso"), em caso
-            contrário.
-        </para>
-    </refsection>
-    <refsection>
-        <title>Exemplos</title>
-        <programlisting role="example"><![CDATA[
-isglobal(1)
-global a
-isglobal(a)
- ]]></programlisting>
-    </refsection>
-    <refsection>
-        <title> Ver Também </title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="global">global</link>
-            </member>
-            <member>
-                <link linkend="clearglobal">clearglobal</link>
-            </member>
-            <member>
-                <link linkend="who">who</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>
index c376373..85c1c7b 100644 (file)
@@ -1,28 +1,45 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<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="ru" xml:id="isglobal">
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2017 - Samuel GOUGEON
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * 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:mml="http://www.w3.org/1998/Math/MathML"
+        xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
+        xml:lang="ru" xml:id="isglobal">
     <refnamediv>
         <refname>isglobal</refname>
-        <refpurpose>
-            проверка, является ли переменная глобальной
-        </refpurpose>
+        <refpurpose>проверяет имеет ли локальная переменная глобальную копию</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Синтаксис</title>
-        <synopsis>t = isglobal(x)</synopsis>
+        <synopsis>t = isglobal(varname)</synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Аргументы</title>
         <variablelist>
             <varlistentry>
-                <term>x</term>
+                <term>varname</term>
                 <listitem>
-                    <para>любая переменная.</para>
+                    <para>
+                        текст: имя любой отдельной локальной переменной. Это не переменная
+                        сама по себе (это предоставляет своё содержимое), а её имя.
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>t</term>
                 <listitem>
-                    <para>логическое значение.</para>
+                    <para>логическое значение</para>
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection>
         <title>Описание</title>
         <para>
-            <code>isglobal(x)</code> возвращает <emphasis>истину</emphasis>, если <varname>x</varname>
-            была объявлена глобальной переменной, и <emphasis>ложь</emphasis> в противном случае.
+            <literal>isglobal("x")</literal> возвращает <literal>%T</literal>, если переменная
+            <varname>x</varname> определена локально и указывает на глобальную копию. В противном случае
+            она возвращает <literal>%F</literal>.
         </para>
+        <important>
+            <itemizedlist>
+                <listitem>
+                    Если <literal>x</literal> определена в глобальном пространстве, но не в локальном,
+                    то <literal>isglobal("x")</literal> вернёт <literal>%F</literal>
+                    (как <literal>isdef("x")</literal>).
+                </listitem>
+                <listitem>
+                    Если <varname>varname</varname> является текстом, не соответствующим имени какой-либо
+                    переменной, то ошибки не возникает и возвращается <literal>%F</literal>.
+                </listitem>
+            </itemizedlist>
+        </important>
+        <note>
+            Список всех переменных, определённых в глобальном пространстве (не не обязательно в локальном)
+            может быть получен с помощью <literal>who("global")</literal>.
+        </note>
     </refsection>
     <refsection>
         <title>Примеры</title>
+        <para>
+            <emphasis role="bold">Пример №1</emphasis> с предопределённой глобальной переменной:
+        </para>
         <programlisting role="example"><![CDATA[
-isglobal(1)
-global a
-isglobal(a)
+mprintf("%s\n", who("global")) // demolist содержит глобальную переменную...
+isdef("demolist")       // %F: ... но нет локальной переменной (пока)
+demolist(1)             // => "Переменная не определена"
+isglobal("demolist")    // => %F, поскольку в нём нет локальных определений
+global demolist         // Мы определяем локальный demolist и заставляем его указывать на
+                        //  существующую глобальную переменную
+demolist($,:)           // Здесь последняя строка содержимого существующей глобальной переменной
+isglobal("demolist")    // => теперь %T
+ ]]></programlisting>
+    <screen><![CDATA[
+--> mprintf("%s\n", who("global")) // demolist содержит глобальную переменную...
+%helps
+%modalWarning
+%toolboxes
+%toolboxes_dir
+demolist
+
+--> isdef("demolist")       // %F: ... но нет локальной переменной (пока)
+ ans  =
+  F
+
+--> demolist(1)             // => "Переменная не определена"
+Неопределённая переменная: demolist
+
+--> isglobal("demolist")    // => %F, поскольку в нём нет локальных определений
+ ans  =
+  F
+
+--> global demolist   // Мы определяем локальный demolist и заставляем его указывать на
+                      //  существующую глобальную переменную
+--> demolist($,:)     // Здесь последняя строка содержимого существующей глобальной переменной
+ ans  =
+!Xcos  SCI\modules\xcos\demos\xcos.dem.gateway.sce  !
+
+--> isglobal("demolist")    // => теперь %T
+ ans  =
+  T
+]]></screen>
+    <para>
+        <emphasis role="bold">Пример №2</emphasis> с пользовательской переменной:
+    </para>
+    <programlisting role="example"><![CDATA[
+// В списке ниже "abc" не существует. Давайте создадим её локально и глобально:
+global abc              // инициализируется как []
+isdef("abc")            // => %T
+isglobal("abc")         // => %T
+abc = %pi;              // Записывает одновременно в локальном И глобальном пространствах
+clear abc               // Удаляем локальное определение, но не глобальное
+abc                     // => "неопределённая переменная"
+isglobal("abc")         // => %F, поскольку больше нет локальных псевдонимов
+global abc              // переопределим abc, связанную с её глобальной копией. Что это?
+abc
  ]]></programlisting>
+    <screen><![CDATA[
+--> // В списке ниже "abc" не существует. Давайте создадим её локально и глобально:
+--> global abc              // инициализируется как []
+--> isdef("abc")            // => %T
+ ans  =
+  T
+
+--> isglobal("abc")         // => %T
+ ans  =
+  T
+
+--> abc = %pi;              // Записывает одновременно в локальном И глобальном пространствах
+--> clear abc               // Удаляем локальное определение, но не глобальное
+--> abc                     // => "неопределённая переменная"
+Неопределённая переменная: abc
+
+--> isglobal("abc")         // => %F, поскольку больше нет локальных псевдонимов
+ ans  =
+  F
+
+--> global abc              // переопределим abc, связанную с её глобальной копией. Что это?
+--> abc
+ abc  =
+   3.1415927
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>Смотрите также</title>
@@ -54,6 +166,9 @@ isglobal(a)
             <member>
                 <link linkend="who">who</link>
             </member>
+            <member>
+                <link linkend="isdef">isdef</link>
+            </member>
         </simplelist>
     </refsection>
 </refentry>