[q-lang-cvs] qcalc/doc gnuplot.png,NONE,1.1 qcalc.xml,1.24,1.25

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/q-lang/qcalc/doc
In directory sc8-pr-cvs16.sourceforge.net:/tmp/cvs-serv11240

Modified Files:
	qcalc.xml 
Added Files:
	gnuplot.png 
Log Message:
update documentation

--- NEW FILE: gnuplot.png ---
(This appears to be a binary file; contents omitted.)

Index: qcalc.xml
===================================================================
RCS file: /cvsroot/q-lang/qcalc/doc/qcalc.xml,v
retrieving revision 1.24
retrieving revision 1.25
diff -C2 -d -r1.24 -r1.25
*** qcalc.xml	2 Dec 2007 10:33:37 -0000	1.24
--- qcalc.xml	4 Dec 2007 21:33:19 -0000	1.25
***************
*** 120,124 ****
  </para>
  <para>
! There are also many useful keyboard and mouse shortcuts. You can browse through your spreadsheet with the mouse or the cursor keys, including the <keycap>Tab</keycap> and <keycap>Backtab</keycap> keys which traverse to the next and previous table cell (in row-major order), respectively. <keycap>F3</keycap> edits a cell, <keycap>Esc</keycap> aborts the edit (reverting the cell to its previous value), and <keycap>F2</keycap> or <keycap>Return</keycap> stores the edited value (and does any necessary computations). You can force reevaluation of a cell by pressing <keycap>F2</keycap> while the cell is selected, and a double click opens a cell for editing. You can also just start typing when a cell is selected, to overwrite its current value. All editing is done in place, right there in the cell; there is no separate line edit control as in other spreadsheets. Cell indices and formulas are shown in the status line when you click on them.
  </para>
  <para>
--- 120,124 ----
  </para>
  <para>
! There are also many useful keyboard and mouse shortcuts. You can browse through your spreadsheet with the mouse or the cursor keys, including the <keycap>Tab</keycap> and <keycap>Backtab</keycap> keys which traverse to the next and previous table cell (in row-major order), respectively. <keycap>F3</keycap> or <keycap>Shift-F3</keycap> edits a cell (the former edits the cell "in-place", while the latter invokes a separate multiline editor which is often more convenient for complicated formulas), <keycap>Esc</keycap> aborts the edit (reverting the cell to its previous value), and <keycap>F2</keycap> or <keycap>Return</keycap> stores the edited value (and does any necessary computations). You can force reevaluation of a cell by pressing <keycap>F2</keycap> while the cell is selected, and a double click opens a cell for editing. You can also just start typing when a cell is selected, to overwrite its current value. Cell indices and formulas are shown in the status line when you click on them.
  </para>
  <para>
***************
*** 217,221 ****
  <section id="printing"><title>Printing</title>
  <para>
! You can print a spreadsheet with the <guimenuitem>Print</guimenuitem> (<keycap>Ctrl-P</keycap>) command in the <guimenu>File</guimenu> menu. This isn't very sophisticated right now, and it isn't "WYSIWYG" either, but at least it does simple pagination and adds some formatting. After invoking this operation, QCalc shows Qt's standard printer setup dialog:
  </para>
  <screenshot>
--- 217,221 ----
  <section id="printing"><title>Printing</title>
  <para>
! You can print a spreadsheet with the <guimenuitem>Print</guimenuitem> (<keycap>Ctrl-P</keycap>) command in the <guimenu>File</guimenu> menu. This isn't very sophisticated right now, and it isn't "WYSIWYG" either, but at least it does simple pagination, adds some formatting, and renders plots created with gnuplot (cf. <xref linkend="gnuplot"/>). After invoking this operation, QCalc shows Qt's standard printer setup dialog:
  </para>
  <screenshot>
***************
*** 232,236 ****
  </screenshot>
  <para>
! Here you can choose which parts of the document should be printed (spreadsheet, script, or both) and whether to print just the cell values, just the formulas, or both. There are also configurable headers and footers which can show the spreadsheet filename and running page numbers, and for the script printout you can enable or disable the line numbering. These options are remembered across invocations, whereas the printer setup only sticks for the duration of the QCalc session.
  </para>
  </section>
--- 232,236 ----
  </screenshot>
  <para>
! Here you can choose which parts of the document should be printed (spreadsheet, script, or both) and whether to print just the cell contents, just the formulas, or both. There are also configurable headers and footers which can show the spreadsheet filename and running page numbers, and for the script printout you can enable or disable the line numbering. These options are remembered across invocations, whereas the printer setup only sticks for the duration of the QCalc session.
  </para>
  </section>
***************
*** 558,561 ****
--- 558,596 ----
  </sect1>
  
+ <sect1 id="gnuplot"><title>Gnuplot Support</title>
+ 
+ <para>
+ The following convenience function is provided to set up a task window running gnuplot.
+ </para>
+ 
+ <para>
+ <literal>public gnuplot CMD DATA;</literal>
+ </para>
+ 
+ <para>
+ The <literal>gnuplot</literal> function allows you to embed graphical plots of your data in a spreadaheet. <ulink url="http://gnuplot.sourceforge.net">Gnuplot</ulink> is a very comprehensive plotting software with which you can produce most common kinds of 2D and 3D diagrams quite easily. NOTE: Currently this feature only works under X11 and it also requires a fairly recent gnuplot version which supports the 'x11-external' option (any gnuplot version no older than 4.3, or CVS as of Dec 4 2007, should do). Also note that by default, the <literal>gnuplot</literal> function assumes that your installed gnuplot program is named <command>gnuplot</command>. If necessary, you can set the <literal>GNUPLOT</literal> string variable to a different name for the executable.
+ </para>
+ 
+ <para>
+ The <literal>CMD</literal> parameter of <literal>gnuplot</literal> is a string containing the gnuplot command used to produce the plot, and <literal>DATA</literal> is the data to be plotted, usually a range of cell values. <literal>DATA</literal> can also be <literal>()</literal> if no additional data is required, or a tuple of lists if multiple datasets are to be plotted. Each dataset must either be a list of integer or floating point values, or a list of lists of such values, which will be translated to inline data in ASCII format as described in Section 61 of the gnuplot manual. Each element of the dataset becomes one line in the ASCII format. Blank lines (which are required by some plotting commands) can be produced using an empty list inside your dataset. You then use <literal>'-'</literal> to specify each dataset inside the gnuplot command as usual. Alternatively, you can also specify the data yourself inside the gnuplot command string, employing any of gnuplot's supported data formats, and use <literal>()</literal> as the <literal>DATA</literal> argument.
+ </para>
+ 
+ <para>
+ You can use pretty much any gnuplot command in the command string; multiple gnuplot commands are separated with a semicolon or a newline character. However, your command shouldn't specify any output terminal or file (as set with the <literal>set term</literal> and <literal>set output</literal> commands) since these will be set up by QCalc when rendering the plot for the display or a printout. Also note that plots in different cells are each produced with their own gnuplot instance, so all required setup information (axes, titles, plot styles etc.) must be included in each gnuplot command; there is no sharing of such information between different cells.
+ </para>
+ 
+ <para>
+ See the <filename>plot.qcalc</filename> spreadsheet included in the QCalc distribution for an example. Here is a screenshot showing gnuplot in action:
+ <screenshot>
+ <graphic fileref="gnuplot.png" align="center"/>
+ </screenshot>
+ </para>
+ 
+ <para>
+ Note that the plots are really full instances of gnuplot running inside the table cells, which can be operated with the mouse as usual. For instance it is possible to rotate the 3D plot shown on the right by just dragging around the mouse in the cell.
+ </para>
+ 
+ </sect1>
+ 
  </chapter>
  
***************
*** 581,584 ****
--- 616,622 ----
  You'll need the Q programming system, including the Qt/Q module, available from the Q website at <ulink url="http://q-lang.sourceforge.net">http://q-lang.sourceforge.net</ulink>. Currently this script needs Qt3 (<ulink url="http://trolltech.com">http://trolltech.com</ulink>), but we're planning to port it to Qt4 asap.
  </para>
+ <para>
+ To utilize the plotting functionality discussed in <xref linkend="gnuplot"/>, you'll also need X11 and a gnuplot version which supports the 'x11-external' option (gnuplot version 4.3 or later, or CVS as of Dec 4 2007), available from <ulink url="http://gnuplot.sourceforge.net">http://gnuplot.sourceforge.net</ulink>. (Make sure that you compile gnuplot with png support, since gnuplot's png terminal is needed to render plots when printing a spreadsheet.)
+ </para>
  </sect1>