[q-lang-cvs] qcalc README,1.11,1.12

[Albert G. <ag...@us...>]

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

Modified Files:
	README 
Log Message:
update README

Index: README
===================================================================
RCS file: /cvsroot/q-lang/qcalc/README,v
retrieving revision 1.11
retrieving revision 1.12
diff -C2 -d -r1.11 -r1.12
*** README	30 Oct 2007 00:42:59 -0000	1.11
--- README	30 Oct 2007 18:31:16 -0000	1.12
***************
*** 16,27 ****
  different way. But if you've ever worked with MS Excel or its OpenOffice and
  KOffice equivalents, you should feel right at home. The only major difference
! is that each cell may hold either text, a number *or* any Q value.
! 
! Also note that there's only one spreadsheet (of fixed size) and one script per
! file in the current implementation. But the provided 128x26 cells should be
! plenty for most purposes, considering that each cell may hold an arbitrarily
! complex Q value. And the user script may import other source files as
! necessary, using Q's import/include statements, so the single script page
! doesn't really limit what you can do.
  
  IMPLEMENTATION NOTE: This program uses forkpty to implement the pipe to the Q
--- 16,21 ----
  different way. But if you've ever worked with MS Excel or its OpenOffice and
  KOffice equivalents, you should feel right at home. The only major difference
! is that each cell may hold either text, a number *or* any Q value, and that
! the full Q interpreter is used to evaluate your formulas.
  
  IMPLEMENTATION NOTE: This program uses forkpty to implement the pipe to the Q
***************
*** 43,59 ****
  -----
  
! As usual, real documentation still needs to be written, so here are some basic
! instructions which will hopefully help you to get started using QCalc. Please
! also have a look at the spreadsheet in example.qcalc (included in the tarball)
! for some examples.
  
  After installing the program, you can simply fire it up using the command
  'qcalc' or 'qcalc mysheet.qcalc'. To exit the program, use the 'Quit' option
! of the 'File' menu or just press Ctrl+Q; you will be warned and get a chance
  to abort the operation if the current file hasn't be saved yet.
  
! QCalc saves spreadsheets in a text format which is in fact valid Q script
! syntax, but uses the '.qcalc' extension by default. (The contents of the
! spreadsheet are stored as comments at the beginning of the script; it goes
  without saying that you shouldn't remove or alter these lines if you edit the
  file with a text editor!) It is also possible to open any plain Q script,
--- 37,53 ----
  -----
  
! Documentation can be found in the doc directory, and is also available online
! with the F1 key or the corresponding options in the Help menu of the
! application. Please also have a look at the spreadsheets in the examples
! directory for some examples.
  
  After installing the program, you can simply fire it up using the command
  'qcalc' or 'qcalc mysheet.qcalc'. To exit the program, use the 'Quit' option
! of the 'File' menu or just press Ctrl-Q; you will be warned and get a chance
  to abort the operation if the current file hasn't be saved yet.
  
! Note that QCalc saves spreadsheets in a text format which is in fact valid Q
! script syntax, but uses the '.qcalc' extension by default. (The contents of
! the spreadsheet are stored as comments at the beginning of the script; it goes
  without saying that you shouldn't remove or alter these lines if you edit the
  file with a text editor!) It is also possible to open any plain Q script,
***************
*** 61,262 ****
  script.
  
! FORMULAS AND EVALUATION
! -------- --- ----------
! 
! Q expressions to be evaluated are written in the customary '= <expr>' format.
! (Note that the '=' symbol must be the first character, the formula won't be
! recognized as such if it is preceded by whitespace). Thus, e.g., if you have
! the literal values '1' and '2' in cells A1 and B1, and A2 contains '= A1+B2',
! then you will get the value '3' there. The cell will also show a little arrow
! symbol to indicate that there is a computed value there, so it will actually
! look like '>       3'.
! 
! In your formulas you can use relative and absolute cell references like A1,
! B$2, $C5 or $E$9 just like in any other spreadsheet. These work exactly the
! same, as far as evaluation is concerned, but behave differently when they are
! copied or filled (see "EDITING" below). You can also employ ranges of the form
! A1:A10, which are mapped to Q lists (or lists of lists, if they span multiple
! rows *and* columns, as in B5:C12).
! 
! You can also do calculations with strings, of course, using Q's string
! operators and functions, but note that to get an empty string value you'll
! have to use the formula '= ""'. That's because the value of an empty cell
! defaults to the integer 0 (rather than the empty string) in calculations.
! 
! In fact, this spreadsheet is much more powerful than others in that cells can
! hold *any* Q value and you can do calculations with *any* kind of Q data,
! including "infinite" values such as streams (lazy lists). And, because of Q's
! term rewriting heritage, you can do symbolic calculations, too!
! 
! Also note that if an expression doesn't evaluate because some arguments don't
! match, this is not an error in Q -- the expression is then considered a normal
! form and will be printed "as is". So, if the computed value in a cell looks
! "weird", take a second look at the computed formula; you will always find that
! there's something in there which "doesn't compute", as they say. Actually,
! this feature is quite useful, as it really shows you where your computation
! went wrong, instead of just giving you some silly error message.
! 
! On the other hand, it *is* an error if an expression doesn't have a value,
! either because it is not valid Q syntax, or because it raises an exception
! (e.g., by calling 'halt' or 'throw') when evaluated. In the former case, the
! cell will just show the formula as literal text (without the arrow symbol).
! The latter kind of error is flagged (quite literally) with a little red flag
! instead of the arrow symbol, showing the offending formula as the contents of
! the cell. (Currently QCalc doesn't show you the actual exception raised by an
! expression, but you can easily find out about these by making judicious use of
! Q's built-in 'catch' function.)
! 
! 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=A1-1) are not
! permitted; the red flag will appear on all affected cells in such cases, and
! you will have to edit (at least) one of the cells to break the cycle.
! 
! The entire spreadsheet is reevaluated each time it is loaded, or when you
! recompile the script of the spreadsheet (see "THE SCRIPT" below).
! 
! Note that QCalc doesn't limit your spreadsheet to operations which always
! terminate. If a computation (indicated by the status message "Computing...") 
! takes longer than expected, or just loops indefinitely, you can abort it with
! Ctrl-G (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 F9 (see "THE SCRIPT" below).
! 
! EDITING
! -------
! 
! The editing operations provided by QCalc are rather straightforward. You can
! browse through your spreadsheet with the mouse or the cursor keys. F3 edits a
! cell, Esc aborts the edit (reverting the cell to its previous value), and F2
! or Return stores the edited value (and does any necessary computations). You
! can also force reevaluation of a cell by pressing F2 while the cell is
! selected. There are menu operations and toolbar buttons to achieve the same,
! 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.
! 
! Rectangular ranges of spreadsheet cells can be selected by dragging the mouse
! over them as usual. You can also click a row or column header to select the
! entire row or column. Such ranges can be cut, copied and pasted as usual, also
! between different instances of QCalc, with automatic adjustment of relative
! column and row indices in formulas. Thus, if you copy a cell containing the
! formula '= foo A1' to a position at an offset of, say, 2 rows and 3 columns
! from the original position, it will become '= foo D3'. As usual, you can use
! the '$' symbol to indicate absolute row or column indices (or both) which will
! not be adjusted.
! 
! The Copy operation only works with the QCalc program, but there is also a
! second "Copy values" operation to just copy the literal cell contents (without
! the formulas). This uses a tab-delimited textual format to store the selection
! in the clipboard, which can readily be pasted into almost any other
! application, including text editors and other spreadsheet programs, just as
! well as QCalc. On X11, the global selection is also supported; just select a
! range of cells, and you can paste their contents in textual format into any
! other application with the middle mouse button.
! 
! There's also a special "fill" operation which basically works like dragging
! the little "hook" in other spreadsheets to copy a value or formula to adjacent
! cells. To use this, select the range (a sequence of cells in either a single
! row or column) that you want, with the value to be copied in the topmost or
! leftmost selected cell, and then just push the "Fill" button (the one with the
! magic wand symbol on it), or press Ctrl-L. This will copy the formula in the
! principal cell to the adjacent cells, adjusting it across the range as usual.
! The same operation also allows you to fill a series of cells with an
! arithmetic sequence. For this purpose, the topmost/leftmost one or two cell
! values determine the first member(s) of the sequence.
! 
! Note that drag and drop of selected cells isn't currently supported, but
! cut/copy/paste works just as well for most purposes.
! 
! Last but not least, there's also an unlimited undo/redo facility, so if you
! mess up your spreadsheet you can always go back and forth in time as needed.
! 
! THE SCRIPT
! --- ------
! 
! You get to the script page by switching to the corresponding tab located right
! below the menu and toolbar. In the upper pane of the script page, there is a
! full-featured text editor with syntax highlighting for Q scripts. In the
! editor you can enter any Q script, which is submitted to the Q compiler when
! you invoke the Compile operation (F9). If there are any errors or warning
! messages, they will be shown in the lower "log" pane of the script page. (The
! log pane is also used to show output produced by Q's I/O operations like puts
! or printf. But note that the log is just that, a log of everything that is
! printed either by the Q compiler or the operations in your spreadsheet; it's
! *not* an interactive kind of terminal window, so it isn't possible to enter
! any input to operations like gets and scanf there. Also note that the log is
! cleared automatically whenever you recompile your script or load a new
! spreadsheet.)
! 
! You *must* correct all errors in your script before you can evaluate anything.
! As soon as your script is error-free, after pressing F9 the entire spreadsheet
! will be reevaluated, using the definitions from your script.
! 
! For instance, if you want to use a function 'square' in your spreadsheet,
! which isn't provided by the Q library, you can define it yourself as follows:
! 
! square X = X*X;
! 
! Enter this definition in the script editor and press F9. Voila, the new
! function is now available and you can use it in your spreadsheet just like any
! other function. E.g., you can now type the formula '= square 9' into a cell
! and it will evaluate to 81.
! 
! The script editor has two additional editing operations provided for your
! convenience, the Find/Replace dialog (Ctrl-F) which lets you, well, find text
! and replace it, and the "Goto line" (F5) operation to locate the given line
! number, which comes in handy to find the lines listed in compiler error
! messages.
! 
! NOTE: With the Qt3 highlighting engine, the syntax highlighting of the script
! editor can slow things down quite a bit with large scripts. As a remedy, if
! the highlighting makes the editor unresponsive and sluggish, you can disable
! it with the "Syntax highlighting" toggle (Ctrl-H).
! 
! OTHER OPTIONS
! ----- -------
! 
! Row and column sizes can be changed by dragging the borders in the row and
! column headers, and you can also quickly adjust the size by double-clicking on
! the border. The sizes will be remembered on a per-file basis when the
! spreadsheet is saved and then reloaded.
! 
! You can also change the font of the spreadsheet or the text editor by
! selecting the corresponding tab and invoking the "Choose font" operation.
! Fixed width fonts seem to work best for most purposes, although YMMV. Also
! note that the font set for the spreadsheet is also used for printing, see
! below.
! 
! The "Zoom in" and "Zoom out" (Ctrl-+ and Ctrl--) commands allow you to quickly
! change the font size on either the sheet or the script page, and, as already
! mentioned, the "Syntax highlighting" toggle (Ctrl-H) switches syntax
! highlighting in the script editor on and off. These settings are global and
! are remembered across invocations of the program.
! 
! Cell formatting is fixed in the current implementation. In particular, the
! format used for displaying floating point numbers ("%0.6g" by default) is
! hard-coded (see the FFORMAT variable at the beginning of the qcalc.q script),
! but you can easily change this in qcalc.q if you know what you are doing.
! 
! You can print a spreadsheet with the Print command. This isn't very
! sophisticated right now, but at least it lets you choose the target printer or
! file, does simple pagination, and adds some formatting. You can choose which
! sections to print (spreadsheet, script, or both) and whether to print just the
! cell values, just the formulas, or both. There are also configurable headers
! and footers showing the spreadsheet filename and page numbers. These options
! are available in the "Print options" dialog in the File menu, and will be
! remembered across invocations.
  
  TODO
  ----
  
! Online documentation is missing, from the options in the Help menu only the
! About box is implemented right now.
! 
! Other stuff that would be nice to have in future releases:
  
  - CSV file import and export.
--- 55,69 ----
  script.
  
! Also note that there's only one spreadsheet (of fixed size) and one script per
! file in the current implementation. But the provided 128x26 cells should be
! plenty for most purposes, considering that each cell may hold an arbitrarily
! complex Q value. And the user script may import other source files as
! necessary, using Q's import/include statements, so the single script page
! doesn't really limit what you can do.
  
  TODO
  ----
  
! Some stuff that would be nice to have in future releases:
  
  - CSV file import and export.