[Kst] branches/work/kst/newdocs/doc/kst

[Duncan Hanson]

SVN commit 648315 by dhanson:

docs for static vectors/matrices.

 M  +52 -68    data-chapter.docbook  
 M  +1 -0      views-chapter.docbook  


--- branches/work/kst/newdocs/doc/kst/data-chapter.docbook #648314:648315
@@ -169,19 +169,17 @@
 <para>
 As vectors can potentially be quite large, it is a good idea to be aware of the amount of memory &kst; has
 allocated for use.  The current available memory is displayed in the lower right corner of the status bar
-of the main &kst; window.
+of the main &kst; window. If the status bar is not available, ensure that <guimenuitem>Show Statusbar</guimenuitem> is checked in the <guimenu>Settings</guimenu> menu.
 </para>
 
-<tip>
 <para>
-If the status bar is not available, ensure that <guimenuitem>Show Statusbar</guimenuitem> is checked
-in the <guimenu>Settings</guimenu> menu.
+There are two kinds of vector- <link linkend="data-types-vectors-data">data vectors</link> and <link linkend="data-types-vectors-static">static vectors</link>. Data vectors are read into &kst; through a data source. Static vectors, on the other hand, are generated by &kst;. They represent an evenly spaced list of numbers, and can be useful e.g. for generating an x-axis for a plot.
 </para>
-</tip>
 
+<sect3 id="data-types-vectors-data">
+<title>Data Vectors</title>
 <para>
-The following is a screenshot of the window displayed when creating or editing vectors.  Explanations of the
-settings are listed below.
+The following is a screenshot of the window displayed when editing data vectors. A new data vector is created if you choose the <guibutton>Read from data source</guibutton> radio button in the New Vector dialog. Explanations of the settings are listed below.
 </para>
 
 <screenshot>
@@ -247,7 +245,31 @@
 </listitem>
 </varlistentry>
 </variablelist>
+</sect3>
 
+<sect3 id="data-types-vectors-static">
+<title>Static Vectors</title>
+<para>
+The following is a screenshot of the window displayed when editing static vectors. A new static vector is created if you choose the <guibutton>Generate</guibutton> radio button in the New Vector dialog. Explanations of the settings for static vectors are listed below.
+</para>
+
+<screenshot>
+<screeninfo>Edit Static Vectors</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-data-staticvectoredit.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>Edit Vectors</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>
+The entries of the vector will be From + (To - From)/(#samples - 1)*(i-1) for i = 1,...,#samples.
+</para>
+</sect3>
+
 </sect2>
 
 <sect2 id="data-types-curves">
@@ -862,9 +884,6 @@
 <title>Matrix</title>
 <para>
 A matrix represents a set of three-dimensional data points (x, y, z) arranged in a two-dimensional grid.
-The z values of the matrix are obtained from a vector, and the grid structure is manually specified using
-the Edit or New Matrix dialog.  The descriptions below refer to the following diagram depicting
-&kst;'s matrix structure.
 </para>
 
 <screenshot>
@@ -877,11 +896,17 @@
 </screenshot>
 
 <para>
-A screenshot and explanation of the options in the Matrix edit dialog follow.
+Just as is the case with the <link linkend="data-types-vectors">vector</link> datatype, there are two kinds of matrix: data and static. <link linkend="data-types-matrix-data">Data matrices</link> are read in from data sources, and <link linkend="data-types-matrix-static">static matrices</link> are generated by &kst;.
 </para>
 
+<sect3 id="data-types-matrix-data">
+<title>Data Matrix</title>
+<para>
+The following is a screenshot of the window displayed when editing data matrix. A new data matrix is created if you choose the <guibutton>Read from data source</guibutton> radio button in the New Matrix dialog. 
+</para>
+
 <screenshot>
-<screeninfo>Edit Matrix</screeninfo>
+<screeninfo>Edit Data Matrix</screeninfo>
 <mediaobject>
 <imageobject>
 <imagedata fileref="Screenshot-kst-data-matrixedit.png" format="PNG" />
@@ -889,72 +914,31 @@
 </mediaobject>
 </screenshot>
 
-<variablelist>
-<varlistentry>
-<term>
-<guilabel>File name</guilabel>
-</term>
-<listitem>
 <para>
-The path to the desired data file.  Clicking the button to the right displays a file browser
-window that can be used to graphically browse for the file.
+All of the options which are available for data matrices are analogous to the options for <link linkend="data-types-vectors-data">Data Vectors</link>.
 </para>
-</listitem>
-</varlistentry>
+</sect3>
 
-<varlistentry>
-<term>
-<guilabel>Field or column</guilabel>
-</term>
-<listitem>
-<para>
-The field or column from which to obtain the Z vector.
-</para>
-</listitem>
-</varlistentry>
+<sect3 id="data-types-matrix-static">
+<title>Static Matrix</title>
 
-<varlistentry>
-<term>
-<guilabel>X Minimum</guilabel> and <guilabel>Y Minimum</guilabel>
-</term>
-<listitem>
 <para>
-The origin of the matrix is specified by the coordinates (X Minimum, Y Minimum).
-The location of the origin is represented by a red circle in the above diagram.
+The following is a screenshot of the window displayed when editing static matrices. Static matrices allow you to create gradient matrices such as the one shown in the background of the annotation object <link linkend="view-overview-concepts-example">example</link>. A new static matrix is created if you choose the <guibutton>Generate gradient</guibutton> radio button in the New Matrix dialog.
 </para>
-</listitem>
-</varlistentry>
 
-<varlistentry>
-<term>
-<guilabel>X Step Size</guilabel> and <guilabel>Y Step Size</guilabel>
-</term>
-<listitem>
-<para>
-These two values specify the dimensions of each rectangular cell in the matrix grid. All cells
-in the matrix have identical dimensions.
-</para>
-</listitem>
-</varlistentry>
+<screenshot>
+<screeninfo>Edit Static Matrix</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-data-staticmatrixedit.png" format="PNG" />
+</imageobject>
+</mediaobject>
+</screenshot>
 
-<varlistentry>
-<term>
-<guilabel>Dimensions</guilabel> and <guilabel>Use maximum x length</guilabel>
-</term>
-<listitem>
 <para>
-Enter the number of steps for the x dimension of the matrix, followed by the number of
-steps for the y dimension of the matrix.  If <guilabel>Use maximum x length</guilabel> is
-checked, the x dimension of the matrix will be determined based on the length of the vector
-and the entered y dimension.  If this option is checked and the length of the vector
-subsequently changes, the x dimension of the matrix will be updated accordingly.
+These options allow you to construct a matrix which has a linear gradient in Z along either the X or Y axis. The steps options allow you to set the size of the matrix, and the X/Y minimum and step size options allow you to set the X and Y ranges.
 </para>
-<para>
-Note that the minimum allowed y dimension is 1, while the minimum allowed x dimension is 0.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
+</sect3>
 
 </sect2>
 
--- branches/work/kst/newdocs/doc/kst/views-chapter.docbook #648314:648315
@@ -42,6 +42,7 @@
 Here is an sample use of view objects in &kst;, where we have used a Plot, Labels, Arrows, Lines, and a transparent PNG Picture to mark up a color magnitude diagram.
 </para>
 
+<anchor id="view-overview-concepts-example"></anchor>
 <screenshot>
 <screeninfo>View objects example</screeninfo>
 <mediaobject>