Better help for (sg)et[default]language functions 91/17491/2
Francois Granade [Tue, 24 Nov 2015 10:06:53 +0000 (11:06 +0100)]
Change-Id: Ifcaf077c26c517cf3f9fe03e3b6ec6e77c0ac745

scilab/modules/localization/help/en_US/getlanguage.xml
scilab/modules/localization/help/en_US/setdefaultlanguage.xml
scilab/modules/localization/help/en_US/setlanguage.xml
scilab/modules/localization/sci_gateway/cpp/sci_setdefaultlanguage.cpp

index 4e67fb1..7fbdd0b 100644 (file)
@@ -14,7 +14,7 @@
 <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="getlanguage">
     <refnamediv>
         <refname>getlanguage</refname>
-        <refpurpose>returns current language used by Scilab.</refpurpose>
+        <refpurpose>returns the current language used by Scilab.</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Calling Sequence</title>
@@ -23,7 +23,7 @@
     <refsection>
         <title>Description</title>
         <para>
-            <literal>getlanguage()</literal> returns current language used by Scilab.
+            <literal>getlanguage()</literal> returns the current language used by Scilab.
         </para>
     </refsection>
     <refsection>
index 858f11b..0c7a1f6 100644 (file)
@@ -13,7 +13,7 @@
 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="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="setdefaultlanguage" xml:lang="en">
     <refnamediv>
         <refname>setdefaultlanguage</refname>
-        <refpurpose>sets and saves the internal LANGUAGE value.</refpurpose>
+        <refpurpose>Permanently changes the language of Scilab's user interface.</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Calling Sequence</title>
@@ -25,7 +25,7 @@
             <varlistentry>
                 <term>language</term>
                 <listitem>
-                    <para>a string, can have following values: 'fr', 'en', 'ru_RU', 'zh_TW', ...</para>
+                    <para>a string made of a two-letter, lower-case, ISO Language Code, optionally followed by an underscore and a two-letter, upper-case, ISO country code), such as: 'fr', 'en', 'en_US', 'ru_RU', 'zh_TW'...</para>
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection>
         <title>Description</title>
         <para>
-            <literal>setdefaultlanguage(language)</literal> changes current
-            language and saves this value in Scilab.
+            <literal>setdefaultlanguage(language)</literal> changes the language used by Scilab user interface, including help, error messages, and saves this changes as the default for subsequent runs of Scilab.
         </para>
-        <para>You have to restart Scilab, if you want to use menus.</para>
+        <para>Menus will only be changed to the new language once Scilab is restarted.</para>
         <para>
-            <literal>setdefaultlanguage('')</literal> resets language to the system value.
+            <literal>setdefaultlanguage('')</literal> resets the language to the system value.
         </para>
         <para>
-            <literal>setdefaultlanguage</literal> is used only Windows. On others operating systems 
-            it returns always <literal>%f</literal>. 
+            <literal>setdefaultlanguage</literal> only works on Windows. On others operating systems, it does nothing and always returns <literal>%f</literal>. 
         </para>
     </refsection>
     <refsection>
index 2c40e2c..38aa84c 100644 (file)
@@ -14,8 +14,7 @@
 <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="setlanguage">
     <refnamediv>
         <refname>setlanguage</refname>
-        <refpurpose>sets the internal LANGUAGE
-            value (for Windows only)
+        <refpurpose>Changes the language of Scilab's user interface</refpurpose>
         </refpurpose>
     </refnamediv>
     <refsynopsisdiv>
@@ -28,7 +27,7 @@
             <varlistentry>
                 <term>language</term>
                 <listitem>
-                    <para>with language='fr' or  'en', ... </para>
+                    <para>string made of a two-letter, lower-case, ISO Language Code, optionally followed by an underscore and a two-letter, upper-case, ISO country code), such as: 'fr', 'en', 'en_US', 'ru_RU', 'zh_TW'...</para>
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection>
         <title>Description</title>
         <para>
-            <literal>setlanguage(language)</literal> changes current language in scilab.
+            <literal>setlanguage(language)</literal> changes the language used by Scilab user interface, including help, error messages, for the current execution of Scilab.
+        </para>
+        <para>
+            <literal>setlanguage('')</literal> resets the language to the system value.
+        </para>
+        <para>
+            <literal>setlanguage</literal> works on all supported operating systems. 
         </para>
     </refsection>
     <refsection>
index 9f6d196..c9cb2a2 100644 (file)
@@ -76,7 +76,7 @@ types::Function::ReturnValue sci_setdefaultlanguage(types::typed_list &in, int _
     */
     if (getWarningMode())
     {
-        sciprint(_("%ls: This feature is only used on Windows.\n"), L"setdefaultlanguage");
+        sciprint(_("%ls: This feature is only supported on Windows.\n"), L"setdefaultlanguage");
     }
 
     types::Bool* pbOut = new types::Bool(FALSE);