home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 December / simtel1292_SIMTEL_1292_Walnut_Creek.iso / msdos / lotus123 / ad36.arc / EXAMPLE.FOR < prev    next >
Text File  |  1988-09-01  |  12KB  |  257 lines
  1.  
  2. --------------------------------------------------------------------------------
  3. AutoDoc v3.60 
  4. Listing of d:\example.wk1, File Date:07/10/88 11:28:22                    Page 1
  5. --------------------------------------------------------------------------------
  6. Cell Range     |A       |B       |C       |D       |E       |F       |G       |H       
  7. --------------------------------------------------------------------------------
  8. A1..C1         Example
  9. A3             Expenditures
  10. A4..F4         ;;       Jan      Feb      Mar      April    Total
  11.  
  12.                apples[t] = $apples[t] * apples[t] 
  13.                  = <<2.4 to 18.9>>, for t = Jan to Total, at B5..F5
  14.  
  15. A5..F5         apples   2.400000 3.900000 5.600000 7.500000 18.9000000
  16.  
  17.                oranges[t] = $oranges[t] * oranges[t] 
  18.                  = <<5.2 to 33.35>>, for t = Jan to Total, at B6..F6
  19.  
  20. A6..F6         oranges  5.200000 8.400000 13.50000 6.400000 33.3500000
  21. B7..F7                  -------- -------- -------- -------- ---------
  22.  
  23.                Total[t] = SUM( apples[t]..oranges[t] )  
  24.                  = <<7.6 to 52.25>>, for t = Jan to Total, at B8..F8
  25.  
  26. A8..F8         Total    7.600000 12.30000 19.10000 13.90000 52.2500000
  27. A11            Quantities
  28. B12..F12                Jan      Feb      Mar      April    Total
  29.  
  30.                apples[t] = SUM( apples[t-4]..apples[t-1] )  
  31.                  = <<14.>>, for t = Total, at F13
  32.  
  33. A13..F13       apples   2        3        4        5        14.0000000
  34.  
  35.                oranges[t] = SUM( oranges[t-4]..oranges[t-1] )  
  36.                  = <<23.>>, for t = Total, at F14
  37.  
  38. A14..F14       oranges  4        6        9        4        23.0000000
  39. B15..F15                -------- -------- -------- -------- ---------
  40.  
  41.                Total[t] = SUM( apples[t]..oranges[t] )  
  42.                  = <<6. to 37.>>, for t = Jan to Total, at B16..F16
  43.  
  44. A16..F16       Total    6.000000 9.000000 13.00000 9.000000 37.0000000
  45. A18            Prices
  46. B19..F19                Jan      Feb      Mar      April    Total
  47.  
  48.                $apples[t] = @AVG( $apples[t-4]..$apples[t-1] )  
  49.                  = <<1.35>>, for t = Total, at F20
  50.  
  51. A20..F20       $apples  1.200000 1.300000 1.400000 1.500000 1.3500000
  52.  
  53.                $oranges[t] = @AVG( $oranges[t-4]..$oranges[t-1] )  
  54.                  = <<1.45>>, for t = Total, at F21
  55.  
  56. A21..F21       $oranges 1.300000 1.400000 1.500000 1.600000 1.4500000
  57.  
  58. --------------------------------------------------------------------------------
  59. AutoDoc v3.60 
  60. Listing of d:\example.wk1, File Date:07/10/88 11:28:22                    Page 2
  61. --------------------------------------------------------------------------------
  62. Range Names And Definitions In d:\example.wk1
  63. --------------------------------------------------------------------------------
  64.  
  65. --------------------------------------------------------------------------------
  66. AutoDoc v3.60 
  67. Listing of d:\example.wk1, File Date:07/10/88 11:28:22                    Page 3
  68. --------------------------------------------------------------------------------
  69. Index Of Row Names[1..15] (And Which Rows Referenced Them) In d:\example.wk1
  70. --------------------------------------------------------------------------------
  71.  
  72.            apples:5|    8
  73.           apples:13|    5   13   16
  74.          oranges:14|    6   14
  75.          $apples:20|    5   20
  76.         $oranges:21|    6   21
  77. --------------------------------------------------------------------------------
  78. AutoDoc v3.60 
  79. Listing of d:\example.wk1, File Date:07/10/88 11:28:22                    Page 4
  80. --------------------------------------------------------------------------------
  81.  
  82.               Automated Documentation Of Spreadsheet Equations
  83.               ------------------------------------------------
  84.  
  85.                                    by
  86.  
  87.                   Copyright (c) 1988, John D. Pearson
  88.  
  89.  
  90. Have you ever wondered why spreadsheets have to be so @DA..  @DIFF..  to read.
  91. Commercial "cell" listings help but so far they do not translate the structure
  92. of the spreadsheet back into english.  This program tries a different tack.
  93.  
  94. It assumes that your spreadsheet follows a convention that rows correspond to
  95. variables and columns to time periods like so:
  96.  
  97.                A         B         C         D         E
  98.      1
  99.      2         ;;           Jan       Feb       Mar       Apr
  100.      3         apples         1         2         0         3
  101.      4         oranges       22        44       -10       100
  102.      5         -----     ------    ------    ------    ------
  103.      6         Total     +B3+B4    +C3+C4    +D3+D4    +E3+E4
  104.  
  105. The example shows a very simple spreadsheet.  Apart from the data it has one
  106. repeated formula in the cell range A6..E6.  Commercial cell listing programs
  107. repeat this formula in every cell.  AutoDoc treats this as an equation.
  108.  
  109. To AutoDoc an equation is simply a cell formula that is repeated for two or more
  110. cells in a row.  In the example above the equation in range A6..E6 defines the
  111. "total" as the sum of the "apples" and "oranges" for each of the periods "Jan"
  112. to "Apr".
  113.  
  114. AutoDoc recovers the equations from the spreadsheet and displays the equation in
  115. the context of the text and data as follows.
  116.  
  117. Cell Range     |A        |B        |C        |D        |E
  118. ---------------------------------------------------------------
  119.      A2..E2    ;;        Jan       Feb       Mar       Apr
  120.      A3..E3    apples    1         2         0         3
  121.      A4..E4    oranges   22        44        -10       100
  122.      A5..E5    -----     -----     -----     -----     -----
  123.  
  124.                Total[t] = apples[t] + oranges[t]
  125.                  = <<23..103>>, for t = Jan to Apr in B6 to E6
  126.  
  127.      A6        Total     23        46        -10       103
  128.  
  129. Now this may appear to be trivial (and it is), however take a more complicated
  130. situation with many equations with forward and backward references and this same
  131. idea makes a complex spreadsheet very readable.
  132.  
  133. AutoDoc generates an ASCII output file like the above which contains the
  134. following:
  135.  
  136.          The first column shows the range of cells in the
  137.          rows that contain entries since only one page width
  138.          of text/data will be displayed.
  139.  
  140.          The remaining columns contain the entries as they
  141.          might appear on the screen but left justified in
  142.          each column width.
  143.  
  144.          All equations found are summarized as above with
  145.          [t] referring to the current cell "time period" and
  146.          <<23..103>> provides the first and last values
  147.          computed using the equation.  The cell range shows
  148.          where they are in the spreadsheet row.
  149.  
  150. You may customize the names by adding a column and rows(s) of sensible
  151. abbreviations then add markers ;; as above to show which row contains
  152. the current column headers and which column contains sensible variable
  153. names.
  154.  
  155. If you do not then AutoDoc will construct variable names from the
  156. leading text in each row, but the column headers will be the usual
  157. 1-2-3 headers.  A..IV.  If nothing is provided then surrogate row
  158. names are invented Row:236 etc.  Even this can be helpful.
  159.  
  160. AutoDoc appends a listing of the ranges found and a simple listing of
  161. the references to each of the variable names or rows.
  162.  
  163. Absolute row and column references are flagged as in 1-2-3 using the $
  164. sign.  An absolute column reference will be [$D] while an absolute row
  165. reference will appear as row:232:$[$D].  If range names are defined
  166. then AutoDoc uses these in the equation listing.
  167.  
  168. Operation And Screen Output
  169. ---------------------------
  170.  
  171. To use AutoDoc you will need this program and an IBM compatible running with PC
  172. or MS-DOS, then type:
  173.  
  174. AUTODOC  [input [output]]
  175.  
  176. at the DOS prompt, with [ ] meaning optional.  (Do not type the [] symbols).
  177. The INPUT and OUTPUT files may be fully qualified drive\path\name specifications
  178. with .WK1 default on input and .FOR on output.
  179.  
  180. It takes no other parameters and if neither INPUT nor OUTPUT are given then it
  181. is entirely menu driven.  A configuration file is automatically written to the
  182. default drive for each use and is read for the default options next time.
  183.  
  184. For example if you have a file test.wk1 on c:\123\data and your AUTODOC.EXE file
  185. is on a floppy in the A drive: then type:
  186.  
  187. c:
  188. cd c:\123\data
  189. a:autodoc
  190.  
  191. -- and you will be prompted for everything else by the menus including the
  192. format options available for the formula file output.  The help key F1 and the
  193. file choice keys F9 and F10 provide a range of available choices for each option
  194. in most cases.
  195.  
  196. After providing the file to be listed and approving the output format, AUTODOC
  197. will read the file once to identify all usable row and column names.  Next it
  198. re-reads the file and generates the equation listing on an auxiliary file with
  199. extension .FOR.  At the same time a video MAP is displayed showing the first 55
  200. columns of the spreadsheet.  You may also list this map as one of the options.
  201.  
  202. The MAP display flags in color and highlights changes in row structure along
  203. each row.  This may show a formula that has been miscopied along a row.  Each
  204. break in the row is independently listed to the formula file and should be
  205. examined.  Most users are so entranced with the marching screen display that
  206. they do not notice the errors.  The MAP list reports the changes by
  207. capitalizing the cell type symbols.
  208.  
  209. Limitations of this program:
  210. ----------------------------
  211. Comments on the current version of AutoDoc (and some remedies):
  212.  
  213. AutoDoc ONLY thrives on spreadsheets that follow the variable/time convention
  214. described above.  On all others it will generate more paper than insight since
  215. every cell may becomes a fresh equation.
  216.  
  217. It is designed to fully process rows 1..1001 of Lotus 1-2-3 version 2 files.
  218. Further rows 1002..  are processed without any ;; names but otherwise everything
  219. else continues.  First time users with an arbitrary spreadsheet are advised to
  220. turn on "variable names" and "row numbers" as configuration options.
  221.  
  222. It does not automatically check and correct for duplicate variable names, macro
  223. text or range names used out of context.  Be warned that absolute row or column
  224. references can be very misleading.  If duplicate names are used then key
  225. references will appear to be the same unless the option "add row numbers to
  226. names" is used.
  227.  
  228. The popular LIST.COM program by Vernon Buerg and available on most bulletin
  229. boards, is an excellent way to peruse the output file and selectively print
  230. pages.
  231.  
  232. ------------------------------------------------------------------------------
  233. Finally this is a simple but powerful interpretative program.  But..it is your
  234. responsibility to review the output carefully and to base any conclusions
  235. derived from the results solely upon your own judgement.  If in doubt check a
  236. 1-2-3 cell listing.  While every effort has been made to ensure that the program
  237. is bug-free on a PC/XT and a Compaq 386 under DOS 3, there are almost
  238. certainly situations and PC configurations that AutoDoc has not encountered and
  239. in which it may not function correctly.
  240. ------------------------------------------------------------------------------
  241.  
  242. Updates
  243. -------
  244. AutoDoc is copyrighted by the author and distributed for comment.  You are
  245. encouraged to try it and circulate it with this file attached.  If
  246. you find it useful then for an updated version of this program with
  247. documentation write to:
  248.  
  249.      John D. Pearson,
  250.      2007 Franklin Avenue,
  251.      McLean Va. 22101.
  252.  
  253. and enclose $15.  Suggestions for improvement are welcome.
  254.  
  255. This file supercedes version 2.1 called AD21.ARC (version 3.5 7/1/88.)
  256.  
  257.