Debian Codegraph @

upstream/fedora-44/man1/sc.1

raw
1 .\" Warning: The string "sc" is converted to the true program name
2 .\" by the makefile, throughout this document.
3 .\"
4 .\" Warning: The order of presentation of commands largely matches the
5 .\" help screen built into the program.
6 .\"
7 .\" Conventions:
8 .\" - sc italicized and never uppercased (it's a proper name).
9 .\" - Refer to lists of commands in the same order as introduced.
10 .\" - Command and function names bold when introduced, italicized in all
11 .\" other places if possible, or in `` '' if not.
12 .\" - Cell names italicized except when used in expressions; row numbers
13 .\" and column names not italicized.
14 .\" - Use `` '' rather than " " except referring to literal input or output.
15 .\" - TPs use default indent except for function names, then 18.
16 .\" - Smallify uppercase strings.
17 .\" - Avoid passive voice and third person.
18 .\" $Revision: 7.16 $
19 .\"
20 .TH SC 1 "19 September 2002" "SC 7.16"
21 .SH NAME
22 sc \- spreadsheet calculator
23 .SH SYNOPSIS
24 .B sc
25 .RB [ -a ]
26 .RB [ -c ]
27 .RB [ -e ]
28 .RB [ -m ]
29 .RB [ -n ]
30 .RB [ -o ]
31 .RB [ -q ]
32 .RB [ -r ]
33 .RB [ -v ]
34 .RB [ -x ]
35 .RB [ -C ]
36 .RB [ -R ]
37 .RB [ -P
38 .IR range [ /address ]
39 |
40 .IR /address ]
41 .RB [ -W
42 .IR range ]
43 .RI [ file... ]
44 .\" ==========
45 .SH DESCRIPTION
46 The spreadsheet calculator
47 .I sc
48 is based on rectangular tables much like a financial spreadsheet.
49 When invoked, it first looks for a file in the user's home
50 directory called .scrc and if found, reads that file into memory.
51 If that file contains the command
52 .RI `` set\ scrc '',
53 .I sc
54 looks for a file called .scrc in the current directory,
55 and if found, reads that file into memory, too.
56 Next, it reads the options from the command line, and
57 finally, it reads in the file or files specified on
58 the command line and presents the data in a table
59 organized as rows and columns of cells.
60 If invoked without a
61 .I file
62 argument, the table is initially empty, unless it is
63 running in a pipeline, in which case it will read
64 its data from the standard input.
65 If more than one file is specified,
66 all files except the first one will be merged.
67 The default filename for saving a file with the
68 .I Put
69 command will be the same as the first file specified,
70 and the other files will be treated as macros.
71 If you want to use advanced macros from the command
72 line, the ``|'' must be quoted to prevent it from being
73 expanded by the shell.
74 .LP
75 Options begin with -.
76 However, an argument of a single - will be
77 interpreted to mean that spreadsheet data
78 will be taken from the standard input.
79 This is useful for including
80 .I sc
81 in a pipeline if the system supports pipes.
82 However, if standard input is not a terminal,
83 the - is only necessary if there are multiple
84 files and standard input is not the last to be
85 read, since standard input is automatically
86 read in after all other files in such cases
87 if it is not specified explicitly, or if there
88 are no other filenames on the command line.
89 If
90 .I sc
91 is included in a pipeline, and a filename of ``-''
92 is not specified, the standard input will be merged
93 in after all of the other named files have been
94 processed.
95 .LP
96 The first argument not beginning with a -,
97 or a single - by itself, and any subsequent
98 arguments will all be interpreted as
99 filenames (a filename of - meaning
100 standard input as noted above).
101 In addition, an argument of -- may
102 be used to signify that all subsequent
103 arguments should be treated as filenames
104 even if they begin with a -, but unlike -,
105 -- won't be treated as a filename itself.
106 .LP
107 Each cell may have associated with it
108 a numeric value,
109 a label string,
110 and/or an expression (formula)
111 which evaluates to a numeric value or label string,
112 often based on other cell values.
113 .LP
114 For an online tutorial, type the command:
115 .IP
116 sc /usr/share/doc/sc/tutorial.sc
117 .LP
118 To print a quick reference card, type the command:
119 .IP
120 scqref | [your_printer_commmand]
121 .\" ----------
122 .SH OPTIONS
123 .\" ----------
124 .TP
125 .B \-a
126 Do not run the autorun macro, if one is specified in the file.
127 .\" ----------
128 .TP
129 .B \-c
130 Start the program with the recalculation being done in column order.
131 .\" ----------
132 .TP
133 .B \-e
134 Start the program with round-to-even (banker's rounding) enabled.
135 .\" ----------
136 .TP
137 .B \-m
138 Start the program with automatic recalculation disabled.
139 The spreadsheet will be recalculated only when the ``@'' command is used.
140 .\" ----------
141 .TP
142 .B \-n
143 Start the program in quick numeric entry mode (see below).
144 .\" ----------
145 .TP
146 .B \-o
147 Start the program with automatic optimization of expressions enabled.
148 .\" ----------
149 .TP
150 .B \-q
151 Quit after loading all files, but before becoming interactive.
152 This is useful in shell scripts for getting information from
153 a file, for example, or using
154 .I sc
155 as a non-interactive calculator using the
156 .I eval
157 command.
158 .\" ----------
159 .TP
160 .B \-r
161 Start the program with the recalculation being done in row
162 order (default option).
163 .\" ----------
164 .TP
165 .B \-v
166 When piping data out using the
167 .I -P
168 option (below), change all expressions to values.
169 The
170 .I -v
171 option must precede the
172 .I -P
173 option to have an effect.
174 If the
175 .I -P
176 option is used more than once, there must be a separate
177 .I -v
178 option for each instance of the
179 .I -P
180 option.
181 .\" ----------
182 .TP
183 .B \-x
184 Cause the
185 .I Get
186 and
187 .I Put
188 commands (see below) to encrypt and decrypt data files.
189 .\" ----------
190 .TP
191 .B \-C
192 Start the program with automatic newline action set to increment the column
193 (see below).
194 .\" ----------
195 .TP
196 .BI \-P " range[/address]"
197 .PD 0
198 .TP
199 .BI \-P " /address"
200 .PD
201 Pipe a range to standard output.
202 The output is similar to that of the
203 .I Put
204 command (below), except that only cell data and
205 formatting information for cells in the range are
206 output, without all of the colors, range definitions,
207 column formatting, etc.
208 The optional
209 .I /address
210 is used to adjust all addresses
211 in the range to a new starting point.
212 This is useful for copying data from one file to
213 another, especially when used in conjunction with the
214 .I -v
215 option (above), using something like
216 .I "merge ""|sc -v -Prange/address filename"""
217 (note the pipe symbol).
218 This option may be used more than once to specify multiple ranges.
219 Note, however, that the
220 .I -v
221 option must precede the
222 .I -P
223 option on the command line,
224 and there must be a separate
225 .I -v
226 option for each instance of the
227 .I -P
228 option.
229 Any instance of
230 .I -P
231 not preceded by its own
232 .I -v
233 option will output unevaluated expressions.
234
235 A range of
236 .RI `` % ''
237 may be used to refer to the entire spreadsheet.
238 If the range is left out, as shown in the
239 second form above,
240 .I sc
241 will be started interactively in navigate mode,
242 allowing you to navigate the spreadsheet and
243 highlight the range you want to output.
244 Pressing ESC, ^G, or q will terminate without
245 outputting any data.
246 .\" ----------
247 .TP
248 .B \-R
249 Start the program with automatic newline action set to increment the row
250 (see below).
251 .\" ----------
252 .TP
253 .B \-W
254 Pipe a range to standard output.
255 The output is identical to that of the
256 .I Write
257 command (below).
258 This option may be used more than once to specify multiple ranges.
259 A range of
260 .RI `` % ''
261 may be used to refer to the entire spreadsheet.
262 .\" ----------
263 .PP
264 All of these options can be changed with the
265 .I ^T
266 and
267 .I S
268 commands (see below) while
269 .I sc
270 is running. Options specified when
271 .I sc
272 is invoked
273 override options saved in the data file.
274 .\" ==========
275 .SS "Personal Initialization File"
276 .\" ----------
277 When
278 .I sc
279 first starts, it looks for a file in the user's home
280 directory called .scrc and if found, loads it into memory.
281 The format of this file is the same as any other
282 .I sc
283 file, but should be reserved for setting certain defaults.
284 Any options set which have equivalent command line options may
285 be overridden by the command line.
286 If that file contains the command
287 .RI `` set\ scrc '',
288 .I sc
289 will then look for a file called .scrc in the current directory,
290 and if found, load that file into memory, too (this is analogous
291 to the ``set exrc'' command used by vi/ex).
292 These ``dotfiles'' may be created by any text editor.
293 Several commands exist specifically for setting default file
294 name extensions in the .scrc file, although they may also
295 be used from macros, ordinary spreadsheet files, or from within
296 .I sc
297 at the command line.
298 They will not, however, be saved along with the file.
299 The extensions should be quoted, and should not include
300 the preceding `.' (e.g.,
301 .I scext\ "sc"
302 will add the extension
303 .I .sc
304 ).
305 These commands are:
306 .\" ----------
307 .TP
308 .B scext
309 This is the default extension for normal
310 .I sc
311 files (those created with the
312 .I Put
313 command).
314 If this command is not used, all
315 .I sc
316 files will be saved without an extension,
317 and any existing extension will not be removed.
318 Setting this option causes all
319 .I sc
320 files to be saved with the specified extension added,
321 unless it is already present.
322 If the file name already has an extension of
323 .I .sc,
324 it will first be removed.
325 Any other extension will not be removed.
326 .\" ----------
327 .TP
328 .B ascext
329 This is the default extension for plain text files
330 created with the
331 .I Write
332 command.
333 The file name will first be checked to see if it
334 already has an extension of either
335 .I .sc
336 or the extension specified with
337 .I scext
338 above, and if either one exists, it will first
339 be removed before adding the new extension.
340 If this option is not set,
341 a default of
342 .I .asc
343 will be used.
344 .\" ----------
345 .TP
346 .B tbl0ext
347 This is the default extension for files
348 created with the
349 .I Tbl
350 command if tblstyle is set to 0 (default).
351 The file name will first be checked to see if it
352 already has an extension of either
353 .I .sc
354 or the extension specified with
355 .I scext
356 above, and if either one exists, it will first
357 be removed before adding the new extension.
358 If this option is not set,
359 a default of
360 .I .cln
361 will be used.
362 .\" ----------
363 .TP
364 .B tblext
365 This is the default extension for files
366 created with the
367 .I Tbl
368 command if tblstyle is set to tbl.
369 The file name will first be checked to see if it
370 already has an extension of either
371 .I .sc
372 or the extension specified with
373 .I scext
374 above, and if either one exists, it will first
375 be removed before adding the new extension.
376 If this option is not set,
377 a default of
378 .I .tbl
379 will be used.
380 .\" ----------
381 .TP
382 .B latexext
383 This is the default extension for files
384 created with the
385 .I Tbl
386 command if tblstyle is set to latex.
387 The file name will first be checked to see if it
388 already has an extension of either
389 .I .sc
390 or the extension specified with
391 .I scext
392 above, and if either one exists, it will first
393 be removed before adding the new extension.
394 If this option is not set,
395 a default of
396 .I .lat
397 will be used.
398 .\" ----------
399 .TP
400 .B slatexext
401 This is the default extension for files
402 created with the
403 .I Tbl
404 command if tblstyle is set to slatex.
405 The file name will first be checked to see if it
406 already has an extension of either
407 .I .sc
408 or the extension specified with
409 .I scext
410 above, and if either one exists, it will first
411 be removed before adding the new extension.
412 If this option is not set,
413 a default of
414 .I .stx
415 will be used.
416 .\" ----------
417 .TP
418 .B texext
419 This is the default extension for files
420 created with the
421 .I Tbl
422 command if tblstyle is set to tex.
423 The file name will first be checked to see if it
424 already has an extension of either
425 .I .sc
426 or the extension specified with
427 .I scext
428 above, and if either one exists, it will first
429 be removed before adding the new extension.
430 If this option is not set,
431 a default of
432 .I .tex
433 will be used.
434 .\" ==========
435 .SS "General Information"
436 .\" ----------
437 The screen is divided into four regions.
438 The top line is for entering commands and displaying cell values.
439 The second line is for messages from
440 .IR sc .
441 The third line and the first four columns show the column and row numbers,
442 from which are derived cell addresses, e.g.
443 .I A0
444 for the cell in column A, row 0.
445 Note that column names are case-insensitive: you can enter
446 .I A0
447 or
448 .IR a0 .
449 .\" ----------
450 .PP
451 The rest of the screen forms a window looking at a portion of the table.
452 The total number of display rows and columns available,
453 hence the number of table rows and columns displayed,
454 is set by
455 .IR curses (3)
456 and may be overridden by setting the
457 .SM LINES
458 and
459 .SM COLUMNS
460 environment variables, respectively.
461 .\" ----------
462 .PP
463 The screen has two cursors:
464 a cell cursor, indicated by either a highlighted cell
465 or a ``<'' on the screen, and a character cursor,
466 indicated by the terminal's hardware cursor.
467 .\" ----------
468 .PP
469 If a cell's numeric value is wider than the column width (see the
470 .I f
471 command), the cell is filled with asterisks.
472 If a cell's label string is wider than the column width,
473 it is truncated at the start of the next non-blank cell in the row, if any.
474 .\" ----------
475 .PP
476 Cursor control commands and row and column commands
477 can be prefixed by a numeric argument
478 which indicates how many times the command is to be executed.
479 You can type
480 .I ^U
481 before a repeat count if quick numeric entry mode is enabled.
482 .\" ==========
483 .SS "Changing Options"
484 .\" ----------
485 \0 \" exactly one blank line (hard to get)
486 .PD 0
487 .TP
488 .BI ^T o
489 Toggle options.
490 This command allows you to switch the state of one option selected by
491 .IR o .
492 A small menu lists the choices for
493 .I o
494 when you type
495 .IR ^T .
496 Unless otherwise noted, the options selected are saved
497 when the data and formulas are saved so that you will
498 have the same setup next time you enter the spreadsheet.
499 .PD
500 .RS
501 .\" ----------
502 .TP
503 .B a
504 Automatic Recalculation.
505 When set, each change in the spreadsheet
506 causes the entire spreadsheet be recalculated.
507 Normally this is not noticeable, but for very large
508 spreadsheets, it may be faster to clear
509 automatic recalculation mode and update the
510 spreadsheet via explicit ``@'' commands.
511 Default is automatic recalculation on.
512 .\" ----------
513 .TP
514 .B b
515 Braille enhancement mode.
516 See the braille section under the
517 .I Set
518 command below for a complete description of
519 how to use this mode.
520 This option is not saved when saving a file,
521 to allow blind and sighted users to easily
522 share files. It is intended for use in a user's
523 .I .scrc
524 file.
525 .\" ----------
526 .TP
527 .B c
528 Current cell highlighting.
529 If enabled, the current cell is highlighted
530 (using the terminal's standout mode, if available)
531 and the cell pointer ``<'' is turned off.
532 This is enabled by default.
533 .\" ----------
534 .TP
535 .B e
536 External function execution.
537 When disabled, external functions (see
538 .IR @ext ()
539 below) are not called.
540 This saves a lot of time at each screen update.
541 External functions are disabled by default.
542 If disabled, and external functions are used anywhere,
543 a warning is printed each time the screen is updated,
544 and the result of
545 .IR @ext ()
546 is the value from the previous call, if any, or a null string.
547 .\" ----------
548 .TP
549 .B i
550 Automatic insertion of rows/columns.
551 If this is enabled and craction is set to move the
552 cell cursor either down or to the right after entering
553 data into a cell, and the last cell in a row/column
554 in the scrolling portion of a framed range was just
555 filled, causing the cell cursor to move outside of this
556 range, a new column/row will be inserted, thus enlarging
557 the range and allowing you to continue entering data
558 into the row/column without overwriting the frame (which
559 may contain expressions of some sort, such as totals).
560 If autowrap is also enabled, it will take precedence,
561 and a new row/column will only be inserted after
562 entering data in the very last cell (bottom right corner)
563 of the scrolling range.
564 The default is no automatic insertion.
565 .\" ----------
566 .TP
567 .B w
568 Automatic wrap to next row/column.
569 If this is enabled and craction is set to move the
570 cell cursor either down or to the right after entering
571 data into a cell, and the last cell in a row/column
572 in the scrolling portion of a framed range was just
573 filled, causing the cell cursor to move outside of this
574 range, the cell cursor will move to the first cell in
575 the next row/column in this range.
576 If this would also take the cursor out of the scrolling
577 portion of the range, the cursor will remain in last
578 edited cell instead, unless autoinsert is also enabled,
579 in which case a new row/column will be added so that
580 the cursor can wrap.
581 The default is no autowrap.
582 .\" ----------
583 .TP
584 .B l
585 Autolabeling.
586 If enabled, using the define command (rd) causes
587 a label to be automatically generated in the cell
588 to the left of the defined cell.
589 This is only done if the cell to the left is empty.
590 Default is enabled.
591 .\" ----------
592 .TP
593 .B n
594 Quick numeric entry.
595 If enabled,
596 a typed digit is assumed to be
597 the start of a numeric value for the current cell,
598 not a repeat count, unless preceded by
599 .IR ^U .
600 Also, the `+' and `-' keys will enter insert mode
601 and append a `+' or `-' to the existing contents
602 of the cell, allowing the user to easily add to or
603 subtract from the current numeric contents of the cell.
604 The cursor controls
605 .RI ( ^P ,
606 .IR ^N ,
607 or any of the arrow keys)
608 in this mode will end a numeric entry if the entry
609 was started by pressing `+', `-', or a digit.
610 Switching from insert mode to edit mode will cause the
611 cursor controls to revert to their normal functions.
612 .\" ----------
613 .TP
614 .B o
615 Automatic optimization of expressions.
616 If this is enabled, expressions which evaluate to
617 a constant are automatically optimized upon entry.
618 For example, if you enter @pow(2,32) into a cell,
619 the value 4294967296 will be stored in that cell,
620 whereas if optimization is turned off, the calculated
621 value will be displayed, but the actual expression will
622 be stored in the cell instead.
623 This allows you to edit the expression instead of
624 re-entering it from scratch when you just want to
625 make a minor change.
626 Default is automatic optimization off.
627 .\" ----------
628 .TP
629 .B t
630 Top line display.
631 If enabled,
632 the name and value of the current cell is
633 displayed on the top line.
634 If there is an associated label string,
635 the first character of the string value
636 is ``|'' for a centered string, ``<'' for a
637 leftstring or ``>'' for a rightstring (see below),
638 followed by "\fIstring\fP" for a constant string or
639 .RI { expr }
640 for a string expression.
641 A constant string may be preceeded with a backslash (`\\').
642 In this case the constant string will be used as a ``wheel''
643 to fill a column, e.g. "\\-" for a line in a column,
644 and "\\Yeh\ " for "Yeh\ Yeh\ Ye".
645 If the cell has a numeric value,
646 it follows as
647 .RI [ value ],
648 which may be a constant or expression.
649 .\" ----------
650 .TP
651 .B $
652 Dollar prescale.
653 If enabled, all numeric
654 .B constants
655 (not expressions) which you enter are multipled by 0.01
656 so you don't have to keep typing the decimal point
657 if you enter lots of dollar figures.
658 .\" ----------
659 .TP
660 .B r
661 Newline action.
662 This is a 3-way toggle which determines which direction to
663 move after pressing the
664 .SM RETURN
665 key to enter data into a cell.
666 It has the same effect as using the
667 .I set
668 (S) command to set the value of craction.
669 After selecting this option, you will be prompted for
670 the direction you want to move.
671 Valid directions are down (craction=1) and to the right (craction=2).
672 Pressing j, ^N, or the cursor-down key will cause
673 the cursor to move down a cell each time you press
674 the
675 .SM RETURN
676 key and pressing l, the cursor-right key, or the
677 space bar will cause the cursor to move one cell to the right.
678 Pressing the
679 .SM RETURN
680 key at the prompt selects no action
681 (craction=0, which means that the cursor will remain in
682 the current cell).
683 No action is the default unless
684 .I sc
685 is started with either the -R or -C option.
686 This option is ignored if the cell into which data is
687 being entered is not the current cell.
688 .\" ----------
689 .TP
690 .B s
691 Enable/disable color slop.
692 If a cell's label string is wider than the column width,
693 it will slop over into the next cell to the right if that
694 cell is empty.
695 However, if that cell is in a different color range than
696 the first, this slopover will be disabled, regardless of
697 whether the colors assigned to the two ranges are different
698 or not.
699 If cslop is enabled, strings may slop over even if the
700 next cell is in a different color range, carrying their
701 color with them, which may cause a ragged boundary between
702 the ranges, but may allow the strings to be seen in their
703 entirety.
704 Cslop is disabled by default.
705 .\" ----------
706 .TP
707 .B x
708 Encryption.
709 See the
710 .B \-x
711 option.
712 .\" ----------
713 .TP
714 .B z
715 Set newline action limits.
716 This option sets limits to the newline action option above.
717 When this option is invoked, the row and column of the
718 current cell are remembered.
719 If a later newline action would take the current cell to the right of
720 the remembered column, then the current cell is instead moved to the
721 first column of the next row.
722 If a newline action would take the current cell below the remembered row,
723 then the current cell is instead moved to the top row of the next column.
724 .\" ----------
725 .TP
726 .B C
727 Color.
728 This option enables color, and must be set before any
729 other color options, such as colorneg (color negative
730 numbers) or colorerr (color cells with errors), will
731 have an effect.
732 On a slow connection, turning off color can noticeably
733 speed up screen updates.
734 .\" ----------
735 .TP
736 .B E
737 Color cells with errors.
738 Setting this option will cause all cells with expressions
739 which evaluate to ERROR or INVALID to be set to color 3.
740 Color must be enabled for this option to take effect.
741 .\" ----------
742 .TP
743 .B N
744 Color negative numbers.
745 When this option is set, all cells containing negative
746 numbers will have their color number incremented by one.
747 Cells with color 8 will cycle back to color 1.
748 Color must be enabled for this option to take effect.
749 .PP
750 The quick numeric entry, newline action and set
751 newline action limits options can be combined to
752 allow very quick entry of large amounts of data.
753 If all the data to be entered is in a single row
754 or column then setting the quick numeric entry and
755 the appropriate newline action will allow the
756 numbers to be entered without any explicit commands
757 to position the current cell or enter a number.
758 .PP
759 If the data entry involves several entries in each row for many rows, then
760 setting the quick numeric entry option, setting the newline action to move
761 right after each entry and setting the newline action limits on the last
762 column on which data should be entered will allow the data to entered
763 quickly.
764 An alternative to setting newline action limits is to
765 enclose the range for entry in a frame (see "Framed Ranges"
766 below), and setting the autowrap option.
767 Setting autoinsert will insert new rows as needed if the
768 frame includes data at the bottom.
769 If necessary, columns which do not need data to be
770 entered can be hidden with the
771 .B z
772 command.
773 Similar arrangements can be made for entering several rows of data
774 in each column.
775 .RE
776 .\" ----------
777 \0 \" exactly one blank line (hard to get)
778 .PD 0
779 .TP
780 .B S
781 Set options. This command allows you to set various options.
782 A small menu lists the options that cannot be changed through
783 .I ^T
784 above.
785 .PD
786 .RS
787 .\" ----------
788 .TP
789 .BR byrows / bycols
790 Specify the order cell evaluation when updating.
791 These options also affect the order in which
792 cells are filled (see
793 .IR rf )
794 and whether a row or column is cleared by an
795 .I x
796 command.
797 .\" ----------
798 .TP
799 .BI iterations =n
800 Set the maximum number of recalculations before
801 the screen is displayed again.
802 .I Iterations
803 is set to 10 by default.
804 .\" ----------
805 .TP
806 .BI tblstyle =s
807 Control the output of the
808 .I T
809 command.
810 .I s
811 can be:
812 .B 0
813 (default) to give colon delimited fields, with no
814 .I tbl
815 control lines;
816 .B tbl
817 to give colon delimited fields, with
818 .IR tbl (1)
819 control lines;
820 .B latex
821 to give a
822 .I LaTeX
823 tabular environment;
824 .B slatex
825 to give a
826 .I SLaTeX (Scandinavian LaTeX)
827 tabular environment;
828 .B tex
829 to give a
830 .I TeX
831 simple tabbed alignment with ampersands as delimiters; and
832 .B frame
833 to give a tblstyle output for FrameMaker.
834 .\" ----------
835 .TP
836 .BI pagesize =n
837 Set the page size for the PageUp, PageDown, J, and K commands.
838 If set to 0, the default is to move up or down
839 half the number of rows displayed on the screen,
840 or if the current cell is in a framed range,
841 half the number of displayed rows in the scrolling
842 region of that range.
843 .\" ----------
844 .PP
845 Other
846 .I Set
847 options are normally used only in
848 .I sc
849 data files since they are available through
850 .IR ^T .
851 You can also use them interactively.
852 .\" ----------
853 .TP
854 .BR autocalc / !autocalc
855 Set/clear auto recalculation mode.
856 .\" ----------
857 .TP
858 .BR autoinsert / !autoinsert
859 Set/clear automatic insertion mode.
860 .\" ----------
861 .TP
862 .BR autowrap / !autowrap
863 Set/clear autowrap mode.
864 .\" ----------
865 .TP
866 .BR optimize / !optimize
867 Set/clear auto optimize mode.
868 .\" ----------
869 .TP
870 .BR numeric / !numeric
871 Set/clear numeric mode.
872 .\" ----------
873 .TP
874 .BR prescale / !prescale
875 Set/clear numeric prescale mode.
876 .\" ----------
877 .TP
878 .BR extfun / !extfun
879 Enable/disable external functions.
880 .\" ----------
881 .TP
882 .BR toprow / !toprow
883 Set/clear top row display mode.
884 .\" ----------
885 .TP
886 .BR rndtoeven / !rndtoeven
887 Default: *.5 will be rounded up to the next integer;
888 doing a 'set rndtoeven' will cause it to be rounded to
889 the closest even number instead (aka banker's rounding).
890 Round-to-even has advantages over the default rounding
891 for some applications.
892 For example, if X+Y is an integer,
893 then X+Y = rnd(X)+rnd(Y) with round-to-even,
894 but not always with the defaulting rounding method.
895 This could be an advantage, for example, when trying to
896 split an odd amount of money evenly between two people (it
897 would determine who gets the extra penny).
898 Note: rndtoeven only effects the @rnd and @round functions.
899 It has no effect on how a number is rounded to fit the
900 display format of a cell.
901 .\" ----------
902 .TP
903 .BI craction =n
904 Set the newline action.
905 .I n
906 can be:
907 .B 0
908 (default) to give no action;
909 .B 1
910 to move down after each entry; or
911 .B 2
912 to move right after each entry.
913 .TP
914 .BI rowlimit =n
915 Set the remembered limit for the maximum row below which
916 the current cell will be moved to the top of the next column
917 if the newline action is set to move the current cell down.
918 .I n
919 can be
920 .B -1
921 (default) to disable this facility.
922 .\" ----------
923 .TP
924 .BI collimit =n
925 Set the remembered limit for the maximum column to the right of which
926 the current cell will be moved to the left of the next row
927 if the newline action is set to move the current cell right.
928 .I n
929 can be
930 .B -1
931 (default) to disable this facility.
932 .\" ----------
933 .TP
934 .BR color / !color
935 Enable color.
936 This option must be set for any other color options,
937 such as colorneg or colorerr, to take effect.
938 On a slow connection, turning off color can noticeably
939 speed up screen updates.
940 .\" ----------
941 .TP
942 .BR colorneg / !colorneg
943 Color negative numbers.
944 When this option is set, all cells containing negative
945 numbers will have their color number increased by one.
946 Cells with color 8 will cycle back to color 1.
947 Color must be enabled for this option to take effect.
948 .\" ----------
949 .TP
950 .BR colorerr / !colorerr
951 Color cells with errors.
952 Setting this option will cause all cells with expressions
953 which evaluate to ERROR or INVALID to be set to color 3.
954 Color must be enabled for this option to take effect.
955 .\" ----------
956 .TP
957 .BR cslop / !cslop
958 Enable color slop.
959 If a cell's label string is wider than the column width,
960 it will slop over into the next cell to the right if that
961 cell is empty.
962 However, if that cell is in a different color range than
963 the first, this slop over will be disabled, regardless of
964 whether the colors assigned to the two ranges are different
965 or not.
966 If cslop is enabled, strings may slop over even if the
967 next cell is in a different color range, carrying their
968 color with them, which may cause a ragged boundary between
969 the ranges, but may allow the strings to be seen in their
970 entirety.
971 Cslop is disabled by default.
972 .PP
973 The following
974 .I Set
975 options are considered personal preferences,
976 or are terminal dependent, and are therefore not
977 saved when saving a file, but are instead intended
978 for use in a user's .scrc file.
979 .\" ----------
980 .TP
981 .BR braille / !braille
982 Set/clear braille enhancement mode.
983 When braille enhancement mode is set, the cursor
984 behaves in a manner that makes the use of
985 .I sc
986 much easier when using a braille display.
987 In spite of its name, this mode also works well with
988 screen readers such as SpeakUp, and can even be used
989 by sighted users to make cutting and pasting using the
990 .I screen
991 program much easier.
992
993 There are actually two different braille modes.
994 When the braille option is set, the
995 .I C
996 command, which is normally used to set colors,
997 will instead change from one braille mode to the other.
998 If it is desired to set/change colors so you can
999 share files with others not using a braille display,
1000 braille mode will have to be switched off temporarily,
1001 and then switched back on after the color operation
1002 is done.
1003
1004 When the braille option is set, the default braille mode
1005 will cause the cursor to be positioned at the left edge of
1006 the current cell, while the alternate braille mode will
1007 cause the cursor to be placed at the beginning of the top
1008 line, which will contain information such as the current
1009 cell address, contents of the cell, and column formatting
1010 information.
1011 The column names will also be moved to the left edge of
1012 their respective columns in order to remain aligned with
1013 the cursor as it moves up and down the column.
1014
1015 In either mode, the cursor will be placed in the
1016 top line when editing a line, except when switching
1017 to navigate mode, in which case the cursor will be
1018 placed in either the current cell (default braille mode)
1019 or the second line, where the cell address or default
1020 range will be displayed (alternate braille mode).
1021
1022 Whenever a message is displayed on the second line,
1023 such as an error message or prompt for further
1024 information, both modes will cause the cursor to
1025 be placed at the beginning of that message.
1026 After this message goes away, the cursor will
1027 revert to its former behavior.
1028 The easiest way to make this message go away
1029 without effecting anything, except in the cases
1030 where it is asking the user for more information,
1031 is to press
1032 .IR CC ,
1033 which effectively changes modes twice, with a net
1034 effect of leaving
1035 .I sc
1036 in the original mode.
1037 .\" ----------
1038 .TP
1039 .BR locale / !locale
1040 If locale support is compiled into
1041 .IR sc ,
1042 this option will cause certain locale-dependent
1043 behaviors, such as the display of numbers and the
1044 determination of word boundaries for some operations
1045 in edit mode.
1046 Note that if this option is set and the environment
1047 variable LC_ALL is unrecognized, unset, or set to
1048 either ``POSIX'' or ``C'', commas in format commands
1049 will be ignored.
1050 .\" ----------
1051 .TP
1052 .BR cellcur / !cellcur
1053 Set/clear current cell highlighting mode.
1054 This option is included here because it is likely to
1055 be terminal dependent and/or a user preference,
1056 and therefore is not saved when saving a file.
1057 .\" ----------
1058 .TP
1059 .BI scrc
1060 It tells
1061 .I sc
1062 to also read the file .scrc in the current directory when starting.
1063 Settings in this file will override those in $HOME/.scrc
1064 but may themselves be overridden by command line options.
1065 Setting this could be a potential security risk, since starting
1066 .I sc
1067 with an unknown .scrc could potentially execute arbitrary commands.
1068 This risk is probably very slight, since a spreadsheet program
1069 is not likely to be run in just any directory, and should
1070 .B never
1071 be run as root.
1072 .RE
1073 .\" ==========
1074 .SS "Cursor Control Commands"
1075 .\" ----------
1076 \0 \" exactly one blank line (hard to get)
1077 .PD 0
1078 .TP
1079 .B ^A
1080 Go to cell
1081 .I A0
1082 (same as HOME).
1083 .PD
1084 .\" ----------
1085 .TP
1086 .B ^P
1087 Move the cell cursor up to the previous row.
1088 .\" ----------
1089 .TP
1090 .B ^N
1091 Move the cell cursor down to the next row.
1092 .\" ----------
1093 .TP
1094 .B ^H
1095 Move the cell cursor backward one column.
1096 .\" ----------
1097 .TP
1098 .B SPACE
1099 Move the cell cursor forward one column.
1100 When in navigate mode, if a range is highlighted,
1101 insert the highlighted range into the command line,
1102 followed by a space, while remaining in navigate mode.
1103 This is useful when entering copy, move, or frame commands,
1104 for example, which accept more than one range argument.
1105 .\" ----------
1106 .TP
1107 .B "h, j, k, l"
1108 These are alternate,
1109 .IR vi -compatible
1110 cell cursor controls (left, down, up, right).
1111 Space is just like l (right).
1112 .TP
1113 .B "H, J, K, L"
1114 These move the cursor
1115 by half pages (left, down, up, right).
1116 If
1117 .I pagesize
1118 is nonzero, up/down paging will be by
1119 .I pagesize
1120 rows, instead.
1121 .\" ----------
1122 .TP
1123 .B "^F, ^B"
1124 Same as J and K above.
1125 .\" ----------
1126 .TP
1127 .B PAGE-DOWN PAGE-UP
1128 Same as J and K above.
1129 .\" ----------
1130 .TP
1131 .B TAB
1132 If the character cursor is on the top line,
1133 .SM TAB
1134 tries to complete a range name if the character
1135 immediately preceding it is alphanumeric or ``_'',
1136 and starts a range if not (see below).
1137 Otherwise, move the cell cursor forward one column.
1138 .\" ----------
1139 .TP
1140 .B HOME
1141 Go to cell
1142 .IR A0 .
1143 .\" ----------
1144 .TP
1145 .B END
1146 Same as ^E (see below).
1147 .\" ----------
1148 .TP
1149 .B "Arrow Keys"
1150 The terminal's arrow keys provide another alternate
1151 set of cell cursor controls if they exist and are
1152 supported in the appropriate
1153 .I termcap
1154 entry.
1155 Some terminals have arrow keys which conflict with other control key codes.
1156 For example, a terminal might send
1157 .I ^H
1158 when the back arrow key is pressed.
1159 In these cases, the conflicting arrow key performs the same function
1160 as the key combination it mimics.
1161 .\" ----------
1162 .TP
1163 .B ^
1164 Move the cell cursor up to row 0 of the current column.
1165 .\" ----------
1166 .TP
1167 .B #
1168 Move the cell cursor down to the last valid row of the current column.
1169 .\" ----------
1170 .TP
1171 .B 0
1172 Move the cell cursor backward to column A of the current row.
1173 This command must be prefixed with
1174 .I ^U
1175 if quick numeric entry mode is enabled.
1176 .\" ----------
1177 .TP
1178 .B $
1179 Move the cell cursor forward to the last valid column of the current row.
1180 .\" ----------
1181 .TP
1182 .B b
1183 Scan the cursor backward (left and up) to the previous valid cell.
1184 .\" ----------
1185 .TP
1186 .B w
1187 Scan the cursor forward (right and down) to the next valid cell.
1188 .\" ----------
1189 .TP
1190 .B g
1191 Go to a cell.
1192 .I sc
1193 prompts for a cell's name, a regular expression surrounded by
1194 quotes, or a number.
1195 If a cell's name such as
1196 .I ae122
1197 or the name of a defined range is given, the cell cursor goes
1198 directly to that cell.
1199 If a quoted regular expression such as "
1200 .I Tax Table
1201 " or "
1202 .I ^Jan [0-9]*$
1203 " is given,
1204 .I sc
1205 searches for a cell containing a string matching the regular
1206 expression.
1207 See
1208 .I regex(3)
1209 or
1210 .I ed(1)
1211 for more details on the form of regular
1212 expressions.
1213 .IP
1214 You can also search formatted numbers or expressions
1215 using regular expressions by preceding the opening quotes
1216 of the regular expression with a ``#'' (for formatted
1217 numbers) or a ``%'' (for expressions).
1218 These are handy for searching for dates within a specified
1219 range or cells which reference a given cell, for example,
1220 although they are somewhat slower than searching through
1221 ordinary strings, since all numbers must be formatted or
1222 expressions decompiled on the fly during the search.
1223 .IP
1224 If a number is given,
1225 .I sc
1226 will search for a cell containing that number.
1227 Searches for either strings or numbers proceed forward from the
1228 current cell, wrapping back to a0 at the end of the table, and
1229 terminate at the current cell if the string or number is not found.
1230 You may also go to a cell with an ERROR (divide by zero, etc. in this cell)
1231 or INVALID (references a cell containing an ERROR).
1232 .IR g\ error
1233 will take you to the next ERROR, while
1234 .IR g\ invalid
1235 take you to the next INVALID.
1236 The last
1237 .I g
1238 command is saved, and can be re-issued by entering
1239 .IR g<return> .
1240 You can also repeat the last search by pressing
1241 .IR n .
1242 .IP
1243 An optional second argument is available whose meaning
1244 depends on whether you're doing a search or jumping to a
1245 specific cell. When doing a search, the second argument
1246 specifies a range to search. When jumping to a specific
1247 cell, the second argument specifies which cell should be
1248 in the upper lefthand corner of the screen, if possible,
1249 which allows you to position the destination cell where
1250 you want it on the screen.
1251 .\" ----------
1252 .TP
1253 .BI ^E d
1254 Go to end of range.
1255 Follow
1256 .I ^E
1257 by a direction indicator such as
1258 .I ^P
1259 or
1260 .IR j .
1261 If the cell cursor starts on a non-blank cell,
1262 it goes in the indicated direction until the
1263 last non-blank adjacent cell.
1264 If the cell cursor starts on a blank cell,
1265 it goes in the indicated direction until
1266 the first non-blank cell.
1267 This command is useful when specifying ranges
1268 of adjacent cells (see below), especially when
1269 the range is bigger than the visible window.
1270 .IP
1271 If
1272 .I ^E
1273 is pressed twice in succession,
1274 or if it is pressed after another
1275 .I ^E
1276 or a
1277 .IR ^Y ,
1278 it will cause the screen to scroll up without
1279 moving the cell cursor, unless the cell cursor
1280 is already at the top of the screen, in which
1281 case, it will remain at the top of the visible
1282 screen.
1283 .\" ----------
1284 .TP
1285 .B ^Y
1286 Causes the screen to scroll down without moving
1287 the cell cursor, unless the cell cursor is
1288 already at the bottom of the screen, in which case,
1289 it will remain at the bottom of the visible screen.
1290 .\" ----------
1291 .TP
1292 .BI m x
1293 Mark the current cell.
1294 .I sc
1295 will prompt for a lowercase letter to be
1296 used as a mark specifier.
1297 Marked cells may be used as the source for the
1298 .I c
1299 (copy a marked cell) command, or as the target of a
1300 .I `
1301 or
1302 .I '
1303 (go to marked cell) command.
1304 In addition to cells marked with lowercase letters,
1305 .I sc
1306 also automatically marks the last nine cells that
1307 have been edited with the numbers 1-9, and the
1308 current cell being edited with the number 0.
1309 When not editing a cell, marks 0 and 1 usually
1310 refer to the same cell, unless the last edit was
1311 begun in one cell, but the cell address was changed
1312 before pressing the
1313 .SM RETURN
1314 key, or the last edit was aborted prematurely.
1315 .\" ----------
1316 .TP
1317 .BI ` x
1318 Jump to a previously marked cell.
1319 If the target cell is currently on the screen,
1320 .I sc
1321 will simply jump to the target cell, making it current.
1322 Otherwise,
1323 .I sc
1324 will attempt to center the cell on the screen, if possible.
1325 As a special case, following the ` with another ` will
1326 return you to the cell you were in before the last g, ', `,
1327 *, or ^E (or END key) was used to jump to another cell.
1328 .\" ----------
1329 .TP
1330 .BI ' x
1331 Jump to a previously marked cell.
1332 .I '
1333 works just like
1334 .I `
1335 , except that
1336 .I '
1337 will attempt to restore the marked cell to the same
1338 position on the screen as when it was marked.
1339 It does this by remembering which cell was in the upper
1340 left hand corner of the screen at the time the mark was
1341 set, and restoring that cell to its original position.
1342 As a special case, following the ' with another ' will
1343 return you to the cell you were in before the last g, ', `,
1344 *, or ^E (or END key) was used to jump to another cell,
1345 and will also try to position that cell on the screen in
1346 the same position as when you left it.
1347 .\" ----------
1348 .TP
1349 .BI z<RETURN>
1350 Move the current row to the top of the screen.
1351 If the current row is in a framed range, move the current
1352 row to the top of the scrolling region.
1353 .\" ----------
1354 .TP
1355 .BI z.
1356 Move the current row to the center of the screen.
1357 .\" ----------
1358 .TP
1359 .BI z|
1360 Move the current column to the center of the screen.
1361 .\" ----------
1362 .TP
1363 .BI zc
1364 Center the current cell both horizontally and vertically.
1365 .\" ==========
1366 .SS "Cell Entry and Editing Commands"
1367 .\" ----------
1368 Cells can contain both a numeric value and a string value.
1369 Either value can be the result of an expression,
1370 but not both at once,
1371 i.e. each cell can have only one expression associated with it.
1372 Entering a valid numeric expression
1373 alters the cell's previous numeric value, if any,
1374 and replaces the cell's previous string expression, if any,
1375 leaving only the previously computed constant label string.
1376 Likewise, entering a valid string expression
1377 alters the cell's the previous label string, if any,
1378 and replaces the cell's previous numeric expression, if any,
1379 leaving only the previously computed constant numeric value.
1380 .TP
1381 .B =
1382 Enter a numeric constant or expression into the current cell.
1383 .I sc
1384 prompts for the expression on the top line.
1385 The usual way to enter a number into a cell is to type ``='',
1386 then enter the number in response to the prompt on the top line.
1387 The quick numeric entry option, enabled through the
1388 .B \-n
1389 option or
1390 .I ^T
1391 command, shows the prompt when you enter the first digit of a number
1392 (you can skip typing ``='').
1393 If you want to begin entering an expression in the current cell,
1394 but you want to start out in navigate mode (e.g. to enter cell
1395 addresses, or sums of ranges using ``@sum''), use the ``+''
1396 command instead (see below).
1397 .\" ----------
1398 .TP
1399 .B <
1400 Enter a label string into the current cell
1401 to be flushed left against the left edge of the cell.
1402 .\" ----------
1403 .IP \fB\\\\\fP
1404 Enter a label string into the current cell
1405 to be centered in the column.
1406 .\" ----------
1407 .TP
1408 .B >
1409 Enter a label string into the current cell
1410 to be flushed right against the right edge of the cell.
1411 .\" ----------
1412 .TP
1413 .B {
1414 Left justify the string in the current cell.
1415 .\" ----------
1416 .TP
1417 .B |
1418 Center the string in the current cell.
1419 .\" ----------
1420 .TP
1421 .B }
1422 Right justify the string in the current cell.
1423 .\" ----------
1424 .TP
1425 .B F
1426 Enter a format string into the current cell.
1427 This format string overrides the precision
1428 specified with the
1429 .I f
1430 command unless
1431 .I &
1432 is present in the fractional part of the format
1433 string (see below).
1434 The format only applies to numeric values.
1435 There are two types of format strings allowed:
1436 standard numeric and date.
1437 (Note: these format strings may also be used with the
1438 .I f
1439 command to create user-defined format types.)
1440 The following characters can be used to build
1441 a standard numeric format string:
1442 .RS
1443 .TP
1444 .BR #
1445 Digit placeholder.
1446 If the number has fewer digits on either
1447 side of the decimal point than there are
1448 `#' characters in the format, the extra `#'
1449 characters are ignored.
1450 The number is rounded to the number of digit
1451 placeholders as there are to the right
1452 of the decimal point.
1453 If there are more digits in the number than
1454 there are digit placeholders on the left side
1455 of the decimal point, then those digits
1456 are displayed.
1457 .TP
1458 .BR 0
1459 Digit placeholder.
1460 Same as for `#' except that the number
1461 is padded with zeroes on either side of the decimal point.
1462 The number of zeroes used in padding is determined by the
1463 number of digit placeholders after the `0' for digits on
1464 the left side of the decimal point and by the number of
1465 digit placeholders before the `0' for digits on the right
1466 side of the decimal point.
1467 .TP
1468 .BR .
1469 Decimal point.
1470 Determines how many digits are placed on
1471 the right and left sides of the decimal point in the number.
1472 If
1473 .I locale
1474 is set, the decimal point for the user's current locale
1475 will be used when formatting a number.
1476 Note that numbers smaller than 1 will begin with a decimal
1477 point if the left side of the decimal point contains only
1478 a `#' digit placeholder.
1479 Use a `0' placeholder to get a leading zero in decimal formats.
1480 .TP
1481 .BR %
1482 Percentage.
1483 For each `%' character in the format, the actual
1484 number gets multiplied by 100 (only for purposes of formatting
1485 -- the original number is left unmodified) and the `%' character
1486 is placed in the same position as it is in the format.
1487 .TP
1488 .BR ,
1489 Thousands separator.
1490 The presence of a `,' in the format
1491 (multiple commas are treated as one) will cause the number
1492 to be formatted with a `,' separating each set of three digits
1493 in the integer part of the number with numbering beginning
1494 from the right end of the integer.
1495 If
1496 .I locale
1497 is set, the thousands separator for the user's current
1498 locale will be used in place of the comma.
1499 If the environment variable LC_ALL is unset, unrecognized,
1500 or is set to ``POSIX'' or ``C'', any commas in the format
1501 string will be ignored.
1502 .TP
1503 .BR &
1504 Precision.
1505 When this character is present in the fractional
1506 part of the number, it is equivalent to a number of 0's equal
1507 to the precision specified in the column format command.
1508 For example, if the precision is 3, `&' is equivalent to `000'.
1509 .TP
1510 .BR \e
1511 Quote.
1512 This character causes the next character to be
1513 inserted into the formatted string directly with no
1514 special interpretation.
1515 .TP
1516 .BR E-\ E+\ e-\ e+
1517 Scientific format.
1518 Causes the number to be formatted in scientific notation.
1519 The case of the `E' or `e' given is preserved.
1520 If the format uses a `+', then the sign is
1521 always given for the exponent value.
1522 If the format uses a `-', then the sign is
1523 only given when the exponent value is negative.
1524 Note that if there is no digit placeholder
1525 following the `+' or `-', then that part of the
1526 formatted number is left out.
1527 In general, there should be one or more digit
1528 placeholders after the `+' or `-'.
1529 .TP
1530 .BR ;
1531 Format selector.
1532 Use this character to separate the format
1533 into two distinct formats.
1534 The format to the left of the `;' character
1535 will be used if the number given is zero or positive.
1536 The format to the right of the `;' character is
1537 used if the number given is negative.
1538 .RE
1539 .IP
1540 Some example formats are integer (``0'' or ``#''),
1541 fixed (``0.00''), percentage (``0%'' or ``0.00%''),
1542 scientific (``0.00E+00''),
1543 and currency (``$#,0.00;($#,0.00)'').
1544 .IP
1545 Date format strings are identified by the
1546 presence of a ^D in the first postition.
1547 If this is present, the remainder of the
1548 string is passed to the strftime() function,
1549 and therefore uses the same conversion
1550 specifiers as strftime().
1551 For more information on conversion specifiers
1552 for date format strings, see the man page
1553 for strftime(3).
1554 .\" ----------
1555 .PP
1556 Strings you enter must start with ".
1557 You can leave off the trailing " and
1558 .I sc
1559 will add it for you.
1560 You can also enter a string expression
1561 by backspacing over the opening " in the prompt.
1562 .\" ----------
1563 .TP
1564 .B e
1565 Edit the value associated with the current cell.
1566 This is identical to ``=''
1567 except that the command line starts out containing
1568 the old numeric value or expression associated with the cell.
1569 The editing in this mode is vi-like.
1570 .RS
1571 .TP
1572 .BR ^H
1573 Move back a character
1574 .TP
1575 .BR "^V, v"
1576 Enter navigate mode.
1577 This mode allows you to navigate the spreadsheet
1578 while editing a command.
1579 When in navigate mode,
1580 .I v
1581 will insert the
1582 numeric value of the current cell, if any,
1583 into the command line, instead, while
1584 .I ^V
1585 will return to the previous mode (like
1586 the ESCAPE key).
1587 .TP
1588 .BR ^W
1589 Insert the expression attached to the current
1590 cell into the command line.
1591 If there is none, the result is ``?''.
1592 This only works while in navigate mode.
1593 .TP
1594 .BR ^A
1595 In navigate mode, go to cell
1596 .IR A0 .
1597 When not in navigate mode, jump to the
1598 beginning of the line instead.
1599 .TP
1600 .BR ^E
1601 Jump to the end of the line.
1602 Unlike ``$'' (below), this can also be used from insert mode.
1603 .TP
1604 .BR TAB
1605 If the character immediately preceding the
1606 cursor is alphanumeric or ``_'',
1607 .SM TAB
1608 tries to find a match in the list of range names,
1609 and if one is found, the name will be completed
1610 on the command line.
1611 If there are multiple matches, pressing
1612 .SM TAB
1613 repeatedly without any other intervening keys
1614 will cycle through all of the valid matches.
1615 If the character immediately preceding the cursor
1616 is not alphanumeric or ``_'',
1617 .SM TAB
1618 defines a range of cells via the cursor control commands or the arrow keys.
1619 Pressing
1620 .SM TAB
1621 automatically switches
1622 .I sc
1623 to navigate mode if you haven't already done so using the
1624 .I ^V
1625 command, and the range is highlighted,
1626 starting at the cell where you typed
1627 .SM TAB,
1628 and continuing through the current cell.
1629 Pressing
1630 .SM TAB
1631 again causes the highlighted range to be inserted into
1632 the command line, the highlighting to be turned off,
1633 and the previous mode to be restored.
1634 This is most useful for defining ranges to functions such as
1635 .IR @sum ().
1636 Pressing ``)'' acts just like typing the
1637 .SM TAB
1638 key the second time and adds the closing ``)''.
1639 Note that when you give a range command,
1640 if the first argument to the command is a range,
1641 you don't need to press the first
1642 .SM TAB
1643 to begin defining a range starting with the current cell.
1644 .TP
1645 .BR :
1646 Synonym for
1647 .SM TAB,
1648 when in navigate mode.
1649 .TP
1650 .BR "` '"
1651 In navigate mode, go to marked cell.
1652 .TP
1653 .BR *
1654 In navigate mode, go to note linked to current cell.
1655 .TP
1656 .BR +
1657 Forward through history (same as j)
1658 .TP
1659 .BR -
1660 Backward through history (same as k)
1661 .TP
1662 .BR ESC
1663 Done editing
1664 .TP
1665 .BR CR
1666 Save.
1667 When in navigate mode, insert the name of the current
1668 cell (the one at the cell cursor) into the command line.
1669 This is useful when entering expressions
1670 which refer to other cells in the table.
1671 .TP
1672 .BR $
1673 Goto last column
1674 .TP
1675 .BR %
1676 Goto matching parenthesis
1677 .TP
1678 .BR .
1679 Insert current dot buffer.
1680 When in navigate mode, this is a synonym for : or
1681 .SM TAB.
1682 .TP
1683 .BR ;
1684 Repeat the last f, F, t, or T command.
1685 .TP
1686 .BR ,
1687 Repeat the last f, F, t, or T command,
1688 but in the reverse direction.
1689 .TP
1690 .BR ~
1691 Change the case of the character under the cursor.
1692 .TP
1693 .BR /
1694 Search backwards for a string in the history
1695 .RS
1696 \fBESC\fP edit the string you typed
1697 .br
1698 \fBCR\fP search
1699 .br
1700 \fB^H\fP backspace
1701 .RE
1702 .TP
1703 .BR ?
1704 Search forward for a string in the history (see ``/'' above)
1705 .TP
1706 .BR 0
1707 Goto column 0
1708 .TP
1709 .BR B
1710 Move back a word.
1711 Like
1712 .IR b ,
1713 except words are space delimited only.
1714 .TP
1715 .BR C
1716 Change to end of line (delete first, then enter insert mode)
1717 .TP
1718 .BR D
1719 Delete to end of line
1720 .TP
1721 .BR F
1722 Find the next char typed, moving backwards in the line
1723 .TP
1724 .BR G
1725 Go to the end of history, i.e., to the line being currently entered
1726 .TP
1727 .BR I
1728 Insert at column 0; ESC revert back to edit mode
1729 .TP
1730 .BR N
1731 Repeat the last search in the opposite direction
1732 .TP
1733 .BR P
1734 Insert the most recently deleted text before the cursor
1735 .TP
1736 .BR R
1737 Replace mode; ESC revert back to edit mode
1738 .TP
1739 .BR T
1740 Goto a char, moving backwards in the line
1741 .TP
1742 .BR W
1743 Forward a word.
1744 Like
1745 .IR w ,
1746 except words are space delimited only.
1747 .TP
1748 .BR X
1749 Delete the char to the left
1750 .TP
1751 .BR a
1752 Append after cursor; ESC revert back to edit mode
1753 .TP
1754 .BR b
1755 Move back a word
1756 .TP
1757 .BR c
1758 Change mode; ESC revert back to edit mode.
1759 In navigate mode, insert color range which includes
1760 the current cell.
1761 .TP
1762 .BR d
1763 Delete ...
1764 .RS
1765 \fB0\fP delete to beginning of line\br
1766 .br
1767 \fB$\fP delete to end of line\br
1768 .br
1769 \fBb\fP back word\br
1770 .br
1771 \fBe\fP delete to end of word\br
1772 .br
1773 \fBf\fP forward (right)\br
1774 .br
1775 \fBh\fP back char\br
1776 .br
1777 \fBl\fP forward\br
1778 .br
1779 \fBt\fP delete forward up to a given char (next char typed)\br
1780 .br
1781 \fBw\fP delete next word forward\br
1782 .RE
1783 .TP
1784 .BR e
1785 Forward to next end-of-word
1786 .TP
1787 .BR f
1788 Find the next char typed.
1789 In navigate mode, insert the outer frame range which
1790 includes the current cell.
1791 .TP
1792 .BR g
1793 In navigate mode, allows you to `goto' a cell or range,
1794 just like the regular
1795 .I goto
1796 command.
1797 Ignored in edit, insert or replace modes.
1798 .TP
1799 .BR h
1800 Move left a char
1801 .TP
1802 .BR i
1803 Insert before cursor; ESC revert back to edit mode
1804 .TP
1805 .BR j
1806 Forward through history (same as +)
1807 .TP
1808 .BR k
1809 Backward through history (same as -)
1810 .TP
1811 .BR l
1812 Move right a char
1813 .TP
1814 .BR n
1815 Repeat the last search (find the next match)
1816 .TP
1817 .BR o
1818 When highlighting a range in navigate mode, move
1819 to the opposite corner of the highlighted range.
1820 .TP
1821 .BR p
1822 Insert the most recently deleted text after the cursor
1823 .TP
1824 .BR q
1825 Stop editing
1826 .TP
1827 .BR r
1828 Replace char.
1829 In navigate mode, insert the inner frame range which
1830 includes the current cell.
1831 .TP
1832 .BR s
1833 Delete current char and enter insert mode (stands for substitute)
1834 .TP
1835 .BR t
1836 Goto a char
1837 .TP
1838 .BR u
1839 Undo
1840 .TP
1841 .BR w
1842 Forward a word
1843 .TP
1844 .BR x
1845 Delete the current char (moving to the right)
1846 .TP
1847 .BR y
1848 Copies to the delete buffer without deleting.
1849 Use like d (above).
1850 .RE
1851 .\" ----------
1852 .TP
1853 .B E
1854 Edit the string associated with the current cell.
1855 This is identical to ``<'', ``\\'', or ``>''
1856 except that the command line starts out containing
1857 the old string value or expression associated with the cell.
1858 SEE
1859 .I e
1860 ABOVE.
1861 .\" ----------
1862 .PP
1863 To enter and edit a cell's number part, use the ``='', ``+'', and
1864 .I e
1865 commands.
1866 To enter and edit a cell's string part, use the ``<'', ``\\'', ``>'', and
1867 .I E
1868 commands.
1869 See the sections below on numeric and string
1870 expressions for more information.
1871
1872 Note that the descriptions of the ``+'' and ``-'' commands below
1873 may seem very confusing at first, but once they're understood,
1874 they can facilitate the rapid entry of expressions which add and
1875 subtract large numbers of cells and sums of ranges of cells, so read
1876 them over carefully several times until you understand them.
1877 .\" ----------
1878 .IP \fB"\fP
1879 Specify a named buffer for the next
1880 yank/delete/pull command.
1881 Buffers are named with a single character.
1882 Buffers
1883 .RI `` a ''
1884 through
1885 .RI `` z ''
1886 are general purpose buffers,
1887 buffers
1888 .RI `` 1 ''
1889 through
1890 .RI `` 9 ''
1891 hold the last nine deletions,
1892 with buffer
1893 .RI `` 1 ''
1894 being the most recent,
1895 and buffer
1896 .RI `` 0 ''
1897 holds the last cell or range yanked.
1898 Buffer
1899 .RI `` """" ''
1900 is the default buffer, which holds the last
1901 cell or range that was deleted or yanked.
1902 .\" ----------
1903 .TP
1904 .B x
1905 Clear the current cell.
1906 Deletes the numeric value, label string, and/or
1907 numeric or string expression.
1908 You can prefix this command with a count of the
1909 number of cells on the current row to clear.
1910 The current column is used if column
1911 recalculation order is set.
1912 Cells cleared with this command may be recalled
1913 with any of the
1914 .I pull
1915 commands (see below).
1916 .\" ----------
1917 .TP
1918 .BI m x
1919 Mark the current cell.
1920 .I sc
1921 will prompt for a lowercase letter to
1922 be used as a mark specifier.
1923 Marked cells may be used as the source for the
1924 .I copy
1925 command, or as the target of a
1926 .I `
1927 or
1928 .I '
1929 (go to marked cell) command.
1930 .\" ----------
1931 .TP
1932 .BI c x
1933 Copy a marked cell to the current cell, adjusting row and
1934 column references in its numeric or string expression, if any.
1935 .I sc
1936 will prompt for the name of the cell to be copied, which may
1937 be a lowercase letter specified previously with the
1938 .I m
1939 command, a digit 1-9 to reference one of the last nine edited
1940 cells (0 will reference the last cell in which an edit was
1941 begun, regardless of whether the edit was completed or not), or
1942 .RI `` . ''
1943 to reference the current cell, which, as a special case, is to
1944 be used as a source rather than a destination, and is to be
1945 copied into a range which includes the current cell.
1946 When
1947 .RI `` . ''
1948 is specified, the current cell is set as the default source
1949 range for the range copy
1950 .RI ( rc )
1951 command, and then the
1952 .I copy
1953 command is entered into the command line and
1954 .I sc
1955 switches to navigate mode.
1956 Moving the cell cursor will then highlight the destination
1957 range.
1958 After the desired range is highlighted, press
1959 .SM RETURN
1960 to execute the copy.
1961 .\" ----------
1962 .TP
1963 .B +
1964 If not in numeric mode, add the current numeric argument
1965 (default 1) to the value of the current cell.
1966 The current value of the cell must not be an expression.
1967 In numeric mode,
1968 .I +
1969 switches to insert mode and appends a ``+'' to the current
1970 expression or value, if any, which makes it easy to add to
1971 existing data.
1972
1973 In navigate mode,
1974 .I +
1975 inserts the current cell address into the line, followed
1976 by another
1977 .IR + ,
1978 and
1979 .I sc
1980 remains in navigate mode, unless a range is highlighted.
1981 If a range is highlighted and the character immediately
1982 preceding the cursor is a ``+'' or ``-'',
1983 or the cursor is at the beginning of an empty ``let''
1984 expression, the string ``@sum('' will be
1985 inserted, followed by the highlighted range, followed
1986 by ``)+''.
1987 If a range is highlighted and the character immediately
1988 preceding the cursor is not a ``+'' or ``-'', and the
1989 cursor is not at the beginning of an empty ``let''
1990 expression, the highlighted range will be inserted,
1991 followed by ``)+''.
1992 .\" ----------
1993 .TP
1994 .B -
1995 If not in numeric mode, subtract the current numeric
1996 argument (default 1) from the value of the current cell.
1997 The current value of the cell must not be an expression.
1998 In numeric mode,
1999 .I -
2000 switches to insert mode and appends a ``-'' to the current
2001 expression or value, if any, which makes it easy to subtract
2002 from existing data.
2003
2004 In navigate mode,
2005 .I -
2006 inserts the current cell address into the line, followed
2007 by another
2008 .IR - ,
2009 and
2010 .I sc
2011 remains in navigate mode, unless a range is highlighted.
2012 If a range if highlighted and the character immediately
2013 preceding the cursor is a ``+'' or ``-'',
2014 or the cursor is at the beginning of an empty ``let''
2015 expression, the string ``@sum('' will be
2016 inserted, followed by the highlighted range, followed
2017 by ``)-''.
2018 If a range is highlighted and the character immediately
2019 preceding the cursor is not a ``+'' or ``-'', and the
2020 cursor is not at the beginning of an empty ``let''
2021 expression, the highlighted range will be inserted,
2022 followed by ``)-''.
2023 .\" ----------
2024 .TP
2025 .B RETURN
2026 If you are not editing a cell (top line is empty),
2027 pressing
2028 .SM RETURN
2029 will make
2030 .I sc
2031 enter insert mode.
2032 At this point you may type any valid command or press
2033 .B ESC
2034 once to edit.
2035 .\" ==========
2036 .SS "File Commands"
2037 .\" ----------
2038 \0 \" exactly one blank line (hard to get)
2039 .PD 0
2040 .TP
2041 .B G
2042 Get a new database from a file.
2043 If encryption is enabled,
2044 the file is decrypted before it is loaded into the spreadsheet.
2045 .PD
2046 .\" ----------
2047 .TP
2048 .B P
2049 Put the current database into a file.
2050 If encryption is enabled,
2051 the file is encrypted before it is saved.
2052 .\" ----------
2053 .TP
2054 .B ZZ
2055 Save the current database into a file if
2056 it has been modified, and then quit.
2057 This is like the
2058 .I P
2059 command followed by the
2060 .I q
2061 command, except that the default filename will
2062 be used instead of prompting you for one, and
2063 the file will only be saved if it was modified.
2064 If there is no default filename, an error message
2065 will be displayed, and no action taken.
2066 .\" ----------
2067 .TP
2068 .B W
2069 Write a listing of the current database into a file
2070 in a form that matches its appearance on the screen.
2071 This differs from the
2072 .I Put
2073 command in that its files are intended to be reloaded with
2074 .IR Get ,
2075 while
2076 .I Write
2077 produces a file for people to look at.
2078 Hidden rows or columns are not shown when the data is printed.
2079 .\" ----------
2080 .TP
2081 .B T
2082 Write a listing of the current database to a file,
2083 but include delimiters suitable for processing by the
2084 .IR tbl ,
2085 .IR LaTeX ,
2086 or
2087 .I TeX
2088 table processors.
2089 The delimiters are controlled by the
2090 .I tblstyle
2091 option. See
2092 .I Set
2093 above.
2094 The delimiters are a colon\ (:) for style
2095 .IR 0
2096 or
2097 .IR tbl
2098 and an ampersand\ (&) for style
2099 .IR latex
2100 or
2101 .IR tex .
2102 .\" ----------
2103 .PP
2104 With the
2105 .IR Put ,
2106 .IR Write ,
2107 and
2108 .I Table
2109 commands, the optional range argument writes a subset
2110 of the spreadsheet to the output file.
2111 .\" ----------
2112 .PP
2113 With the
2114 .I Write
2115 and
2116 .I Table
2117 commands, if you try to write to the last file used with the
2118 .I Get
2119 or
2120 .I Put
2121 commands, or the file specified on the command line when
2122 .I sc
2123 was invoked, you are asked to confirm that the
2124 (potentially) dangerous operation is really what you want.
2125 .\" ----------
2126 .PP
2127 The three output commands,
2128 .IR Put ,
2129 .IR Write ,
2130 and
2131 .IR Table ,
2132 can pipe their (unencrypted only) output to a program.
2133 To use this feature,
2134 enter ``| program'' to the prompt asking for a filename.
2135 For example, to redirect the output of the
2136 .I Write
2137 command to the printer,
2138 you might enter ``| lpr -p''.
2139 .\" ----------
2140 .TP
2141 .B M
2142 Merge the database from the named file into the current database.
2143 Values and expressions defined in the named file
2144 are read into the current spreadsheet overwriting
2145 the existing entries at matching cell locations.
2146 .\" ----------
2147 .TP
2148 .B R
2149 Run macros.
2150 There are two different kinds of macros that can be used with
2151 .IR sc :
2152 simple macros, which are stored in plain text files,
2153 and advanced macros, which are executable files, and
2154 which can be written in the language of your choice.
2155 Advanced macros are only available on systems that support pipes.
2156
2157 Simple macros are interpreted by
2158 .IR sc 's
2159 internal parser, and use the same commands
2160 used to enter data and perform other operations
2161 (the single key commands are shortcuts which switch
2162 to input mode after first entering the beginning of
2163 the full command for you).
2164 These are also the same commands found in
2165 .I sc
2166 files created with the Put command.
2167 Since
2168 .I sc
2169 files are saved as ASCII files,
2170 it is possible to use them as primitive macro definition files.
2171 The
2172 .I Run
2173 command makes this easier.
2174 It's like the
2175 .I Merge
2176 command,
2177 but prints a saved path name as the start of the filename to merge in.
2178 The string to use is set with the
2179 .I Define
2180 command.
2181 To write macros, you must be familiar with the file format written by the
2182 .I Put
2183 command.
2184
2185 Advanced macros use executable files that are started by
2186 .I sc
2187 as a child process with stdin and stdout redirected back to
2188 .I sc
2189 for bidirectional communication.
2190 Special commands are available for requesting information
2191 such as cell contents, formatting information, or the
2192 current location of the cell cursor.
2193 Commands are written to stdout, and responses are read from
2194 stdin.
2195 To use advanced macros, the filename must be preceded by
2196 a | (the pipe symbol), and the file must be executable.
2197 If the pathname set with the
2198 .I Define
2199 command begins with a |, all files in that path will
2200 be executed as advanced macros.
2201 It is also possible to include a filename as
2202 part of the path when using advanced macros,
2203 which allows you to put multiple macros in a single
2204 file, and use the
2205 .I Run
2206 command to add command line arguments or options
2207 to determine which macro should be run.
2208 Advanced macros are relatively new, and
2209 documentation is still incomplete.
2210 This feature will probably be enhanced in future releases.
2211 .\" ----------
2212 .TP
2213 .B A
2214 Specify a macro to be automatically run whenever
2215 the current sheet is reloaded from a file.
2216 .\" ----------
2217 .TP
2218 .B D
2219 Define a path for the
2220 .I Run
2221 command to use (see above).
2222 .\" ----------
2223 .PP
2224 All file operations take a filename as the first argument
2225 to the prompt on the top line.
2226 The prompt supplies a " to aid in typing in the filename.
2227 The filename can also be obtained from a cell's label string
2228 or string expression.
2229 In this case, delete the leading " with the backspace key
2230 and enter a cell name such as
2231 .I a22
2232 instead.
2233 If the resulting string starts with ``|'',
2234 the rest of the string is interpreted as a
2235 .SM UNIX
2236 command, as above.
2237 .\" ==========
2238 .SS "Row and Column Commands"
2239 .\" ----------
2240 These are two-letter commands which can be used on
2241 either rows or columns. The exceptions are the
2242 .I f
2243 command, which only works on columns, and therefore
2244 doesn't require a second letter, and the
2245 .I p
2246 command which, in addition to operating on rows or columns,
2247 has several other options for merging the data in directly,
2248 without opening up a new row or column.
2249 There are also a few special cases where pressing the same
2250 letter twice will affect only the current cell instead of
2251 a row or column (except for
2252 .IR ZZ ,
2253 which is a special case all its own).
2254 .PP
2255 In all of the remaining cases, the second letter of the
2256 command will be either
2257 .I r
2258 or
2259 .IR c ,
2260 depending on whether the operation should be performed on
2261 rows or columns, respectively (additional options for the
2262 .I p
2263 command and the double letter cases are listed below).
2264 A small menu lists the choices for the second letter
2265 when you type the first letter of one of these commands.
2266 .PP
2267 Alternatively, you may define a range of rows or columns
2268 by moving the cell cursor, either a cell at a time, or
2269 by pages (roughly 1/2 screen, unless the
2270 .I pagesize
2271 option has been set), but this only works for the
2272 .IR d ,
2273 .IR y ,
2274 and
2275 .I Z
2276 commands.
2277 Vertical cursor movement will begin highlighting rows,
2278 and horizontal movement will highlight columns.
2279 Pressing the
2280 .SM RETURN
2281 key will then perform the chosen operation
2282 on the specified rows/columns.
2283 .PP
2284 Commands which copy cells also modify the row and
2285 column references in affected cell expressions.
2286 The references may be frozen by using the
2287 .I @fixed
2288 operator or using the
2289 .I $
2290 character in the reference to the cell (see below).
2291 Commands which create new rows or columns will include
2292 all newly created cells in the same ranges (named, framed,
2293 color, or those used in expressions) as their counterparts
2294 in the current row or column.
2295 This can sometimes be a significant factor when deciding
2296 whether to use
2297 .IR ir / ic " or " or / oc .
2298 .\" ----------
2299 .TP
2300 .B "ir, ic"
2301 Insert a new row (column) by moving the row (column)
2302 containing the cell cursor, and all following
2303 rows (columns), down (right) one row (column).
2304 The new row (column) is empty.
2305 Inserting rows while the cell cursor is in a framed
2306 range will only effect rows in that range, leaving
2307 all rows to the left and right untouched.
2308 .\" ----------
2309 .TP
2310 .B "or, oc"
2311 Open a new row (column).
2312 These commands work like the
2313 .I ir
2314 and
2315 .I ic
2316 commands, except that the new row (column) will be
2317 inserted
2318 .I after
2319 the current row (column) instead of before it.
2320 .\" ----------
2321 .TP
2322 .B "ar, ac"
2323 Append a new row (column) immediately following
2324 the current row (column).
2325 It is initialized as a copy of the current one.
2326 Appending rows while the cell cursor is in a framed
2327 range will only effect rows in that range, leaving
2328 all rows to the left and right untouched.
2329 .\" ----------
2330 .TP
2331 .B "dr, dc, dd"
2332 Delete the current row (column).
2333 .I dd
2334 deletes the current cell (i.e., it is a synonym for
2335 .IR x ).
2336 Deleting rows while the cell cursor is in a framed
2337 range will only effect rows in that range, leaving
2338 all rows to the left and right untouched.
2339 .\" ----------
2340 .TP
2341 .B "yr, yc, yy"
2342 Yank a copy of the current row (column) into the
2343 delete buffer without actually deleting it.
2344 .I yy
2345 yanks the current cell (similar to
2346 .IR x ,
2347 but without actually deleting the contents of the cell).
2348 Yanking rows while the cell cursor is in a framed
2349 range will only copy the portion of each row contained
2350 in that range, while ignoring everything outside the
2351 range.
2352 .\" ----------
2353 .TP
2354 .B "pr, pc, pp, pm, px, pt, pC, p."
2355 Pull deleted rows/columns/cells back into the spreadsheet.
2356 The last set of cells that was deleted or yanked is put
2357 back into the spreadsheet at the current location.
2358 .I pr
2359 inserts enough rows to hold the data.
2360 .I pc
2361 inserts enough columns to hold the data.
2362 .I pp
2363 (paste) does not insert rows or columns;
2364 it overwrites the cells beginning at the
2365 current cell cursor location.
2366 .I pm
2367 (merge) merges the cells in at the current cell
2368 cursor location, but does not erase the destination
2369 range first like
2370 .IR pp .
2371 The difference between
2372 .I pp
2373 and
2374 .I pm
2375 is similar to the difference between the
2376 .I Get
2377 and
2378 .I Merge
2379 commands.
2380 .I pf
2381 (format) works like
2382 .I pm
2383 except that only cell formatting information is merged in,
2384 leaving the actual data untouched.
2385 This makes it easy to copy cell formats from one part of the
2386 spreadsheet to another, such as when expanding an existing
2387 spreadsheet file.
2388 .I px
2389 (exchange) copies the contents of the delete buffer into
2390 the range beginning at the current cell cursor location,
2391 while simultaneously copying the contents of this range
2392 back into the delete buffer, replacing its current contents.
2393 .I pt
2394 (transpose) overwrites the cells beginning at the current
2395 cell cursor location like
2396 .I pp,
2397 but transposes rows for columns and vice versa.
2398 .I pC
2399 (copy) works like
2400 .I pp,
2401 except that all cell references are adjusted in
2402 the same way that they are for the
2403 .I copy
2404 command.
2405 .I p.
2406 is the same as
2407 .I pC,
2408 except that it switches to navigate mode and allows
2409 you to define the destination range to be used.
2410 This works like the
2411 .I copy
2412 command in that if the source range (the contents of
2413 the delete buffer) is a single row, column, or cell,
2414 multiple copies may be made.
2415 .\" ----------
2416 .TP
2417 .B "vr, vc, vv"
2418 Remove expressions from the affected rows (columns),
2419 leaving only the values which were in the cells
2420 before the command was executed.
2421 When used in a framed range,
2422 .I vr
2423 only affects the portion of the the row inside the range,
2424 leaving the rest of the row unchanged.
2425 .I vv
2426 only affects the contents of the current cell.
2427 .\" ----------
2428 .TP
2429 .B "Zr, Zc, ZZ"
2430 Hide (``zap'') the current row (column).
2431 This keeps a row (column) from being displayed
2432 but keeps it in the data base.
2433 The status of the rows and columns is saved with
2434 the data base so hidden rows and columns will
2435 still be hidden when you reload the spreadsheet.
2436 Hidden rows or columns are not printed by the
2437 .I W
2438 command.
2439 The
2440 .IR ZZ
2441 command is a special case.
2442 It does not hide anything.
2443 Instead, the file will be saved, if modified, and
2444 .I sc
2445 will exit.
2446 See
2447 .I ZZ
2448 above, under
2449 .I "File Commands."
2450 .\" ----------
2451 .TP
2452 .B "sr, sc"
2453 Show hidden rows (columns).
2454 Enter a range of rows (columns) to be revealed.
2455 The default is the first range of rows (columns) currently hidden.
2456 This command ignores the repeat count, if any.
2457 .\" ----------
2458 .TP
2459 .B f
2460 Set the output format to be used for printing the
2461 numeric values in each cell in the current column.
2462 This command has only a column version (no second letter).
2463 You may change the column width by pressing the
2464 .IR h ,
2465 .IR < ,
2466 or cursor left key to reduce it, or the
2467 .IR l ,
2468 .IR > ,
2469 or cursor right key to increase it.
2470 Likewise, you may change the precision (the
2471 number of digits to follow decimal points)
2472 by pressing the
2473 .IR j ,
2474 .IR - ,
2475 or cursor down key to reduce it, or the
2476 .IR k ,
2477 .IR + ,
2478 or cursor up key to increase it.
2479 You may also change the format type for the
2480 column by pressing any digit.
2481 If the
2482 .I f
2483 command is preceded by a numeric argument,
2484 that argument will determine how many columns should
2485 be changed, beginning with the current column, and
2486 in the case of incrementing or decrementing the width
2487 or precision of the columns, each column will be
2488 incremented or decremented separately, regardless of
2489 its initial values.
2490 Several formatting operations may be performed in sequence.
2491 To leave the formatting command, simply press
2492 .BR ESC ,
2493 .IR ^G ,
2494 .IR q ,
2495 or
2496 .SM RETURN .
2497 .IP
2498 Alternatively, you may press
2499 .BR SPACE
2500 to get the
2501 .I format
2502 command in the top line and enter all three values directly.
2503 In order, these are:
2504 the total width in characters of the column,
2505 the precision, and the format type.
2506 Format types are 0 for fixed point, 1 for scientific
2507 notation, 2 for engineering notation, 3 for dates with
2508 a two digit year, and 4 for dates with a four digit year.
2509 Values are rounded off to the least significant digit displayed.
2510 The total column width affects displays of strings as well as numbers.
2511 A preceding count can be used to affect more than one column.
2512 .IP
2513 You can also create your own format types by pressing
2514 .I =
2515 after the
2516 .I f
2517 command, followed by any digit (see the
2518 .I F
2519 command above under
2520 .I "Cell Entry and Editing Commands"
2521 for a description of how to build a format string).
2522 Format numbers 0 through 4 will supersede the
2523 built-in format types, while numbers 5 through 9
2524 will supplement them.
2525 User defined format types may be used in
2526 the same way as the built-in types.
2527 For example, the command
2528 .RS
2529 .IP
2530 .I "format 5 = ""#,0.& ;(#,0.&)"""
2531 .RE
2532 .IP
2533 will define a currency format which may then be
2534 assigned to column C, for example, with the command
2535 .RS
2536 .IP
2537 .I format C 10 2 5
2538 .RE
2539 .\" ----------
2540 .TP
2541 .B "@myrow, @mycol"
2542 Are functions that return the row or column
2543 of the current cell respectively.
2544 ex: The cell directly above a cell in the D
2545 column could then be accessed by @nval("d",@myrow-1).
2546 NOTE: @myrow and @mycol can't be used in specifying ranges.
2547 .\" ----------
2548 .TP
2549 .B "@lastrow, @lastcol"
2550 These return the last row and column of the spreadsheet, respectively.
2551 They are useful for macros designed to default to the
2552 whole spreadsheet.
2553 .\" ==========
2554 .SS "Range Commands"
2555 .\" ----------
2556 Range operations affect a rectangular region on the screen
2557 defined by the upper left and lower right cells in the region.
2558 All of the commands in this class begin with ``r'';
2559 the second letter of the command indicates which command.
2560 A small menu lists the choices for the second letter when you type ``r''.
2561 .I sc
2562 prompts for needed parameters for each command.
2563 Phrases surrounded by square brackets in the prompt are
2564 informational only and may be erased with the backspace key.
2565 .\" ----------
2566 .PP
2567 Prompts requesting variable names may be satisfied
2568 with either an explicit variable name, such as
2569 .IR A10 ,
2570 or with a variable name previously defined in a
2571 .I rd
2572 command (see below).
2573 Range name prompts require either an explicit range such as
2574 .IR A10:B20 ,
2575 or a range name previously defined with a
2576 .I rd
2577 command.
2578 A default range shown in the second line
2579 is used if you omit the range from the command or press the
2580 .SM TAB
2581 key (see below).
2582 The default range can be changed by moving the cell cursor
2583 via the control commands
2584 .RI ( ^P " or " ^N )
2585 or the arrow keys.
2586 The cells in the default range are highlighted
2587 (using the terminal's standout mode, if available).
2588 .\" ----------
2589 .TP
2590 .B rx
2591 Clear a range.
2592 Cells cleared with this command will be saved in the
2593 delete buffer, and may be recalled with any of the
2594 .I pull
2595 commands.
2596 .\" ----------
2597 .TP
2598 .B ry
2599 Yank a range.
2600 Like
2601 .IR rx ,
2602 cells yanked with this command will be saved in the
2603 delete buffer, and may be recalled with any of the
2604 .I pull
2605 commands.
2606 This command differs from
2607 .IR rx ,
2608 however, in that the original cells will not be cleared.
2609 Although this command may be used to copy a range of
2610 cells, it treats all references as fixed.
2611 Use
2612 .I rc
2613 if you want references to be relative to the
2614 cell which contains them unless specified otherwise,
2615 either with the
2616 .I @fixed
2617 operator or using the
2618 .I $
2619 character in the reference to the cell.
2620 .\" ----------
2621 .TP
2622 .B rc
2623 Copy a source range to a destination range.
2624 The source and destination may be different sizes.
2625 The result is always one or more full copies of the source.
2626 Copying a row to a row yields a row.
2627 Copying a column to a column yields a column.
2628 Copying a range to anything yields a range.
2629 Copying a row to a column or a column to a
2630 row yields a range with as many copies of the
2631 source as there are cells in the destination.
2632 This command can be used to duplicate a
2633 cell through an arbitrary range by making
2634 the source a single cell range such as
2635 .IR b20:b20 .
2636
2637 If the source range is omitted (second argument),
2638 the source range from the last
2639 .I copy
2640 command will be used, unless a range is currently
2641 highlighted, in which case the highlighted range
2642 will be copied instead.
2643 If both the source range and destination range
2644 are omitted, the current cell will be used as
2645 the destination, unless a range is currently
2646 highlighted, in which case the highlighted range
2647 will serve as the destination, and the source
2648 range from the last
2649 .I copy
2650 command will be copied into that destination.
2651 .\" ----------
2652 .TP
2653 .B rm
2654 Move a source range to a destination range.
2655 This differs from deleting a range with
2656 .I rx
2657 and pulling it back in with
2658 .I pm
2659 in that any expressions that reference a cell
2660 in the range to be moved will reference the cell
2661 at its new address after the move.
2662 Unlike the
2663 .I rc
2664 command, the destination of a move is a single cell,
2665 which will be the upper lefthand corner of the
2666 source range after the move.
2667 .\" ----------
2668 .TP
2669 .B rv
2670 Values only.
2671 This command removes the expressions from a range of cells,
2672 leaving just the values of the expressions.
2673 .\" ----------
2674 .TP
2675 .B rs
2676 Sort a range.
2677 The rows in the specified range will be sorted according
2678 to criteria given in the form of a string of characters.
2679 This string, enclosed in double quotes, may comprise a
2680 single criterion or multiple criteria in decreasing order
2681 of precedence.
2682 Each criterion has three parts, all of which are mandatory.
2683 The first part is a single character, which must be either
2684 .I +
2685 or
2686 .IR - ,
2687 which specifies whether the sort should be done in ascending
2688 or descending order, respectively.
2689 The second part, which is also a single character, must be either
2690 .I #
2691 or
2692 .IR $ ,
2693 and is used to specify whether the sort should be based
2694 on the numeric portion or the string portion, respectively,
2695 of the cells being used for the comparison.
2696 The third part may be either one or two characters, and
2697 must be alphabetic (case insensitive), and specifies
2698 the column to be used when making the comparisons.
2699 This column must be in the range being sorted.
2700 Any number of criteria may be concatenated, and will
2701 be used in the order specified.
2702 If no criteria are specified, the default behavior is to sort
2703 in ascending order, first by string and then by number,
2704 using the leftmost column of the range being sorted.
2705 This is equivalent to specifying the sort criteria to be
2706 .RI """ +$a+#a """,
2707 where both
2708 .IR a 's
2709 are replaced by the name of the leftmost
2710 column of the range being sorted.
2711 .\" ----------
2712 .TP
2713 .B rf
2714 Fill a range with constant values
2715 starting with a given value and increasing by a given increment.
2716 Each row is filled before moving on to the
2717 next row if row order recalculation is set.
2718 Column order fills each column in the range
2719 before moving on to the next column.
2720 The start and increment numbers may be positive or negative.
2721 To fill all cells with the same value, give an increment of zero.
2722 .\" ----------
2723 .TP
2724 .B r{
2725 Left justify all strings in the specified range.
2726 .\" ----------
2727 .TP
2728 .B r}
2729 Right justify all strings in the specified range.
2730 .\" ----------
2731 .TP
2732 .B r|
2733 Center all strings in the specified range.
2734 .\" ----------
2735 .TP
2736 .B rd
2737 Use this command to assign a symbolic name to a single
2738 cell or a rectangular range of cells on the screen.
2739 The parameters are the name, surrounded by "",
2740 and either a single cell name such as
2741 .I A10
2742 or a range such as
2743 .IR a1:b20 .
2744 Names defined in this fashion are used by the program in future prompts,
2745 may be entered in response to prompts requesting a cell or range name,
2746 and are saved when the spreadsheet is saved with the
2747 .I Put
2748 command.
2749 Names defined may be any combination of alphanumeric
2750 characters and
2751 .RI ` _ '
2752 as long as the name isn't a valid cell address.
2753 Thus,
2754 .IR x ,
2755 .IR H2SO4 ,
2756 and
2757 .I 3rdDay
2758 are all valid names, but
2759 .I H2
2760 is not.
2761 .\" ----------
2762 .TP
2763 .B rl
2764 Use this command to lock the current cell or
2765 a range of cells, i.e. make them immune
2766 to any type of editing.
2767 A locked cell can't be changed in
2768 any way until it is unlocked.
2769 .\" ----------
2770 .TP
2771 .B rU
2772 This command is the opposite of the
2773 .I rl
2774 command and thus unlocks a locked cell and makes it editable.
2775 .\" ----------
2776 .TP
2777 .B rS
2778 This command shows lists of the currently defined
2779 range names, framed ranges, and color definitions
2780 and ranges, one after the other.
2781 The output of this command will be piped to
2782 .IR less .
2783 If the environment variable PAGER is set,
2784 its value is used in place of
2785 .IR less .
2786 .\" ----------
2787 .TP
2788 .B ru
2789 Use this command to undefine a previously defined range name.
2790 .\" ----------
2791 .TP
2792 .B rF
2793 Use this command to assign a value format string (see
2794 the ``F'' cell entry command) to a range of cells.
2795 .\" ----------
2796 .TP
2797 .B rr
2798 This command is used for creating, modifying,
2799 and deleting framed ranges.
2800 A framed range, is one which has a number of rows
2801 or columns specified at the top, bottom, left,
2802 and/or right (the frame) which must remain onscreen
2803 whenever the cell cursor is within that range.
2804 In other words, a frame consists of an outer range
2805 and an inner range, where the inner range is allowed
2806 to scroll within the outer range.
2807 Once a frame is defined, the inner range may be
2808 resized, but the outer range remains fixed unless
2809 rows or columns are added or deleted within the range.
2810
2811 When this command is invoked, you will be prompted for
2812 the type of frame-related action you would like to perform.
2813 You may select an option from the list by typing its
2814 first letter.
2815
2816 The options are
2817 .IR top ,
2818 .IR bottom ,
2819 .IR left ,
2820 .IR right ,
2821 .IR all ,
2822 and
2823 .I unframe.
2824 If you choose
2825 .IR top ,
2826 .IR bottom ,
2827 .IR left ,
2828 or
2829 .I right,
2830 you will be prompted for a range and number of rows/columns.
2831 The range may be omitted if the cell cursor is
2832 in a previously defined framed range, in which case
2833 that range's outer range will be used instead.
2834 The number of rows/columns will set or adjust the
2835 width of the corresponding side of the frame.
2836 If all of these widths are set to zero, the frame
2837 will be undefined (same as the unframe command).
2838
2839 If you choose
2840 .IR all ,
2841 you will be prompted for an outer range and an inner range,
2842 in which case the inner range will scroll within the outer
2843 range, and any rows or columns outside of the inner range,
2844 but inside the outer range will be part of the ``frame''
2845 that is to remain onscreen.
2846 The outer range may be omitted if the cell cursor is
2847 in a previously defined framed range, in which case
2848 the previously defined outer range will be used.
2849 However, if a single range is specified on the command line,
2850 while another range wholly contained within this range is
2851 highlighted, the specified range will be used as the
2852 outer range, and the highlighted range will be used as
2853 the inner range.
2854 If no range is specified on the command line, but a range
2855 is highlighted, and the highlighted range is wholly contained
2856 within a previously defined framed range, the highlighted
2857 range will be used as the inner range, and the previously
2858 defined outer range will be used as the outer range.
2859
2860 If you choose
2861 .IR unframe,
2862 you will be prompted for a range, and if the
2863 range is found in the list of frames, the frame
2864 will be deleted, and the framing will no longer
2865 be active (the specified range must be the outer
2866 range of the previously defined frame to be deleted).
2867 The range may be omitted if the cell cursor is
2868 in a previously defined framed range, in which case
2869 that range will be used by default.
2870
2871 Framed ranges may not be nested or overlapping.
2872 If you try to define a range that contains any cells
2873 in common with a previously defined framed range,
2874 an error message will be issued, and the frame
2875 will not be created.
2876 .\" ----------
2877 .TP
2878 .B rC
2879 This command defines a color range, and specifies a
2880 foreground/background pair to be used for that range.
2881 See "Color Commands" below for more information.
2882 .\" ==========
2883 .SS "Note Commands"
2884 .\" ----------
2885 A note is a cell or range of cells that can
2886 be jumped to quickly from another cell by
2887 creating a special link in that cell.
2888 The note may contain text explaining the
2889 contents of the cell containing the link,
2890 similar to a footnote, or it may simply be
2891 another part of the spreadsheet that is
2892 related to the cell in some way.
2893 When you press the `n' key, you will get a
2894 short prompt asking you whether you want
2895 to add or delete a note, or to ``show''
2896 (by highlighting) which cells on the
2897 screen have attached notes.
2898 .PP
2899 If a cell with an attached note contains
2900 numeric data, it will be preceded with an ``*''.
2901 If color is available and turned on, the ``*''
2902 will be displayed with color 4.
2903 Also, the note address will be displayed
2904 in curly braces on the top line, preceded by an ``*'',
2905 when the cell is current (e.g.
2906 .I {*AC30:AE43}
2907 or
2908 .I {*note1}
2909 for a named range).
2910 You may also use the
2911 .I *s
2912 (Note/Show) command to highlight all cells
2913 on the current screen with attached notes.
2914 .TP
2915 .B *a
2916 Add a note.
2917 This will bring up the addnote command
2918 in the top line, followed by the target address
2919 of the cell where you want the note added. You
2920 must then enter the cell or range where the note
2921 resides to add the note.
2922 If you omit the note address or range, the currently
2923 highlighted range, if any, will be used.
2924 Otherwise, the current cell will be used (you
2925 would, of course, want to move away from the
2926 cell in which the addnote command was invoked
2927 in the latter case).
2928 .\" ----------
2929 .TP
2930 .B *d
2931 Delete a note.
2932 If there is a note attached to the current
2933 cell, the link will be removed (deleted).
2934 The note itself will not be removed from
2935 the spreadsheet.
2936 If it is no longer needed, it must be deleted
2937 in a separate step.
2938 .\" ----------
2939 .TP
2940 .B *s
2941 Show all notes on the current screen.
2942 If there are any cells on the visible portion
2943 of the spreadsheet which contain attached
2944 notes, they will be highlighted until the
2945 next screen change, no matter how minor.
2946 Simply moving to a new cell will be enough
2947 to turn off the highlighting.
2948 .\" ----------
2949 .TP
2950 .B **
2951 Jump to a note.
2952 If there is a note attached to the current cell,
2953 you will be immediately transported to that cell.
2954 You may return from the note to where you were
2955 by pressing ` twice.
2956 .\" ==========
2957 .SS "Color Commands"
2958 .\" ----------
2959 Color may be enabled by setting the color option
2960 (``set color''), or by toggling it with ^TC
2961 (control-T followed by an uppercase C).
2962 If color is enabled, you may define up to eight
2963 color pairs, each consisting of a foreground
2964 color and a background color.
2965 Each of these colors may be defined by an expression
2966 which is evaluated at the same time the rest of the
2967 spreadsheet is evaluated.
2968 Color expressions may be simple, specifying only
2969 a foreground color and a background color, or
2970 they may be arbitrarily complex, causing the colors
2971 to change based upon other data in the spreadsheet,
2972 for example.
2973 Color ranges may then be defined using the
2974 .I rC
2975 command, with a color number (1-8) assigned to
2976 the range (see below).
2977 .PP
2978 Some of the color numbers may have special meaning
2979 under certain circumstances, but may also be used
2980 explicitly at the same time.
2981 For example, color 1 is the default color pair if
2982 color is enabled but no color has been defined for
2983 a given cell.
2984 It is also the color used for the column and row
2985 labels and the top two lines of the display, which
2986 are used for prompts, input, error messages, etc.
2987 Color 2, while not explicitly used for all negative
2988 numbers, will be used for negative numbers in cells
2989 which have no other color defined when colorneg is
2990 turned on (``set colorneg'' or ^TN).
2991 This is because colorneg causes all cells with
2992 negative numbers to have their color number incremented
2993 by one (cycling back to color 1 if the cell is defined
2994 as using color 8).
2995 Color 3 is used for all cells with errors (ERROR or
2996 INVALID), if colorerr is set (``set colorerr'' or ^TE),
2997 regardless of which color they have been defined to use,
2998 or whether they have been defined to use any color at all.
2999 Color 4 is used to highlight the ``*'' which signifies
3000 that a cell has a note attached.
3001 .PP
3002 If two color ranges are nested or overlapping, any
3003 cell that is common to both will be displayed using
3004 the color of the most recently defined color range.
3005 You can list all color definitions and color ranges
3006 with the rS (show) command (see below).
3007 .TP
3008 .B C
3009 This command first prompts you for the color
3010 number you would like to define (or redefine).
3011 After selecting a number (1-8), you may enter
3012 an expression which defines the foreground and
3013 background colors.
3014 If the chosen color has previously been defined,
3015 the old definition will be presented for editing.
3016 The syntax of the color command is:
3017 .RS
3018 .IP
3019 .B color
3020 .I number
3021 =
3022 .I expression
3023 .RE
3024 .IP
3025 where
3026 .I number
3027 is the number of the color pair you want to define, and
3028 .I expression
3029 is the definition.
3030 If the expression is missing, the specified
3031 color number will be unset (it will revert
3032 to its default start-up colors).
3033 Unlike setting it explicitly to its original
3034 value, this will not cause the expression
3035 to be written to the file when saved.
3036 See below for an explanation of the format
3037 of a color expression.
3038 .\" ----------
3039 .TP
3040 .B rC
3041 This command defines a color range, and specifies a
3042 foreground/background pair to be used for that range.
3043 Although this command also uses the
3044 .I color
3045 command, the syntax is different from that used for
3046 defining a color pair.
3047 This syntax is:
3048 .RS
3049 .IP
3050 .B color
3051 .I range number
3052 .RE
3053 .\" ----------
3054 .TP
3055 .B rS
3056 This command shows lists of the currently defined
3057 range names, framed ranges, and color definitions
3058 and ranges, one after the other.
3059 The output of this command will be piped to
3060 .IR less .
3061 If the environment variable PAGER is set,
3062 its value is used in place of
3063 .IR less .
3064 .PP
3065 Color expressions are exactly like any other numeric expression,
3066 and may contain any function or operator that is valid in
3067 any other numeric expression.
3068 There are, however special functions designed specifically for
3069 defining colors.
3070 These functions are:
3071 .IP
3072 @black
3073 @red
3074 @green
3075 @yellow
3076 @blue
3077 @magenta
3078 @cyan
3079 @white
3080 .PP
3081 Although these function names are intended to reflect the
3082 color they produce, and use the same names as the curses
3083 colors, @yellow may appear as brown on many displays,
3084 especially those based on the VGA standard.
3085 .PP
3086 In addition to special functions for specifying colors,
3087 there is also a special operator for combining two such
3088 colors into a single number which specifies both a
3089 foreground and a background color.
3090 This operator is the semicolon (;).
3091 For example, the command
3092 .IP
3093 .I color 1 = @white;@green
3094 .PP
3095 will set the foreground color to white and the
3096 background color to green for any cell or range
3097 of cells defined to use color 1, or which have no color
3098 defined.
3099 If the semicolon operator is not used, and only one
3100 color is specified, that color will be used for the
3101 foreground, and the background will default to black.
3102 .PP
3103 Although the above example is the easiest way to specify
3104 foreground and background colors, and will probably meet
3105 most people's needs,
3106 .I sc
3107 allows much more power and flexibility, should the
3108 need arise, due to the fact that any color can be
3109 specified by an expression.
3110 For example,
3111 .IP
3112 .I color 5 = B23<E75?(@black;@cyan):(@white;@magenta)
3113 .PP
3114 will cause all cells defined with color 5 to be displayed
3115 as black text on a cyan background if the numeric value
3116 in cell B23 is less than the numeric value in cell E75;
3117 otherwise, they will be displayed as white text on a
3118 magenta background. If you prefer to have the foreground
3119 and background colors dependent on different criteria,
3120 you could do something like this:
3121 .IP
3122 .I color 5 = (B23<E75?@white:@cyan);(D5%2?@red:@blue)
3123 .PP
3124 This will cause the text color for color 5 to be either white
3125 or cyan, depending on the numeric values in cells B23 and E75,
3126 as in the previous example, and the background color to be
3127 either red or blue, depending on whether the numeric value in
3128 cell D5 is odd or even.
3129 .PP
3130 Note that although a color expression may contain any
3131 function which is valid in any other numeric expression,
3132 the @myrow and @mycol functions will always evaluate to 0.
3133 This is because a color expression is not tied to any
3134 particular cell, but is instead evaluated once, and the
3135 result used for all cells defined to use that color.
3136 .PP
3137 Also note that if a color expression results in an error,
3138 the color will default to black text on a black background.
3139 If color 1 results in an error, color will be disabled so
3140 that you can see the input line to correct the error,
3141 after which color will need to be reenabled manually.
3142 .PP
3143 Default colors are in effect for all colors until defined
3144 otherwise.
3145 These default colors are as follows:
3146 .IP
3147 color 1 = @white;@blue
3148 color 2 = @red;@blue
3149 color 3 = @white;@red
3150 color 4 = @black;@yellow
3151 color 5 = @black;@cyan
3152 color 6 = @red;@cyan
3153 color 7 = @white;@black
3154 color 8 = @red;@black
3155 .\" ==========
3156 .SS "Miscellaneous Commands"
3157 .\" ----------
3158 \0 \" exactly one blank line (hard to get)
3159 .PD 0
3160 .TP
3161 .B Q
3162 .TP
3163 .B q
3164 .TP
3165 .B ^C
3166 Exit from
3167 .IR sc .
3168 If you made any changes since the last
3169 .I Get
3170 or
3171 .IR Put ,
3172 .I sc
3173 asks about saving your data before exiting.
3174 .PD
3175 .\" ----------
3176 .TP
3177 .B ^G
3178 .PD 0
3179 .TP
3180 .B ESC
3181 Abort entry of the current command.
3182 .PD
3183 .\" ----------
3184 .TP
3185 .B ?
3186 Enter an interactive help facility.
3187 Lets you look up brief summaries of
3188 the main features of the program.
3189 The help facility is structured like this
3190 manual page so it is easy to find more
3191 information on a particular topic,
3192 although it may not be completely
3193 up-to-date.
3194 .\" ----------
3195 .TP
3196 .B !
3197 Shell escape.
3198 .I sc
3199 prompts for a shell command to run.
3200 End the command line with the
3201 .SM RETURN
3202 key.
3203 If the environment variable
3204 .SM SHELL
3205 is defined, that shell is run.
3206 If not, /bin/sh is used.
3207 Giving a null command line starts the shell in interactive mode.
3208 A second ``!'' repeats the previous command.
3209 .\" ----------
3210 .TP
3211 .B ~
3212 Abbreviations.
3213 You may set abbreviations to speed up the entry of repetitive data.
3214 Abbreviations work much like abbreviations in vi, except that
3215 when defining an abbreviation, both the abbreviation and the
3216 expanded text must be contained within quotes, separated by a
3217 single space.
3218 If more than one space separates the abbreviation from the
3219 expanded text, it will be included as part of the expanded
3220 text.
3221
3222 There are three types of abbreviations available in sc.
3223 In the first type, all characters must be either alphanumeric
3224 or ``_''.
3225 In the second type, the last character must be alphanumeric
3226 or ``_'', but all other characters must not be alphanumeric
3227 or ``_''.
3228 Neither type may contain spaces.
3229 The third type of abbreviation is a single character, and
3230 must be alphanumeric or ``_''.
3231
3232 When using abbreviations, the first type must be at the beginning
3233 of the line, or must be preceded by any character which is not
3234 alphanumeric or ``_''.
3235 The second type must be at the beginning of the line, or must
3236 be preceded either by an alphanumeric character, ``_'', or a
3237 space.
3238 Single character abbreviations must be at the beginning of the
3239 line or preceded by a space.
3240
3241 Abbreviations will be automatically expanded as soon as the
3242 space bar or return key is pressed, or when pressing the
3243 ESC key at the end of the abbreviation to switch to edit mode.
3244 You can also force an abbreviation to be expanded by following
3245 it with a
3246 .IR ^] ,
3247 which won't be inserted into the line.
3248 If you don't want an abbreviation to be expanded, you must
3249 either press
3250 .I ^V
3251 twice or switch to edit mode and back again
3252 somewhere within the abbreviation (pressing
3253 .I ^V
3254 twice also has the effect of switching to navigate mode
3255 and back again).
3256
3257 If the string in the abbreviation command contains no spaces,
3258 the entire string will be looked up in the list of abbreviations,
3259 and if found, the definition will be displayed in the form of
3260 the original
3261 .I abbreviation
3262 command used to define it.
3263 When looking up an abbreviation in this manner, be sure to
3264 disable abbreviation expansion, as described above, or the
3265 results may not be what you expect.
3266
3267 If the string is empty, a list of all abbreviations and their
3268 corresponding expanded text will be output to your pager.
3269 Note that abbreviations are not saved with the file.
3270 This allows each user to create his own file of abbreviations
3271 and either merge them in or include them in his own .scrc file,
3272 rather than force all users who access a file to use the same
3273 list of abbreviations.
3274 .\" ----------
3275 .TP
3276 .B ^L
3277 Redraw the screen.
3278 .\" ----------
3279 .TP
3280 .B ^R
3281 Redraw the screen with special highlighting of cells to be filled in.
3282 This is useful for finding values you need to provide
3283 or update in a form with which you aren't familiar
3284 or of which you have forgotten the details.
3285
3286 It's also useful for checking a form you are creating.
3287 All cells which contain constant numeric values
3288 (not the result of a numeric expression)
3289 are highlighted temporarily,
3290 until the next screen change, however minor.
3291 To avoid ambiguity,
3292 the current range (if any) and current cell are not highlighted.
3293 .\" ----------
3294 .TP
3295 .B ^X
3296 This command is similar to
3297 .IR ^R ,
3298 but highlights cells which have expressions.
3299 It also displays the expressions in the highlighted cells
3300 as left-flushed strings,
3301 instead of the numeric values and/or label strings of those cells.
3302 This command makes it easier to check expressions,
3303 at least when they fit in their cells or the following
3304 cell(s) are blank so the expressions can slop over
3305 (like label strings).
3306 In the latter case, the slop over is not cleared
3307 on the next screen update, so you may want to type
3308 .I ^L
3309 after the
3310 .I ^X
3311 in order to clean up the screen.
3312 .\" ----------
3313 .TP
3314 .B @
3315 Recalculates the spreadsheet.
3316 .\" ==========
3317 .SS "Variable Names"
3318 .\" ----------
3319 Normally, a variable name is just the name of a cell, such as
3320 .IR K20 .
3321 The value is the numeric or string value of the cell,
3322 according to context.
3323 .\" ----------
3324 .PP
3325 When a cell's expression (formula) is copied to another location via
3326 .I copy
3327 or
3328 .IR range-copy ,
3329 variable references are by default offset by the amount the formula moved.
3330 This allows the new formula to work on new data.
3331 If cell references are not to change,
3332 you can either use the
3333 .I @fixed
3334 operator (see below),
3335 or one of the following variations on the cell name.
3336 .\" ----------
3337 .TP
3338 .I K20
3339 References cell
3340 .IR K20 ;
3341 the reference changes when the formula is copied.
3342 .\" ----------
3343 .TP
3344 .BI $ K $ 20
3345 Always refers to cell
3346 .IR K20 ;
3347 the reference stays fixed when the formula is copied.
3348 .\" ----------
3349 .TP
3350 .BI $ K20
3351 Keeps the column fixed at column K;
3352 the row is free to vary.
3353 .\" ----------
3354 .TP
3355 .IB K $ 20
3356 Similarly, this fixes the row and allows the column to vary.
3357 .\" ----------
3358 .PP
3359 These conventions also hold on defined ranges.
3360 Range references vary when formulas containing them are copied.
3361 If the range is defined with fixed variable references,
3362 the references do not change.
3363 .\" ----------
3364 .TP
3365 .B @fixed
3366 To make a variable not change automatically when a cell moves,
3367 put the word
3368 .I @fixed
3369 in front of the reference, for example:
3370 B1 \(** @fixed C3.
3371 .\" ==========
3372 .SS "Numeric Expressions"
3373 .\" ----------
3374 Numeric expressions used with the ``=''
3375 and
3376 .I e
3377 commands have a fairly conventional syntax.
3378 Terms may be
3379 constants,
3380 variable names,
3381 parenthesized expressions,
3382 and negated terms.
3383 Ranges may be operated upon with range functions such as sum
3384 .RI ( @sum ())
3385 and average
3386 .RI ( @avg ()).
3387 Terms may be combined using binary operators.
3388 .\" ----------
3389 .TP
3390 .BI \- e
3391 Negation.
3392 .\" ----------
3393 .TP
3394 .IB e + e
3395 Addition.
3396 .\" ----------
3397 .TP
3398 .IB e \- e
3399 Subtraction.
3400 .\" ----------
3401 .TP
3402 .IB e \(** e
3403 Multiplication.
3404 .\" ----------
3405 .TP
3406 .IB e / e
3407 Division.
3408 .\" ----------
3409 .TP
3410 .IB e1 % e2
3411 e1 mod e2.
3412 .\" ----------
3413 .TP
3414 .IB e ^ e
3415 Exponentiation.
3416 .\" ----------
3417 .TP
3418 .IB e < e
3419 .PD 0
3420 .TP
3421 .IB e <= e
3422 .TP
3423 .IB e = e
3424 .TP
3425 .IB e != e
3426 .TP
3427 .IB e >= e
3428 .TP
3429 .IB e > e
3430 Relationals:
3431 true (1) if and only if the indicated relation holds,
3432 else false (0).
3433 Note that ``<='', ``!='', and ``>=''
3434 are converted to their ``!()'' equivalents.
3435 .PD
3436 .\" ----------
3437 .TP
3438 .BI ~ e
3439 Boolean operator
3440 .SM NOT.
3441 .\" ----------
3442 .TP
3443 .IB e & e
3444 Boolean operator
3445 .SM AND.
3446 .\" ----------
3447 .TP
3448 .IB e | e
3449 Boolean operator
3450 .SM OR.
3451 .\" ----------
3452 .TP
3453 .BI @if( e , e , e )
3454 .PD 0
3455 .TP
3456 .IB e ? e : e
3457 .PD
3458 Conditional:
3459 If the first expression is true then the value of the second is returned,
3460 otherwise the value of the third.
3461 .\" ----------
3462 .PP
3463 Operator precedence from highest to lowest is:
3464 .PP
3465 .nf
3466 .RS
3467 \-, ~, !
3468 ^
3469 \(**, /
3470 +, \-
3471 <, <=, =, !=, >=, >
3472 &
3473 |
3474 ?:
3475 .RE
3476 .fi
3477 .\" ==========
3478 .SS "Built-in Range Functions"
3479 .\" ----------
3480 These functions return numeric values.
3481 The @sum, @prod, @avg, @count, @max, @min, and @stddev functions
3482 may take an optional second argument which is an expression that
3483 is to be evaluated for each cell in the specified range to determine
3484 which cells to include in the function.
3485 Only those cells for which the expression evaluates to true (non-zero)
3486 will be used in calculating the value of the function.
3487 Before evaluation for each cell, the expression is first converted
3488 as if it was being copied from the cell in the upper left-hand corner
3489 of the range into the cell under consideration, with all cell
3490 references adjusted accordingly.
3491 Because the parts of the expression that should remain fixed during
3492 the evaluation of the function may not necessarily be the same as
3493 those which should remain fixed during an actual copy operation,
3494 the rules for adjusting cell references during a copy operation are
3495 slightly different than normal.
3496 In particular, these rules differ in two different ways.
3497
3498 The first difference is that the
3499 .I @fixed
3500 operator is ignored during a copy operation unless it is enclosed
3501 in parentheses.
3502 This is so that selected cells whose addresses should remain fixed
3503 during any given evaluation of a range function can be adjusted
3504 relative to the cell containing the range function when copied (the
3505 .I $
3506 prefix is still honored for these cells when copying).
3507 Enclosing the
3508 .I @fixed
3509 operator in parentheses will have the opposite effect.
3510 That is, it will cause cell references to be fixed while copying,
3511 while allowing them to be adjusted when the function is being evaluated,
3512 subject to any
3513 .I $
3514 prefixes present.
3515 Note that only the
3516 .I @fixed
3517 operator itself should be enclosed in parentheses for this to work properly.
3518
3519 The second difference is that any references in the expression
3520 that refer to cells in the range in the first argument of the
3521 range function will have any
3522 .I $
3523 prefixes ignored, and the references will be treated instead
3524 as if they had the same
3525 .I $
3526 prefixes as the left side of the range argument.
3527 For example, if the left side of the range argument (the cell
3528 address on the left side of the colon) has a fixed row, but does not
3529 have a fixed column, any cell references that refer to cells in
3530 that range will also have a fixed row, but will not have a fixed
3531 column.
3532 This is so that if the range reference moves when copying,
3533 references to any cells in that range will also move accordingly.
3534
3535 Note that the test expression will be evaluated once for every cell in
3536 the range, which means that excessive use of these functions with the
3537 optional test expression, or the use of overly complex test expressions
3538 or with very large ranges can greatly slow down the recalculation of a
3539 spreadsheet, and may require turning off autocalc for speed, and then manually
3540 recalculating with the
3541 .I @
3542 command.
3543 .\" ----------
3544 .TP 18
3545 .BI @sum( r )
3546 .PD 0
3547 .TP 18
3548 .BI @sum( r , e )
3549 .PD
3550 Sum all valid (nonblank) entries in the region
3551 whose two corners are defined by the two variable names (e.g.
3552 .IR c5:e14 )
3553 or the range name specified.
3554 The optional second argument is an expression which can be
3555 used to determine which cells in the range to sum (see above).
3556 .\" ----------
3557 .TP 18
3558 .BI @prod( r )
3559 .PD 0
3560 .TP 18
3561 .BI @prod( r , e )
3562 .PD
3563 Multiply together all valid (nonblank) entries in the specified region.
3564 The optional second argument is an expression which can be
3565 used to determine which cells in the range to multiply (see above).
3566 .\" ----------
3567 .TP 18
3568 .BI @avg( r )
3569 .PD 0
3570 .TP 18
3571 .BI @avg( r , e )
3572 .PD
3573 Average all valid (nonblank) entries in the specified region.
3574 The optional second argument is an expression which can be
3575 used to determine which cells in the range to average (see above).
3576 .\" ----------
3577 .TP 18
3578 .BI @count( r )
3579 .PD 0
3580 .TP 18
3581 .BI @count( r , e )
3582 .PD
3583 Count all valid (nonblank) entries in the specified region.
3584 The optional second argument is an expression which can be
3585 used to determine which cells in the range to count (see above).
3586 .\" ----------
3587 .TP 18
3588 .BI @max( r )
3589 .PD 0
3590 .TP 18
3591 .BI @max( r , e )
3592 .PD
3593 Return the maximum value in the specified region.
3594 The optional second argument is an expression which can be
3595 used to exclude specific cells in the range when determining
3596 this maximum value (see above).
3597 See also the multi argument version of
3598 .I @max
3599 below.
3600 .\" ----------
3601 .TP 18
3602 .BI @min( r )
3603 .PD 0
3604 .TP 18
3605 .BI @min( r , e )
3606 .PD
3607 Return the minimum value in the specified region.
3608 The optional second argument is an expression which can be
3609 used to exclude specific cells in the range when determining
3610 this minimum value (see above).
3611 See also the multi argument version of
3612 .I @min
3613 below.
3614 .\" ----------
3615 .TP 18
3616 .BI @stddev( r )
3617 .PD 0
3618 .TP 18
3619 .BI @stddev( r , e )
3620 .PD
3621 Return the sample standard deviation of the cells in the specified region.
3622 The optional second argument is an expression which can be
3623 used to exclude specific cells in the range when calculating
3624 the standard deviation (see above).
3625 .\" ----------
3626 .TP 18
3627 .BI @rows( r )
3628 Return the number of rows in the specified range.
3629 .\" ----------
3630 .TP 18
3631 .BI @cols( r )
3632 Return the number of columns in the specified range.
3633 .\" ----------
3634 .TP 18
3635 .BI @lookup( e , r )
3636 .PD 0
3637 .TP 18
3638 .BI @lookup( r , e )
3639 .PD 0
3640 .TP 18
3641 .BI @lookup( se , r )
3642 .PD 0
3643 .TP 18
3644 .BI @lookup( r , se )
3645 .PD
3646 Evaluates the expression then searches through the range
3647 .I r
3648 for a matching value.
3649 The range should be either a single row or a single column.
3650 The expression can be either a string expression
3651 or a numeric expression.
3652 If it is a numeric expression, the range is searched
3653 for the the last value less than or equal to
3654 .IR e .
3655 If the expression is a string expression, the string portions
3656 of the cells in the range are searched for an exact string match.
3657 The value returned is the numeric value from the next row and the same
3658 column as the match, if the range was a single row, or the value from
3659 the next column and the same row as the match if the range was a single
3660 column.
3661 .\" ----------
3662 .TP 18
3663 .BI @hlookup( e , r , n )
3664 .PD 0
3665 .TP 18
3666 .BI @hlookup( r , e , n )
3667 .PD 0
3668 .TP 18
3669 .BI @hlookup( se , r , n )
3670 .PD 0
3671 .TP 18
3672 .BI @hlookup( r , se , n )
3673 .PD
3674 Evaluates the expression then searches through the first row in the range
3675 .I r
3676 for a matching value.
3677 The expression can be either a string expression
3678 or a numeric expression.
3679 If it is a numeric expression,
3680 the row is searched for the the last value less than or equal to
3681 .IR e .
3682 If the expression is a string expression, the string portions
3683 of the cells in the row are searched for an exact string match.
3684 The value returned is the numeric value from the same column
3685 .I n
3686 rows below the match.
3687 .\" ----------
3688 .TP 18
3689 .BI @vlookup( e , r , n )
3690 .PD 0
3691 .TP 18
3692 .BI @vlookup( r , e , n )
3693 .PD 0
3694 .TP 18
3695 .BI @vlookup( se , r , n )
3696 .PD 0
3697 .TP 18
3698 .BI @vlookup( r , se , n )
3699 .PD
3700 Evaluates the expression then searches through
3701 the first column in the range
3702 .I r
3703 for a matching value.
3704 The expression can be either a string
3705 expression or a numeric expression.
3706 If it is a numeric expression, the column is searched
3707 for the the last value less than or equal to
3708 .IR e .
3709 If the expression is a string expression, the string portions
3710 of the cells in the column are searched for an exact string match.
3711 The value returned is the numeric value from the same row
3712 .I n
3713 columns to the right of the match.
3714 .\" ----------
3715 .TP 18
3716 .BI @index( e1 , r )
3717 .PD 0
3718 .TP 18
3719 .BI @index( r , e1 )
3720 .PD 0
3721 .TP 18
3722 .BI @index( r , e1 , e2 )
3723 .PD
3724 Use the values of expressions
3725 .I e1
3726 and (optionally)
3727 .I e2
3728 to index into
3729 the range
3730 .IR r .
3731 The numeric value at that position is returned.
3732 With two arguments, the range should be either a
3733 single row or a single column.
3734 An expression with the value 1 selects the first
3735 item in the range, 2 selects the second item, etc.
3736 With three arguments, the range must come first,
3737 and the second and third arguments will then be
3738 interpreted as row and column, respectively,
3739 for indexing into a two-dimensional table.
3740 .\" ----------
3741 .TP 18
3742 .BI @stindex( e1 , r )
3743 .PD 0
3744 .TP 18
3745 .BI @stindex( r , e1 )
3746 .PD 0
3747 .TP 18
3748 .BI @stindex( r , e1 , e2 )
3749 .PD
3750 Use the values of expressions
3751 .I e1
3752 and (optionally)
3753 .I e2
3754 to index into
3755 the range
3756 .IR r .
3757 The string value at that position is returned.
3758 With two arguments, the range should be either a
3759 single row or a single column.
3760 An expression with the value 1 selects the first
3761 item in the range, 2 selects the second item, etc.
3762 With three arguments, the range must come first,
3763 and the second and third arguments will then be
3764 interpreted as row and column, respectively,
3765 for indexing into a two-dimensional table.
3766 .\" ==========
3767 .SS "Built-in Numeric Functions"
3768 .\" ----------
3769 All of these functions operate on floating point numbers (doubles)
3770 and return numeric values.
3771 Most of them are standard system functions more fully described in
3772 .IR math (3).
3773 The trig functions operate with angles in radians.
3774 .\" ----------
3775 .TP 18
3776 .BI @sqrt( e )
3777 Return the square root of
3778 .IR e .
3779 .\" ----------
3780 .TP 18
3781 .BI @exp( e )
3782 Return the exponential function of
3783 .IR e .
3784 .\" ----------
3785 .TP 18
3786 .BI @ln( e )
3787 Return the natural logarithm of
3788 .IR e .
3789 .\" ----------
3790 .TP 18
3791 .BI @log( e )
3792 Return the base 10 logarithm of
3793 .IR e .
3794 .\" ----------
3795 .TP 18
3796 .BI @floor( e )
3797 Return the largest integer not greater than
3798 .IR e .
3799 .\" ----------
3800 .TP 18
3801 .BI @ceil( e )
3802 Return the smallest integer not less than
3803 .IR e .
3804 .\" ----------
3805 .TP 18
3806 .BI @rnd( e )
3807 Round
3808 .I e
3809 to the nearest integer.
3810 default: *.5 will be rounded up to the next integer;
3811 doing a 'set rndtoeven' will cause it to be rounded to
3812 the closest even number instead (aka banker's round).
3813 Round-to-even has advantages over the default rounding
3814 for some applications.
3815 For example, if X+Y is an integer,
3816 then X+Y = rnd(X)+rnd(Y) with round-to-even,
3817 but not always with the defaulting rounding method.
3818 This could be an advantage, for example, when trying to
3819 split an odd amount of money evenly between two people (it
3820 would determine who gets the extra penny).
3821 .TP 18
3822 .BI @round( e , n )
3823 Round
3824 .I e
3825 to
3826 .I n
3827 decimal places.
3828 .I n
3829 may be positive to round off the right side of the decimal
3830 or negative to round off the left side.
3831 See @rnd(e) above for rounding types.
3832 .\" ----------
3833 .TP 18
3834 .BI @abs( e )
3835 .PD 0
3836 .TP 18
3837 .BI @fabs( e )
3838 Return the absolute value of
3839 .IR e .
3840 .PD
3841 .\" ----------
3842 .TP 18
3843 .BI @pow( e1 , e2 )
3844 Return
3845 .I e1
3846 raised to the power of
3847 .IR e2 .
3848 .\" ----------
3849 .TP 18
3850 .BI @hypot( e1 , e2 )
3851 Return sqrt(e1\(**e1+e2\(**e2), taking precautions
3852 against unwarranted overflows.
3853 .\" ----------
3854 .TP 18
3855 .B @pi
3856 A constant quite close to pi.
3857 .\" ----------
3858 .TP 18
3859 .BI @dtr( e )
3860 Convert
3861 .I e
3862 in degrees to radians.
3863 .\" ----------
3864 .TP 18
3865 .BI @rtd( e )
3866 Convert
3867 .I e
3868 in radians to degrees.
3869 .\" ----------
3870 .TP 18
3871 .BI @sin( e )
3872 .PD 0
3873 .TP 18
3874 .BI @cos( e )
3875 .TP 18
3876 .BI @tan( e )
3877 Return trigonometric functions of radian arguments.
3878 The magnitude of the arguments are not checked
3879 to assure meaningful results.
3880 .PD
3881 .\" ----------
3882 .TP 18
3883 .BI @asin( e )
3884 Return the arc sine of
3885 .I e
3886 in the range -pi/2 to pi/2.
3887 .\" ----------
3888 .TP 18
3889 .BI @acos( e )
3890 Return the arc cosine of
3891 .I e
3892 in the range 0 to pi.
3893 .\" ----------
3894 .TP 18
3895 .BI @atan( e )
3896 Return the arc tangent of
3897 .I e
3898 in the range -pi/2 to pi/2.
3899 .\" ----------
3900 .TP 18
3901 .BI @atan2( e1 , e2 )
3902 Returns the arc tangent of
3903 .IR e1 / e2
3904 in the range -pi to pi.
3905 .\" ----------
3906 .TP 18
3907 .BI @max( e1 , e2 , ... )
3908 Return the maximum of the values of the expressions.
3909 Two or more expressions may be specified.
3910 See also the range version of
3911 .I @max
3912 above.
3913 .\" ----------
3914 .TP 18
3915 .BI @min( e1 , e2 , ... )
3916 Return the minimum of the values of the expressions.
3917 Two or more expressions may be specified.
3918 See also the range version of
3919 .I @min
3920 above.
3921 .\" ----------
3922 .TP 18
3923 .BI @ston( se )
3924 Convert string expression
3925 .I se
3926 to a numeric value.
3927 .\" ----------
3928 .TP 18
3929 .BI @eqs( se1 , se2 )
3930 Return 1 if string expression
3931 .I se1
3932 has the same value as string expression
3933 .IR se2 ,
3934 0 otherwise.
3935 .\" ----------
3936 .TP 18
3937 .BI @nval( se , e )
3938 Return the numeric value of a cell selected by name.
3939 String expression
3940 .I se
3941 must evaluate to a column name (``A''-``AE'') and
3942 .I e
3943 must evaluate to a row number (0-199).
3944 If
3945 .I se
3946 or
3947 .I e
3948 is out of bounds, or the cell has no numeric value, the result is 0.
3949 You can use this for simple table lookups.
3950 Be sure the table doesn't move unexpectedly!
3951 See also
3952 .IR @sval ()
3953 below.
3954 .\" ----------
3955 .TP 18
3956 .B @err
3957 Force an error.
3958 This will force the expression which contains it
3959 to result in an error.
3960 .\" ==========
3961 .SS "String Expressions"
3962 .\" ----------
3963 String expressions are made up of constant strings
3964 (characters surrounded by double quotation marks),
3965 variables
3966 (cell names, which refer to the cells's label strings or expressions),
3967 and string functions.
3968 Note that string expressions are only allowed
3969 when entering a cell's label string, not its numeric part.
3970 Also note that string expression results may
3971 be left or right flushed or centered,
3972 according to the type of the cell's string label.
3973 .\" ----------
3974 .TP
3975 .B #
3976 Concatenate strings.
3977 For example, the string expression
3978 .IP ""
3979 A0 # "zy dog"
3980 .IP ""
3981 displays the string ``the lazy dog'' in the cell if the value of
3982 .IR A0 's
3983 string is ``the la''.
3984 .\" ==========
3985 .SS "Built-in String Functions"
3986 .\" ----------
3987 \0 \" exactly one blank line (hard to get)
3988 .PD 0
3989 .TP 18
3990 .BI @filename( e )
3991 Return the current default filename, as specified
3992 when the file was first loaded or created,
3993 or during the last save, with the
3994 .I Put
3995 command.
3996 If
3997 .I e
3998 is 0, only the actual filename will be returned,
3999 with any path removed.
4000 If non-zero, the full path specified on the command line
4001 or in the last
4002 .I Get
4003 or
4004 .I Put
4005 command will be returned.
4006 If the path begins with ``~'', it will be expanded to
4007 the appropriate users home directory.
4008 .PD
4009 .\" ----------
4010 .TP 18
4011 .BI @substr( se , e1 , e2 )
4012 Extract and return from string expression
4013 .I se
4014 the substring indexed by character number
4015 .I e1
4016 through character number
4017 .I e2
4018 (defaults to the size of
4019 .I se
4020 if beyond the end of it).
4021 If
4022 .I e1
4023 is less than 1 or greater than
4024 .IR e2 ,
4025 the result is the null string.
4026 For example,
4027 .IP ""
4028 @substr ("Nice jacket", 4, 8)
4029 .IP ""
4030 returns the string ``e jac''.
4031 .\" ----------
4032 .TP 18
4033 .BI @fmt( se , e )
4034 Convert a number to a string.
4035 The argument
4036 .I se
4037 must be a valid
4038 .IR printf (3)
4039 format string.
4040 .I e
4041 is converted according to the standard rules.
4042 For example, the expression
4043 .IP ""
4044 @fmt ("\(**\(**%6.3f\(**\(**", 10.5)
4045 .IP ""
4046 yields the string ``\(**\(**10.500\(**\(**''.
4047 .I e
4048 is a double, so applicable formats are e, E, f, g, and G.
4049 Try ``%g'' as a starting point.
4050 .\" ----------
4051 .TP 18
4052 .BI @sval( se , e )
4053 Return the string value of a cell selected by name.
4054 String expression
4055 .I se
4056 must evaluate to a column name (``A''-``AE'') and
4057 .I e
4058 must evaluate to a row number (0-199).
4059 If
4060 .I se
4061 or
4062 .I e
4063 is out of bounds, or the cell has no string value,
4064 the result is the null string.
4065 You can use this for simple table lookups.
4066 Be sure the table doesn't move unexpectedly!
4067 .\" ----------
4068 .TP 18
4069 .BI @upper( se )
4070 .PD 0
4071 .TP 18
4072 .BI @lower( se )
4073 will case the string expression to upper or lower.
4074 .PD
4075 .\" ----------
4076 .TP 18
4077 .BI @capital( se )
4078 will convert the first letter of words in a string
4079 into upper case and other letters to lower case
4080 (the latter if all letters of the string are upper case).
4081 .\" ----------
4082 .TP 18
4083 .BI @ext( se , e )
4084 Call an external function (program or script).
4085 The purpose is to allow arbitrary functions on values,
4086 e.g. table lookups and interpolations.
4087 String expression
4088 .I se
4089 is a command or command line to call with
4090 .IR popen (3).
4091 The value of
4092 .I e
4093 is converted to a string and appended to the
4094 command line as an argument.
4095 The result of
4096 .IR @ext ()
4097 is a string:
4098 the first line printed to standard output by the command.
4099 The command should emit exactly one output line.
4100 Additional output, or output to standard error, messes up the screen.
4101 .IR @ext ()
4102 returns a null string and prints an appropriate warning
4103 if external functions are disabled,
4104 .I se
4105 is null, or the attempt to run the command fails.
4106 .IP ""
4107 External functions can be slow to run,
4108 and if enabled are called at each screen update,
4109 so they are disabled by default.
4110 You can enable them with
4111 .I ^T
4112 when you really want them called.
4113 .IP ""
4114 A simple example:
4115 .IP ""
4116 @ext ("echo", a1)
4117 .IP ""
4118 You can use
4119 .IR @ston ()
4120 to convert the
4121 .IR @ext ()
4122 result back to a number.
4123 For example:
4124 .IP ""
4125 @ston (@ext ("form.sc.ext", a9 + b9))
4126 .IP ""
4127 Note that you can build a command line (including more argument values)
4128 from a string expression with concatenation.
4129 You can also "hide" the second argument by ending the command line
4130 (first argument) with `` #'' (shell comment).
4131 .\" ----------
4132 .TP 18
4133 .BI @coltoa( e )
4134 Returns a string name for a column from the numeric argument.
4135 For example:
4136 .IP ""
4137 @coltoa(@mycol-1)
4138 @nval(coltoa(@mycol-1), @myrow+1)
4139 .IP ""
4140 .\" ==========
4141 .SS "Built-in Financial Functions"
4142 .\" ----------
4143 Financial functions compute the mortgage (or loan)
4144 payment, future value, and the present value functions.
4145 Each accepts three arguments, an amount, a rate of interest
4146 (per period), and the number of periods.
4147 These functions are the same as those commonly found
4148 in other spreadsheets and financial calculators
4149 .\" ----------
4150 .TP 18
4151 .BI @pmt( e1 , e2 , e3 )
4152 .IR @pmt (60000,.01,360)
4153 computes the monthly payments for a $60000 mortgage at
4154 12% annual interest (.01 per month) for 30 years (360 months).
4155 .\" ----------
4156 .TP 18
4157 .BI @fv( e1 , e2 , e3 )
4158 .IR @fv (100,.005,36)
4159 computes the future value for 36 monthly payments
4160 of $100 at 6% interest (.005 per month).
4161 It answers the question:
4162 "How much will I have in 36 months if I deposit $100
4163 per month in a savings account paying 6% interest
4164 compounded monthly?"
4165 .\" ----------
4166 .TP 18
4167 .BI @pv( e1 , e2 , e3 )
4168 .IR @pv (1000,.015,36)
4169 computes the present value of an ordinary annuity of
4170 36 monthly payments of $1000 at 18% annual interest.
4171 It answers the question:
4172 "How much can I borrow at 18% for 3 years if I
4173 pay $1000 per month?"
4174 .\" ==========
4175 .SS "Built-in Date and Time Functions"
4176 .\" ----------
4177 Time for
4178 .I sc
4179 follows the system standard:
4180 the number of seconds since the beginning of 1970.
4181 All date and time functions except
4182 .IR @date ()
4183 return numbers, not strings.
4184 .\" ----------
4185 .TP 18
4186 .B @now
4187 Return the current time encoded
4188 as the number of seconds since the beginning of the
4189 epoch (December 31, 1969, midnight, GMT).
4190 .\" ----------
4191 .TP 18
4192 .BI @dts( e1 , e2 , e3 )
4193 Convert a date to the number of seconds from the epoch
4194 to the first second of the specified date, local time.
4195 Dates may be specified in either (m,d,y) or (y,m,d) format,
4196 although the latter is preferred, since it's more universally
4197 recognized (m,d,y is only used in America).
4198 If e2 > 12 or e3 > 31, then (m,d,y) is assumed.
4199 Otherwise, (y,m,d) is assumed.
4200 For example,
4201 .IR @date(@dts(1976,12,14))
4202 yields
4203 .IP ""
4204 .I " Tue Dec 14 00:00:00 1976"
4205 .IP ""
4206 The month should range from 1 to 12;
4207 the day should range from 1 to the number
4208 of days in the specified month;
4209 and the year should include the century
4210 (e.g. 1999 instead of 99).
4211 Any date capable of being handled by the system
4212 is valid, typically 14 Dec 1901 to 18 Jan 2038
4213 on a system that uses a 32 bit time_t.
4214 Invalid dates or dates outside of this range will return ERROR.
4215 For rapid entry of dates using only the numeric keypad,
4216 .I sc
4217 provides the alternate syntax
4218 .IR y.m.d
4219 or
4220 .IR m.d.y,
4221 which is automatically converted to the @dts(...) format above.
4222 The year, month, and day must be entered numerically
4223 in the alternate syntax; formulas are not allowed.
4224 .\" ----------
4225 .TP 18
4226 .BI @tts( e1 , e2 , e3 )
4227 .IR @tts (8,20,45)
4228 converts the time 8:40:45 to the number of seconds since
4229 midnight, the night before.
4230 The hour should range from 0 to 23;
4231 the minutes and seconds should range from 0 to 59.
4232 .\" ----------
4233 .PP
4234 The following functions take the time in seconds
4235 (e.g. from
4236 .IR @now )
4237 as an argument and return the specified value.
4238 The functions all convert from GMT to local time.
4239 .\" ----------
4240 .TP 18
4241 .BI @date( e )
4242 .PD 0
4243 .TP 18
4244 .BI @date( e , se )
4245 .PD
4246 Convert the time in seconds to a date string.
4247 With a single numeric argument, the date will
4248 be 24 characters long in the following form:
4249 .IP ""
4250 .I " Sun Sep 16 01:03:52 1973"
4251 .IP ""
4252 Note that you can extract parts of this fixed-format string with
4253 .IR @substr ().
4254 A format string compatible with the strftime()
4255 function may optionally be given as a second
4256 argument to override the default format.
4257 See the strftime(3) man page for details.
4258 .\" ----------
4259 .TP 18
4260 .BI @year( e )
4261 Return the year.
4262 Valid years begin with 1970, although many
4263 systems will return years prior to 1970 if
4264 .I e
4265 is negative.
4266 The last legal year is system dependent.
4267 .\" ----------
4268 .TP 18
4269 .BI @month( e )
4270 Return the month, encoded as 1 (January) to 12 (December).
4271 .\" ----------
4272 .TP 18
4273 .BI @day( e )
4274 Return the day of the month, encoded as 1 to 31.
4275 .\" ----------
4276 .TP 18
4277 .BI @hour( e )
4278 Return the number of hours since midnight, encoded as 0 to 23.
4279 .\" ----------
4280 .TP 18
4281 .BI @minute( e )
4282 Return the number of minutes since the last full hour,
4283 encoded as 0 to 59.
4284 .\" ----------
4285 .TP 18
4286 .BI @second( e )
4287 Return the number of seconds since the last full minute,
4288 encoded as 0 to 59.
4289 .\" ==========
4290 .SS "Spreadsheet Update"
4291 .\" ----------
4292 Re-evaluation of spreadsheet expressions is done by row
4293 or by column depending on the selected calculation order.
4294 Evaluation is repeated up to
4295 .I iterations
4296 times for each update if necessary,
4297 so forward references usually work as expected.
4298 See
4299 .I set
4300 above.
4301 If stability is not reached after ten iterations,
4302 a warning is printed.
4303 This is usually due to a long series of forward references,
4304 or to unstable cyclic references (for example, set
4305 .IR A0 's
4306 expression to ``A0+1'').
4307 .TP 18
4308 .B @numiter
4309 Returns the number of iterations performed so far.
4310 .\" ==========
4311 .SS "Programmable Function Keys"
4312 .\" ----------
4313 Function keys can be used in
4314 .I sc
4315 if your terminal supports them, and they are programmable.
4316 To program the function keys, you use the
4317 .I fkey
4318 command.
4319 This command may be used in a
4320 .I .scrc
4321 file or a macro file, or it may be entered directly into
4322 .IR sc 's
4323 command line.
4324 Defined function keys will be saved with the file.
4325 There is no shortcut, as there is with most commands,
4326 so the full command must be typed in.
4327 Pressing enter when not editing a line will start
4328 you off with a blank line for this purpose.
4329 The format of the
4330 .I fkey
4331 command is:
4332 .IP
4333 .B fkey
4334 .I n
4335 =
4336 .I """command""
4337 .LP
4338 where
4339 .I n
4340 is the function key number (n = 1 for F1, n = 2 for F2, etc.), and
4341 .I command
4342 is the command to be run.
4343 For example,
4344 .IP
4345 .I "fkey 2 = ""merge \\\\""|~/scmacros/macro1\\\\""""
4346 .LP
4347 will run the macro called
4348 .I macro1
4349 located in a subdirectory of your home directory called
4350 .IR scmacros
4351 when the F2 key is pressed.
4352 Note that embedded quotes must be escaped by a backslash.
4353 If you want to include the cell address of the
4354 current cell in the command line,
4355 you may do so by entering ``$$'' in its place
4356 in the command.
4357 For example,
4358 .IP
4359 .I "fkey 5 = ""fmt $$ \\\\""^D%A\\\\""""
4360 .LP
4361 will cause the F5 key to format the current cell to display the
4362 full weekday name of the numeric date value stored there.
4363 The ^D is a CTRL-D character, which denotes a date format.
4364 .LP
4365 Although it may be overridden by the
4366 .I fkey
4367 command, the F1 key is predefined by default to execute
4368 .I man sc.
4369 Unlike the user-defined function keys, this definition will also
4370 work in edit, insert, replace, and navigate modes.
4371 .LP
4372 To undefine a function key, merely define it as
4373 the empty string ("").
4374 Undefining the F1 key will restore the default behavior.
4375 .\" ==========
4376 .SS "Plugins"
4377 .\" ----------
4378 There are three ways in which external
4379 programs can be used as plugins with
4380 .IR sc .
4381 First, they can be used as external commands.
4382 When used as an external command, any command
4383 not recognized by
4384 .I sc
4385 will be searched for first in $HOME/.sc/plugins,
4386 and then in /usr/share/doc/sc/plugins.
4387 If found, it will be run with its standard input
4388 and standard output redirected back to
4389 .IR sc .
4390 These are used to send commands to, and receive
4391 responses back from
4392 .I sc
4393 in the same way that advanced macros do.
4394 .LP
4395 The second and third ways that programs can be used
4396 as plugins with
4397 .I sc
4398 are to automatically convert files to and from
4399 .I sc
4400 format based on their extensions.
4401 In order to use them in this way, you must first
4402 associate a given extension to a corresponding
4403 plugin (for reading) or plugout (for writing) using
4404 the
4405 .I plugin
4406 and
4407 .I plugout
4408 commands.
4409 These commands should be placed in your
4410 .I .scrc
4411 file, and have the following syntax:
4412 .IP
4413 .B plugin
4414 .I """ext""
4415 =
4416 .I """programname""
4417 .LP
4418 or
4419 .IP
4420 .B plugout
4421 .I """ext""
4422 =
4423 .I """programname""
4424 .LP
4425 where
4426 .I ext
4427 is the extension and
4428 .I programname
4429 is the name of the plugin program to be used
4430 for filenames with that extension.
4431 For input, the plugin merely reads the specified file,
4432 performs whatever conversion is necessary, and writes
4433 the resulting data to standard output.
4434 For output, the plugin writes
4435 .I sc
4436 commands to standard output and reads the replies
4437 from standard input in the same way that an advanced
4438 macro would, and then converts the data to the
4439 appropriate format and writes it to a file with
4440 the specified filename.
4441 .\" ==========
4442 .SH FILES
4443 .TP 3in
4444 /usr/share/doc/sc/tutorial.sc
4445 Tutorial spreadsheet.
4446 .TP 3in
4447 $HOME/.scrc
4448 Initialization commands.
4449 .IP "./.scrc"
4450 More initialization commands.
4451 .SH SEE ALSO
4452 bc(1), dc(1), crypt(1), psc(1)
4453 .\" ==========
4454 .SH BUGS
4455 Top-to-bottom, left-to-right evaluation of expressions is silly.
4456 A proper following of the dependency graph
4457 with (perhaps) recourse to relaxation should be implemented.
4458 .\" ----------
4459 .PP
4460 On some systems,
4461 if the cell cursor is in column 0 with topline enabled
4462 (so the current cell is highlighted),
4463 or if any cell in column 0 is highlighted,
4464 the corresponding row number gets displayed and then blanked
4465 during a screen refresh.
4466 This looks like a bug in
4467 .IR curses .
4468 .\" ----------
4469 .PP
4470 Many commands give no indication (a message or beep)
4471 if they have null effect.
4472 Some should give confirmation of their action, but they don't.
4473 .SH AUTHORS
4474 This is a much modified version of a public domain spread sheet
4475 originally authored by James Gosling,
4476 and subsequently modified and posted to USENET by
4477 Mark Weiser under the name
4478 .IR vc .
4479 The program was subsequently renamed
4480 .IR sc ,
4481 and further modified by numerous contributors,
4482 Jeff Buhrt
4483 of Proslink, Inc.
4484 and Robert Bond of Sequent,
4485 prominent among them.
4486 The current maintainer is Chuck Martin ([email protected]).
4487 .PP
4488 Other contributors include:
4489 Tom Anderson,
4490 Glenn T. Barry,
4491 Gregory Bond,
4492 Stephen (Steve) M. Brooks,
4493 Peter Brower,
4494 John Campbell,
4495 Lawrence Cipriani,
4496 Jim Clausing,
4497 Dave Close,
4498 Chris Cole,
4499 Jonathan Crompron,
4500 David I. Dalva,
4501 Glen Ditchfield,
4502 Sam Drake,
4503 James P. Dugal,
4504 Paul Eggert,
4505 Andy Fyfe,
4506 Jack Goral,
4507 Piercarlo "Peter" Grandi,
4508 Henk Hesselink,
4509 Jeffrey C Honig,
4510 Kurt Horton,
4511 Jonathan I. Kamens,
4512 Peter King,
4513 Tom Kloos,
4514 Michael Lapsley,
4515 Casey Leedom,
4516 Jay Lepreau,
4517 Dave Lewis,
4518 Rick Linck,
4519 Soren Lundsgaard,
4520 Tad Mannes,
4521 Rob McMahon,
4522 Chris Metcalf,
4523 Mark Nagel,
4524 Ulf Noren,
4525 Marius Olafsson,
4526 Gene H. Olson,
4527 Henk P. Penning,
4528 Rick Perry,
4529 Larry Philps,
4530 Eric Putz,
4531 Jim Richardson,
4532 Michael Richardson,
4533 R. P. C. Rodgers,
4534 Kim Sanders,
4535 Mike Schwartz,
4536 Alan Silverstein,
4537 Lowell Skoog,
4538 Herr Soeryantono,
4539 Tim Theisen,
4540 Tom Tkacik,
4541 Andy Valencia,
4542 Adri Verhoef,
4543 Rick Walker,
4544 Petri Wessman,
4545 and
4546 Tim Wilson.
4547 .\" end of man page