home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 December / simtel1292_SIMTEL_1292_Walnut_Creek.iso / msdos / lotus123 / ad36.arc / AUTODOC.HLP < prev    next >
Text File  |  1988-09-01  |  9KB  |  193 lines
  1.  
  2.                 Automated Documentation Of Spreadsheet Equations
  3.                 ------------------------------------------------
  4.  
  5.                                        by
  6.  
  7.                       Copyright (c) 1988, John D. Pearson
  8.  
  9.  
  10. Have you ever wondered why spreadsheets have to be so @DA..  @DIFF..  to read.
  11. Commercial "cell" listings help but so far they do not translate the structure
  12. of the spreadsheet back into english.  This program tries a different tack.
  13.  
  14. It assumes that your spreadsheet follows a convention that rows correspond to
  15. variables and columns to time periods like so:
  16.  
  17.                A         B         C         D         E
  18.      1
  19.      2         ;;           Jan       Feb       Mar       Apr
  20.      3         apples         1         2         0         3
  21.      4         oranges       22        44       -10       100
  22.      5         -----     ------    ------    ------    ------
  23.      6         Total     +B3+B4    +C3+C4    +D3+D4    +E3+E4
  24.  
  25. The example shows a very simple spreadsheet.  Apart from the data it has one
  26. repeated formula in the cell range A6..E6.  Commercial cell listing programs
  27. repeat this formula in every cell as shown.  AutoDoc treats this as an equation.
  28.  
  29. To AutoDoc an equation is simply a cell formula that is repeated for two or more
  30. cells in a row.  In the example above the equation in range A6..E6 defines the
  31. "total" as the sum of the "apples" and "oranges" for each of the periods "Jan"
  32. to "Apr".
  33.  
  34. AutoDoc recovers the equations from the spreadsheet and displays the equation in
  35. the context of the text and data as follows.
  36.  
  37. Cell Range     |A        |B        |C        |D        |E
  38. ---------------------------------------------------------------
  39.      A2..E2    ;;        Jan       Feb       Mar       Apr
  40.      A3..E3    apples    1         2         0         3
  41.      A4..E4    oranges   22        44        -10       100
  42.      A5..E5    -----     -----     -----     -----     -----
  43.  
  44.                Total[t] = apples[t] + oranges[t]
  45.                  = <<23..103>>, for t = Jan to Apr in B6 to E6
  46.  
  47.      A6        Total     23        46        -10       103
  48.  
  49. Now this may appear to be trivial (and it is), however take a more complicated
  50. situation with many equations with forward and backward references and this
  51. simple idea makes a complex spreadsheet very readable.
  52.  
  53. AutoDoc generates an ASCII output file like the above which contains the
  54. following:
  55.  
  56.          The first column shows the range of cells in the
  57.          rows that contain entries since only one page width
  58.          of text/data will be displayed. (Up to 255 characters)
  59.  
  60.          The remaining columns contain the entries as they
  61.          might appear on the screen but left justified in
  62.          each column width.
  63.  
  64.          All equations found are summarized as above with
  65.          [t] referring to the current cell "time period" and
  66.          <<23..103>> provides the first and last values
  67.          computed using the equation.  The cell range shows
  68.          where they are in the spreadsheet row even if not displayed
  69.  
  70. You may customize the names by adding a column and rows(s) of sensible
  71. abbreviations then add markers ;; as above to show which row contains the
  72. current column headers and which column contains sensible variable names.
  73.  
  74. If you do not make any changes to your spreadsheet then AutoDoc will construct
  75. variable names from the leading text in each row, but the column headers will be
  76. the usual 1-2-3 headers.  A..IV.  AutoDoc generates proper names that do not
  77. contain algebraic operator symbols (+-/).  If nothing is provided then surrogate
  78. row names are invented Row:236 etc.  Even this can be helpful.
  79.  
  80. AutoDoc appends a listing of the ranges found and a simple unsorted listing of
  81. the references to each of the variable names or rows.
  82.  
  83. Absolute row and column references are flagged as in 1-2-3 using the $ sign.  An
  84. absolute column reference will be [$D] while an absolute row reference will
  85. appear as row:232:$[$D].  If range names are defined then AutoDoc uses these in
  86. the equation listing in upper case.
  87.  
  88. Operation And Screen Output
  89. ---------------------------
  90.  
  91. To use AutoDoc you will need this program and an IBM compatible running with PC
  92. or MS-DOS, then type:
  93.  
  94. AUTODOC  [input [output]]
  95.  
  96. at the DOS prompt, with [ ] meaning optional.  (Do not type the [] symbols).
  97. The INPUT and OUTPUT files may be fully qualified drive\path\name specifications
  98. with .WK1 default on input and .FOR on output.
  99.  
  100. It takes no other parameters.  If neither INPUT nor OUTPUT are given then
  101. AUTODOC is entirely menu driven.  A configuration file is automatically written
  102. to the source drive for each use and is read for the default options next time.
  103.  
  104. For example if you have a file test.wk1 on c:\123\data and your AUTODOC.EXE file
  105. is in a utility directory c:\utils then type:
  106.  
  107. c:
  108. cd c:\123\data
  109. c:\utils\autodoc
  110.  
  111. -- and you will be prompted for everything else by the menus including the
  112. format options available for the formula file output.  The resulting
  113. configuration file will be written back to "c:\utils\autodoc.cnf".
  114.  
  115. The help key F1 and the file choice keys F9 and F10 provide a range of available
  116. choices for each option in most cases which try to be self explanatory.  Try
  117. experimenting on the test example to get a feel for the programs capability.
  118.  
  119. After providing the file to be listed and approving the output format, AUTODOC
  120. will read the file once to identify all usable row and column names.  Next it
  121. re-reads the file and generates the equation listing on an auxiliary file with
  122. extension .FOR.  At the same time a video MAP is displayed showing the first 55
  123. columns of the spreadsheet.  You may also list this map as one of the options.
  124.  
  125. The MAP display flags in color and highlights changes in row structure along
  126. each row.  This may show a formula that has been miscopied along a row.  Each
  127. break in the row is independently listed to the formula file and should be
  128. examined.  Most users are so entranced with the marching screen display that
  129. they do not notice the errors.  The MAP list reports the changes by capitalizing
  130. the cell type symbols.
  131.  
  132. Limitations of this program:
  133. ----------------------------
  134. Comments on the current version (3.5) of AutoDoc:
  135.  
  136. AutoDoc ONLY thrives on spreadsheets that follow the variable/time convention
  137. described above.  On all others it will generate more paper than insight since
  138. every cell may becomes a fresh equation.
  139.  
  140. It is designed to fully process rows 1..1001 of Lotus 1-2-3 version 2 files.
  141. Further rows 1002..  are processed without any ;; names but otherwise everything
  142. else continues.  First time users with an arbitrary spreadsheet are advised to
  143. turn on "variable names" and "row numbers" as configuration options.
  144.  
  145. If you have insufficient memory then on large spreadsheets or with a large
  146. number of range names you may encounter a "heap over-flow" error.  Memory used
  147. to be cheap..buy some.
  148.  
  149. It does NOT automatically check and correct for duplicate variable names, macro
  150. text or range names used out of context.  New 1-2-3 or @addin functions will
  151. appear as "@unknown_function" and cause that formula to be truncated but the
  152. listing continues.
  153.  
  154. Be warned that absolute row or column references can be VERY misleading.  If
  155. duplicate names are used then key references will appear to be the same unless
  156. the option "add row numbers to names" is used.
  157.  
  158. The popular LIST.COM program by Vernon Buerg and available on most bulletin
  159. boards, is an excellent way to peruse the output file and selectively print
  160. pages.
  161.  
  162. ------------------------------------------------------------------------------
  163. Finally this is a simple but powerful interpretative program.  It is your
  164. responsibility to review the output carefully and to base any conclusions
  165. derived from the results solely upon your own judgement.  If in doubt check a
  166. 1-2-3 cell listing.
  167.  
  168. While every effort has been made to ensure that the program is bug-free on a
  169. turbo XT and on a COMPAQ 386, there are almost certainly situations and PC
  170. configurations that AutoDoc has not encountered and in which it may not function
  171. correctly.
  172. ------------------------------------------------------------------------------
  173.  
  174. Updates
  175. -------
  176. AutoDoc is copyrighted by the author and distributed "as-is" for comment and
  177. personal use only.  It is not placed in the public domain.  You are encouraged
  178. to try it and circulate it with this file attached.  If you find it useful or
  179. for an updated version of this program with documentation write to:
  180.  
  181.      Dr. John D. Pearson,
  182.      2007 Franklin Avenue,
  183.      McLean Va. 22101.
  184.  
  185. and enclose $15 to cover expenses.  Suggestions for improvements are welcome.
  186.  
  187.  
  188. This file supercedes version 2.1 called AD21.ARC (version 3.6 9/1/88.)
  189.  
  190. It is automatically appended to the .FOR output file as long as it is
  191. on the source path to AUTODOC.EXE
  192.  
  193.