* Bug 10723 fixed [doc]: subplot() page improved

[scilab.git] / scilab / modules / graphics / help / en_US / axes_operations / subplot.xml

diff --git a/scilab/modules/graphics/help/en_US/axes_operations/subplot.xml b/scilab/modules/graphics/help/en_US/axes_operations/subplot.xml
index 1bf9d44..4bd3cc4 100644 (file)
--- a/scilab/modules/graphics/help/en_US/axes_operations/subplot.xml
+++ b/scilab/modules/graphics/help/en_US/axes_operations/subplot.xml
@@ -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) 2019 - 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.
@@ -13,14 +13,18 @@
  * 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="subplot">
+<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="subplot">
     <refnamediv>
         <refname>subplot</refname>
-        <refpurpose>virtually grids the figure and sets the plotting area to a chosen cell</refpurpose>
+        <refpurpose>sets the current axes to a chosen cell of the current gridded figure</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>subplot(m,n,p)
+        <synopsis>
+            subplot(m,n,p)
             subplot(mnp)
         </synopsis>
     </refsynopsisdiv>
@@ -28,7 +32,7 @@
         <title>Arguments</title>
         <variablelist>
             <varlistentry>
-                <term>m,n,p</term>
+                <term>m, n, p</term>
                 <listitem>
                     <para>positive integers</para>
                 </listitem>
@@ -46,24 +50,39 @@
     <refsection>
         <title>Description</title>
         <para>
-            subplot(m,n,p) or subplot(mnp) breaks the graphics window
-            into an m-by-n matrix of sub-windows and selects the p-th sub-window
-            for drawing  the current plot.  The number of a sub-window into the
-            matrices is counted row by row ie the sub-window corresponding to element
-            (i,j) of the matrix has number (i-1)*n + j.
+            subplot(m,n,p) or subplot(mnp) virtually grids the graphics window into an m-by-n
+            matrix of sub-windows, and selects the p<superscript>th</superscript> sub-window
+            for receiving the forthcoming drawings.
+        </para>
+        <para>
+            Into the grid, cells are indexed along each row, starting from the top row.
+            Hence, for instance the last cell of the first row is the p = n<superscript>th</superscript>
+            one. The cell on the row #i and the column #j has the index <literal>p=(i-1)*n+j</literal>.
+        </para>
+        <para>
+            When the selected area matches exactly an existing axes, <literal>subplot(…)</literal>
+            just sets it as the current axes, and returns.
+        </para>
+        <para>
+            Otherwise, <literal>subplot(…)</literal> creates an empty axes covering the selected area,
+            ready to receive forthcoming plotting contents.
         </para>
     </refsection>
     <refsection>
         <title>Examples</title>
         <programlisting role="example"><![CDATA[
-subplot(221)
-plot2d()
-subplot(222)
-plot3d()
-subplot(2,2,3)
-param3d()
-subplot(2,2,4)
-hist3d()
+            clf
+            subplot(221)
+            plot2d()
+
+            subplot(222)
+            plot3d()
+
+            subplot(2,2,3)
+            param3d()
+
+            subplot(2,2,4)
+            hist3d()
  ]]></programlisting>
         <scilab:image>
             subplot(221)
@@ -75,21 +94,66 @@ hist3d()
             subplot(2,2,4)
             hist3d()
         </scilab:image>
+        <para/>
+        <para>
+            <emphasis role="bold">A more complex layout</emphasis>, but still gridable:
+        </para>
+        <programlisting role="example"><![CDATA[
+            clf
+            subplot(1,2,2)
+            Matplot1()
+            xtitle("Matplot1() example","","")
+
+            subplot(2,2,1)
+            histplot
+            delete(findobj("type","Legend"))
+
+            subplot(2,2,3)
+            title("Smaller plots:", "fontsize",3)
+
+            subplot(2,4,5)
+            polarplot()
+
+            subplot(2,4,6)
+            param3d()
+            xtitle("","","","")
+ ]]></programlisting>
+        <scilab:image>
+            clf
+            subplot(1,2,2)
+            Matplot1()
+            xtitle("Matplot1() example","","")
+
+            subplot(2,2,1)
+            histplot
+            delete(findobj("type","Legend"))
+
+            subplot(2,2,3)
+            title("Smaller plots:", "fontsize",3)
+
+            subplot(2,4,5)
+            polarplot()
+
+            subplot(2,4,6)
+            param3d()
+            xtitle("","","","")
+            gcf().axes_size = [670 400];
+        </scilab:image>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
-                <link linkend="plot2d">plot2d</link>
+                <link linkend="xsetech">xsetech</link>
             </member>
             <member>
-                <link linkend="plot3d">plot3d</link>
+                <link linkend="newaxes">newaxes</link>
             </member>
             <member>
-                <link linkend="xstring">xstring</link>
+                <link linkend="axes_properties">axes_properties</link>
             </member>
             <member>
-                <link linkend="xtitle">xtitle</link>
+                <link linkend="plotframe">plotframe</link>
             </member>
         </simplelist>
     </refsection>