[q-lang-cvs] qcalc/doc qcalc.xml,1.14,1.15

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-serv12988

Modified Files:
	qcalc.xml 
Log Message:
update documentation

Index: qcalc.xml
===================================================================
RCS file: /cvsroot/q-lang/qcalc/doc/qcalc.xml,v
retrieving revision 1.14
retrieving revision 1.15
diff -C2 -d -r1.14 -r1.15
*** qcalc.xml	17 Nov 2007 10:36:06 -0000	1.14
--- qcalc.xml	17 Nov 2007 12:23:45 -0000	1.15
***************
*** 102,107 ****
  </para>
  <para>
! When you enter a new or edit an existing cell value, the evaluation algorithm used by QCalc will only reevaluate the cells affected by this change. Cyclic computations (e.g., if cell A1 is computed using A1 itself, or if there is a
! cyclic chain of cell dependencies, such as A1=A2+1 and A2=2*A1) are permitted, but are executed in a "depth-first" order which breaks cycles in an apparently random way. The only thing that you can count on in such cases is that if you edit a given cell, then the change will propagate to other cells from there and each dependent cell will be recomputed at most once using the most recent values of all its requisite cells.
  </para>
  <para>
--- 102,106 ----
  </para>
  <para>
! When you enter a new or edit an existing cell value, the evaluation algorithm used by QCalc will only reevaluate the cells affected by this change. Cyclic computations (e.g., if cell A1 is computed using A1 itself, or if there is a cyclic chain of cell dependencies, such as A1=A2+1 and A2=2*A1) are permitted, but are executed in a "depth-first" order which breaks cycles in an apparently random way. The only thing that you can count on in such cases is that if you edit a given cell, then the change will propagate to other cells from there and each dependent cell will be recomputed at most once using the most recent values of all its requisite cells.
  </para>
  <para>
***************
*** 111,114 ****
--- 110,116 ----
  Note that QCalc doesn't limit your spreadsheet to operations which always terminate. If a computation (indicated by the wait cursor) takes longer than expected, or just loops indefinitely, you can abort it with <keycap>Ctrl-G</keycap> (this is the only operation active while an evaluation is in progress), and correct the offending spreadsheet cells and/or definitions in the script. In the latter case you can then force a reevaluation of the entire spreadsheet by recompiling the script with <keycap>F9</keycap> (see <xref linkend="script"/> below).
  </para>
+ <para>
+ Also note that all computations are actually executed in a secondary process running your script in a separate instance of the Q interpreter, so it shouldn't be possible to mess up QCalc no matter how badly your script behaves. In the worst case, if your script just "hangs" or "dies", so that QCalc cannot perform further calculations, you should still be able to correct your script in the editor and then just restart it with <keycap>F9</keycap>.
+ </para>
  </section>

***************
*** 234,269 ****
  </chapter>

! <chapter id="credits"><title>Credits and License</title>
! <para>
! QCalc is Copyright (c) 2007 Albert Graef and is distributed under the <ulink url="gplv2.html">GNU General Public License</ulink>. This document is Copyright (c) 2007 Albert Graef. The documentation is licensed under the terms of the <ulink url="fdl.html">GNU Free Documentation License</ulink>.
! </para>
! <para>
! Special thanks are due to Eddie Rucker from the Blue Montain College for testing, reporting bugs and providing examples.
! </para>
! </chapter>
! 
! <appendix id="installation"><title>Installation</title>
! 
! <sect1 id="getting"><title>How to obtain QCalc</title>
! <para>
! QCalc is available together with the other Qt/Q applications as a source tarball, as well as source and binary RPM packages, from the Q website at <ulink url="http://q-lang.sourceforge.net">http://q-lang.sourceforge.net</ulink>.
! </para>
! </sect1>
! 
! <sect1 id="requirements"><title>Requirements</title>
! <para>
! 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>
! </sect1>
! 
! <sect1 id="installing"><title>Installation Process</title>
! <para>
! As with other plain Q scripts, there's no compilation, so just run <command>make install</command> when installing from the sources. You may have to specify the proper installation prefix with <command>prefix=/some/path</command>; this should match Q's installation prefix, usually <filename>/usr/local</filename> or <filename>/usr</filename>. There are also some icons and desktop files included in the package, which are useful for the KDE and Gnome desktop environments, but these will have to be installed manually. (If you're installing from an RPM, hopefully these files will be copied the appropriate locations automatically, so that your application menu will show an entry for QCalc after installation.)
! </para>
! </sect1>
! 
! </appendix>
! 
! <appendix id="programming"><title>Programming QCalc</title>

  <para>
--- 236,240 ----
  </chapter>

! <chapter id="programming"><title>Programming QCalc</title>

  <para>
***************
*** 272,276 ****

  <para>
! Note that to use any of these functions in your spreadsheet script, you have to add an import declaration to your script:
  <programlisting><![CDATA[import calclib;
  ]]></programlisting>
--- 243,247 ----

  <para>
! To use any of these functions in your spreadsheet script, an appropriate import declaration is needed:
  <programlisting><![CDATA[import calclib;
  ]]></programlisting>
***************
*** 278,282 ****

  <para>
! (No explicit import is needed if you just want to use the operations in formulas.)
  </para>

--- 249,253 ----

  <para>
! Place this somewhere near the beginning of your script. (No explicit import is needed if you just want to use the operations in formulas.)
  </para>

***************
*** 284,306 ****

  <para>
! These functions are used inside formulas to access the row and column indices of the cell currently being computed. The index function returns both indices as a pair <literal>(I,J)</literal> where <literal>I</literal> and <literal>J</literal> are the zero-based row and column indices, respectively. Thus <literal>A1</literal> will be returned as <literal>(0,0)</literal>, <literal>A2</literal> as <literal>(1,0)</literal>, <literal>B1</literal> as <literal>(0,1)</literal>, etc. The row and column functions return only the row and column number, respectively.
  </para>

  <para>
! These functions can be used to convert between numeric cell indices like <literal>(0,0)</literal> and symbolic ones, either in string form (<literal>"A1"</literal>) or as a quoted symbol (<literal>'A1</literal>). The <literal>cellindex</literal> function converts from a string or a quoted symbol to the numeric index of the form <literal>(I,J)</literal>, whereas <literal>cellstr</literal> and <literal>cellname</literal> convert a numeric index back to a string or a quoted symbol, respectively.
  </para>

  <para>
! In the string and quoted symbol form, the <literal>$</literal> symbol is permitted as well. Note that constructions like <literal>'(A$4)</literal> aren't really symbols in Q, but applications of the built-in <literal>$</literal> operator, so they have to be surrounded with parentheses, as indicated. Also note that, when converting from a numeric index back to its symbolic form, the <literal>$</literal> indicators are lost since they aren't included in the numeric representation.
  </para>

--- 255,275 ----

  <para>
! The following functions allow you to retrieve information about the spreadsheet cell currently being worked on, and provide feedback about ongoing operations in the QCalc status line.
  </para>

  <para>
! <literal>public index, row, column;</literal>
  </para>

  <para>
! These functions are used inside formulas to access the row and column indices of the cell currently being computed. The index function returns both indices as a pair <literal>(I,J)</literal> where <literal>I</literal> and <literal>J</literal> are the zero-based row and column indices, respectively. Thus <literal>A1</literal> will be returned as <literal>(0,0)</literal>, <literal>A2</literal> as <literal>(1,0)</literal>, <literal>B1</literal> as <literal>(0,1)</literal>, etc. The <literal>row</literal> and <literal>column</literal> functions return only the row and column number, respectively.
  </para>

  <para>
! <literal>public cellindex X, cellstr KEY, cellname KEY;</literal>
  </para>

  <para>
! These functions can be used to convert between numeric cell indices like <literal>(0,0)</literal> and symbolic ones, either in string form (<literal>"A1"</literal>) or as a quoted symbol (<literal>'A1</literal>). The <literal>cellindex</literal> function converts from a string or a quoted symbol to the numeric index of the form <literal>(I,J)</literal>, whereas <literal>cellstr</literal> and <literal>cellname</literal> convert a numeric index back to a string or a quoted symbol, respectively. In the string and quoted symbol form, the <literal>$</literal> symbol is permitted as well. Note that constructs like <literal>'(A$4)</literal> aren't really symbols in Q, but applications of the built-in <literal>$</literal> operator, so they have to be surrounded with parentheses, as indicated. Also note that, when converting from a numeric index back to its symbolic form, the <literal>$</literal> indicators are lost since they aren't included in the numeric representation.
  </para>

***************
*** 310,315 ****

  <para>
! <programlisting><![CDATA[public message S;
! ]]></programlisting>
  </para>

--- 279,283 ----

  <para>
! <literal>public message S;</literal>
  </para>

***************
*** 323,341 ****

  <para>
! <programlisting><![CDATA[public setval KEY X;
! ]]></programlisting>
  </para>

  <para>
! This operation changes a cell value. It also returns that value, so that it can be applied to several cells in sequence. The given cell index <literal>KEY</literal> can be either in the numeric format as returned by the <literal>index</literal> function or in any of the symbolic formats supported by the <literal>cellindex</literal> routine (see <xref linkend="basicops"/>), and <literal>X</literal> may be any Q expression. If the given cell is an ordinary cell (no GUI element), then the current cell value is overwritten, so you should make sure that you do not have important data there. For GUI elements (see <xref linkend="basicguiops"/>), the value of the element is changed accordingly, instead of overwriting the cell. In both cases, after changing the cell value QCalc will update its display and trigger updates in dependent cells as usual. Note, however, that the triggered changes will <emphasis>not</emphasis> take effect immediately, rather they are processed by QCalc when the current computation is finished.
  </para>

  <para>
! These are convenience functions implemented in terms of <literal>setval</literal> to store a list in a matrix or row/column vector of table cells. They return the given list value. For the <literal>matrix</literal> function, <literal>Xs</literal> must be a list of lists which are all of the same size; the component lists become the rows of the matrix. The <literal>rowvect</literal> and <literal>colvect</literal> routines create matrices with just one row or column for a given list of values, respectively. In any case the matrix or vector is inserted into the table starting at the given index <literal>KEY</literal> (given in any of the formats supported by <literal>setval</literal>).
  </para>

--- 291,319 ----

  <para>
! The following functions are provided to change spreadsheet cells programmatically. They also work when executed asynchronously, i.e., from a Q thread executing in the background.
  </para>

  <para>
! <literal>public setval KEY X;</literal>
  </para>

  <para>
! This operation changes a cell value. It also returns that value, so that it can be applied to several cells in sequence. The given cell index <literal>KEY</literal> can be a pair of numbers as returned by the <literal>index</literal> function, or it may be specified in any of the symbolic formats supported by the <literal>cellindex</literal> routine (see <xref linkend="basicops"/>). The <literal>X</literal> parameter may be any Q expression. If the given cell is an ordinary cell (no GUI element), then the current cell value is overwritten, so you should make sure that you do not have important data there. For GUI elements (see <xref linkend="basicguiops"/>), the value of the element is changed accordingly, instead of overwriting the cell. In both cases, after changing the cell value QCalc will update its display and trigger updates in dependent cells as usual. Note, however, that the triggered changes will <emphasis>not</emphasis> take effect immediately, rather they are processed by QCalc when the current computation is finished.
  </para>

  <para>
! <literal>public clearval KEY X;</literal>
! </para>
! 
! <para>
! This function works like <literal>setval</literal>, but clears the cell before setting the new value. This is useful if you want to overwrite a cell already populated with a GUI element.
! </para>
! 
! <para>
! <literal>public matrix KEY Xs, rowvect KEY Xs, colvect KEY Xs;</literal>
! </para>
! 
! <para>
! These are convenience functions implemented in terms of <literal>setval</literal> to store a list in a matrix or a row or column vector of table cells. They return the given list value. For the <literal>matrix</literal> function, <literal>Xs</literal> must be a list of lists which are all of the same size; the component lists become the rows of the matrix. The <literal>rowvect</literal> and <literal>colvect</literal> routines create matrices with just one row or column for a given list of values, respectively. In any case the matrix or vector is inserted into the table starting at the given index <literal>KEY</literal> (given in any of the formats supported by <literal>setval</literal>).
  </para>

***************
*** 345,359 ****

  <para>
! These operations serve to define basic GUI elements in table cells. Currently supported are checkboxes, comboboxes (both non-editable and editable), spinboxes, horizontal and vertical sliders, push buttons and toggle buttons.
  </para>

  <para>
! The argument tuple <literal>ARGS</literal> depends on the specific kind of widget:
  </para>

--- 323,335 ----

  <para>
! These functions allow you to populate spreadsheet cells with basic GUI elements.
  </para>

  <para>
! <literal>public checkbox ARGS, combobox ARGS, comboedit ARGS, spinbox ARGS, hslider ARGS, vslider ARGS, pushbutton ARGS, togglebutton ARGS;</literal>
  </para>

  <para>
! Currently supported widget types are checkboxes, comboboxes (both non-editable and editable), spinboxes, horizontal and vertical sliders, push buttons and toggle buttons. The argument tuple <literal>ARGS</literal> depends on the specific kind of widget:
  </para>

***************
*** 371,375 ****
  <listitem>
  <para>
! <literal>pushbutton S</literal> or <literal>pushbutton (S,ICON)</literal>, where <literal>S</literal> is the text of the button and <literal>ICON</literal> is the name of a pixmap file. Both arguments are strings.
  </para>
  <para>
--- 347,351 ----
  <listitem>
  <para>
! <literal>pushbutton S</literal> or <literal>pushbutton (S,ICON)</literal>, where <literal>S</literal> is the text of the button and <literal>ICON</literal> is the filename of a pixmap to be shown on the button. Both arguments are strings.
  </para>
  <para>
***************
*** 404,411 ****
  <listitem>
  <para>
! <literal>spinbox (MIN,MAX,STEP,INIT,SPECIAL,PREF,SUFF)</literal>, where <literal>MIN</literal> and <literal>MAX</literal> are the minimum and maximum value, <literal>STEP</literal> is the stepsize, <literal>INIT</literal> the initial value, <literal>SPECIAL</literal> a special string used to display the minimum value (commonly used for defaults) and <literal>PREF</literal> and <literal>SUFF</literal> are strings used as prefixes and suffixes in the value display (commonly used for currency symbols and units), respectively. See the QSpinBox page in the Qt manual for details.
! </para>
! <para>
! All arguments except <literal>MIN</literal> and <literal>MAX</literal> are optional. The numeric arguments <literal>MIN</literal>, <literal>MAX</literal>, <literal>STEP</literal> and <literal>INIT</literal> may be integers or floating point values; other Q <literal>Real</literal> values are coerced to <literal>Float</literal> if possible.
  </para>
  <para>
--- 380,384 ----
  <listitem>
  <para>
! <literal>spinbox (MIN,MAX,STEP,INIT,SPECIAL,PREF,SUFF)</literal>, where <literal>MIN</literal> and <literal>MAX</literal> are the minimum and maximum value, <literal>STEP</literal> is the stepsize, <literal>INIT</literal> the initial value, <literal>SPECIAL</literal> a special string used to display the minimum value (commonly used for defaults) and <literal>PREF</literal> and <literal>SUFF</literal> are strings used as prefixes and suffixes in the value display (commonly used for currency symbols and units), respectively. See the QSpinBox page in the Qt manual for details. All arguments except <literal>MIN</literal> and <literal>MAX</literal> are optional. The numeric arguments <literal>MIN</literal>, <literal>MAX</literal>, <literal>STEP</literal> and <literal>INIT</literal> may be integers or floating point values; other Q <literal>Real</literal> values are coerced to <literal>Float</literal> if possible.
  </para>
  <para>
***************
*** 416,423 ****
  <listitem>
  <para>
! <literal>hslider (MIN,MAX,STEP,INIT)</literal>, where <literal>MIN</literal> and <literal>MAX</literal> are the minimum and maximum value, <literal>STEP</literal> is the page stepsize and <literal>INIT</literal> the initial value (which is "clamped "to the given bounds). This creates a horizontal slider. See the QSlider page in the Qt manual for details.
! </para>
! <para>
! All arguments must be integer. The <literal>STEP</literal> and <literal>INIT</literal> parameters are optional.
  </para>
  <para>
--- 389,393 ----
  <listitem>
  <para>
! <literal>hslider (MIN,MAX,STEP,INIT)</literal>, where <literal>MIN</literal> and <literal>MAX</literal> are the minimum and maximum value, <literal>STEP</literal> is the page stepsize and <literal>INIT</literal> the initial value (which is "clamped" to the given bounds). This creates a horizontal slider. See the QSlider page in the Qt manual for details. All arguments must be integer. The <literal>STEP</literal> and <literal>INIT</literal> parameters are optional.
  </para>
  <para>
***************
*** 463,511 ****

  <para>
! The action button is a special push button with a slightly different visual appearance, which has an associated Q expression (special argument) to be evaluated in the inferior Q process whenever the button is clicked. The <literal>ARGS</literal> parameter has the same format as for toggle buttons (the <literal>INIT</literal> parameter specifies the initial value of the button, 0 by default). The result returned by the action expression (which can be any Q value) becomes the value of the button when it is clicked.
  </para>

  <para>
! The task button works in a similar fashion, but instead of a direct action it has an associated <emphasis>background task</emphasis> (a Q thread) to be executed in the inferior Q process, and the button is operated as a <emphasis>toggle</emphasis> button which enables the user to "start" and "stop" the task. The <literal>ARGS</literal> parameter is the same as for <literal>togglebutton</literal>, without the <literal>ICON</literal> parameter (instead, the icon on the button is set and animated automatically in response to the current activation status of the thread). The special <literal>X</literal> parameter is the Q expression to be evaluated by the task.
  </para>

  <para>
! Inside the background task, the <literal>task_input</literal>, <literal>task_index</literal>, <literal>task_row</literal> and <literal>task_column</literal> functions are available to provide the input semaphore and the cell index of the task, respectively. (Note that the <literal>index</literal>, <literal>row</literal> and <literal>column</literal> functions don't work in background tasks, they can only be used inside formulas, so you have to use <literal>task_index</literal>, <literal>task_row</literal> and <literal>task_column</literal> instead. Also note that these values are only available in the original background task started by the <literal>taskbutton</literal> function; if your task in turn creates other threads which need to access these values, you have to pass them on to the secondary threads.)
  </para>

  <para>
! The <literal>task_input</literal> semaphore is a Q semaphore queue used to communicate values to the executing task in response to GUI actions inside QCalc. Usually these are either <literal>true</literal> or <literal>false</literal>, and are sent when the button state changes (<literal>true</literal> = button is switched on, i.e. the task was "started" by the user; <literal>false</literal> = button is off, the task was "stopped" or paused"). The background task can respond to these by taking some appropriate action, e.g., pause operation (or terminate altogether) if the <literal>false</literal> value is sent, or resume operation (if still active) when <literal>true</literal> is sent. Note that it is completely up to the task how it actually responds to these messages, if at all. However, it is a good idea to have the task at least empty the semaphore in regular time intervals to prevent the semaphore from being flooded with useless messages. In any case the semaphore queue will initially contain just the "startup" message (<literal>true</literal> if the task is initially started, <literal>false</literal> otherwise) when the tread is kicked off.
  </para>

  <para>
! The task_input semaphore may also yield a quoted taskbutton call of the form <literal>'(taskbutton (S,INIT) X)</literal> to indicate that the task button itself was updated while the task is still running. This happens when a triggered update of the button is caused by some requisite cells of the task button formula changing values. In such a case, rather than reexecuting the <literal>taskbutton</literal> function and restarting the task from scratch, the <literal>taskbutton</literal> expression with the new parameters are sent via the semaphore. Again, it is completely up to the task how it handles such a message; it may completely ignore it, or it may just evaluate the (unquoted) <literal>taskbutton</literal> call to replace itself with the new task (to support this, the <literal>taskbutton</literal> function, unlike the other GUI elements, may also be executed asynchronously). Alternatively, the task may also extract the needed data from the quoted taskbutton call and update its own internal state accordingly. To help with this, we provide the <literal>task_params</literal> special form which, when applied to the quoted expression <literal>'(taskbutton (S,INIT) (F X1 ... Xn))</literal>, where <literal>F X1 ... Xn</literal> is the new task expression, returns the parameter tuple <literal>(S,INIT,X1,...,Xn)</literal>:
  </para>

  <para>
! <programlisting><![CDATA[public special task_params X;
! ]]></programlisting>
  </para>

  <para>
! At any time, the background task can also send values back to the hosting QCalc process, using the <literal>setval</literal> function (see <xref linkend="changeops"/>) with <literal>task_index</literal> as the <literal>KEY</literal> argument. For instance, you can invoke <literal>setval task_index false</literal> to indicate that processing has finished and the task is stopped (this is also done automatically when the thread terminates). Currently, the recognized values to be sent back are <literal>false</literal> (the task is stopped), <literal>true</literal> (the task has been started, maybe in response to an asynchronous event), and arbitrary string values (which change the text label shown on the task button). QCalc will update the button in response to these messages and also change the cell value of the task button accordingly, which may trigger updates in other, dependent cells, see the description of the setval function below for further details.
  </para>

  <para>
! Note that, no matter what the purported "start/stopped" status of the button is, the user can always check whether the task associated with the button is currently up and running by taking a look at the arrow symbol shown on the button. If the task is currently executing (even if it hasn't been "started" by pushing down the button yet), the arrow symbol will be "lit" in green, otherwise it will be greyed out. Also note that in the latter case, if the thread has exited when the user starts it by pressing the button, the task will be restarted automatically.
  </para>

--- 433,477 ----

  <para>
! <literal>public special actionbutton ~ARGS X;</literal>
  </para>

  <para>
! The action button is a special push button with a slightly different visual appearance, which has an associated Q expression (special argument) to be evaluated whenever the button is clicked. The <literal>ARGS</literal> parameter has the same format as for toggle buttons (the <literal>INIT</literal> parameter specifies the initial value of the button, 0 by default). The result returned by the action expression (which can be any Q value) becomes the value of the button when it is clicked.
  </para>

  <para>
! <literal>public special taskbutton ~ARGS X;</literal>
  </para>

  <para>
! The task button works in a similar fashion, but instead of a direct action it has an associated <emphasis>background task</emphasis> (a Q thread) to be executed, and the button is operated as a <emphasis>toggle</emphasis> button which enables the user to "start" and "stop" the task. The <literal>ARGS</literal> parameter is the same as for <literal>togglebutton</literal>, without the <literal>ICON</literal> parameter (instead, the icon on the button is set and animated automatically in response to the current activation status of the thread). The special <literal>X</literal> parameter is the Q expression to be evaluated by the task.
  </para>

  <para>
! Inside the background task, the <literal>index</literal>, <literal>row</literal> and <literal>column</literal> functions work as usual and provide you with the cell index of the task. (Note that these values are in fact only available in the original background task started by the <literal>taskbutton</literal> function; if your task in turn creates other threads which need to access these values, you have to pass them on to the secondary threads.)
  </para>

  <para>
! <literal>public task_input;</literal>
  </para>

  <para>
! The <literal>task_input</literal> function equips you with a Q semaphore queue used to communicate values to the executing task in response to GUI actions inside QCalc. Usually these are either <literal>true</literal> or <literal>false</literal>, and are sent when the button state changes (<literal>true</literal> = button is switched on, i.e. the task was "started" by the user; <literal>false</literal> = button is off, the task was "stopped" or paused"). The background task can respond to these by taking some appropriate action, e.g., pause operation (or terminate altogether) if the <literal>false</literal> value is sent, or resume operation (if still active) when <literal>true</literal> is sent. Note that it is completely up to the task how it actually responds to these messages, if at all. However, it is a good idea to have the task at least empty the semaphore in regular time intervals to prevent the semaphore from being flooded with useless messages. In any case the semaphore queue will initially contain just the "startup" message (<literal>true</literal> if the task is initially started, <literal>false</literal> otherwise) when the tread is kicked off.
  </para>

  <para>
! The <literal>task_input</literal> semaphore may also yield a quoted <literal>taskbutton</literal> call of the form <literal>'(taskbutton (S,INIT) X)</literal> to indicate that the task button itself was updated while the task is still running. This happens when a triggered update of the button is caused by some requisite cells of the task button formula changing values. In such a case, rather than reexecuting the <literal>taskbutton</literal> function and restarting the task from scratch, the <literal>taskbutton</literal> expression with the new parameters is sent via the semaphore. Again, it is completely up to the task how it handles such a message; it may completely ignore it, or it may just evaluate the (unquoted) <literal>taskbutton</literal> call to replace itself with the new task (to support this, the <literal>taskbutton</literal> function, unlike the other GUI elements, may also be executed asynchronously). Alternatively, the task may also extract the needed data from the quoted <literal>taskbutton</literal> call and update its own internal state accordingly. To help with this, the following <literal>task_params</literal> special form is provided, which, when applied to a quoted expression of the form <literal>'(taskbutton (S,INIT) (F X1 ... Xn))</literal>, where <literal>F X1 ... Xn</literal> is the new task expression, returns the parameter tuple <literal>(S,INIT,X1,...,Xn)</literal>:
  </para>

  <para>
! <literal>public special task_params X;</literal>
  </para>

  <para>
! At any time, the background task can also send values back to the hosting QCalc process, using the <literal>setval</literal> function (see <xref linkend="changeops"/>) with <literal>index</literal> as the <literal>KEY</literal> argument. For instance, you can invoke <literal>setval index false</literal> to indicate that processing has finished and the task is stopped (this is also done automatically when the thread terminates). Currently, the recognized values to be sent back are <literal>false</literal> (the task is stopped), <literal>true</literal> (the task has been started, maybe in response to an asynchronous event), and arbitrary string values (which change the text label shown on the task button). QCalc will update the button in response to these messages and also change the cell value of the task button accordingly, which may trigger updates in other, dependent cells, see the description of the <literal>setval</literal> function for further details.
  </para>

  <para>
! Note that, no matter what the purported "start/stopped" status of the button is, the user can always check whether the task associated with the button is currently up and running by taking a look at the arrow symbol shown on the button. If the task is currently executing (even if it hasn't been "started" by pushing down the button yet), the arrow symbol will be "lit" in green, otherwise it will be greyed out. Also note that in the latter case, if the thread has exited when the user starts it by pressing the button, the task will be restarted automatically and will initially be fed with the message <literal>true</literal> to indicate that it should now go ahead with its business.
  </para>

***************
*** 516,519 ****
--- 482,516 ----
  </sect1>

+ </chapter>
+ 
+ <chapter id="credits"><title>Credits and License</title>
+ <para>
+ QCalc is Copyright (c) 2007 Albert Graef and is distributed under the <ulink url="gplv2.html">GNU General Public License</ulink>. This document is Copyright (c) 2007 Albert Graef. The documentation is licensed under the terms of the <ulink url="fdl.html">GNU Free Documentation License</ulink>.
+ </para>
+ <para>
+ Special thanks are due to Eddie Rucker from the Blue Montain College for testing, reporting bugs and providing examples.
+ </para>
+ </chapter>
+ 
+ <appendix id="installation"><title>Installation</title>
+ 
+ <sect1 id="getting"><title>How to obtain QCalc</title>
+ <para>
+ QCalc is available together with the other Qt/Q applications as a source tarball, as well as source and binary RPM packages, from the Q website at <ulink url="http://q-lang.sourceforge.net">http://q-lang.sourceforge.net</ulink>.
+ </para>
+ </sect1>
+ 
+ <sect1 id="requirements"><title>Requirements</title>
+ <para>
+ 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>
+ </sect1>
+ 
+ <sect1 id="installing"><title>Installation Process</title>
+ <para>
+ As with other plain Q scripts, there's no compilation, so just run <command>make install</command> when installing from the sources. You may have to specify the proper installation prefix with <command>prefix=/some/path</command>; this should match Q's installation prefix, usually <filename>/usr/local</filename> or <filename>/usr</filename>. There are also some icons and desktop files included in the package, which are useful for the KDE and Gnome desktop environments, but these will have to be installed manually. (If you're installing from an RPM, hopefully these files will be copied the appropriate locations automatically, so that your application menu will show an entry for QCalc after installation.)
+ </para>
+ </sect1>
+ 
  </appendix>