* Bug 14098 [doc]: genlib() and library pages updated for Scilab 6 67/21667/5
Samuel GOUGEON [Sat, 2 Jan 2021 18:21:36 +0000 (19:21 +0100)]
  http://bugzilla.scilab.org/14098

  Proposed updates (PDF):
    genlib:  http://bugzilla.scilab.org/attachment.cgi?id=5212
    library: http://bugzilla.scilab.org/attachment.cgi?id=5213

Change-Id: I00d89dd42ccb08314b92806a1d225ff6cd7ecd7c

scilab/CHANGES.md
scilab/modules/core/help/en_US/types/library.xml
scilab/modules/core/help/ja_JP/types/library.xml [deleted file]
scilab/modules/core/help/pt_BR/types/library.xml [deleted file]
scilab/modules/functions/help/en_US/libraries/genlib.xml
scilab/modules/functions/help/ja_JP/libraries/genlib.xml [deleted file]
scilab/modules/functions/help/pt_BR/libraries/genlib.xml [deleted file]
scilab/modules/functions/help/ru_RU/libraries/genlib.xml [new file with mode: 0644]
scilab/modules/functions/help/ru_RU/libraries/library.xml [new file with mode: 0644]

index 523087c..fe7944d 100644 (file)
@@ -336,6 +336,7 @@ Bug Fixes
 * [#13855](https://bugzilla.scilab.org/13855): The documentation of `pause` was not up-to-date and could be improved.
 * [#13985](https://bugzilla.scilab.org/13985): The display of lists was very loose and poor.
 * [#14033](https://bugzilla.scilab.org/14033): `x_matrix` could not edit matrices of booleans, encoded integers or text. Matrices of real or complex numbers were poorly displayed.
+* [#14098](https://bugzilla.scilab.org/14098): The `genlib` and `library` help pages were outdated with respect to Scilab 6.
 * [#14435](https://bugzilla.scilab.org/14435): Errors were not well handled in overloaded functions.
 * [#14488](https://bugzilla.scilab.org/14488): The `frameflag=9` and `strf=".9."` values of these `plot2d` options were no longer accepted. Their documentation was ambiguous.
 * [#14718](https://bugzilla.scilab.org/14718): `user` is removed for a while but was still documented.
index 8d7a7f9..72de12f 100644 (file)
@@ -2,8 +2,8 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) ????-2008 - INRIA
- *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2021 - 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.
  * 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="library">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="library">
     <refnamediv>
         <refname>library</refname>
-        <refpurpose>library datatype description
+        <refpurpose>library datatype
         </refpurpose>
     </refnamediv>
-    <refsynopsisdiv>
-        <title>Syntax</title>
-
-    </refsynopsisdiv>
     <refsection>
         <title>Description</title>
         <para>
-            A library is a data type with type number 14. It contains a path-name
-            and a set of names. It allows automatic loading of variables using the
-            following algorithm:
+            <emphasis role="bold">
+                What a library of functions written in Scilab language is made of?
+            </emphasis>
+        </para>
+        <para>
+            Such a library is made of a directory containing
+            <itemizedlist>
+                <listitem>
+                    an editable XML file always named <literal>lib</literal>. This file contains
+                    <orderedlist>
+                        <listitem>
+                            the name of the library
+                        </listitem>
+                        <listitem>
+                            the list of names of public functions belonging to the library.
+                        </listitem>
+                    </orderedlist>
+                    This file is generated by <literal>genlib(..)</literal>. It can't be made by hand.
+                    <para/>
+                </listitem>
+                <listitem>
+                    a set of binary files named with the <literal>.bin</literal> extension,
+                    whose basenames are the names of functions possibly registered in the
+                    <literal>lib</literal> file.
+                    <para/>
+                </listitem>
+                <listitem>
+                    and possibly -- but it's not mandatory to load and use the library --, the
+                    <literal>.sci</literal> sources files written in Scilab language, whose
+                    compilation with <code>genlib(..)</code> has generated the
+                    <literal>lib</literal> and <literal>.bin</literal> files.
+                    <para/>
+                    <warning>
+                        When the <literal>foo.sci</literal> source file of a foo()
+                        function is not provided in the library's directory,
+                        <literal>edit foo</literal> won't be able to edit its Scilab code, and
+                        will open a empty file from scratch.
+                    </warning>
+                    <para/>
+                </listitem>
+            </itemizedlist>
+        </para>
+        <para>
+            <emphasis role="bold">
+                Loading / declaring a library in the session
+            </emphasis>:
+        </para>
+        <para>
+            <literal>load("/path/to/lib")</literal> then loads the targeted library in the
+            Scilab session: a variable whose name is the library's name -- say
+            <literal>libname</literal> -- is created. Its dedicated <literal>type(libname)</literal>
+            is 14. Its <literal>typeof(libname)</literal> is <literal>"library"</literal>. This
+            library's handle contains
+            <itemizedlist>
+                <listitem>
+                    the path to the library's root directory
+                </listitem>
+                <listitem>
+                    the list of public functions names belonging to the library.
+                </listitem>
+            </itemizedlist>
+        </para>
+        <para>
+            Both parts can be retrieved with either the libraryinfo() or the string() functions.
+        </para>
+        <para>
+            Example: <literal>interpolationlib</literal> is a native Scilab library:
+            <screen>
+--> interpolationlib
+ interpolationlib  =
+
+Functions files location : SCI\modules\interpolation\macros\.
+interp1  mesh2d  interpln  smooth
+
+--> type(interpolationlib)
+ ans  =
+   14.
+
+--> [typeof(interpolationlib), typeof(interpolationlib, "overload")]
+ ans  =
+  "library"  "f"
+
+--> string(interpolationlib)
+ ans  =
+  "SCI\modules\interpolation\macros\"
+  "interp1"
+  "mesh2d"
+  "interpln"
+  "smooth"
+
+--> [fnames, libpath] = libraryinfo("interpolationlib")
+ fnames  =
+  "interp1"
+  "mesh2d"
+  "interpln"
+  "smooth"
+
+ libpath  =
+  "SCI\modules\interpolation\macros\"
+</screen>
+        </para>
+        <para>
+            <emphasis role="bold">Autoloading when first calling a function</emphasis>:
         </para>
         <para>
-            Suppose the Scilab user references the variable named <literal>foo</literal>.
-            Scilab first looks if <literal>foo</literal> is the name of a primitive or of an
-            already defined variable. If not, it looks for <literal>foo</literal> sequentially
-            (the newest first) in all defined library .
+            When the name of a function -- say <literal>foo()</literal> -- belonging
+            to the library is called in the session, Scilab does the following:
+            <orderedlist>
+                <listitem>
+                    Is <literal>foo</literal> the name of a builtin function?
+                    If so, this builtin is called. Otherwise,
+                    <para/>
+                </listitem>
+                <listitem>
+                    Is <literal>foo</literal> the name of a local variable, possibly the
+                    required foo() (provided that it has been already called)?
+                    If so, this variable is used. Otherwise,
+                    <para/>
+                </listitem>
+                <listitem>
+                    All loaded libraries are scanned -- in anti-alphabetical order of libraries names --
+                    for the searched foo(). The first found is then "loaded" from its
+                    <literal>.bin</literal> file, and finally called. Next calls to foo()
+                    will then go up to the step #2 that will be successful, unless
+                    the <literal>foo</literal> handle has been cleared in the meantime.
+                    <para/>
+                </listitem>
+            </orderedlist>
         </para>
         <para>
-            Suppose <literal>foo</literal> belongs to the set of names of the library <literal>xlib</literal>
-            then Scilab tries to load the file
-            &lt;xlib-path-name&gt;/foo.bin. &lt;xlib-path-name&gt;/foo.bin must have been
-            created using the <literal>save</literal> function
+            Without the step #3, a user's function not belonging to any library and that would
+            be cleared can not be automatically retrieved.
         </para>
         <para>
-            Library are often used for collection of functions, but they can also
-            be used for any collection of scilab variables
+            <warning>
+                If the <literal>foo.sci</literal> file is modified while foo() has been already
+                called, then recompiling and reloading its library won't update the current
+                foo() behavior: foo() being already known, Scilab will stop at the step #2,
+                without reloading the updated library, and will use the former foo().
+                Entering <literal>clear foo</literal> before the next call to foo(..)
+                will force Scilab going up to the step #3 during the next call, and so
+                load and use the updated foo().
+            </warning>
         </para>
         <para>
-            If a function is defined in more than one library, the default search
-            algorithm loads thode contained in the newest. It possible to force
-            the use of a specific library using dot notation:
+            <emphasis role="bold">Homonymous functions in distinct libraries: libname.foo()</emphasis>
         </para>
         <para>
-            <literal>xlib.foo</literal> loads the variable <literal>foo</literal> contained in <literal>xlib</literal>.
-            if <literal>foo</literal> is a function
-            and <literal>xlib.foo(args)</literal> executes the functions
+            If several loaded libraries have a foo() public function, the anti-alphabetical priority
+            can be unrelevant. Fortunately, it is always
+            possible to force to use the instance of a given library, with the dot-name's resolution
+            syntax:
+            <literal>libname.foo(..)</literal> will call the foo() instance belonging to the
+            <literal>libname</literal> library.
         </para>
     </refsection>
     <refsection>
         <title>Examples</title>
+        <para>
+            <literal>interpolationlib</literal> is a native Scilab library:
+        </para>
         <programlisting role="example"><![CDATA[
-// elemlib is a predefined library
-elementary_functionlib //displays the contents of the library
-A=rand(3,3);
-cosm(A) //loads cosm and executes it
-whos -name cosm // now cosm is a variable
-elementary_functionlib.sinm //loads sinm from the library
-elementary_functionlib.cosm(A) //reloads cosm and executes it
- ]]></programlisting>
+interpolationlib        //displays the contents of the library
+type(interpolationlib)
+[typeof(interpolationlib), typeof(interpolationlib, "overload")]
+string(interpolationlib)
+[fnames, libpath] = libraryinfo("interpolationlib")
+     ]]></programlisting>
+        <para>
+            The output is illustrated in the above Description section.
+        </para>
+        <para/>
+        <para>
+            Handling calls of homonymous functions:
+        </para>
+        <programlisting role="example"><![CDATA[
+whereis(blanks)
+clear blanks, isdef("blanks","l")
+blanks(20)          // loads blanks() and calls it
+isdef("blanks","l") // It stays in the workspace
+
+// Building a library with our own homonymous blanks() function
+libDir = fullfile(TMPDIR, "mylib");
+code = ["function r = blanks(n, nbsp)"
+        "    if nbsp, r = part(ascii(160),ones(1,n)),"
+        "    else r = ""ABC"","
+        "    end"
+        "endfunction" ];
+mkdir(libDir);
+mputl(code, libDir + filesep() + "blanks.sci");
+genlib("mylib", libDir);    // Compiling our own library
+
+clear blanks
+ascii(blanks(3)) // stringlib.blanks() is called ⇐ "stringlib" > "mylib"
+clear blanks
+ascii(mylib.blanks(3,%t)) // forced call to mylib.blanks()
+blanks(3)        // Next call is with the default stringlib.blanks()
+     ]]></programlisting>
+        <screen><![CDATA[
+--> whereis(blanks)
+ ans  =
+  "stringlib"
+
+--> clear blanks, isdef("blanks","l")
+ ans  =
+  F
+
+--> blanks(20)          // loads blanks() and calls it
+ ans  =
+  "                    "
+--> isdef("blanks","l") // It stays in the workspace
+ ans  =
+  T
+
+--> // Building a library with our own homonymous blanks() function
+--> libDir = fullfile(TMPDIR, "mylib");
+--> code = ["function r = blanks(n, nbsp)"
+  >         "    if nbsp, r = part(ascii(160),ones(1,n)),"
+  >         "    else r = ""ABC"","
+  >         "    end"
+  >         "endfunction" ];
+--> mkdir(libDir);
+--> mputl(code, libDir + filesep() + "blanks.sci");
+--> genlib("mylib", libDir);    // Compiling our own library
+
+--> clear blanks
+--> ascii(blanks(3)) // stringlib.blanks() is called ⇐ "stringlib" > "mylib"
+ ans  =
+   32.   32.   32.
+
+--> clear blanks
+--> ascii(mylib.blanks(3,%t)) // forced call to mylib.blanks()
+ ans  =
+   194.   160.   194.   160.   194.   160.
+
+--> blanks(3)        // Next call is with the default stringlib.blanks()
+ ans  =
+  "   "
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
+                <link linkend="load">load</link>
+            </member>
+            <member>
                 <link linkend="lib">lib</link>
             </member>
             <member>
+                <link linkend="genlib">genlib</link>
+            </member>
+            <member>
+                <link linkend="libraryinfo">libraryinfo</link>
+            </member>
+            <member>
                 <link linkend="string">string</link>
             </member>
             <member>
-                <link linkend="load">load</link>
+                <link linkend="whereis">whereis</link>
             </member>
             <member>
-                <link linkend="save">save</link>
+                <link linkend="librarieslist">librarieslist</link>
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0.0</revnumber>
+                <revdescription>
+                    <itemizedlist>
+                        <listitem>
+                            A library can now contain only functions, no longer any variables
+                            of other types.
+                        </listitem>
+                        <listitem>
+                            The lib file is now an editable XML file, no longer a binary one.
+                        </listitem>
+                        <listitem>
+                            When a foo.sci source file contains several consecutive
+                            function/endfunction blocks, only the defined foo()
+                            is now registered in the library. Other defined functions are now
+                            private and known only from foo().
+                        </listitem>
+                    </itemizedlist>
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
diff --git a/scilab/modules/core/help/ja_JP/types/library.xml b/scilab/modules/core/help/ja_JP/types/library.xml
deleted file mode 100644 (file)
index 50114da..0000000
+++ /dev/null
@@ -1,97 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) ????-2008 - INRIA
- *
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- *
- * 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="ja" xml:id="library">
-    <refnamediv>
-        <refname>library</refname>
-        <refpurpose>ライブラリのデータ型の説明
-        </refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>呼び出し手順</title>
-    </refsynopsisdiv>
-    <refsection>
-        <title>説明</title>
-        <para>
-            ライブラリは型番号14のデータ型です.
-            これには,パス名と名前の集合が含まれます.
-            これにより,以下のアルゴリズムにより変数を自動的に
-            ロードすることが可能になります:
-        </para>
-        <para>
-            Scilabユーザが<literal>foo</literal>という名前の変数を参照すると
-            仮定します.
-            Scilabはまず<literal>foo</literal>がプリミティブの名前または
-            すでに定義ずみであるかどうかを調べます.
-            そうでない場合,<literal>foo</literal>を(新しいものから順に)
-            順番に全ての定義済みのライブラリの中で探します.
-        </para>
-        <para>
-            <literal>foo</literal> がライブラリ<literal>xlib</literal>の
-            名前の集合に属すると仮定すると,
-            Scilabはファイル &lt;xlib-path-name&gt;/foo.bin をロード
-            します.
-            &lt;xlib-path-name&gt;/foo.bin は
-            <literal>save</literal> 関数により作成されている必要があります.
-        </para>
-        <para>
-            ライブラリはしばしば関数の集約に使用されますが,
-            Scilab変数の集約にも使用することができます.
-        </para>
-        <para>
-            ある関数が1つ以上のライブラリで定義されている場合,
-            デフォルトの探索アルゴリズムは最新のライブラリに
-            含まれる関数をロードします.
-            ドット表記により
-            特定のライブラリの関数を強制的に使用することも可能です:
-        </para>
-        <para>
-            <literal>xlib.foo</literal> は
-            <literal>xlib</literal>に含まれる変数<literal>foo</literal>
-            をロードします.
-            <literal>foo</literal>が関数の場合,
-            <literal>xlib.foo(args)</literal>はこの関数を実行します.
-        </para>
-    </refsection>
-    <refsection>
-        <title>例</title>
-        <programlisting role="example"><![CDATA[
-// elemlib は定義済みのライブラリです
-elementary_functionlib //ライブラリの中身を表示
-A=rand(3,3);
-cosm(A) //cosmをロードし実行
-whos -name cosm // ここでcosmは変数です
-elementary_functionlib.sinm //sinmをライブラリからロード
-elementary_functionlib.cosm(A) //cosmを再ロードし,実行
- ]]></programlisting>
-    </refsection>
-    <refsection role="see also">
-        <title>参照</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="lib">lib</link>
-            </member>
-            <member>
-                <link linkend="string">string</link>
-            </member>
-            <member>
-                <link linkend="load">load</link>
-            </member>
-            <member>
-                <link linkend="save">save</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>
diff --git a/scilab/modules/core/help/pt_BR/types/library.xml b/scilab/modules/core/help/pt_BR/types/library.xml
deleted file mode 100644 (file)
index 3edcacd..0000000
+++ /dev/null
@@ -1,88 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) ????-2008 - INRIA
- *
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- *
- * 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:ns3="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="library" xml:lang="pt">
-    <refnamediv>
-        <refname>library</refname>
-        <refpurpose>descrição de tipo de dado bibilioteca</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Seqüência de Chamamento</title>
-
-    </refsynopsisdiv>
-    <refsection>
-        <title>Descrição</title>
-        <para>Uma bibilioteca é um tipo de dado com número 14. Contém um nome de
-            endereço e um conjunto de nomes. Permite o carregamento automático de
-            variáveis utilizando o seguinte algoritmo:
-        </para>
-        <para>Suponha o usuário Scilab referencie a variável de nome
-            <literal>foo</literal>. O Scilab procura primeiro se
-            <literal>foo</literal> é o nome de uma primitiva, ou de uma variável já
-            definida. Se naõ for, procura por <literal>foo</literal> seqüencialmente
-            (a mais nova) em toda a biblioteca definida .
-        </para>
-        <para>
-            Suponha que <literal>foo</literal> pertence ao conjunto de nomes da
-            biblioteca <literal>xlib</literal>. Então o Scilab tenta carregar o
-            arquivo &lt;xlib-path-name&gt;/foo.bin. &lt;xlib-path-name&gt;/foo.bin
-            deve ter sido criado utilizando-se a função
-            <literal>save</literal>.
-        </para>
-        <para>Bibliotecas geralmente são utilizadas para coleções de funções, mas
-            também podem ser utilizadas para coleções de variáveis Scilab.
-        </para>
-        <para>Se uma função estiver definida em mais de uma biblioteca, o
-            algoritmo de busca padrão carrega aquela contida na mais nova. É possível
-            forçar o uso de uma biblioteca específica utilizando a notação de
-            ponto:
-        </para>
-        <para>
-            <literal>xlib.foo</literal> carrega a variável
-            <literal>foo</literal> contida em <literal>xlib</literal>, if
-            <literal>foo</literal> for uma função e <literal>xlib.foo(args)</literal>
-            executa as funções.
-        </para>
-    </refsection>
-    <refsection>
-        <title>Exemplos</title>
-        <programlisting role="example"><![CDATA[
-// elemlib é uma biblioteca predefinida
-elementary_functionlib //exibindo o conteúdo da biblioteca
-A=rand(3,3);
-cosm(A) //carregando cosm e executando-o
-whos -name cosm // agora, cosm é uma variável
-elementary_functionlib.sinm //carregando sinm da biblioteca
-elementary_functionlib.cosm(A) //carregando novamente cosm e executando-o
- ]]></programlisting>
-    </refsection>
-    <refsection role="see also">
-        <title>Ver Também</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="lib">lib</link>
-            </member>
-            <member>
-                <link linkend="string">string</link>
-            </member>
-            <member>
-                <link linkend="load">load</link>
-            </member>
-            <member>
-                <link linkend="save">save</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>
index 8ce385b..bb6e0ee 100644 (file)
@@ -2,8 +2,8 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) ????-2008 - INRIA
- *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2021 - 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.
  * 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="genlib">
+-->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="genlib">
     <refnamediv>
         <refname>genlib</refname>
-        <refpurpose>build library from functions in given directory</refpurpose>
+        <refpurpose>
+            builds a library from a set of *.sci files defining functions in a given directory
+        </refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>genlib(lib_name [[,dir_name, [ Force [,verb [,Names]]]])
-            genlib(lib_name [,path=dir_name] [,verbose=verb] [,force=Force] [,names=Names])
+        <synopsis>
+            genlib(lib_name)
+            genlib(lib_name, dir_name)
+            genlib(lib_name, dir_name, Force)
+            genlib(lib_name, dir_name, Force, verb)
+            genlib(lib_name [,path=dir_name] [,verbose=verb] [,force=Force])
         </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
         <variablelist>
             <varlistentry>
-                <term>lib_name:  </term>
+                <term>lib_name</term>
                 <listitem>
-                    <para>Scilab string.  The variable name of the library to (re)create.</para>
+                    Scilab string:  The identifying name ascribed to the library to build.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>dir_name:  </term>
+                <term>dir_name</term>
                 <listitem>
-                    <para>Scilab string.  The name of the directory to look for
-                        <literal>.sci</literal>-files.
-                    </para>
+                    Scilab string:  The pathname of the directory containing
+                    <literal>.sci</literal> functions files, and where the <literal>lib</literal>
+                    file generated and defining the library will be stored.
+                    By default, the current working directory is considered.
+                    <warning>
+                        The <varname>dir_name</varname> directory and its <literal>lib</literal>
+                        and <literal>.bin</literal> files must be writable.
+                    </warning>
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>Force</term>
                 <listitem>
-                    <para>
-                        boolean value (default value is <literal>%f</literal>). Set it to
-                        <literal>%t</literal> to force the sci-files recompilation.
-                    </para>
+                    boolean value (default value is <literal>%f</literal>). Set it to
+                    <literal>%t</literal> to force the sci-files recompilation.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>verb</term>
                 <listitem>
-                    <para>
-                        boolean values (default value is <literal>%f</literal>). Set it to
-                        <literal>%t</literal> to get information.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>Names</term>
-                <listitem>
-                    <para>a vector of strings, the names of function to include in the
-                        library. By default all the sci-files are taken into account
-                    </para>
+                    boolean value (default value is <literal>%f</literal>). Set it to
+                    <literal>%t</literal> to display more information during the build.
+                    <para/>
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection>
         <title>Description</title>
         <para>
-            For each <literal>.sci</literal> file in <literal>dir_name</literal> (or only those
-            specified by the <literal>Names</literal> argument), <literal>genlib</literal> executes a
-            <literal>exec</literal> and saves the functions to the corresponding <literal>.bin</literal>
-            file.  The <literal>.sci</literal> file must not contain anything but Scilab
-            functions.  If a <literal>.bin</literal> file is newer than the associated
-            <literal>.sci</literal> file, <literal>genlib</literal> does not translate and save the file.
+            <literal>genlib(..)</literal> selects all files belonging to the
+            <varname>dir_name</varname> directory and with the <literal>.sci</literal> extension.
+            If any, subdirectories are never considered. If it is required, they must be compiled
+            apart into independent libraries.
+        </para>
+        <para>
+            Then, an XML editable file named <literal>lib</literal> is created in the
+            <varname>dir_name</varname> directory. The name <varname>lib_name</varname>
+            of the library is recorded into it.
         </para>
         <para>
-            This default behaviour can be changed if <literal>force</literal> is given and
-            set to <literal>%t</literal>. In this latter case the recompilation is always
-            performed for each <literal>.sci</literal> file.
+            Then, for each <literal>.sci</literal> file:
+            <itemizedlist>
+                <listitem>
+                    If
+                    <itemizedlist>
+                        <listitem>
+                            there is no related <literal>.bin</literal> file in <varname>dir_name</varname>
+                            with the same basename (as for the initial build of the library), or
+                        </listitem>
+                        <listitem>
+                            the content of the <literal>.sci</literal> file has changed since
+                            the previous build,
+                        </listitem>
+                    </itemizedlist>
+                    <para/>
+                    <para>
+                        the <literal>.sci</literal> file is compiled (<emphasis>almost</emphasis>
+                        as it would be with <literal>exec(..)</literal>):
+                        <itemizedlist>
+                            <listitem>
+                                <para>
+                                    If it contains at least one <literal>function .. endfunction</literal>
+                                    block, a <literal>.bin</literal> binary file with the same basename
+                                    is generated and stored in <varname>dir_name</varname>.
+                                    It contains the binary code of ALL functions defined in the
+                                    <literal>.sci</literal> source file.
+                                    <itemizedlist>
+                                        <listitem>
+                                            If the name of one of the function(s) defined in the
+                                            file is the basename of the <literal>.sci</literal>
+                                            file, this function is registered in the
+                                            <literal>lib</literal> file.
+                                            <para/>
+                                        </listitem>
+                                        <listitem>
+                                            Otherwise, no function from the <literal>.sci</literal>
+                                            file is registered: Its whole content is considered as
+                                            dead code.
+                                        </listitem>
+                                    </itemizedlist>
+                                </para>
+                                <para>
+                                    <warning>
+                                        If a <literal>test.sci</literal> file defines the
+                                        <literal>test()</literal> function AND other functions like
+                                        sub(), sub() functions are then considered as private to
+                                        test(). For instance,
+                                        <table>
+                                            <tr>
+                                                <td>
+                                                    <screen>
+function r = sub(a)
+    r = 2*a
+endfunction
+
+function test()
+    disp("A test")
+endfunction
+
+function r = other(b)
+    r = 2^b
+endfunction
+</screen>
+                                                </td>
+                                                <td>
+                                                    is equivalent to
+                                                </td>
+                                                <td>
+                                                    <screen>
+function test()
+    function r = sub(a)
+        r = 2*a
+    endfunction
+    function r = other(b)
+        r = 2^b
+    endfunction
+
+    disp("A test")
+endfunction
+</screen>
+                                                </td>
+                                            </tr>
+                                        </table>
+                                        Hence, sub() and other() won't exist out of test(), and
+                                        won't be registered in the library.
+                                    </warning>
+                                </para>
+                            </listitem>
+                            <listitem>
+                                Otherwise, no <literal>.bin</literal> file is generated: The whole
+                                content of the <literal>.sci</literal> file is considered as dead code.
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                </listitem>
+                <listitem>
+                    Otherwise: If the file's content has not changed and has already a function
+                    entry in the <literal>lib</literal> file, this entry is kept.
+                </listitem>
+            </itemizedlist>
         </para>
         <para>
-            When all <literal>.sci</literal> files have been processed, <literal>genlib</literal> creates a
-            library variable named <literal>lib_name</literal> and saves it in the file
-            <literal>lib</literal> in <literal>dir_name</literal>. If the Scilab variable
-            <literal>lib_name</literal> is not protected (see <link linkend="predef">predef</link>) this
-            variable is updated.
+            Finally, <literal>genlib(..)</literal> loads the created or updated library and sets
+            its identifier to a variable named <varname>lib_name</varname>, in the current scope.
+            If the variable <varname>lib_name</varname> already exists and is protected,
+            an error occurs: The library has been created but can't be loaded
+            (<link linkend="predef">predef all</link> can be used to unprotect the variable
+            named <varname>lib_name</varname> before running <literal>genlib(..)</literal>).
         </para>
         <para>
-            If <literal>verbose</literal> is et to <literal>%t</literal> information are displayed during
-            the build process.
+            If the option <literal>force=%t</literal> is used, all <literal>.sci</literal> files
+            are compiled, even if their content has not changed.
         </para>
         <para>
-            If <literal>dir_name</literal> argument is not given and if <literal>lib_name</literal>
-            Scilab variable  exists and it is a library dir_name is taken equal to the
-            <literal>lib_name</literal> library path (update mode).
+            When in the directory of a library some former .sci files have been removed while
+            all remaining .sci files are unchanged, rebuilding the library without the
+            <literal>force=%t</literal> will anyway update the list of library's members.
         </para>
-    </refsection>
-    <refsection>
-        <title>Restrictions</title>
         <para>
-            Scilab tacitly assumes that file <literal>foo.sci</literal> defines at least a
-            function named <literal>foo</literal>. If subsidiary functions are included,
-            they are made known to Scilab only after the function <literal>foo</literal>
-            had been referenced.
+            If the option <literal>verbose</literal> is true, more information is displayed during
+            the build process.
         </para>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
-                <link linkend="getd">getd</link>
+                <link linkend="library">library</link>
             </member>
             <member>
-                <link linkend="exec">exec</link>
+                <link linkend="load">load</link>
             </member>
             <member>
-                <link linkend="save">save</link>
+                <link linkend="getd">getd</link>
             </member>
             <member>
                 <link linkend="lib">lib</link>
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0.0</revnumber>
+                <revdescription>
+                    <itemizedlist>
+                        <listitem>
+                            The file <literal>names</literal> is no longer required.
+                            The <literal>Names</literal> option is removed.
+                        </listitem>
+                        <listitem>
+                            When a .sci file contains functions not named accordingly with the
+                            file name, they are no longer public: They are visible and callable only
+                            from the main function.
+                        </listitem>
+                        <listitem>
+                            When a library named <varname>lib_name</varname> is already loaded, the
+                            default <varname>dir_name</varname> directory is no longer its
+                            directory (update mode), but always the current working one.
+                        </listitem>
+                        <listitem>
+                            The generated <literal>lib</literal> file is now a human-readable XML
+                            file, instead of a binary.
+                        </listitem>
+                        <listitem>
+                            genlib() can no longer register any variable as full member of a library.
+                        </listitem>
+                        <listitem>
+                            By default, any .sci file is now recompiled if its content has
+                            changed, no longer if its modification date is newer than the .bin's one.
+                        </listitem>
+                        <listitem>
+                            The generated <literal>.bin</literal> files can no longer be loaded
+                            independently with load().
+                        </listitem>
+                    </itemizedlist>
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
diff --git a/scilab/modules/functions/help/ja_JP/libraries/genlib.xml b/scilab/modules/functions/help/ja_JP/libraries/genlib.xml
deleted file mode 100644 (file)
index a2fdbb4..0000000
+++ /dev/null
@@ -1,275 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) ????-2008 - INRIA
- *
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- *
- * 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="ja" xml:id="genlib">
-
-    <refnamediv>
-
-        <refname>genlib</refname>
-
-        <refpurpose>指定したディレクトリの関数からライブラリを構築する </refpurpose>
-
-    </refnamediv>
-
-    <refsynopsisdiv>
-
-        <title>呼び出し手順</title>
-
-        <synopsis>genlib(lib_name [[,dir_name, [ Force [,verb [,Names]]]])
-
-            genlib(lib_name [,path=dir_name] [,verbose=verb] [,force=Force] [,names=Names])
-
-        </synopsis>
-
-    </refsynopsisdiv>
-
-    <refsection>
-
-        <title>引数</title>
-
-        <variablelist>
-
-            <varlistentry>
-
-                <term>lib_name:  </term>
-
-                <listitem>
-
-                    <para>Scilab文字列.  (再)作成するライブラリの変数名.</para>
-
-                </listitem>
-
-            </varlistentry>
-
-            <varlistentry>
-
-                <term>dir_name:  </term>
-
-                <listitem>
-
-                    <para>Scilab文字列.
-
-                        <literal>.sci</literal>-ファイルを探すディレクトリの名前.
-
-                    </para>
-
-                </listitem>
-
-            </varlistentry>
-
-            <varlistentry>
-
-                <term>Force</term>
-
-                <listitem>
-
-                    <para>
-
-                        論理値 (デフォルト値は <literal>%f</literal>).
-
-                        sci-ファイルの再コンパイルを強制的に行う場合,
-
-                        <literal>%t</literal>に設定してください.
-
-                    </para>
-
-                </listitem>
-
-            </varlistentry>
-
-            <varlistentry>
-
-                <term>verb</term>
-
-                <listitem>
-
-                    <para>
-
-                        論理値 (デフォルト値は <literal>%f</literal>).
-
-                        情報を取得するには <literal>%t</literal> に設定してください.
-
-                    </para>
-
-                </listitem>
-
-            </varlistentry>
-
-            <varlistentry>
-
-                <term>Names</term>
-
-                <listitem>
-
-                    <para>文字列のベクトルで, ライブラリに含まれる
-
-                        関数の名前です.
-
-                        デフォルトで全ての sci-ファイルが取得されます.
-
-                    </para>
-
-                </listitem>
-
-            </varlistentry>
-
-        </variablelist>
-
-    </refsection>
-
-    <refsection>
-
-        <title>説明</title>
-
-        <para>
-
-            <literal>dir_name</literal>にある各<literal>.sci</literal>ファイル
-
-            (または<literal>Names</literal>引数で指定されたファイルのみ)について,
-
-            <literal>genlib</literal>は<literal>exec</literal>を
-
-            実行し,対応する<literal>.bin</literal>ファイルに関数を保存します.
-
-            <literal>.sci</literal>ファイルにはScilab関数以外のものを含んでは
-
-            いけません.
-
-            ある<literal>.bin</literal>ファイルが対応する<literal>.sci</literal>ファイルよりも
-
-            新しい場合, <literal>genlib</literal>はこのファイルを変換/保存しません.
-
-        </para>
-
-        <para>
-
-            このデフォルトの動作は<literal>force</literal>が指定され,
-
-            <literal>%t</literal> に設定された場合に変更できます.
-
-            この場合, 各<literal>.sci</literal>ファイル毎に常に再コンパイルが
-
-            行われます.
-
-        </para>
-
-        <para>
-
-            全ての<literal>.sci</literal> ファイルが処理された場合,
-
-            <literal>genlib</literal>は<literal>lib_name</literal>という
-
-            名前のライブラリ変数を作成し,
-
-            <literal>dir_name</literal>の中のファイル<literal>lib</literal>に
-
-            この変数を保存します.
-
-            Scilab変数
-
-            <literal>lib_name</literal>が保護されていない場合
-
-            (<link linkend="predef">predef</link>参照),
-
-            この変数は更新されます.
-
-        </para>
-
-        <para>
-
-            <literal>verbose</literal> に <literal>%t</literal>が
-
-            指定された場合, 構築処理中に情報が表示されます.
-
-        </para>
-
-        <para>
-
-            <literal>dir_name</literal> 引数が指定されない場合に,
-
-            Scilab変数<literal>lib_name</literal>が存在し,
-
-            それがライブラリの場合,
-
-            dir_name は,
-
-            <literal>lib_name</literal>ライブラリパスに等しく
-
-            設定されます (更新モード).
-
-        </para>
-
-    </refsection>
-
-    <refsection>
-
-        <title>制約</title>
-
-        <para>
-
-            Scilab は, ファイル<literal>foo.sci</literal>が,
-
-            少なくとも<literal>foo</literal>という名前の関数を
-
-            定義すると仮定します.
-
-            補助関数が含まれる場合,これらは
-
-            関数<literal>foo</literal>が参照された後でのみ
-
-            Scilabから既知となります.
-
-        </para>
-
-    </refsection>
-
-    <refsection role="see also">
-
-        <title>参照</title>
-
-        <simplelist type="inline">
-
-            <member>
-
-                <link linkend="getd">getd</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="exec">exec</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="save">save</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="lib">lib</link>
-
-            </member>
-
-        </simplelist>
-
-    </refsection>
-
-</refentry>
-
diff --git a/scilab/modules/functions/help/pt_BR/libraries/genlib.xml b/scilab/modules/functions/help/pt_BR/libraries/genlib.xml
deleted file mode 100644 (file)
index 4ba9b98..0000000
+++ /dev/null
@@ -1,139 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) ????-2008 - INRIA
- *
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- *
- * 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: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="genlib" xml:lang="pt">
-    <refnamediv>
-        <refname>genlib</refname>
-        <refpurpose>constrói biblioteca a partir de funções em um
-            diretório
-        </refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Seqüência de Chamamento</title>
-        <synopsis>genlib(lib_name [[,dir_name, [ Force [,verb [,Names]]]])
-            genlib(lib_name [,path=dir_name] [,verbose=verb] [,force=Force] [,names=Names])
-        </synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>Parâmetros</title>
-        <variablelist>
-            <varlistentry>
-                <term>lib_name:</term>
-                <listitem>
-                    <para>string. O nome da variável biblioteca a ser (re)criada.</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>dir_name:</term>
-                <listitem>
-                    <para>string. O nome do diretório onde se deve procurar arquivos
-                        <literal>.sci</literal>.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>Force</term>
-                <listitem>
-                    <para>
-                        booleano (o padrão é <literal>%f</literal>). Para forçar
-                        recompilação de arquivos .sci, ajuste-o para
-                        <literal>%t</literal>.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>verb</term>
-                <listitem>
-                    <para>
-                        booleano (o padrão é <literal>%f</literal>). Para obter
-                        informações ajuste-o para <literal>%t</literal>.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>Names</term>
-                <listitem>
-                    <para>vetor de strings, os nomes das funções a serem inclusas na
-                        bibilioteca. Por padrão, todos os arquivos sci são levados em
-                        conta.
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Descrição</title>
-        <para>
-            Para cada arquivo <literal>.sci</literal> em
-            <literal>dir_name</literal> (ou apenas para aqueles especificados pelo
-            argumento <literal>Names</literal>), <literal>genlib</literal> executa um
-            <literal>exec</literal> e salva as funções no arquivo
-            <literal>.bin</literal> correspondente. O arquivo <literal>.sci</literal>
-            só pode conter instruções Scilab. Se um arquivo <literal>.bin</literal>
-            for mais novo que o arquivo <literal>.sci</literal> assicuadi,
-            <literal>genlib</literal> não traduz nem salva o arquivo.
-        </para>
-        <para>O comportamento padrão pode ser modificado se
-            <literal>force</literal> for fornecido e ajustado para
-            <literal>%t</literal>. Neste último caso, a recompilação é sempre feita
-            para cada arquivo <literal>.sci</literal>.
-        </para>
-        <para>
-            Quando todos os arquivos <literal>.sci</literal> tiverem sido
-            processados, <literal>genlib</literal> cria uma biblioteca nomeada
-            <literal>lib_name</literal> e a salva arquivo <literal>lib</literal> em
-            <literal>dir_name</literal>. Se a variável Scilab
-            <literal>lib_name</literal> não estiver protegida (ver <link linkend="predef">predef</link>), esta variável é atualizada.
-        </para>
-        <para>
-            Se <literal>verb</literal> estiver ajustado para
-            <literal>%t</literal> informações são exibidas durante o processo de
-            construção.
-        </para>
-        <para>
-            Seo argumento <literal>dir_name</literal> não for fornecido e se a
-            variável Scilab <literal>lib_name</literal> existe e é uma variável
-            dir_name é tomado como sendo igual a o endereço de bibilioteca
-            <literal>lib_name</literal> (modo de atualização).
-        </para>
-    </refsection>
-    <refsection>
-        <title>Restrições</title>
-        <para>
-            Scilab assume implicitamente que <literal>foo.sci</literal> define
-            pelo menos uma função de nome <literal>foo</literal>. Se funções
-            subsidiárias estiverem inlusas, elas são tornadas conhecidas ao Scilab
-            apenas depois que função <literal>foo</literal> tiver sido
-            referencida.
-        </para>
-    </refsection>
-    <refsection role="see also">
-        <title>Ver Também</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="getd">getd</link>
-            </member>
-            <member>
-                <link linkend="exec">exec</link>
-            </member>
-            <member>
-                <link linkend="save">save</link>
-            </member>
-            <member>
-                <link linkend="lib">lib</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>
diff --git a/scilab/modules/functions/help/ru_RU/libraries/genlib.xml b/scilab/modules/functions/help/ru_RU/libraries/genlib.xml
new file mode 100644 (file)
index 0000000..ed54f63
--- /dev/null
@@ -0,0 +1,281 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) ????-2008 - INRIA
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2021 - 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:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:lang="ru" xml:id="genlib">
+    <refnamediv>
+        <refname>genlib</refname>
+        <refpurpose>
+            строит библиотеку из набора *.sci-файлов, определяющих функции в указанной директории
+        </refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Синтаксис</title>
+        <synopsis>
+            genlib(lib_name)
+            genlib(lib_name, dir_name)
+            genlib(lib_name, dir_name, Force)
+            genlib(lib_name, dir_name, Force, verb)
+            genlib(lib_name [,path=dir_name] [,verbose=verb] [,force=Force])
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Аргументы</title>
+        <variablelist>
+            <varlistentry>
+                <term>lib_name</term>
+                <listitem>
+                    Scilab-строка: идентифицирующее имя присваиваемое библиотеку,
+                    которую нужно построить.
+                    <para/>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>dir_name</term>
+                <listitem>
+                    Scilab-строка: путь к директории, содержащей файлы
+                    <literal>.sci</literal>-функций, и где генерируется файл
+                    <literal>lib</literal> и определяющая, где будет храниться
+                    библиотека. По умолчанию рассматривается текущая рабочая директория.
+                    <warning>
+                        Директория <varname>dir_name</varname> directory и её <literal>lib</literal>-
+                        и <literal>.bin</literal>-файлы должны иметь право на запись.
+                    </warning>
+                    <para/>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>Force</term>
+                <listitem>
+                    логическое значение (значение по умолчанию <literal>%f</literal>). Установите
+                    его в <literal>%t</literal>, чтобы принудить к рекомпиляции sci-файлов.
+                    <para/>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>verb</term>
+                <listitem>
+                    логическое значение (значение по умолчанию <literal>%f</literal>).
+                    Установите его в <literal>%t</literal>, чтобы отобразить больше
+                    информации во время сборки.
+                    <para/>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Описание</title>
+        <para>
+            <literal>genlib(..)</literal> выбирает все файлы, принадлежащие директории
+            <varname>dir_name</varname> и с расширением <literal>.sci</literal>.
+            Поддиректории, если они есть, никогда не рассматриваются. Если требуется,
+            они должны компилироваться отдельно в независимые библиотеки.
+        </para>
+        <para>
+            Затем создаётся редактируемый XML-файл <literal>lib</literal> в директории
+            <varname>dir_name</varname>. Имя <varname>lib_name</varname> библиотеки
+            записывается в него.
+        </para>
+        <para>
+            Далее, для каждого <literal>.sci</literal>-файла:
+            <itemizedlist>
+                <listitem>
+                    Если
+                    <itemizedlist>
+                        <listitem>
+                            нет связанного <literal>.bin</literal>-файла в <varname>dir_name</varname>
+                            с тем же базовым именем (что и для исходной сборки библиотеки), либо
+                        </listitem>
+                        <listitem>
+                            содержимое <literal>.sci</literal>-файла было изменено
+                            со времени предыдущей сборки,
+                        </listitem>
+                    </itemizedlist>
+                    <para/>
+                    <para>
+                        <literal>.sci</literal>-файл скомпилирован (<emphasis>почти</emphasis>
+                        как если бы это было с <literal>exec(..)</literal>):
+                        <itemizedlist>
+                            <listitem>
+                                <para>
+                                    если он содержит по крайней мере один блок
+                                    <literal>function .. endfunction</literal>, то
+                                    двоичный <literal>.bin</literal>-файл с тем же базовым именем
+                                    генерируется и хранится в <varname>dir_name</varname>.
+                                    Он содержит бинарный код ВСЕХ функций, определённых в
+                                    <literal>.sci</literal>-файле исходного кода.
+                                    <itemizedlist>
+                                        <listitem>
+                                            Если имя одной из функций, определённой в файле,
+                                            является базовым именем <literal>.sci</literal>-файла,
+                                            то эта функция записывается в <literal>lib</literal>-файл.
+                                            <para/>
+                                        </listitem>
+                                        <listitem>
+                                            В противном случае, ни одна функция из <literal>.sci</literal>-файла не записывается: всё
+                                            её содержимое рассматривается как мёртвый код.
+                                        </listitem>
+                                    </itemizedlist>
+                                </para>
+                                <para>
+                                    <warning>
+                                        Если файл <literal>test.sci</literal> определяет функцию
+                                        <literal>test()</literal> И другие функции, такие как
+                                        sub(), то функции sub() тогда рассматриваются как приватные для test(). Например,
+                                        <table>
+                                            <tr>
+                                                <td>
+                                                    <screen>
+function r = sub(a)
+    r = 2*a
+endfunction
+
+function test()
+    disp("A test")
+endfunction
+
+function r = other(b)
+    r = 2^b
+endfunction
+</screen>
+                                                </td>
+                                                <td>
+                                                    эквивалентно
+                                                </td>
+                                                <td>
+                                                    <screen>
+function test()
+    function r = sub(a)
+        r = 2*a
+    endfunction
+    function r = other(b)
+        r = 2^b
+    endfunction
+
+    disp("A test")
+endfunction
+</screen>
+                                                </td>
+                                            </tr>
+                                        </table>
+                                        Следовательно, sub() и other() не существуют вне test() и
+                                        не будут записаны в библиотеку.
+                                    </warning>
+                                </para>
+                            </listitem>
+                            <listitem>
+                                В противном случае, <literal>.bin</literal>-файл не будет
+                                генерироваться: всё содержимое <literal>.sci</literal>-файла
+                                рассматривается как мёртвый код.
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                </listitem>
+                <listitem>
+                    В противном случае: если содержимое файла не изменилось и уже имеет
+                    содержимое функции в <literal>lib</literal>-файле, то это содержимое
+                    сохраняется.
+                </listitem>
+            </itemizedlist>
+        </para>
+        <para>
+            Наконец, <literal>genlib(..)</literal> загружает созданную или обновлённую
+            библиотеку и устанавливает её идентификатор в переменную, названную
+            <varname>lib_name</varname>, в текущей области просмотра. Если переменная
+            <varname>lib_name</varname> уже существует и защищена,то возникает ошибка:
+            библиотека была создана, но не может быть загружена
+            (<link linkend="predef">predef all</link> может использоваться для снятия
+            защиты с переменной, названной <varname>lib_name</varname> перед запуском
+            <literal>genlib(..)</literal>).
+        </para>
+        <para>
+            Если используется опция <literal>force=%t</literal>, то все
+            <literal>.sci</literal>-файлы компилируются, даже если их содержимое не
+            было изменено.
+        </para>
+        <para>
+            Когда из директории библиотеки некоторые старые .sci-файлы были удалены
+            и при этом оставшиеся .sci-файлы остались неизменными, то пересборка
+            библиотеки без <literal>force=%t</literal> в любом случае обновит
+            список членов библиотеки.
+        </para>
+        <para>
+            Если включена опция <literal>verbose</literal>, то во время сборки
+            отображается больше информации.
+        </para>
+    </refsection>
+    <refsection role="see also">
+        <title>Смотрите также</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="library">library</link>
+            </member>
+            <member>
+                <link linkend="load">load</link>
+            </member>
+            <member>
+                <link linkend="getd">getd</link>
+            </member>
+            <member>
+                <link linkend="lib">lib</link>
+            </member>
+        </simplelist>
+    </refsection>
+    <refsection role="history">
+        <title>История</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0.0</revnumber>
+                <revdescription>
+                    <itemizedlist>
+                        <listitem>
+                            Больше не требуется файл <literal>names</literal>.
+                            Опция <literal>Names</literal> удалена.
+                        </listitem>
+                        <listitem>
+                            Если .sci-файл содержит функции, названные не в соответствии с именем
+                            файла, то они теперь не являются публичными: их можно увидеть и
+                            вызвать только из главной функции.
+                        </listitem>
+                        <listitem>
+                            Если библиотека с именем <varname>lib_name</varname> уже загружена,
+                            то директорией по умолчанию <varname>dir_name</varname> теперь
+                            является не её директория (режим обновления), а текущая рабочая
+                            директория.
+                        </listitem>
+                        <listitem>
+                            Сгенерированный <literal>lib</literal>-файл теперь является
+                            XML-файлом, который может прочитать человек, а не двоичный файл.
+                        </listitem>
+                        <listitem>
+                            genlib() теперь не может записать какую-либо переменную в
+                            качестве полноправного члена библиотеки.
+                        </listitem>
+                        <listitem>
+                            По умолчанию любой .sci-файл теперь перекомпилируется,
+                            если его содержимое было изменено, а не, если дата его изменения
+                            новее, чем дата .bin-файла.
+                        </listitem>
+                        <listitem>
+                            Генерируемые <literal>.bin</literal>-файлы более не могут
+                            быть загружены независимо с помощью load().
+                        </listitem>
+                    </itemizedlist>
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/functions/help/ru_RU/libraries/library.xml b/scilab/modules/functions/help/ru_RU/libraries/library.xml
new file mode 100644 (file)
index 0000000..7363c5e
--- /dev/null
@@ -0,0 +1,325 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) ????-2008 - INRIA
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2021 - 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:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:lang="ru" xml:id="library">
+    <refnamediv>
+        <refname>library</refname>
+        <refpurpose>тип данных библиотеки</refpurpose>
+    </refnamediv>
+    <refsection>
+        <title>Описание</title>
+        <para>
+            <emphasis role="bold">
+                Из чего сделана библиотека функций, написанных на языке Scilab?
+            </emphasis>
+        </para>
+        <para>
+            Такая библиотека сделана из директории, содержащей
+            <itemizedlist>
+                <listitem>
+                    редактируемый XML-файл, который всегда называется <literal>lib</literal>.
+                    Этот файл содержит
+                    <orderedlist>
+                        <listitem>
+                            имя библиотеки;
+                        </listitem>
+                        <listitem>
+                            список имён публичных функций, принадлежащих библиотеке.
+                        </listitem>
+                    </orderedlist>
+                    Этот файл сгенерирован с помощью <literal>genlib(..)</literal>.
+                    Его нельзя сделать вручную.
+                    <para/>
+                </listitem>
+                <listitem>
+                    набор двоичных файлов с расширением <literal>.bin</literal>,
+                    чьи основные имена являются именами функций возможно зарегистрированных
+                    в файле <literal>lib</literal>,
+                    <para/>
+                </listitem>
+                <listitem>
+                    и возможно -- но это необязательно для загрузки и использования
+                    библиотеки --, <literal>.sci</literal>-файлы исходников, написанные
+                    на языке Scilab, чья компиляция с помощью <code>genlib(..)</code>
+                    генерирует файлы <literal>lib</literal> и <literal>.bin</literal>.
+                    <para/>
+                    <warning>
+                        Если файл-исходник <literal>foo.sci</literal> функции
+                        <literal>foo()</literal> не предоставлен в директории библиотеки,
+                        то <literal>edit foo</literal> не может править его Scilab-код
+                        и откроет пустой файл с нуля.
+                    </warning>
+                    <para/>
+                </listitem>
+            </itemizedlist>
+        </para>
+        <para>
+            <emphasis role="bold">
+                Загрузка / декларирование библиотеки в сессии
+            </emphasis>:
+        </para>
+        <para>
+            <literal>load("/path/to/lib")</literal> загружает предназначенную библиотеку
+            в сессию Scilab: создаётся переменная, чьё имя является именем библиотеки
+            -- скажем <literal>libname</literal>. Относящийся к ней тип
+            <literal>type(libname)</literal> равен 14. Её <literal>typeof(libname)</literal>
+            соответствует <literal>"library"</literal>. Этот дескриптор библиотеки содержит
+            <itemizedlist>
+                <listitem>
+                    путь к корневой директории библиотеки;
+                </listitem>
+                <listitem>
+                    список имён публичных функций, принадлежащих библиотеке.
+                </listitem>
+            </itemizedlist>
+        </para>
+        <para>
+            Обе части могут быть получены либо с помощью функции <literal>libraryinfo()</literal>,
+            либо с помощью функции <literal>string()</literal>.
+        </para>
+        <para>
+            Пример: <literal>interpolationlib</literal> является родной библиотекой Scilab:
+            <screen>
+--> interpolationlib
+ interpolationlib  =
+
+Functions files location : SCI\modules\interpolation\macros\.
+interp1  mesh2d  interpln  smooth
+
+--> type(interpolationlib)
+ ans  =
+   14.
+
+--> [typeof(interpolationlib), typeof(interpolationlib, "overload")]
+ ans  =
+  "library"  "f"
+
+--> string(interpolationlib)
+ ans  =
+  "SCI\modules\interpolation\macros\"
+  "interp1"
+  "mesh2d"
+  "interpln"
+  "smooth"
+
+--> [fnames, libpath] = libraryinfo("interpolationlib")
+ fnames  =
+  "interp1"
+  "mesh2d"
+  "interpln"
+  "smooth"
+
+ libpath  =
+  "SCI\modules\interpolation\macros\"
+</screen>
+        </para>
+        <para>
+            <emphasis role="bold">Автозагрузка при первом вызове функции</emphasis>:
+        </para>
+        <para>
+            Если имя функции -- скажем, <literal>foo()</literal> -- принадлежащей
+            библиотеке, вызвана в сессии, то Scilab делает следующее:
+            <orderedlist>
+                <listitem>
+                    Является ли <literal>foo</literal> именем встроенной функции?
+                    Если так, то эта встроенная функция вызывается. В противном
+                    случае,
+                    <para/>
+                </listitem>
+                <listitem>
+                    Является ли <literal>foo</literal> именем локальной переменной,
+                    возможно требуемой <literal>foo()</literal> (предполагая, что
+                    она уже была вызвана)? Если так, то используется эта переменная.
+                    В противном случае,
+                    <para/>
+                </listitem>
+                <listitem>
+                    Сканируются все загруженные библиотеки -- в обратном алфавитному порядку имён
+                    библиотек -- для поиска <literal>foo()</literal>. Первая найденная
+                    "загружается" из её <literal>.bin</literal>-файла и, наконец, вызывается.
+                    Следующие вызовы <literal>foo()</literal> будут переходить к шагу №2,
+                    который будет успешным, пока дескриптор <literal>foo</literal> не
+                    будет удалён по ходу дела.
+                    <para/>
+                </listitem>
+            </orderedlist>
+        </para>
+        <para>
+            Без шага №3 пользовательская функция, не принадлежащая ни к одной библиотеке
+            и поэтому в случае удаления не может быть автоматически восстановлена.
+        </para>
+        <para>
+            <warning>
+                Если файл<literal>foo.sci</literal> изменён, когда <literal>foo()</literal>
+                уже была вызвана, то перекомпиляция и перегрузка её библиотеки не обновит
+                текущее поведение <literal>foo()</literal>: <literal>foo()</literal>,
+                является уже известной, поэтому Scilab остановится на шаге №2 без
+                перегрузки обновлённой библиотеки и будет использовать прежнюю
+                <literal>foo()</literal>. Введение <literal>clear foo</literal> перед
+                следующим вызовом <literal>foo()</literal> заставит Scilab перейти
+                к шагу №3 во время следующего вызова и таким образом загрузит и будет
+                использовать обновлённую <literal>foo()</literal>.
+            </warning>
+        </para>
+        <para>
+            <emphasis role="bold">Одноимённые функции в разных библиотеках: libname.foo()</emphasis>
+        </para>
+        <para>
+            Если несколько загруженных библиотек имеют публичную функцию
+            <literal>foo()</literal>, то обратный алфавитный приоритет может быть
+            неуместным. К счастью, всегда можно заставить использовать содержимое
+            указанной библиотеки с помощью синтаксиса разделения точкой:
+            <literal>libname.foo(..)</literal> будет вызывать содержимое
+            <literal>foo()</literal>, принадлежащее библиотеке <literal>libname</literal>.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Примеры</title>
+        <para>
+            <literal>interpolationlib</literal> является родной библиотекой Scilab:
+        </para>
+        <programlisting role="example"><![CDATA[
+interpolationlib        //отображает содержимое библиотеки
+type(interpolationlib)
+[typeof(interpolationlib), typeof(interpolationlib, "overload")]
+string(interpolationlib)
+[fnames, libpath] = libraryinfo("interpolationlib")
+     ]]></programlisting>
+        <para>
+            Вывод иллюстрируется в разделе Описание выше.
+        </para>
+        <para/>
+        <para>
+            Вызовы обработки одноимённых функций:
+        </para>
+        <programlisting role="example"><![CDATA[
+whereis(blanks)
+clear blanks, isdef("blanks","l")
+blanks(20)          // загрузка blanks() и её вызов
+isdef("blanks","l") // она остаётся в workspace
+
+// Построение библиотеки с нашей собственной одноимённой функцией blanks()
+libDir = fullfile(TMPDIR, "mylib");
+code = ["function r = blanks(n, nbsp)"
+        "    if nbsp, r = part(ascii(160),ones(1,n)),"
+        "    else r = ""ABC"","
+        "    end"
+        "endfunction" ];
+mkdir(libDir);
+mputl(code, libDir + filesep() + "blanks.sci");
+genlib("mylib", libDir);    // Компиляция нашей собственной библиотеки
+
+clear blanks
+ascii(blanks(3)) // вызывается stringlib.blanks() ⇐ "stringlib" > "mylib"
+clear blanks
+ascii(mylib.blanks(3,%t)) // принудительный вызов mylib.blanks()
+blanks(3)        // следующий вызов по умолчанию stringlib.blanks()
+     ]]></programlisting>
+        <screen><![CDATA[
+--> whereis(blanks)
+ ans  =
+  "stringlib"
+
+--> clear blanks, isdef("blanks","l")
+ ans  =
+  F
+
+--> blanks(20)          // loads blanks() and calls it
+ ans  =
+  "                    "
+--> isdef("blanks","l") // It stays in the workspace
+ ans  =
+  T
+
+--> // Building a library with our own homonymous blanks() function
+--> libDir = fullfile(TMPDIR, "mylib");
+--> code = ["function r = blanks(n, nbsp)"
+  >         "    if nbsp, r = part(ascii(160),ones(1,n)),"
+  >         "    else r = ""ABC"","
+  >         "    end"
+  >         "endfunction" ];
+--> mkdir(libDir);
+--> mputl(code, libDir + filesep() + "blanks.sci");
+--> genlib("mylib", libDir);    // Compiling our own library
+
+--> clear blanks
+--> ascii(blanks(3)) // stringlib.blanks() is called ⇐ "stringlib" > "mylib"
+ ans  =
+   32.   32.   32.
+
+--> clear blanks
+--> ascii(mylib.blanks(3,%t)) // forced call to mylib.blanks()
+ ans  =
+   194.   160.   194.   160.   194.   160.
+
+--> blanks(3)        // Next call is with the default stringlib.blanks()
+ ans  =
+  "   "
+]]></screen>
+    </refsection>
+    <refsection role="see also">
+        <title>Смотрите также</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="load">load</link>
+            </member>
+            <member>
+                <link linkend="lib">lib</link>
+            </member>
+            <member>
+                <link linkend="genlib">genlib</link>
+            </member>
+            <member>
+                <link linkend="libraryinfo">libraryinfo</link>
+            </member>
+            <member>
+                <link linkend="string">string</link>
+            </member>
+            <member>
+                <link linkend="whereis">whereis</link>
+            </member>
+            <member>
+                <link linkend="librarieslist">librarieslist</link>
+            </member>
+        </simplelist>
+    </refsection>
+    <refsection role="history">
+        <title>История</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0.0</revnumber>
+                <revdescription>
+                    <itemizedlist>
+                        <listitem>
+                            Библиотека теперь содержать только функции, а не переменные
+                            любого типа.
+                        </listitem>
+                        <listitem>
+                            Файл lib теперь является редактируемым XML-файлом, а не бинарным.
+                        </listitem>
+                        <listitem>
+                            Если файл исходного кода foo.sci содержит несколько последовательных
+                            блоков function/endfunction, то только определённая foo() теперь
+                            записывается в библиотеку. Остальные определённые функции теперь
+                            являются приватными и известными только из foo().
+                        </listitem>
+                    </itemizedlist>
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
+</refentry>