[doc] realtime() page improved 13/20613/3
Samuel GOUGEON [Sun, 11 Nov 2018 01:03:21 +0000 (02:03 +0100)]
  http://bugzilla.scilab.org/12545

Change-Id: I61e0daccc4a0eea5d83f9a8483e8317b74386138

scilab/modules/time/help/en_US/realtime.xml
scilab/modules/time/help/ja_JP/realtime.xml

index 6c7f5d7..214e586 100644 (file)
@@ -2,8 +2,8 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) INRIA -
- *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2018 - 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="realtime">
+<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="realtime">
     <refnamediv xml:id="realtimeinit">
         <refname>realtimeinit</refname>
-        <refpurpose>set  time unit</refpurpose>
+        <refpurpose>sets the time unit</refpurpose>
     </refnamediv>
     <refnamediv>
         <refname>realtime</refname>
-        <refpurpose>set  dates origin or waits until date</refpurpose>
+        <refpurpose>sets the initial datetime and starts the chronometer, or waits until a given datetime</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>realtimeinit(time_unit)
+        <synopsis>
+            realtimeinit(time_unit)
+            realtime(t0)
             realtime(t)
         </synopsis>
     </refsynopsisdiv>
                 <term>time_unit</term>
                 <listitem>
                     <para>
-                        a real number. The number of seconds associated to the <literal>realtime</literal> argument
+                        positive decimal number: time unit duration, in seconds.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>t0</term>
+                <listitem>
+                    <para>
+                       decimal number: initial datetime, in <literal>time_unit</literal>.
+                       This meaning holds when <literal>realtime(…)</literal> is called for the
+                       first time after the last <literal>realtimeinit(…)</literal>.
+                       This first call sets the datetime origin and restarts the real timer.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>t</term>
                 <listitem>
-                    <para>a real number.  A date</para>
+                    <para>decimal number: datetime up to which Scilab must wait before performing
+                    the next instruction, expressed in time unit.
+                    </para>
                 </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
     <refsection>
         <title>Description</title>
-        <para>   These two functions can be used to handle real time into Scilab.</para>
         <para>
-            <literal>realtimeinit(time_unit)</literal>  defines the time unit
-            associated to the <literal>realtime</literal> argument <literal>t</literal>
+            While <literal>sleep(d)</literal> waits for a given fixed duration,
+            <literal>realtime(t)</literal> will wait the required (unknown) time to reach the
+            given datetime <varname>t</varname>.
         </para>
         <para>
-            first call to <literal>realtime(t0)</literal> sets current date to
-            (<literal>t0</literal>).
-            subsequent calls to <literal>realtime(t)</literal> wait till date <literal>t</literal> is
-            reached.
+            <literal>realtimeinit(time_unit)</literal>  defines the time unit in which the
+            datetime <varname>t</varname> specified by <literal>realtime</literal> is expressed.
+        </para>
+        <para>
+            After calling <literal>realtimeinit(time_unit)</literal>, the first call to
+            <literal>realtime(t0)</literal> sets the current datetime to <literal>t0</literal>,
+            without any wait. Each new call to <literal>realtime(t)</literal> then waits till
+            datetime <varname>t</varname> is reached. If <varname>t</varname> is already passed,
+            no wait is added.
         </para>
     </refsection>
     <refsection>
         <title>Examples</title>
+        <para>
+        In the following example, in a loop, a job takes an arbitrary time, from
+        0 to 1.50 s. This is simulated with a sleep() of random duration. Although this period
+        is not regular, realtime() is used to compensate and print something every 2.00 seconds:
+        </para>
         <programlisting role="example"><![CDATA[
-realtimeinit(1/2);//sets time unit to half a second
-realtime(0);//sets current date to 0
-for k=1:10
-  realtime(k);
-  mprintf('current time is '+string(k/2)+'sec .\r\n');
-end
-
-//next instruction outputs a dot each 2 seconds
-realtimeinit(2);
+clc
+tic();
+realtimeinit(2.00);
 realtime(0);
-for k=1:10
-  realtime(k);
-  mprintf('.\r\n');
+for k = 1:10
+    if k==1, mprintf("\nSleep for  Wake-up at   Wait until date\n"), end
+    d = rand(1,1);
+    sleep(d*1500);
+    mprintf(' %4.2f s     %5.2f s', d*1.5, toc());
+    realtime(k);
+    mprintf('      %5.2f s\n', toc());
 end
-
-realtimeinit(1);
-realtime(0);
-dt=getdate('s');
-realtime(10);
-getdate('s')-dt
  ]]></programlisting>
+    <screen><![CDATA[
+Sleep for  Wake-up at   Wait until date
+ 0.28 s      0.57 s       2.08 s
+ 0.03 s      2.11 s       4.08 s
+ 1.27 s      5.34 s       6.08 s
+ 0.11 s      6.19 s       8.08 s
+ 1.28 s      9.36 s      10.08 s
+ 0.02 s     10.10 s      12.08 s
+ 0.28 s     12.36 s      14.08 s
+ 0.74 s     14.82 s      16.08 s
+ 1.12 s     17.20 s      18.08 s
+ 1.41 s     19.49 s      20.08 s
+]]></screen>
     </refsection>
-    <programlisting role="example"><![CDATA[
-realtimeinit(1);
-realtime(0);
-t1 = now()
-datevec(t1)
-realtime(10);
-t1 = now()
-datevec(t1)
- ]]></programlisting>
-
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
+                <link linkend="sleep">sleep</link>
+            </member>
+            <member>
                 <link linkend="getdate">getdate</link>
             </member>
+            <member>
+                <link linkend="waitbar">waitbar</link>
+            </member>
+            <member>
+                <link linkend="progressionbar">progressionbar</link>
+            </member>
         </simplelist>
     </refsection>
 </refentry>
index bd4fe50..04d3d81 100644 (file)
@@ -2,8 +2,8 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) INRIA -
- *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2018 - 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="ja" xml:id="realtime">
+<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="realtime">
     <refnamediv xml:id="realtimeinit">
         <refname>realtimeinit</refname>
         <refpurpose>時間の単位を設定</refpurpose>
@@ -24,7 +27,9 @@
     </refnamediv>
     <refsynopsisdiv>
         <title>呼び出し手順</title>
-        <synopsis>realtimeinit(time_unit)
+        <synopsis>
+            realtimeinit(time_unit)
+            realtime(t0)
             realtime(t)
         </synopsis>
     </refsynopsisdiv>
                 </listitem>
             </varlistentry>
             <varlistentry>
+                <term>t0</term>
+                <listitem>
+                    <para>
+                       decimal number: initial datetime, in <literal>time_unit</literal>.
+                       This meaning holds when <literal>realtime(…)</literal> is called for the
+                       first time after the last <literal>realtimeinit(…)</literal>.
+                       This first call sets the datetime origin and restarts the real timer.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
                 <term>t</term>
                 <listitem>
                     <para>実数.  日付</para>
     </refsection>
     <refsection>
         <title>例</title>
+        <para>
+        In the following example, in a loop, a job takes an arbitrary time, from
+        0 to 1.50 s. This is simulated with a sleep() of random duration. Although this period
+        is not regular, realtime() is used to compensate and print something every 2.00 seconds:
+        </para>
         <programlisting role="example"><![CDATA[
-realtimeinit(1/2);//時間の単位を 0.5秒に設定s
-realtime(0);// カレントの時刻を 0に設定
-for k=1:10
-  realtime(k);
-  mprintf('current time is '+string(k/2)+'sec .\r\n');
-end
-//次の命令では2秒毎にドットを出力
-realtimeinit(2);
+clc
+tic();
+realtimeinit(2.00);
 realtime(0);
-for k=1:10
-  realtime(k);
-  mprintf('.\r\n');
+for k = 1:10
+    if k==1, mprintf("\nSleep for  Wake-up at   Wait until date\n"), end
+    d = rand(1,1);
+    sleep(d*1500);
+    mprintf(' %4.2f s     %5.2f s', d*1.5, toc());
+    realtime(k);
+    mprintf('      %5.2f s\n', toc());
 end
-realtimeinit(1);
-realtime(0);
-dt=getdate('s');
-realtime(10);
-getdate('s')-dt
- ]]></programlisting>
-        <programlisting role="example"><![CDATA[
-realtimeinit(1);
-realtime(0);
-t1 = now()
-datevec(t1)
-realtime(10);
-t1 = now()
-datevec(t1)
  ]]></programlisting>
+    <screen><![CDATA[
+Sleep for  Wake-up at   Wait until date
+ 0.28 s      0.57 s       2.08 s
+ 0.03 s      2.11 s       4.08 s
+ 1.27 s      5.34 s       6.08 s
+ 0.11 s      6.19 s       8.08 s
+ 1.28 s      9.36 s      10.08 s
+ 0.02 s     10.10 s      12.08 s
+ 0.28 s     12.36 s      14.08 s
+ 0.74 s     14.82 s      16.08 s
+ 1.12 s     17.20 s      18.08 s
+ 1.41 s     19.49 s      20.08 s
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>参照</title>
         <simplelist type="inline">
             <member>
+                <link linkend="sleep">sleep</link>
+            </member>
+            <member>
                 <link linkend="getdate">getdate</link>
             </member>
+            <member>
+                <link linkend="waitbar">waitbar</link>
+            </member>
+            <member>
+                <link linkend="progressionbar">progressionbar</link>
+            </member>
         </simplelist>
     </refsection>
 </refentry>