home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / unix / volume18 / sc6.1 / part01 next >
Encoding:
Internet Message Format  |  1989-03-20  |  53.2 KB

  1. Subject:  v18i045:  SC spreadsheet, version 6.1, Part01/04
  2. Newsgroups: comp.sources.unix
  3. Sender: sources
  4. Approved: rsalz@uunet.UU.NET
  5.  
  6. Submitted-by: Robert Bond <sequent!rgb>
  7. Posting-number: Volume 18, Issue 45
  8. Archive-name: sc6.1/part01
  9.  
  10. This is a much modified version of the public domain spread sheet sc,
  11. posted several years ago by Mark Weiser as vc, originally by James Gosling.
  12.  
  13. This release has been tested against a Sequent S81 running DYNIX 3.0.14
  14. (BSD 4.2) and an ICM-3216 with system V.3.  The ICM has a National Semi
  15. 32016.  Just check the makefile for the system flags.   I have heard
  16. reports of lots of other machines that work. If you have problems with
  17. lex.c, and don't care about arrow keys, define SIMPLE (-DSIMPLE in the
  18. makefile).  SIMPLE causes the arrow keys to not be used.
  19.  
  20. Sc is not a product of Sequent Computer Systems.  It is supplied as
  21. is with no warranty, express or implied, as a service to Usenet readers.
  22. It is not copyrighted, either.  Have at it.
  23.     Robert Bond             uunet!sequent!rgb
  24.     Sequent Computer Systems
  25.  
  26. # This is a shell archive.  Remove anything before this line
  27. # then unpack it by saving it in a file and typing "sh file"
  28. # (Files unpacked will be owned by you and have default permissions).
  29. # This archive contains the following files:
  30. #    ./README
  31. #    ./CHANGES
  32. #    ./sc.doc
  33. #    ./psc.doc
  34. #
  35. if `test ! -s ./README`
  36. then
  37. echo "Extracting ./README"
  38. cat > ./README << '\SHAR\EOF\'
  39. This is a much modified version of the public domain spread sheet sc,
  40. posted several years ago by Mark Weiser as vc, originally by James Gosling.
  41.  
  42. Changes since my last version (5.1) are detailed at great length :-)
  43. in CHANGES.
  44.  
  45. When you get it built, try "sc tutorial.sc" for a simple introduction
  46. to the basic commands.
  47.  
  48. A new input parser program (psc) has been included.  This program
  49. formats ascii files for use in the spread sheet.  If you don't have
  50. getopts, there is a public domain version by Henry Spencer hidden away
  51. in the VMS_NOTES file.
  52.  
  53. I have modified the makefile to make it easy for you to call the
  54. program what you want (I saw at least five different names in
  55. correspondence and on the net).  Just change "name=sc" and "NAME=SC" to
  56. "name=myfavoritename" and "NAME=MYFAVORITENAME" and try "make
  57. myfavoritename".
  58.  
  59. Similarly, you can make the documentation with "make myfavoritename.man".
  60. "make install" will make and install the code in EXDIR.  The
  61. installation steps and documentation all key off of the name.  The
  62. makefile even changes the name in the nroffable man page.  If you don't
  63. have nroff, you will have to change sc.man yourself.
  64.  
  65. This release has been tested against a Sequent S81 running DYNIX 3.0.14
  66. (BSD 4.2) and an ICM-3216 with system V.3.  The ICM has a National Semi
  67. 32016.  Just check the makefile for the system flags.   I have heard
  68. reports of lots of other machines that work. If you have problems with
  69. lex.c, and don't care about arrow keys, define SIMPLE (-DSIMPLE in the
  70. makefile).  SIMPLE causes the arrow keys to not be used.
  71.  
  72. Guidelines for Hackers:
  73.  
  74. If you want to send changes you have made to SC, please feel free to do
  75. so.  If they work :-) and seem worthwhile, I'll put them in.  Please
  76. refrain from wholesale "style" or "cleanup" changes.  It is easy to add
  77. your changes but it makes it hard to merge in the next guy's stuff if
  78. he used the release as a base.  Leave my $Revision:  identifiers alone-
  79. they help me track what you used as a base.  If you check the code into
  80. rcs, delete the "$"s on the Revison lines before you do.
  81.  
  82. You may not like 4 space indenting and curly braces on the "if" line,
  83. but your code will look like that before it leaves my hands so you may
  84. as well abide by the style in the code when you make your changes.  I
  85. have also been known to break things trying to make them look "right".
  86. If you do string functions, please, PLEASE pay attention to null
  87. pointers, use xmalloc and xfree, and xfree those arguments.  And
  88. don't forget to document your changes in both help.c and sc.doc.
  89.  
  90. Disclaimer:
  91.  
  92. Sc is not a product of Sequent Computer Systems.  It is supplied as
  93. is with no warranty, express or implied, as a service to Usenet readers.
  94. It is not copyrighted, either.  Have at it.
  95.  
  96.                     Bob Bond
  97.  
  98.     Robert Bond             uunet!sequent!rgb
  99.     Sequent Computer Systems
  100. \SHAR\EOF\
  101. else
  102.   echo "will not over write ./README"
  103. fi
  104. if [ `wc -c ./README | awk '{printf $1}'` -ne 2840 ]
  105. then
  106. echo `wc -c ./README | awk '{print "Got " $1 ", Expected " 2840}'`
  107. fi
  108. if `test ! -s ./CHANGES`
  109. then
  110. echo "Extracting ./CHANGES"
  111. cat > ./CHANGES << '\SHAR\EOF\'
  112. CHANGES BETWEEN 5.1 and 6.1:
  113.  
  114. Andy Valencia -
  115.     xmalloc aligns data to a double boundary.
  116.  
  117. Lawrence Cipriani -
  118.     Fixed a bug in the "do you want to save this" sequence.
  119.  
  120. Soren Lundsgaard -
  121.     A null pointer derefrence.
  122.  
  123. Rick Perry -
  124.     Cleaned up a problem with modchk() in sc.c.
  125.  
  126. Gregory Bond -
  127.     Added code for multi argument versions of @min and @max.
  128.  
  129. Tad Mannes -
  130.     Added code to save/restore hidden rows and columns when the
  131.     data base is saved or restored.
  132.  
  133. Marius Olafsson -
  134.     INTERNATIONAL changes.  Allows full 8 bit characters (if
  135.     curses supports them.)
  136.  
  137. Kurt Horton -
  138.     Added support for @pv, @fv and @pmt financial functins.
  139.     Tested lots of different systems, linting.
  140.  
  141. John Campbell -
  142.     Support for VMS.  See VMS_NOTES.
  143.  
  144. Peter King -
  145.      User selection of row or column order for recalculation.
  146.         Also affects order of traversing regions in /f and /r
  147.      User setting of automatic or manual recalculation.
  148.      User setting of number of times to try recalculation.
  149.      + and - commands when in non-numeric mode to do 
  150.         increment and decrement operations.
  151.     @index, @stindex, @atan2, @lookup  functions.
  152.     Save/restore options.
  153.     Support for TeX, LaTeX, and better support for tbl in "T" cmd.
  154.     Provision of a copyent function to copy entries (same code repeated
  155.         in several locations)
  156.     Forwrow, backrow, forwcol, backcol functions to replace
  157.         repeated code
  158.     Correct interpretation of ESCAPE or ^G as an abort when in a 
  159.         two character command such as 'ar' or 'ac'
  160.     Cleanup in eval() - catches non-trap function errors.
  161.  
  162. Bob Bond - 
  163.        Added search options to "g".
  164.        Added supression of hidden columns to "W"
  165.        Added the mod operator "%"
  166.        New help functions.
  167.        Constant prescale "$"
  168.        Added string matching to @lookup.
  169.        Some more bug fixes.
  170.        Testing, integration, documentation.
  171.  
  172. Alan Silverstein-
  173.     Greatly revised the manual entry.
  174.     Added menus for ^E command and row/column commands, which
  175.     involved a bunch of code cleanup.
  176.  
  177.     Changed top row display to clearly indicate string labels
  178.     versus number parts, and to distinguish string functions from
  179.     constant labels.
  180.  
  181.     When the character cursor is on a cell (not topline), ^H
  182.     (backspace) is like ^B (move back one cell), rather than being
  183.     ignored.
  184.  
  185.     When the character cursor is on a cell (not topline), ^I (tab)
  186.     is like ^F (move forward one cell), rather than being ignored.
  187.     ^R is no longer identical with ^L.  Now ^R highlights all cells
  188.     which should be entered by a user because they contain constant
  189.     numeric values (not the result of a numeric expression).
  190.  
  191.     Added a ^X command, similar to ^R, which highlights cells which
  192.     have expressions.  It also displays the expressions in the
  193.     highlighted cells as left-justified strings, instead of the
  194.     label and/or value of the cell.
  195.  
  196.     Added indirection functions (@nval() and @sval()) for simple
  197.     table lookups.  Given a column name and row number, they return
  198.     the numeric or string value of the selected cell.
  199.  
  200.     Added external functions (@ext()) for non-trivial
  201.     computations.  Given a command name and argument, it calls the
  202.     command and reads back one output line.
  203.  
  204.     Added a ^T,e command to toggle enabling of external functions.
  205.  
  206.     Changed ^T,t to only control the top line display, and added
  207.     ^T,c to control current cell highlighting.  (Separated the
  208.     functions.)
  209.  
  210.     "!" (shell escape) gives a vi-style warning if there were any
  211.     changes since the last write.  (No change to manual entry.)
  212.  
  213.     Fixed some startup, error, and prompt messages to be cleaner
  214.     and/or more consistent.  (No changes to manual entry.)
  215.  
  216.     Fixed a bug:  If @substr() upper bound (third parameter) is
  217.     past the end of the string operand, return the substring
  218.     through the end of the string, rather than returning a null
  219.     string.
  220.  
  221.     Fixed a bug:  Reset SIGINT to default after forking before
  222.     calling shell escape program and before starting pipeline (for
  223.     commands which support this).  Didn't reset SIGINT before
  224.     calling crypt and external functions because in both cases it
  225.     should be irrelevant.  (No change to manual entry.)
  226. \SHAR\EOF\
  227. else
  228.   echo "will not over write ./CHANGES"
  229. fi
  230. if [ `wc -c ./CHANGES | awk '{printf $1}'` -ne 4045 ]
  231. then
  232. echo `wc -c ./CHANGES | awk '{print "Got " $1 ", Expected " 4045}'`
  233. fi
  234. if `test ! -s ./sc.doc`
  235. then
  236. echo "Extracting ./sc.doc"
  237. cat > ./sc.doc << '\SHAR\EOF\'
  238. .\" Warning:  The string "pname" is converted to the true program name
  239. .\" by the makefile, throughout this document.
  240. .\"
  241. .\" Warning:  The order of presentation of commands largely matches the
  242. .\" help screen built into the program.
  243. .\"
  244. .\" Conventions:
  245. .\" - pname italicized and never uppercased (it's a proper name).
  246. .\" - Refer to lists of commands in the same order as introduced.
  247. .\" - Command and function names bold when introduced, italicized in all
  248. .\"   other places if possible, or in `` '' if not.
  249. .\" - Cell names italicized except when used in expressions; row numbers
  250. .\"   and column names not italicized.
  251. .\" - Use `` '' rather than " " except referring to literal input or output.
  252. .\" - TPs use default indent except for function names, then 18.
  253. .\" - Smallify uppercase strings.
  254. .\" - Avoid passive voice and third person.
  255. .\" $Revision: 6.1 $
  256. .\"
  257. .TH PNAME 1
  258. .SH NAME
  259. pname \- spreadsheet calculator
  260. .SH SYNOPSIS
  261. .B pname
  262. [
  263. .B -c
  264. ]
  265. [
  266. .B -m
  267. ]
  268. [
  269. .B -n
  270. ]
  271. [
  272. .B -r
  273. ]
  274. [
  275. .B -x
  276. ]
  277. [
  278. .I file
  279. ]
  280. .\" ==========
  281. .SH DESCRIPTION
  282. The spreadsheet calculator
  283. .I pname
  284. is based on rectangular tables much like a financial spreadsheet.
  285. When invoked it presents you with a table
  286. organized as rows and columns of cells.
  287. If invoked without a
  288. .I file
  289. argument, the table is initially empty.
  290. Otherwise
  291. .I file
  292. is read in (see the
  293. .I Get
  294. command below).
  295. Each cell may have associated with it
  296. a numeric value,
  297. a label string,
  298. and/or an expression (formula)
  299. which evaluates to a numeric value or label string,
  300. often based on other cell values.
  301. .\" ----------
  302. .PP
  303. Options are:
  304. .\" ----------
  305. .TP
  306. .B \-c
  307. Start the program with the recalculation being done in column order.
  308. .\" ----------
  309. .TP
  310. .B \-m
  311. Start the program with automatic recalculation disabled.
  312. The spreadsheet will be recalculated only when the ``@'' command is used.
  313. .\" ----------
  314. .TP
  315. .B \-n
  316. Start the program in quick numeric entry mode (see below).
  317. .\" ----------
  318. .TP
  319. .B \-r
  320. Start the program with the recalculation being done in row
  321. order (default option).
  322. .\" ----------
  323. .TP
  324. .B \-x
  325. Cause the
  326. .I Get
  327. and
  328. .I Put
  329. commands (see below) to encrypt and decrypt data files.
  330. .\" ----------
  331. .PP
  332. All of these options can be changed with the
  333. .I ^T
  334. and 
  335. .I S
  336. commands (see below) while
  337. .I pname
  338. is running.  Options specified when
  339. .I pname 
  340. is invoked
  341. override options saved in the data file.
  342. .\" ==========
  343. .SS "General Information"
  344. .\" ----------
  345. The screen is divided into four regions.
  346. The top line is for entering commands and displaying cell values.
  347. The second line is for messages from
  348. .IR pname .
  349. The third line and the first four columns show the column and row numbers,
  350. from which are derived cell addresses, e.g.
  351. .I A0
  352. for the cell in column A, row 0.
  353. Note that column names are case-insensitive: you can enter
  354. .I A0
  355. or
  356. .IR a0 .
  357. .\" ----------
  358. .PP
  359. The rest of the screen forms a window looking at a portion of the table.
  360. The total number of display rows and columns available,
  361. hence the number of table rows and columns displayed,
  362. is set by
  363. .IR curses (3)
  364. and may be overridden by setting the
  365. .SM LINES
  366. and
  367. .SM COLUMNS
  368. environment variables, respectively.
  369. .\" ----------
  370. .PP
  371. The screen has two cursors:
  372. a cell cursor, indicated by a highlighted cell and a ``<'' on the screen,
  373. and a character cursor, indicated by the terminal's hardware cursor.
  374. The cell and character cursors are often the same.
  375. They differ when you type a command on the top line.
  376. .\" ----------
  377. .PP
  378. If a cell's numeric value is wider than the column width (see the
  379. .I f
  380. command), the cell is filled with asterisks.
  381. If a cell's label string is wider than the column width,
  382. it is truncated at the start of the next non-blank cell in the row, if any.
  383. .\" ----------
  384. .PP
  385. Cursor control commands and row and column commands
  386. can be prefixed by a numeric argument
  387. which indicates how many times the command is to be executed.
  388. You can type
  389. .I ^U
  390. before a repeat count if quick numeric entry mode is enabled
  391. or if the number is to be entered
  392. while the character cursor is on the top line.
  393. .\" ----------
  394. .PP
  395. Commands which use the terminal's control key, such as
  396. .IR ^N ,
  397. work both when a command is being typed and when in normal mode.
  398. .\" ==========
  399. .SS "Changing Options"
  400. .\" ----------
  401. \0 \" exactly one blank line (hard to get)
  402. .PD 0
  403. .TP
  404. .BI ^T o
  405. Toggle options.
  406. This command allows you to switch the state of one option selected by
  407. .IR o .
  408. A small menu lists the choices for
  409. .I o
  410. when you type
  411. .IR ^T .
  412. The options selected are saved when the data and formulas are saved
  413. so that you will have the same setup next time you enter the
  414. spreadsheet. 
  415. .PD
  416. .RS
  417. .\" ----------
  418. .TP
  419. .B a
  420. Automatic Recalculation.
  421. When set, each change in the spreadsheet causes the entire spreadsheet
  422. be recalculated.  Normally this is not noticeable, but for very large
  423. spreadsheets, it may be faster to clear automatic recalculation mode and
  424. update the spreadsheet via explicit ``@'' commands.  Default is 
  425. automatic recalculation on.
  426. .\" ----------
  427. .TP
  428. .B c
  429. Current cell highlighting.
  430. If enabled, the current cell is highlighted
  431. (using the terminal's standout mode, if available)
  432. in addition to being marked by the cell cursor.
  433. .\" ----------
  434. .TP
  435. .B e
  436. External function execution.
  437. When disabled, external functions (see
  438. .IR @ext ()
  439. below) are not called.
  440. This saves a lot of time at each screen update.
  441. External functions are disabled by default.
  442. If disabled, and external functions are used anywhere,
  443. a warning is printed each time the screen is updated,
  444. and the result of
  445. .IR @ext ()
  446. is the value from the previous call, if any, or a null string.
  447. .\" ----------
  448. .TP
  449. .B n
  450. Quick numeric entry.
  451. If enabled,
  452. a typed digit is assumed to be
  453. the start of a numeric value for the current cell,
  454. not a repeat count, unless preceded by
  455. .IR ^U .
  456. .\" ----------
  457. .TP
  458. .B t
  459. Top line display.
  460. If enabled,
  461. the name and value of the current cell is displayed on the top line.
  462. If there is an associated label string,
  463. the first character of the string value
  464. is ``<'' for a leftstring or ``>'' for a rightstring (see below),
  465. followed by "\fIstring\fP" for a constant string
  466. or
  467. .RI { expr }
  468. for a string expression.
  469. If the cell has a numeric value,
  470. it follows as
  471. .RI [ value ],
  472. which may be a constant or expression.
  473. .\" ----------
  474. .TP
  475. .B x
  476. Encryption.
  477. See the
  478. .B \-x
  479. option.
  480. .\" ----------
  481. .TP
  482. .B $
  483. Dollar prescale.
  484. If enabled, all numeric
  485. .B constants
  486. (not expressions) which you enter are multipled by 0.01
  487. so you don't have to keep typing the decimal point
  488. if you enter lots of dollar figures.
  489. .RE
  490. .\" ----------
  491. \0 \" exactly one blank line (hard to get)
  492. .PD 0
  493. .TP
  494. .B S
  495. Set options.  This command allows you to set various options.
  496. A small menu lists the options that cannot be changed through
  497. .I ^T
  498. above.
  499. .PD
  500. .RS
  501. .TP
  502. .BR byrows /  bycols
  503. Specify the order cell evaluation when updating.  These options also affect
  504. the order in which cells are filled (see 
  505. .IR /f )
  506. and whether a row or column is cleared by an 
  507. .I x
  508. command.
  509. .TP
  510. .BI iterations =n
  511. Set the maximum number of recalculations before
  512. the screen is displayed again. 
  513. .I Iterations
  514. is set to 10 by default.
  515. .TP
  516. .BI tblstyle =s
  517. Control the output of the 
  518. .I T
  519. command.
  520. .I s
  521. can be:
  522. .B 0
  523. (default) to give colon delimited fields, with no 
  524. .I tbl
  525. control lines;
  526. .B tbl
  527. to give colon delimited fields, with
  528. .IR tbl (1)
  529. control lines;
  530. .B latex
  531. to give a
  532. .I LaTeX
  533. tabular environment; and
  534. .B tex
  535. to give a
  536. .I TeX
  537. simple tabbed alignment with ampersands as delimiters.
  538. .PP
  539. Other
  540. .I Set
  541. options are normally used only in 
  542. .I pname
  543. data files since they are available through 
  544. .IR ^T .
  545. You can also use them interactively
  546. .TP
  547. .BR autocalc / !autocalc
  548. Set/clear auto recalculation mode.
  549. .TP
  550. .BR numeric / !numeric
  551. Set/clear numeric mode.
  552. .TP
  553. .BR prescale / !prescale
  554. Set/clear numeric prescale mode.
  555. .TP
  556. .BR extfun / !extfun
  557. Enable/disable external functions.
  558. .TP
  559. .BR cellcur / !cellcur
  560. Set/clear current cell highlighting mode.
  561. .TP
  562. .BR toprow /  !toprow
  563. Set/clear top row display mode.
  564. .RE
  565. .\" ==========
  566. .SS "Cursor Control Commands"
  567. .\" ----------
  568. \0 \" exactly one blank line (hard to get)
  569. .PD 0
  570. .TP
  571. .B ^P
  572. Move the cell cursor up to the previous row.
  573. .PD
  574. .\" ----------
  575. .TP
  576. .B ^N
  577. Move the cell cursor down to the next row.
  578. .\" ----------
  579. .TP
  580. .B ^B
  581. Move the cell cursor backward one column.
  582. .\" ----------
  583. .TP
  584. .B ^F
  585. Move the cell cursor forward one column.
  586. .\" ----------
  587. .TP
  588. .B "h, j, k, l"
  589. If the character cursor is not on the top line, these are alternate,
  590. .IR vi -compatible
  591. cell cursor controls (left, down, up, right).
  592. .\" ----------
  593. .TP
  594. .B ^H
  595. If the character cursor is not on the top line,
  596. .I ^H
  597. is the same as
  598. .IR ^B .
  599. .\" ----------
  600. .TP
  601. .B SPACE
  602. If the character cursor is not on the top line,
  603. the space bar is the same as
  604. .IR ^F .
  605. .\" ----------
  606. .TP
  607. .B TAB
  608. If the character cursor is on the top line,
  609. .SM TAB
  610. starts a range (see below).
  611. Otherwise, it is the same as
  612. .IR ^F .
  613. .\" ----------
  614. .TP
  615. .B "Arrow Keys"
  616. The terminal's arrow keys provide another alternate set of cell cursor controls
  617. if they exist and are supported in the appropriate
  618. .I termcap
  619. entry.
  620. Some terminals have arrow keys which conflict with other control key codes.
  621. For example, a terminal might send
  622. .I ^H
  623. when the back arrow key is pressed.
  624. In these cases, the conflicting arrow key performs the same function
  625. as the key combination it mimics.
  626. .\" ----------
  627. .TP
  628. .B ^
  629. Move the cell cursor up to row 0 of the current column.
  630. .\" ----------
  631. .TP
  632. .B #
  633. Move the cell cursor down to the last valid row of the current column.
  634. .\" ----------
  635. .TP
  636. .B 0
  637. Move the cell cursor backward to column A of the current row.
  638. This command must be prefixed with
  639. .I ^U
  640. if quick numeric entry mode is enabled.
  641. .\" ----------
  642. .TP
  643. .B $
  644. Move the cell cursor forward to the last valid column of the current row.
  645. .\" ----------
  646. .TP
  647. .B b
  648. Scan the cursor backward (left and up) to the previous valid cell.
  649. .\" ----------
  650. .TP
  651. .B w
  652. Scan the cursor forward (right and down) to the next valid cell.
  653. .\" ----------
  654. .TP
  655. .BI ^E d
  656. Go to end of range.
  657. Follow
  658. .I ^E
  659. by a direction indicator such as
  660. .I ^P
  661. or
  662. .IR j .
  663. If the cell cursor starts on a non-blank cell,
  664. it goes in the indicated direction until the last non-blank adjacent cell.
  665. If the cell cursor starts on a blank cell,
  666. it goes in the indicated direction until the first non-blank cell.
  667. This command is useful when specifying ranges of adjacent cells (see below),
  668. especially when the range is bigger than the visible window.
  669. .\" ----------
  670. .TP
  671. .B g
  672. Go to a cell.
  673. .I pname
  674. prompts for a cell's name, a regular expression surrounded by
  675. quotes, or a number.
  676. If a cell's name such as
  677. .I ae122 
  678. or a the name of a defined range is given, the cell cursor goes
  679. directly to that cell.
  680. If a quoted regular expression such as "
  681. .I Tax Table 
  682. " or "
  683. .I ^Jan [0-9]*$
  684. " is given,
  685. .I pname
  686. searches for a cell containing a string matching the regular
  687. expression.
  688. See 
  689. .I regex(3)
  690. or
  691. .I ed(1)
  692. for more details on the form of regular
  693. expressions.
  694. If a number is given, 
  695. .I pname
  696. will search for a cell containing that number.
  697. Searches for either strings or numbers proceed forward from the
  698. current cell, wrapping back to a0 at the end of the table, and
  699. terminate at the current cell if the string or number is not found.
  700. The last
  701. .I g
  702. command is saved, and can be re-issued by entering 
  703. .IR g<return> .
  704. .\" ==========
  705. .SS "Cell Entry and Editing Commands"
  706. .\" ----------
  707. Cells can contain both a numeric value and a string value.
  708. Either value can be the result of an expression,
  709. but not both at once,
  710. i.e. each cell can have only one expression associated with it.
  711. Entering a valid numeric expression
  712. alters the cell's previous numeric value, if any,
  713. and replaces the cell's previous string expression, if any,
  714. leaving only the previously computed constant label string.
  715. Likewise, entering a valid string expression
  716. alters the cell's the previous label string, if any,
  717. and replaces the cell's previous numeric expression, if any,
  718. leaving only the previously computed constant numeric value.
  719. .TP
  720. .B =
  721. Enter a numeric constant or expression into the current cell.
  722. .I pname
  723. prompts for the expression on the top line.
  724. The usual way to enter a number into a cell is to type ``='',
  725. then enter the number in response to the prompt on the top line.
  726. The quick numeric entry option, enabled through the
  727. .B \-n
  728. option or
  729. .I ^T
  730. command, shows the prompt when you enter the first digit of a number
  731. (you can skip typing ``='').
  732. .\" ----------
  733. .TP
  734. .B <
  735. Enter a label string into the current cell
  736. to be flushed left against the left edge of the cell.
  737. .\" ----------
  738. .IP \fB"\fP
  739. .PD 0
  740. .TP
  741. .B >
  742. Enter a label string into the current cell
  743. to be flushed right against the right edge of the cell.
  744. .PD
  745. .\" ----------
  746. .PP
  747. Strings you enter must start with ".
  748. You can leave off the trailing " and
  749. .I pname
  750. will add it for you.
  751. You can also enter a string expression
  752. by backspacing over the opening " in the prompt.
  753. .\" ----------
  754. .TP
  755. .B e
  756. Edit the value associated with the current cell.
  757. This is identical to ``=''
  758. except that the command line starts out containing
  759. the old numeric value or expression associated with the cell.
  760. .\" ----------
  761. .TP
  762. .B E
  763. Edit the string associated with the current cell.
  764. This is identical to ``<'', ``"'', or ``>''
  765. except that the command line starts out containing
  766. the old string value or expression associated with the cell.
  767. .\" ----------
  768. .PP
  769. To enter and edit a cell's number part, use the ``='' and
  770. .I e
  771. commands.
  772. To enter and edit a cell's string part, use the ``<'', ``"'', ``>'', and
  773. .I E
  774. commands.
  775. See the sections below on numeric and string expressions for more information.
  776. .\" ----------
  777. .TP
  778. .B x
  779. Clear the current cell.
  780. Deletes the numeric value, label string, and/or numeric or string expression.
  781. You can prefix this command with a count
  782. of the number of cells on the current row to clear.  The current column is
  783. used if column recalculation order is set.
  784. Cells cleared with this command may be recalled
  785. with any of the
  786. .I pull
  787. commands (see below).
  788. .\" ----------
  789. .TP
  790. .B m
  791. Mark a cell to be used as the source for the
  792. .I copy
  793. command.
  794. .\" ----------
  795. .TP
  796. .B c
  797. Copy the last marked cell to the current cell,
  798. updating row and column references in its numeric or string expression, if any.
  799. .\" ----------
  800. .TP
  801. .B +
  802. If not in numeric mode, add the current numeric argument (default 1)
  803. to the value of the current cell.  In numeric mode, ``+'' introduces a new
  804. numeric expression or value, the same as ``=''. 
  805. .\" ----------
  806. .TP
  807. .B -
  808. If not in numeric mode, subtract the current numeric argument (default 1)
  809. from the value of the current cell.  In numeric mode, ``-'' introduces a new,
  810. negative, numeric expression or value, like ``=''. 
  811. .\" ==========
  812. .SS "File Commands"
  813. .\" ----------
  814. \0 \" exactly one blank line (hard to get)
  815. .PD 0
  816. .TP
  817. .B G
  818. Get a new database from a file.
  819. If encryption is enabled,
  820. the file is decrypted before it is loaded into the spreadsheet.
  821. .PD
  822. .\" ----------
  823. .TP
  824. .B P
  825. Put the current database into a file.
  826. If encryption is enabled,
  827. the file is encrypted before it is saved.
  828. .\" ----------
  829. .TP
  830. .B W
  831. Write a listing of the current database into a file
  832. in a form that matches its appearance on the screen.
  833. This differs from the
  834. .I Put
  835. command in that its files are intended to be reloaded with
  836. .IR Get ,
  837. while
  838. .I Write
  839. produces a file for people to look at.  Hidden rows or columns
  840. are not shown when the data is printed.
  841. .\" ----------
  842. .TP
  843. .B T
  844. Write a listing of the current database to a file,
  845. but include delimiters suitable for processing by the
  846. .IR tbl ,
  847. .IR LaTeX ,
  848. or
  849. .I TeX
  850. table processors.
  851. The delimiters are controlled by the
  852. .I tblstyle
  853. option.  See
  854. .I Set
  855. above.
  856. The delimters are are a colon\ (:) for style
  857. .IR 0 or tbl
  858. and an ampersand\ (&) for style
  859. .IR latex or tex .
  860. .\" ----------
  861. .PP
  862. With the
  863. .IR Put ,
  864. .IR Write ,
  865. and
  866. .I Table
  867. commands, the optional range argument writes a subset of the spreadsheet to
  868. the output file.
  869. .\" ----------
  870. .PP
  871. With the
  872. .I Write
  873. and
  874. .I Table
  875. commands, if you try to write to the last file used with the
  876. .I Get
  877. or
  878. .I Put
  879. commands, or the file specified on the command line when
  880. .I pname
  881. was invoked, you are asked to confirm
  882. that the (potentially) dangerous operation is really what you want.
  883. .\" ----------
  884. .PP
  885. The three output commands,
  886. .IR Put ,
  887. .IR Write ,
  888. and
  889. .IR Table ,
  890. can pipe their (unencrypted only) output to a program.
  891. To use this feature,
  892. enter ``| program'' to the prompt asking for a filename.
  893. For example, to redirect the output of the
  894. .I Write
  895. command to the printer,
  896. you might enter ``| lpr -p''.
  897. .\" ----------
  898. .TP
  899. .B M
  900. Merge the database from the named file into the current database.
  901. Values and expressions defined in the named file
  902. are read into the current spreadsheet
  903. overwriting the existing entries at matching cell locations.
  904. .\" ----------
  905. .TP
  906. .B R
  907. Run macros.
  908. Since
  909. .I pname
  910. files are saved as ASCII files,
  911. it is possible to use them as primitive macro definition files.
  912. The
  913. .I Run
  914. command makes this easier.
  915. It's like the
  916. .I Merge
  917. command,
  918. but prints a saved path name as the start of the filename to merge in.
  919. The string to use is set with the
  920. .I Define
  921. command.
  922. To write macros, you must be familiar with the file format written by the
  923. .I Put
  924. command.
  925. This facility is still primitive and could be much improved.
  926. .\" ----------
  927. .TP
  928. .B D
  929. Define a path for the
  930. .I Run
  931. command to use.
  932. .\" ----------
  933. .PP
  934. All file operations take a filename as the first argument
  935. to the prompt on the top line.
  936. The prompt supplies a " to aid in typing in the filename.
  937. The filename can also be obtained from a cell's label string
  938. or string expression.
  939. In this case, delete the leading " with the backspace key
  940. and enter a cell name such as
  941. .I a22
  942. instead.
  943. If the resulting string starts with ``|'',
  944. the rest of the string is interpreted as a
  945. .SM UNIX
  946. command, as above.
  947. .\" ==========
  948. .SS "Row and Column Commands"
  949. .\" ----------
  950. These commands can be used on either rows or columns.
  951. The second letter of the command is either a row designator
  952. (one of the characters
  953. .IR r ,
  954. .IR ^B ,
  955. .IR ^F ,
  956. .IR h ,
  957. .IR l )
  958. or a column designator (one of
  959. .IR c ,
  960. .IR ^P ,
  961. .IR ^N ,
  962. .IR k ,
  963. .IR j ).
  964. A small menu lists the choices for the second letter
  965. when you type the first letter of one of these commands.
  966. Commands which move or copy cells
  967. also modify the row and column references in affected cell expressions.
  968. The references may be frozen by using the
  969. .I fixed
  970. operator or using the
  971. .I $
  972. character in the reference to the cell (see below).
  973. .\" ----------
  974. .TP
  975. .B "ir, ic"
  976. Insert a new row (column)
  977. by moving the row (column) containing the cell cursor,
  978. and all following rows (columns), down (right) one row (column).
  979. The new row (column) is empty.
  980. .\" ----------
  981. .TP
  982. .B "ar, ac"
  983. Append a new row (column) immediately following the current row (column).
  984. It is initialized as a copy of the current one.
  985. .\" ----------
  986. .TP
  987. .B "dr, dc"
  988. Delete the current row (column).
  989. .\" ----------
  990. .TP
  991. .B "pr, pc, pm"
  992. Pull deleted rows (columns) back into the spreadsheet.
  993. The last deleted set of cells is put back into the spreadsheet
  994. at the current location.
  995. .I pr
  996. inserts enough rows to hold the data.
  997. .I pc
  998. inserts enough columns to hold the data.
  999. .I pm
  1000. (merge) does not insert rows or columns;
  1001. it overwrites the cells beginning at the current cell cursor location.
  1002. .\" ----------
  1003. .TP
  1004. .B "vr, vc"
  1005. Remove expressions from the affected rows (columns),
  1006. leaving only the values which were in the cells
  1007. before the command was executed.
  1008. .\" ----------
  1009. .TP
  1010. .B "zr, zc"
  1011. Hide (``zap'') the current row (column).
  1012. This keeps a row (column) from being displayed but keeps it in the data base.
  1013. The status of the rows and columns is saved with the data base so hidden
  1014. rows and columns will be still
  1015. be hidden when you reload the spreadsheet.  Hidden rows or columns are not
  1016. printed by the
  1017. .I W
  1018. command.
  1019. .\" ----------
  1020. .TP
  1021. .B "sr, sc"
  1022. Show hidden rows (columns).
  1023. Enter a range of rows (columns) to be revealed.
  1024. The default is the first range of rows (columns) currently hidden.
  1025. This command ignores the repeat count, if any.
  1026. .\" ----------
  1027. .TP
  1028. .B f
  1029. Set the output format to be used
  1030. for printing the numeric values in each cell in the current column.
  1031. Enter two numbers:
  1032. the total width in characters of the column,
  1033. and the number of digits to follow decimal points.
  1034. Values are rounded off to the least significant digit displayed.
  1035. The total column width affects displays of strings as well as numbers.
  1036. A preceding count can be used to affect more than one column.
  1037. This command has only a column version (no second letter).
  1038. .\" ==========
  1039. .SS "Range Commands"
  1040. .\" ----------
  1041. Range operations affect a rectangular region on the screen
  1042. defined by the upper left and lower right cells in the region.
  1043. All of the commands in this class start with a slash;
  1044. the second letter of the command indicates which command.
  1045. A small menu lists the choices for the second letter when you type ``/''.
  1046. .I pname
  1047. prompts for needed parameters for each command.
  1048. Phrases surrounded by square brackets in the prompt are informational only
  1049. and may be erased with the backspace key.
  1050. .\" ----------
  1051. .PP
  1052. Prompts requesting variable names may be satisfied
  1053. with either an explicit variable name, such as
  1054. .IR A10 ,
  1055. or with a variable name previously defined in a
  1056. .I /d
  1057. command (see below).
  1058. Range name prompts require either an explicit range such as
  1059. .IR A10:B20 ,
  1060. or a range name previously defined with a
  1061. .I /d
  1062. command.
  1063. A default range shown in the second line
  1064. is used if you omit the range from the command or press the
  1065. .SM TAB
  1066. key (see below).
  1067. The default range can be changed by moving the cell cursor
  1068. via the control commands
  1069. .RI ( ^P ,
  1070. .IR ^N ,
  1071. .IR ^B ,
  1072. .IR ^F )
  1073. or the arrow keys.
  1074. The cells in the default range are highlighted
  1075. (using the terminal's standout mode, if available).
  1076. .\" ----------
  1077. .TP
  1078. .B /x
  1079. Clear a range.
  1080. Cells cleared with this command may be recalled with any of the
  1081. .I pull
  1082. commands.
  1083. .\" ----------
  1084. .TP
  1085. .B /v
  1086. Values only.
  1087. This command removes the expressions from a range of cells,
  1088. leaving just the values of the expressions.
  1089. .\" ----------
  1090. .TP
  1091. .B /c
  1092. Copy a source range to a destination range.
  1093. The source and destination may be different sizes.
  1094. The result is always one or more full copies of the source.
  1095. Copying a row to a row yields a row.
  1096. Copying a column to a column yields a column.
  1097. Copying a range to anything yields a range.
  1098. Copying a row to a column or a column to a row yields a range
  1099. with as many copies of the source as there are cells in the destination.
  1100. This command can be used to duplicate a cell through an arbitrary range
  1101. by making the source a single cell range such as
  1102. .IR b20:b20 .
  1103. .\" ----------
  1104. .TP
  1105. .B /f
  1106. Fill a range with constant values
  1107. starting with a given value and increasing by a given increment.
  1108. Each row is filled before moving on to the next row if row order
  1109. recalculation is set.  Column order fills each column in the range
  1110. before moving on to the next column.
  1111. The start and increment numbers may be positive or negative.
  1112. To fill all cells with the same value, give an increment of zero.
  1113. .\" ----------
  1114. .TP
  1115. .B /d
  1116. Use this command to assign a symbolic name to a single cell
  1117. or a rectangular range of cells on the screen.
  1118. The parameters are the name, surrounded by "",
  1119. and either a single cell name such as
  1120. .I A10
  1121. or a range such as
  1122. .IR a1:b20 .
  1123. Names defined in this fashion are used by the program in future prompts,
  1124. may be entered in response to prompts requesting a cell or range name,
  1125. and are saved when the spreadsheet is saved with the
  1126. .I Put
  1127. command.
  1128. Names defined must be more than two alpha characters long
  1129. to differentiate them from a column names,
  1130. and must not have embedded special characters.
  1131. Names may include the character ``_'' or numerals
  1132. as long as they occur after the first three alpha characters.
  1133. .\" ----------
  1134. .TP
  1135. .B /s
  1136. This command lists (shows) the currently defined range names.
  1137. If there are no defined range names, then a message is given,
  1138. otherwise
  1139. it pipes output to
  1140. .IR sort ,
  1141. then to
  1142. .IR less .
  1143. If the environment variable PAGER is set, its value is used in place of
  1144. .IR less.
  1145. .\" ----------
  1146. .TP
  1147. .B /u
  1148. Use this command to undefine a previously defined range name.
  1149. .\" ==========
  1150. .SS "Miscellaneous Commands"
  1151. .\" ----------
  1152. \0 \" exactly one blank line (hard to get)
  1153. .PD 0
  1154. .TP
  1155. .B Q
  1156. .TP
  1157. .B q
  1158. .TP
  1159. .B ^C
  1160. Exit from
  1161. .IR pname .
  1162. If you made any changes since the last
  1163. .I Get
  1164. or
  1165. .IR Put ,
  1166. .I pname
  1167. asks about saving your data before exiting.
  1168. .PD
  1169. .\" ----------
  1170. .TP
  1171. .B ^G
  1172. .PD 0
  1173. .TP
  1174. .B ESC
  1175. Abort entry of the current command.
  1176. .PD
  1177. .\" ----------
  1178. .TP
  1179. .B ?
  1180. Enter an interactive help facility.  Lets you look up brief
  1181. summaries of the main features of the program.  The help facility is
  1182. structured like this manual page so it is easy to find more
  1183. information on a particular topic.
  1184. .\" ----------
  1185. .TP
  1186. .B !
  1187. Shell escape.
  1188. .I pname
  1189. prompts for a shell command to run.
  1190. End the command line with the
  1191. .SM RETURN
  1192. key.
  1193. If the environment variable
  1194. .SM SHELL
  1195. is defined, that shell is run.
  1196. If not, /bin/sh is used.
  1197. Giving a null command line starts the shell in interactive mode.
  1198. A second ``!'' repeats the previous command.
  1199. .\" ----------
  1200. .TP
  1201. .B ^L
  1202. Redraw the screen.
  1203. .\" ----------
  1204. .TP
  1205. .B ^R
  1206. Redraw the screen with special highlighting of cells to be filled in.
  1207. This is useful for finding values you need to provide or update
  1208. in a form with which you aren't familiar
  1209. or of which you have forgotten the details.
  1210.  
  1211. It's also useful for checking a form you are creating.
  1212. All cells which contain constant numeric values
  1213. (not the result of a numeric expression)
  1214. are highlighted temporarily,
  1215. until the next screen change, however minor.
  1216. To avoid ambiguity,
  1217. the current range (if any) and current cell are not highlighted.
  1218. .\" ----------
  1219. .TP
  1220. .B ^X
  1221. This command is similar to
  1222. .IR ^R ,
  1223. but highlights cells which have expressions.
  1224. It also displays the expressions in the highlighted cells
  1225. as left-flushed strings,
  1226. instead of the numeric values and/or label strings of those cells.
  1227. This command makes it easier to check expressions,
  1228. at least when they fit in their cells or the following cell(s) are blank
  1229. so the expressions can slop over (like label strings).
  1230. In the latter case, the slop over is not cleared on the next screen update,
  1231. so you may want to type
  1232. .I ^L
  1233. after the
  1234. .I ^X
  1235. in order to clean up the screen.
  1236. .\" ----------
  1237. .TP
  1238. .B @
  1239. Recalculates the spreadsheet.
  1240. .\" ----------
  1241. .TP
  1242. .B ^V
  1243. Type, in the command line, the name of the current cell
  1244. (the one at the cell cursor).
  1245. This is useful when entering expressions
  1246. which refer to other cells in the table.
  1247. .\" ----------
  1248. .TP
  1249. .B ^W
  1250. Type, in the command line, the expression attached to the current cell.
  1251. If there is none, the result is ``?''.
  1252. .\" ----------
  1253. .TP
  1254. .B ^A
  1255. Type, in the command line, the numeric value of the current cell, if any.
  1256. .\" ----------
  1257. .PP
  1258. The
  1259. .IR ^V ,
  1260. .IR ^W ,
  1261. and
  1262. .I ^A
  1263. commands only work when the character cursor
  1264. is on the command line and beyond the first character.
  1265. .\" ----------
  1266. .TP
  1267. .B TAB
  1268. When the character cursor is on the top line,
  1269. defines a range of cells via the cursor control commands or the arrow keys.
  1270. The range is highlighted,
  1271. starts at the cell where you typed
  1272. .SM TAB,
  1273. and continues through the current cell cursor.
  1274. Pressing
  1275. .SM TAB
  1276. again causes the highlighted range to be entered into the command line
  1277. and the highlighting to be turned off.
  1278. This is most useful for defining ranges to functions such as
  1279. .IR @sum ().
  1280. Pressing ``)'' acts just like typing the
  1281. .SM TAB
  1282. key the second time and adds the closing ``)''.
  1283. Note that when you give a range command,
  1284. you don't need to press the first
  1285. .SM TAB
  1286. to begin defining a range starting with the current cell.
  1287. .\" ==========
  1288. .SS "Variable Names"
  1289. .\" ----------
  1290. Normally, a variable name is just the name of a cell, such as
  1291. .IR K20 .
  1292. The value is the numeric or string value of the cell,
  1293. according to context.
  1294. .\" ----------
  1295. .PP
  1296. When a cell's expression (formula) is copied to another location via
  1297. .I copy
  1298. or
  1299. .IR range-copy ,
  1300. variable references are by default offset by the amount the formula moved.
  1301. This allows the new formula to work on new data.
  1302. If cell references are not to change,
  1303. you can either use the
  1304. .I fixed
  1305. operator (see below),
  1306. or one of the following variations on the cell name.
  1307. .\" ----------
  1308. .TP
  1309. .I K20
  1310. References cell
  1311. .IR K20 ;
  1312. the reference changes when the formula is copied.
  1313. .\" ----------
  1314. .TP
  1315. .BI $ K $ 20
  1316. Always refers to cell
  1317. .IR K20 ;
  1318. the reference stays fixed when the formula is copied.
  1319. .\" ----------
  1320. .TP
  1321. .BI $ K20
  1322. Keeps the column fixed at column K;
  1323. the row is free to vary.
  1324. .\" ----------
  1325. .TP
  1326. .IB K $ 20
  1327. Similarly, this fixes the row and allows the column to vary.
  1328. .\" ----------
  1329. .PP
  1330. These conventions also hold on defined ranges.
  1331. Range references vary when formulas containing them are copied.
  1332. If the range is defined with fixed variable references,
  1333. the references do not change.
  1334. .\" ----------
  1335. .TP
  1336. .B fixed
  1337. To make a variable not change automatically when a cell moves,
  1338. put the word
  1339. .I fixed
  1340. in front of the reference, for example:
  1341. B1 \(** fixed C3.
  1342. .\" ==========
  1343. .SS "Numeric Expressions"
  1344. .\" ----------
  1345. Numeric expressions used with the ``=''
  1346. and
  1347. .I e
  1348. commands have a fairly conventional syntax.
  1349. Terms may be
  1350. constants,
  1351. variable names,
  1352. parenthesized expressions,
  1353. and negated terms.
  1354. Ranges may be operated upon with range functions such as sum
  1355. .RI ( @sum ())
  1356. and average
  1357. .RI ( @avg ()).
  1358. Terms may be combined using binary operators.
  1359. .\" ----------
  1360. .TP
  1361. .BR \- e
  1362. Negation.
  1363. .\" ----------
  1364. .TP
  1365. .RB e + e
  1366. Addition.
  1367. .\" ----------
  1368. .TP
  1369. .RB e \- e
  1370. Subtraction.
  1371. .\" ----------
  1372. .TP
  1373. .RB e \(** e
  1374. Multiplication.
  1375. .\" ----------
  1376. .TP
  1377. .RB e / e
  1378. Division.
  1379. .\" ----------
  1380. .TP
  1381. .RB e1 % e2
  1382. e1 mod e2.
  1383. .\" ----------
  1384. .TP
  1385. .RB e ^ e
  1386. Exponentiation.
  1387. .\" ----------
  1388. .TP
  1389. .RB e < e
  1390. .PD 0
  1391. .TP
  1392. .RB e <= e
  1393. .TP
  1394. .RB e = e
  1395. .TP
  1396. .RB e != e
  1397. .TP
  1398. .RB e >= e
  1399. .TP
  1400. .RB e > e
  1401. Relationals:
  1402. true (1) if and only if the indicated relation holds,
  1403. else false (0).
  1404. Note that ``<='', ``!='', and ``>=''
  1405. are converted to their ``~()'' equivalents.
  1406. .PD
  1407. .\" ----------
  1408. .TP
  1409. .BR ~ e
  1410. Boolean operator
  1411. .SM NOT.
  1412. .\" ----------
  1413. .TP
  1414. .RB e & e
  1415. Boolean operator
  1416. .SM AND.
  1417. .\" ----------
  1418. .TP
  1419. .RB e | e
  1420. Boolean operator
  1421. .SM OR.
  1422. .\" ----------
  1423. .TP
  1424. .RB e ? e : e
  1425. Conditional:
  1426. If the first expression is true then the value of the second is returned,
  1427. otherwise the value of the third.
  1428. .\" ----------
  1429. .PP
  1430. Operator precedence from highest to lowest is:
  1431. .PP
  1432. .nf
  1433. .RS
  1434. \-, ~
  1435. ^
  1436. \(**, /
  1437. +, \-
  1438. <, <=, =, !=, >=, >
  1439. &
  1440. |
  1441. ?:
  1442. .RE
  1443. .fi
  1444. .\" ==========
  1445. .SS "Built-in Range Functions"
  1446. .\" ----------
  1447. These functions return numeric values.
  1448. .\" ----------
  1449. .TP 18
  1450. .BR @sum (r)
  1451. Sum all valid (nonblank) entries in the region
  1452. whose two corners are defined by the two variable names (e.g.
  1453. .IR c5:e14 )
  1454. or the range name specified.
  1455. .\" ----------
  1456. .TP 18
  1457. .BR @prod (r)
  1458. Multiply together all valid (nonblank) entries in the specified region.
  1459. .\" ----------
  1460. .TP 18
  1461. .BR @avg (r)
  1462. Average all valid (nonblank) entries in the specified region.
  1463. .\" ----------
  1464. .TP 18
  1465. .BR @max (r)
  1466. Return the maximum value in the specified region.  See also the multi argument
  1467. version of
  1468. .I @max
  1469. below.
  1470. .\" ----------
  1471. .TP 18
  1472. .BR @min (r)
  1473. Return the minimum value in the specified region.  See also the multi argument
  1474. version of
  1475. .I @min
  1476. below.
  1477. .\" ----------
  1478. .TP 18
  1479. .BR @stddev (r)
  1480. Return the sample standard deviation of the cells in the specified region.
  1481. .\" ----------
  1482. .TP 18
  1483. .BR @lookup (e,r)
  1484. .PD 0
  1485. .TP 18
  1486. .BR @lookup (se,r)
  1487. .PD
  1488. Evaluates the expression then searches through the range
  1489. .I r
  1490. for a matching value.
  1491. The range should be either a single row or a single column.
  1492. The expression can be either a string
  1493. expression or a numeric expression.  If it is a numeric expression,
  1494. the range is searched for the the last value less than or equal to 
  1495. .IR e .
  1496. If the expression is a string expression, the string portions
  1497. of the cells in the range are searched for an exact string match.
  1498. The value returned is the numeric value from the next row and the same
  1499. column as the match, if the range was a single row, or the value from
  1500. the next column and the same row as the match if the range was a single
  1501. column.
  1502. .\" ----------
  1503. .TP 18
  1504. .BR @index (e,r)
  1505. Use the value of the expression 
  1506. .I e
  1507. to index into
  1508. the range
  1509. .IR r .
  1510. The numeric value at that position is returned. 
  1511. The value 1 selects the first item in the range,
  1512. 2 selects the second item, etc.
  1513. .I R
  1514. should be either a single row or a single
  1515. column.
  1516. .\" ----------
  1517. .TP 18
  1518. .BR @stindex (e,r)
  1519. Use the value of 
  1520. .I e
  1521. to index into
  1522. the range
  1523. .IR r .
  1524. The string value at that position is returned. 
  1525. The value 1 selects the first item in the range,
  1526. 2 selects the second item, etc.
  1527. The range should be either a single row or a single
  1528. column.
  1529. .\" ==========
  1530. .SS "Built-in Numeric Functions"
  1531. .\" ----------
  1532. All of these functions operate on floating point numbers (doubles)
  1533. and return numeric values.
  1534. Most of them are standard system functions more fully described in
  1535. .IR math (3).
  1536. The trig functions operate with angles in radians.
  1537. .\" ----------
  1538. .TP 18
  1539. .BR @sqrt (e)
  1540. Return the square root of
  1541. .IR e .
  1542. .\" ----------
  1543. .TP 18
  1544. .BR @exp (e)
  1545. Return the exponential function of
  1546. .IR e .
  1547. .\" ----------
  1548. .TP 18
  1549. .BR @ln (e)
  1550. Return the natural logarithm of
  1551. .IR e .
  1552. .\" ----------
  1553. .TP 18
  1554. .BR @log (e)
  1555. Return the base 10 logarithm of
  1556. .IR e .
  1557. .\" ----------
  1558. .TP 18
  1559. .BR @floor (e)
  1560. Return the largest integer not greater than
  1561. .IR e .
  1562. .\" ----------
  1563. .TP 18
  1564. .BR @ceil (e)
  1565. Return the smallest integer not less than
  1566. .IR e .
  1567. .\" ----------
  1568. .TP 18
  1569. .BR @rnd (e)
  1570. Round
  1571. .I e
  1572. to the nearest integer.
  1573. .\" ----------
  1574. .TP 18
  1575. .BR @fabs (e)
  1576. Return the absolute value of
  1577. .IR e .
  1578. .\" ----------
  1579. .TP 18
  1580. .BR @pow (e1,e2)
  1581. Return
  1582. .I e1
  1583. raised to the power of
  1584. .IR e2 .
  1585. .\" ----------
  1586. .TP 18
  1587. .BR @hypot (e1,e2)
  1588. Return sqrt(e1\(**e1+e2\(**e2), taking precautions against unwarranted
  1589. overflows.
  1590. .\" ----------
  1591. .TP 18
  1592. .B pi
  1593. A constant quite close to pi.
  1594. .\" ----------
  1595. .TP 18
  1596. .BR @dtr (e)
  1597. Convert
  1598. .I e
  1599. in degrees to radians.
  1600. .\" ----------
  1601. .TP 18
  1602. .BR @rtd (e)
  1603. Convert
  1604. .I e
  1605. in radians to degrees.
  1606. .\" ----------
  1607. .TP 18
  1608. .BR @sin (e)
  1609. .PD 0
  1610. .TP 18
  1611. .BR @cos (e)
  1612. .TP 18
  1613. .BR @tan (e)
  1614. Return trigonometric functions of radian arguments.
  1615. The magnitude of the arguments are not checked to assure meaningful results.
  1616. .PD
  1617. .\" ----------
  1618. .TP 18
  1619. .BR @asin (e)
  1620. Return the arc sine of
  1621. .I e
  1622. in the range -pi/2 to pi/2.
  1623. .\" ----------
  1624. .TP 18
  1625. .BR @acos (e)
  1626. Return the arc cosine of
  1627. .I e
  1628. in the range 0 to pi.
  1629. .\" ----------
  1630. .TP 18
  1631. .BR @atan (e)
  1632. Return the arc tangent of
  1633. .I e
  1634. in the range -pi/2 to pi/2.
  1635. .\" ----------
  1636. .TP 18
  1637. .BR @atan2 (e1,e2)
  1638. Returns the arc tangent of
  1639. .IR e1 / e2
  1640. in the range -pi to pi.
  1641. .\" ----------
  1642. .TP 18
  1643. .BR @max (e1,e2,...)
  1644. Return the maximum of the values of the expressions.  Two or more expressions
  1645. may be specified.  See also the range version of 
  1646. .I @max
  1647. above.
  1648. .\" ----------
  1649. .TP 18
  1650. .BR @min (e1,e2,...)
  1651. Return the minimum of the values of the expressions.  Two or more expressions
  1652. may be specified.  See also the range version of 
  1653. .I @min
  1654. above.
  1655. .\" ----------
  1656. .TP 18
  1657. .BR @ston (se)
  1658. Convert string expression
  1659. .I se
  1660. to a numeric value.
  1661. .\" ----------
  1662. .TP 18
  1663. .BR @eqs (se1,se2)
  1664. Return 1 if string expression
  1665. .I se1
  1666. has the same value as string expression
  1667. .IR se2 ,
  1668. 0 otherwise.
  1669. .\" ----------
  1670. .TP 18
  1671. .BR @nval (se,e)
  1672. Return the numeric value of a cell selected by name.
  1673. String expression
  1674. .I se
  1675. must evaluate to a column name (``A''-``AE'') and
  1676. .I e
  1677. must evaluate to a row number (0-199). 
  1678. If
  1679. .I se
  1680. or
  1681. .I e
  1682. is out of bounds, or the cell has no numeric value, the result is 0.
  1683. You can use this for simple table lookups.
  1684. Be sure the table doesn't move unexpectedly!
  1685. See also
  1686. .IR @sval ()
  1687. below.
  1688. .\" ==========
  1689. .SS "String Expressions"
  1690. .\" ----------
  1691. String expressions are made up of constant strings
  1692. (characters surrounded by double quotation marks),
  1693. variables
  1694. (cell names, which refer to the cells's label strings or expressions),
  1695. and string functions.
  1696. Note that string expressions are only allowed
  1697. when entering a cell's label string, not its numeric part.
  1698. Also note that string expression results may be left or right flushed,
  1699. according to the type of the cell's string label.
  1700. .\" ----------
  1701. .TP
  1702. .B #
  1703. Concatenate strings.
  1704. For example, the string expression
  1705. .IP ""
  1706.     A0 # "zy dog"
  1707. .IP ""
  1708. displays the string ``the lazy dog'' in the cell if the value of
  1709. .IR A0 's
  1710. string is ``the la''.
  1711. .\" ==========
  1712. .SS "Built-in String Functions"
  1713. .\" ----------
  1714. \0 \" exactly one blank line (hard to get)
  1715. .PD 0
  1716. .TP 18
  1717. .BR @substr (se,e1,e2)
  1718. Extract and return from string expression
  1719. .I se
  1720. the substring indexed by character number
  1721. .I e1
  1722. through character number
  1723. .I e2
  1724. (defaults to the size of
  1725. .I se
  1726. if beyond the end of it).
  1727. If
  1728. .I e1
  1729. is less than 1 or greater than
  1730. .IR e2 ,
  1731. the result is the null string.
  1732. For example,
  1733. .PD
  1734. .IP ""
  1735.     @substr ("Nice jacket", 4, 7)
  1736. .IP ""
  1737. returns the string ``e jac''.
  1738. .\" ----------
  1739. .TP 18
  1740. .BR @fmt (se,e)
  1741. Convert a number to a string.
  1742. The argument
  1743. .I se
  1744. must be a valid
  1745. .IR printf (3)
  1746. format string.
  1747. .I e
  1748. is converted according to the standard rules.
  1749. For example, the expression
  1750. .IP ""
  1751.     @fmt ("\(**\(**%6.3f\(**\(**", 10.5)
  1752. .IP ""
  1753. yields the string ``\(**\(**10.500\(**\(**''.
  1754. .I e
  1755. is a double, so applicable formats are e, E, f, g, and G.
  1756. Try ``%g'' as a starting point.
  1757. .\" ----------
  1758. .TP 18
  1759. .BR @sval (se,e)
  1760. Return the string value of a cell selected by name.
  1761. String expression
  1762. .I se
  1763. must evaluate to a column name (``A''-``AE'') and
  1764. .I e
  1765. must evaluate to a row number (0-199). 
  1766. If
  1767. .I se
  1768. or
  1769. .I e
  1770. is out of bounds, or the cell has no string value,
  1771. the result is the null string.
  1772. You can use this for simple table lookups.
  1773. Be sure the table doesn't move unexpectedly!
  1774. .\" ----------
  1775. .TP 18
  1776. .BR @ext (se,e)
  1777. Call an external function (program or script).
  1778. The purpose is to allow arbitrary functions on values,
  1779. e.g. table lookups and interpolations.
  1780. String expression
  1781. .I se
  1782. is a command or command line to call with
  1783. .IR popen (3).
  1784. The value of
  1785. .I e
  1786. is converted to a string and appended to the command line as an argument.
  1787. The result of
  1788. .IR @ext ()
  1789. is a string:
  1790. the first line printed to standard output by the command.
  1791. The command should emit exactly one output line.
  1792. Additional output, or output to standard error, messes up the screen.
  1793. .IR @ext ()
  1794. returns a null string and prints an appropriate warning
  1795. if external functions are disabled,
  1796. .I se
  1797. is null, or the attempt to run the command fails.
  1798. .IP ""
  1799. External functions can be slow to run,
  1800. and if enabled are called at each screen update,
  1801. so they are disabled by default.
  1802. You can enable them with
  1803. .I ^T
  1804. when you really want them called.
  1805. .IP ""
  1806. A simple example:
  1807. .IP ""
  1808.     @ext ("echo", a1)
  1809. .IP ""
  1810. You can use
  1811. .IR @ston ()
  1812. to convert the
  1813. .IR @ext ()
  1814. result back to a number.
  1815. For example:
  1816. .IP ""
  1817.     @ston (@ext ("form.sc.ext", a9 + b9))
  1818. .IP ""
  1819. Note that you can built a command line (including more argument values)
  1820. from a string expression with concatenation.
  1821. You can also "hide" the second argument by ending the command line
  1822. (first argument) with `` #'' (shell comment).
  1823. .\" ==========
  1824. .SS "Built-in Financial Functions"
  1825. .\" ----------
  1826. Financial functions compute the mortgage (or loan) payment, future value,
  1827. and the present value functions.  Each accepts
  1828. three arguments, an amount, a rate of interest (per period), and 
  1829. the number of periods.
  1830. These functions are the same as those commonly found in other spreadsheets
  1831. and financial calculators
  1832. .\" ----------
  1833. .TP 18
  1834. .BR @pmt (e1,e2,e3)
  1835. .IR @pmt (60000,.01,360)
  1836. computes the monthly payments for a $60000 mortgage at 12% annual interest
  1837. (.01 per month) for 30 years (360 months).
  1838. .\" ----------
  1839. .TP 18
  1840. .BR @fv (e1,e2,e3)
  1841. .IR @fv (100,.005,36)
  1842. computes the future value for of 36 monthly payments of $100 at 6% 
  1843. interest (.005 per month).  It answers the question: "How much
  1844. will I have in 2 years if I deposit $100 per month in a savings account paying
  1845. 6% interest compounded monthly?"
  1846. .\" ----------
  1847. .TP 18
  1848. .BR @pv (e1,e2,e3)
  1849. .IR @pv (1000,.015,36)
  1850. computes the present value of an a ordinary annuity of
  1851. 36 monthly payments of $1000 at 18% annual interest.
  1852. It answers the question: "How much can I borrow at 18% for 30 years
  1853. if I pay $1000 per month?"
  1854. .\" ==========
  1855. .SS "Built-in Date and Time Functions"
  1856. .\" ----------
  1857. Time for
  1858. .I pname
  1859. follows the system standard:
  1860. the number of seconds since 1970.
  1861. All date and time functions except
  1862. .IR @date ()
  1863. return numbers, not strings.
  1864. .\" ----------
  1865. .TP 18
  1866. .B @now
  1867. Return the current time encoded
  1868. as the number of seconds since December 31, 1969, midnight, GMT.
  1869. .\" ----------
  1870. .PP
  1871. The following functions take the time in seconds
  1872. (e.g. from
  1873. .IR @now )
  1874. as an argument and return the specified value.
  1875. The functions all convert from GMT to local time.
  1876. .\" ----------
  1877. .TP 18
  1878. .BR @date (e)
  1879. Convert the time in seconds to a date string
  1880. 24 characters long in the following form:
  1881. .IP ""
  1882. .I "    Sun Sep 16 01:03:52 1973"
  1883. .IP ""
  1884. Note that you can extract parts of this fixed-format string with
  1885. .IR @substr ().
  1886. .\" ----------
  1887. .TP 18
  1888. .BR @year (e)
  1889. Return the year.
  1890. Valid years begin with 1970.
  1891. The last legal year is system dependent.
  1892. .\" ----------
  1893. .TP 18
  1894. .BR @month (e)
  1895. Return the month, encoded as 1 (January) to 12 (December).
  1896. .\" ----------
  1897. .TP 18
  1898. .BR @day (e)
  1899. Return the day of the month, encoded as 1 to 31.
  1900. .\" ----------
  1901. .TP 18
  1902. .BR @hour (e)
  1903. Return the number of hours since midnight, encoded as 0 to 23.
  1904. .\" ----------
  1905. .TP 18
  1906. .BR @minute (e)
  1907. Return the number of minutes since the last full hour, encoded as 0 to 59.
  1908. .\" ----------
  1909. .TP 18
  1910. .BR @second (e)
  1911. Return the number of seconds since the last full minute, encoded as 0 to 59.
  1912. .\" ==========
  1913. .SS "Spreadsheet Update"
  1914. .\" ----------
  1915. Re-evaluation of spreadsheet expressions
  1916. is done by row or by column depending on the selected calculation order.
  1917. Evaluation is repeated up to 
  1918. .I iterations
  1919. times for each update if necessary,
  1920. so forward references usually work as expected.  See
  1921. .I set
  1922. above.
  1923. If stability is not reached after ten iterations,
  1924. a warning is printed.
  1925. This is usually due to a long series of forward references,
  1926. or to unstable cyclic references (for example, set
  1927. .IR A0 's
  1928. expression to ``A0+1'').
  1929. .\" ==========
  1930. .SH SEE ALSO
  1931. bc(1), dc(1), crypt(1), ppname(1)
  1932. .\" ==========
  1933. .SH BUGS
  1934. Top-to-bottom, left-to-right evaluation of expressions is silly.
  1935. A proper following of the dependency graph
  1936. with (perhaps) recourse to relaxation should be implemented.
  1937. .\" ----------
  1938. .PP
  1939. Supports at most 200 rows and 40 columns.
  1940. .\" ----------
  1941. .PP
  1942. Editing is crude.
  1943. All you can do is backspace over and retype text to be altered.
  1944. There is no easy way to switch a leftstring to a rightstring or vice versa.
  1945. Of course, you can always write the spreadsheet to a file with
  1946. .IR Put ,
  1947. edit it by calling an editor on the file with ``!'',
  1948. and read it back with
  1949. .I Get
  1950. -- if you are comfortable editing spreadsheet files.
  1951. .\" ----------
  1952. .PP
  1953. Only one previous value is saved from any call of
  1954. .IR @ext ().
  1955. If it is used more than once in a spreadsheet
  1956. and external functions are enabled and later disabled,
  1957. the last returned value pops up in several places.
  1958. .\" ----------
  1959. .PP
  1960. On some systems,
  1961. if the cell cursor is in column 0 with topline enabled
  1962. (so the current cell is highlighted),
  1963. or if any cell in column 0 is highlighted,
  1964. the corresponding row number gets displayed and then blanked
  1965. during a screen refresh.
  1966. This looks like a bug in
  1967. .IR curses .
  1968. .\" ----------
  1969. .PP
  1970. Many commands give no indication (a message or beep) if they have null effect.
  1971. Some should give confirmation of their action, but they don't.
  1972. \SHAR\EOF\
  1973. else
  1974.   echo "will not over write ./sc.doc"
  1975. fi
  1976. if [ `wc -c ./sc.doc | awk '{printf $1}'` -ne 43202 ]
  1977. then
  1978. echo `wc -c ./sc.doc | awk '{print "Got " $1 ", Expected " 43202}'`
  1979. fi
  1980. if `test ! -s ./psc.doc`
  1981. then
  1982. echo "Extracting ./psc.doc"
  1983. cat > ./psc.doc << '\SHAR\EOF\'
  1984. .\" $Revision $
  1985. .TH PPNAME 1
  1986. .SH NAME
  1987. ppname \- prepare pname files
  1988. .SH SYNOPSIS
  1989. .B ppname
  1990. [
  1991. .I -Lkr
  1992. ]
  1993. [
  1994. .I -s cell
  1995. ]
  1996. [
  1997. .I -R n
  1998. ]
  1999. [
  2000. .I -C n
  2001. ]
  2002. [
  2003. .I -n n
  2004. ]
  2005. [
  2006. .I -d c
  2007. ]
  2008.  
  2009. .SH DESCRIPTION
  2010. .I Ppname
  2011. is used to prepare data for input to the spread sheet calculator
  2012. .I pname(1).
  2013. It accepts normal ascii data on standard input.  Standard output
  2014. is a
  2015. .I pname
  2016. file.
  2017. With no options, 
  2018. .I ppname
  2019. starts the spread sheet in cell A0.  Strings are right justified.
  2020. All data on a line is entered on the same row; new input lines
  2021. cause the output row number to increment by one.  The default delimiters
  2022. are tab and space.  The column formats are set to one larger
  2023. than the number of columns required to hold the largest value
  2024. in the column.
  2025.  
  2026. Options:
  2027.  
  2028. .IP "\-L"
  2029. Left justify strings.
  2030.  
  2031. .IP "\-k"
  2032. Keep all delimiters.  This option causes the output cell to change on
  2033. each new delimiter encountered in the input stream.   The default
  2034. action is to condense multiple delimters to one, so that the cell only
  2035. changes once per input data item.
  2036.  
  2037. .IP "\-r"
  2038. Output the data by row first then column.  For input consisting of a single
  2039. column, this
  2040. option will result in output of one row with multiple columns
  2041. instead of a single
  2042. column spread sheet.
  2043.  
  2044. .IP "\-s cell"
  2045. Start the top left corner of the spread sheet in 
  2046. .I cell.
  2047. For example, 
  2048. .I "-s B33"
  2049. will arrange the output data so that the
  2050. spread sheet starts in column B, row 33.
  2051.  
  2052. .IP "\-R n"
  2053. Increment by
  2054. .I n 
  2055. on each new output row.
  2056.  
  2057. .IP "\-C n"
  2058. Increment by
  2059. .I n 
  2060. on each new output column.
  2061.  
  2062. .IP "\-n n"
  2063. Output 
  2064. .I n
  2065. rows before advancing to the next column.  This option is used when
  2066. the input is arranged in a single column and the spread sheet is to
  2067. have multiple columns, each of which is to be length
  2068. .I n.
  2069.  
  2070. .IP "\-d c"
  2071. Use the single character
  2072. .I c
  2073. as the delimiter between input fields.
  2074.  
  2075. .SH SEE ALSO
  2076. pname(1)
  2077.  
  2078. .SH AUTHOR
  2079.  
  2080. Robert Bond
  2081. \SHAR\EOF\
  2082. else
  2083.   echo "will not over write ./psc.doc"
  2084. fi
  2085. if [ `wc -c ./psc.doc | awk '{printf $1}'` -ne 1871 ]
  2086. then
  2087. echo `wc -c ./psc.doc | awk '{print "Got " $1 ", Expected " 1871}'`
  2088. fi
  2089. echo "Finished archive 1 of 4"
  2090. # if you want to concatenate archives, remove anything after this line
  2091. exit
  2092.  
  2093.