Debian Codegraph @

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