Revision of help page for GlobaProperty (en_US). 12/9812/2
Stanislav KROTER [Tue, 27 Nov 2012 11:06:52 +0000 (17:06 +0600)]
Change-Id: I55d39e99b117a8553410eb1a4de5d19e66bb0ede

scilab/modules/graphics/help/en_US/GlobalProperty.xml

index c51950b..d068d73 100644 (file)
@@ -6,46 +6,75 @@
  * This file must be used under the terms of the CeCILL.
  * This source file is licensed as described in the file COPYING, which
  * you should have received as part of this distribution.  The terms
- * are also available at    
+ * are also available at
  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
  *
  -->
 <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="GlobalProperty">
     <refnamediv>
         <refname>GlobalProperty</refname>
-        <refpurpose>to customize the objects appearance
-            (curves, surfaces...) in a plot or surf command.
+        <refpurpose>
+            to customize the objects appearance (curves, surfaces...) in a plot
+            or surf command
         </refpurpose>
     </refnamediv>
     <refsection>
         <title>Description</title>
         <para>
-            The GlobalProperty is an optional argument that can be used inside a <link linkend="plot">plot</link> or <link linkend="surf">surf</link> command. It allows a global customization of all the new plotted lines (respectivly surfaces). It has to be given as a couple {PropertyName, PropertyValue}. Several couples can be set at the same time in a plot or surf call.
+            The <literal>GlobalProperty</literal> is an optional argument
+            that can be used inside a <link linkend="plot">plot</link> or
+            <link linkend="surf">surf</link> command. It allows a global
+            customization of all the new plotted lines (respectively surfaces).
+            It has to be given as a couple
+            {<literal>PropertyName</literal>,
+            <literal>PropertyValue</literal>}. Several couples can be set
+            at the same time in a <function>plot</function> or
+            <function>surf</function> call.
         </para>
-        <para>PropertyName must be a string defining the property to set.The PropertyValue can be a real, integer or string (scalar or matrix) depending on the type of property used. For example, to specify a red (color) longdash-dot (line style) with diamond marker (marker), the sequence should be : 'Colo','red','LineSt','-.','Marker','diam'.</para>
-        <para>As you can see, a full complete spelling of each property name and value is not required but those arguments, specified in any order, must remain unambiguous. Furthermore, the string specification is not case sensitive. GlobalProperty is predominant on all LineSpec previously stated.</para>
         <para>
-            Here is a complete list of the <literal>PropertyName</literal> you can
-            specify (using <link linkend="plot">plot</link> or <link linkend="surf">surf</link>) and their available
-            associated <literal>PropertyValue</literal>. If not specified, those properties
-            are available for both <literal>Polyline</literal> and <literal>Fac3d</literal>
-            objects (created respectivly by plot or surf) and, as previously said,
-            they are applied to the new created objects (lines or surfaces).
+            <literal>PropertyName</literal> must be a string defining the
+            property to set. The <literal>PropertyValue</literal> can be a
+            real, integer or string (scalar or matrix) depending on the type of
+            property used. For example, to specify a red (color) longdash-dot
+            (line style) with diamond marker (marker), the sequence should be:
+            <literal>'Colo'</literal>, <literal>'red'</literal>, <literal>'LineSt'</literal>, <literal>'-.'</literal>, <literal>'Marker'</literal>, <literal>'diam'</literal>.
         </para>
-        <para>Sometimes, you may have two PropertyName corresponding to one property :
-            the first one is the equivalent default Matlab name, the second is the
-            default name used by Scilab (i.e.:<literal> Color or Foreground</literal> for a
-            line, see below).
+        <para>
+            As you can see, a full complete spelling of each property name and
+            value is not required but those arguments, specified in any order,
+            must remain unambiguous. Furthermore, the string specification is
+            not case sensitive. <literal>GlobalProperty</literal> is
+            predominant on all <literal>LineSpec</literal> previously stated.
+        </para>
+         
+        <para>
+            Here is a complete list of the <literal>PropertyName</literal> you
+            can specify (using <link linkend="plot">plot</link> or <link linkend="surf">surf</link>) and their available
+            associated <literal>PropertyValue</literal>. If not specified,
+            those properties are available for both <literal>Polyline</literal>
+            and <literal>Fac3d</literal> objects (created respectively by
+            <function>plot</function> or <function>surf</function>) and, as
+            previously said, they are applied to the new created objects (lines
+            or surfaces).
+        </para>
+        <para>
+            Sometimes, you may have two <literal>PropertyName</literal>
+            corresponding to one property: the first one is the equivalent
+            default Matlab name, the second is the default name used by Scilab
+            (i.e.: <literal>Color</literal> or <literal>Foreground</literal>
+            for a line, see below).
         </para>
         <variablelist>
             <varlistentry>
                 <term>CData or ColorData: </term>
                 <listitem>
-                    <para>a real matrix specifiying the color at every points defined by
-                        <literal>Z</literal> matrix. This property is linked to the object's
+                    <para>
+                        a real matrix specifying the color at every points
+                        defined by <literal>Z</literal> matrix. This property
+                        is linked to the object's
                         <literal>data.color</literal> property (see
-                        <link linkend="surface_properties">surface_properties</link>). Note that this property is available
-                        for surfaces only.
+                        <link linkend="surface_properties">surface properties</link>).
+                        Note that this property is available for surfaces only.
                     </para>
                 </listitem>
             </varlistentry>
                 <listitem>
                     <para>
                         a string with value <literal>'scaled'</literal> or
-                        <literal>'direct'</literal>. If a <literal>data.color</literal> is set, each index
-                        color data specifies a single value for each vertex.
-                        <literal>cdata_mapping</literal> determines wether those indices are scaled
-                        to map linearly into the current colormap (<literal>'scaled'</literal> mode)
-                        or point directly into this colormap (<literal>'direct</literal>' mode).
-                        This property is useful when <literal>color_flag</literal> equals
-                        <literal>2</literal>,<literal>3</literal> or <literal>4</literal>. Note that this
-                        property exists only with <literal>Fac3d</literal> entities. Note also that
-                        <literal>plot3d</literal> has <literal>'direct'</literal> mode by default and
-                        <literal>surf</literal> has<literal> 'scaled'</literal> mode by default.
+                        <literal>'direct'</literal>. If a <literal>data.color</literal>
+                        is set, each index color data specifies a single value
+                        for each vertex. <literal>cdata_mapping</literal>
+                        determines whether those indices are scaled
+                        to map linearly into the current colormap
+                        (<literal>'scaled'</literal> mode)
+                        or point directly into this colormap
+                        (<literal>'direct</literal>' mode).
+                        This property is useful when
+                        <literal>color_flag</literal> equals
+                        <literal>2</literal>, <literal>3</literal> or
+                        <literal>4</literal>.
+                        <note>
+                            Note that this property exists only with
+                            <literal>Fac3d</literal> entities. Note also that
+                            <function>plot3d</function> has
+                            <literal>'direct'</literal> mode by default and
+                            <function>surf</function> has <literal>'scaled'</literal> mode by default.
+                        </note>
                     </para>
                 </listitem>
             </varlistentry>
                 <listitem>
                     <para>
                         a string <literal>"on"</literal> or <literal>"off"</literal> defining the
-                        clipping mode (<literal>"on"</literal> by default). It is equivalent to the
-                        <literal>clip_state</literal> property. This field contains the
-                        <literal>visible</literal> property (see <link linkend="polyline_properties">polyline_properties</link>).
-                        Note that this property is not yet available for surface
-                        entities.
+                        clipping mode (<literal>"on"</literal> by default). It
+                        is equivalent to the <literal>clip_state</literal>
+                        property. This field contains the
+                        <literal>visible</literal> property (see <link linkend="polyline_properties">polyline properties</link>).
+                        <note>
+                            Note that this property is not yet available for
+                            surface entities.
+                        </note>
                     </para>
                 </listitem>
             </varlistentry>
                     <para>
                         a string defining a known color (see <link linkend="color_list">color_list</link>) or a
                         <literal>1</literal>x<literal>3</literal> (or <literal>3</literal>x<literal>1</literal>) RGB
-                        vector defining a color number. Color number is given as a 3-uple
-                        <literal>R</literal>, <literal>G</literal>, <literal>B</literal> corresponding
-                        respectively to red, green and blue intensity between 0 and 1. This
-                        property is linked to the object's <literal>foreground</literal> property
-                        (see <link linkend="polyline_properties">polyline_properties</link>). <literal>Warning</literal><literal>
-                            :
-                        </literal>
-                        Color is not available for surfaces objects. The
-                        <literal>Foreground</literal> property exists for surfaces objects but is
-                        linked to the Matlab <literal>EdgeColor</literal> property (see
-                        <link linkend="surface_properties">surface_properties</link>).
+                        vector defining a color number. Color number is given as
+                        a 3-uple <literal>R</literal>, <literal>G</literal>,
+                        <literal>B</literal> corresponding respectively to red,
+                        green and blue intensity between 0 and 1. This property
+                        is linked to the object's <literal>foreground</literal> property
+                        (see <link linkend="polyline_properties">polyline properties</link>).
+                        <warning>
+                            Color is not available for surfaces objects. The
+                            <literal>Foreground</literal> property exists for
+                            surfaces objects but is linked to the Matlab
+                            <literal>EdgeColor</literal> property (see
+                            <link linkend="surface_properties">surface properties</link>).
+                        </warning>
                     </para>
                 </listitem>
             </varlistentry>
                     <para>
                         a string defining a known color (see <link linkend="color_list">color_list</link>) or a
                         <literal>1</literal>x<literal>3</literal> (or <literal>3</literal>x<literal>1</literal>) RGB
-                        vector defining a color number. Color number is given as a 3-uple
-                        <literal>R</literal>, <literal>G</literal>, <literal>B</literal> corresponding
-                        respectively to red, green and blue intensity between 0 and 1. This
-                        property is linked to the surface <literal>foreground</literal> property
-                        (see <link linkend="surface_properties">surface_properties</link>). <literal>Warning</literal><literal>
-                            :
-                        </literal>
-                        For polyline objects, the <literal>Foreground</literal> property
-                        exists with a different meaning (see above) and <literal>EdgeColor</literal>
-                        does not exist at all.
+                        vector defining a color number. Color number is given as
+                        a 3-uple <literal>R</literal>, <literal>G</literal>,
+                        <literal>B</literal> corresponding respectively to red,
+                        green and blue intensity between 0 and 1. This property
+                        is linked to the surface <literal>foreground</literal>
+                        property (see <link linkend="surface_properties">surface
+                            properties
+                        </link>
+                        ).
+                        <warning>
+                            For <literal>polyline</literal> objects, the
+                            <literal>Foreground</literal> property
+                            exists with a different meaning (see above) and
+                            <literal>EdgeColor</literal> does not exist at all.
+                        </warning>
                     </para>
                 </listitem>
             </varlistentry>
                 <term>FaceColor: </term>
                 <listitem>
                     <para>
-                        a string with value <literal>'none'</literal>, <literal>'flat'</literal> or
-                        <literal>'interp'</literal> specifying the way the facet's color are
-                        rendered. When<literal> 'none'</literal> is selected, a mesh of the surface
-                        is drawn; if <literal>'flat'</literal> (deault mode) is set, the
-                        <literal>Fac3d</literal> <literal>color.data</literal> values determine one color
-                        per facet using the color of the first vertex of the facet. If the
-                        value is <literal>'interp'</literal>, an interpolated shading is done on the
-                        surface using <literal>color.data</literal> to determine a color at each
-                        vertex of each facet.
+                        a string with value <literal>'none'</literal>,
+                        <literal>'flat'</literal> or <literal>'interp'</literal>
+                        specifying the way the facet's color are rendered.
+                        When <literal>'none'</literal> is selected, a mesh of
+                        the surface is drawn; if <literal>'flat'</literal>
+                        (deault mode) is set, the <literal>Fac3d</literal>
+                        <literal>color.data</literal> values determine one color
+                        per facet using the color of the first vertex of the
+                        facet. If the value is <literal>'interp'</literal>, an
+                        interpolated shading is done on the surface using
+                        <literal>color.data</literal> to determine a color at each vertex of each facet.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>LineStyle: </term>
                 <listitem>
-                    <para>This property value should be a string defining a line style. This
-                        property is linked to tje object's <literal>line_style</literal> property
-                        (see <link linkend="polyline_properties">polyline_properties</link> or
-                        <link linkend="surface_properties">surface_properties</link>).
+                    <para>
+                        This property value should be a string defining a line
+                        style. This property is linked to the object's
+                        <literal>line_style</literal> property
+                        (see <link linkend="polyline_properties">polyline
+                            properties
+                        </link>
+                        or
+                        <link linkend="surface_properties">surface
+                            properties
+                        </link>
+                        ).
                     </para>
                     <para/>
                     <informaltable border="1">
             <varlistentry>
                 <term>Marker or MarkStyle: </term>
                 <listitem>
-                    <para>A string defining the marker type. Note that if you specify a
-                        marker wihtout a line style, both line (with default solid mode
-                        enabled) and marker are drawn.This property is linked to the object's
-                        <literal>mark_style</literal> and <literal>mark_mode</literal> properties (see
-                        <link linkend="polyline_properties">polyline_properties</link> or
-                        <link linkend="surface_properties">surface_properties</link>).
+                    <para>
+                        A string defining the marker type. Note that if you
+                        specify a marker without a line style, both line (with
+                        default solid mode enabled) and marker are drawn.This
+                        property is linked to the object's
+                        <literal>mark_style</literal> and
+                        <literal>mark_mode</literal> properties (see
+                        <link linkend="polyline_properties">polyline
+                            properties
+                        </link>
+                        or <link linkend="surface_properties">surface properties</link>).
                     </para>
                     <informaltable border="1">
                         <tr>
             <varlistentry>
                 <term>MarkerEdgeColor or MarkForeground: </term>
                 <listitem>
-                    <para>a string defining a known color (see color_list) or a
+                    <para>
+                        a string defining a known color (see <link
+                        linkend="color_list">color_list</link>) or a
                         <literal>1</literal>x<literal>3</literal> (or <literal>3</literal>x<literal>1</literal>) RGB
                         vector defining a color number. Color number is given as a 3-uple
                         <literal>R</literal>, <literal>G</literal>, <literal>B</literal> corresponding
                         respectively to red, green and blue intensity between 0 and 1. This
                         property is linked to the object's <literal>mark_foreground</literal>
-                        property (see <link linkend="polyline_properties">polyline_properties</link> or
-                        <link linkend="surface_properties">surface_properties</link>).
+                        property (see <link linkend="polyline_properties">polyline properties</link> or
+                        <link linkend="surface_properties">surface properties</link>).
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>MarkerFaceColor or MarkBackground: </term>
                 <listitem>
-                    <para>a string defining a known color (see color_list) or a
-                        <literal>1</literal>x<literal>3</literal> (or <literal>3</literal>x<literal>1</literal>) RGB
-                        vector defining a color number. Color number is given as a 3-uple
-                        <literal>R</literal>, <literal>G</literal>, <literal>B</literal> corresponding
-                        respectively to red, green and blue intensity between 0 and 1. This
+                    <para>
+                        a string defining a known color (see <link
+                        linkend="color_list">color_list</link>) or a
+                        <literal>1</literal>x<literal>3</literal> (or
+                        <literal>3</literal>x<literal>1</literal>) RGB
+                        vector defining a color number. Color number is given as
+                        a 3-uple <literal>R</literal>, <literal>G</literal>,
+                        <literal>B</literal> corresponding respectively to red,
+                        green and blue intensity between 0 and 1. This
                         property is linked to the object's <literal>mark_background</literal>
-                        property (see <link linkend="polyline_properties">polyline_properties</link> or
-                        <link linkend="surface_properties">surface_properties</link>).
+                        property (see <link linkend="polyline_properties">polyline properties</link>
+                        or <link linkend="surface_properties">surface properties</link>).
                     </para>
                 </listitem>
             </varlistentry>
                         a scalar defining the marker size in <literal>point</literal> unit. This
                         property is linked to the object's <literal>mark_size</literal> property
                         with <literal>mark_size_unit</literal> enabled to <literal>"point"</literal> (see
-                        <link linkend="polyline_properties">polyline_properties</link> or
-                        <link linkend="surface_properties">surface_properties</link>).
+                        <link linkend="polyline_properties">polyline properties</link> or
+                        <link linkend="surface_properties">surface properties</link>).
                     </para>
                 </listitem>
             </varlistentry>
                 <listitem>
                     <para>
                         a string <literal>"on"</literal> or <literal>"off"</literal> defining the
-                        visibility mode (<literal>"on"</literal> by default). This property is
-                        linked to the object's <literal>visible</literal> property (see
-                        <link linkend="polyline_properties">polyline_properties</link> or
-                        <link linkend="surface_properties">surface_properties</link>).
+                        visibility mode (<literal>"on"</literal> by default).
+                        This property is linked to the object's
+                        <literal>visible</literal> property (see
+                        <link linkend="polyline_properties">polyline properties</link> or
+                        <link linkend="surface_properties">surface properties</link>).
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>X data: </term>
                 <listitem>
-                    <para>a real vector or matrix (re-)defining the given data for all the
-                        plotted lines or surfaces. Concerning dimensions, note that this new
-                        data must match all the previous specified <literal>X</literal> data : that
-                        is to say all those data matrices must be of the same dimensions. This
-                        property is linked to the object's <literal>data.x</literal> property (see
-                        <link linkend="polyline_properties">polyline_properties</link> or
-                        <link linkend="surface_properties">surface_properties</link>).
+                    <para>
+                        a real vector or matrix (re-)defining the given data for
+                        all the plotted lines or surfaces. Concerning
+                        dimensions, note that this new data must match all the
+                        previous specified <literal>X</literal> data: that
+                        is to say all those data matrices must be of the same
+                        dimensions. This property is linked to the object's
+                        <literal>data.x</literal> property (see
+                        <link linkend="polyline_properties">polyline properties</link> or
+                        <link linkend="surface_properties">surface properties</link>).
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>Y data: </term>
                 <listitem>
-                    <para>a real vector or matrix (re-)defining the given data for all the
-                        plotted lines or surfaces. Concerning dimensions, note that this new
-                        data must match all the previous specified <literal>Y</literal> data : that
-                        is to say all those data matrices must be of the same dimensions. This
-                        property is linked to the object's <literal>data.y</literal> property (see
-                        <link linkend="polyline_properties">polyline_properties</link> or
-                        <link linkend="surface_properties">surface_properties</link>).
+                    <para>
+                        a real vector or matrix (re-)defining the given data for
+                        all the plotted lines or surfaces. Concerning
+                        dimensions, note that this new data must match all the
+                        previous specified <literal>Y</literal> data: that
+                        is to say all those data matrices must be of the same
+                        dimensions. This property is linked to the object's
+                        <literal>data.y</literal> property (see
+                        <link linkend="polyline_properties">polyline properties</link> or
+                        <link linkend="surface_properties">surface properties</link>).
                     </para>
                 </listitem>
             </varlistentry>
                 <term>Z data: </term>
                 <listitem>
                     <para>
-                        when used with <literal>plot</literal>, a real vector or matrix adding
-                        a
-                    </para>
-                    <para>
-                        <literal>Z</literal> data for all the plotted lines ; with
-                        <literal>surf</literal>, a real matrix (re-)defining the given data for all
-                        the surfaces. Concerning dimensions, note that this new data must
-                        match all the previous specified <literal>X</literal> and <literal>Y</literal>
-                        data. This property is linked to the object's <literal>data.z</literal>
-                        property (see <link linkend="polyline_properties">polyline_properties</link> or
-                        <link linkend="surface_properties">surface_properties</link>).
+                        when used with <function>plot</function>, a real vector
+                        or matrix adding a <literal>Z</literal> data for all the
+                        plotted lines; with <function>surf</function>, a real
+                        matrix (re-)defining the given data for all the
+                        surfaces. Concerning dimensions, note that this new data
+                        must match all the previous specified
+                        <literal>X</literal> and <literal>Y</literal>
+                        data. This property is linked to the object's
+                        <literal>data.z</literal> property (see <link
+                        linkend="polyline_properties">polyline properties</link>
+                        or <link linkend="surface_properties">surface properties</link>).
                     </para>
                 </listitem>
             </varlistentry>
@@ -489,10 +565,10 @@ surf(Z,'edgeco','b','marker','d','markersiz',9,'markerfac','k','xdata',-50:-41)
                 <link linkend="clf">clf</link>
             </member>
             <member>
-                <link linkend="polyline_properties">polyline_properties</link>
+                <link linkend="polyline_properties">polyline properties</link>
             </member>
             <member>
-                <link linkend="surface_properties">surface_properties</link>
+                <link linkend="surface_properties">surface properties</link>
             </member>
         </simplelist>
     </refsection>