home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / fish / disks / d1019.lha / Programs / AXDiff / AXDiff.doc < prev    next >
Encoding:
Text File  |  1994-09-17  |  13.0 KB  |  290 lines
  1. DOCUMENTATION and other information for AxDiff (by Jim Lawrie)
  2. ==============================================================
  3.  
  4. Unless the program is registered (see section on Registration below
  5. for instructions), you will only get a maximum of 5 differences.
  6. Files may contain more than 5 sections which differ, but only the
  7. first five will be seen by AXDiff.  The rest of the file is assumed to
  8. have no differences, which may look strange on screen.  Full print and
  9. merge capabilities exist for the 5 differences found.  After the 5th
  10. difference, the left file is copied to the merge file if merging.
  11.  
  12. AXDiff may be executed from the Workbench or from the CLI.  If
  13. executed from the CLI, the names of the files may be given with which
  14. to compare and do the merge to.  If run from the Workbench, then only
  15. the name of the merge file may be given in the tool types of the
  16. AXDiff icon.
  17.  
  18. The only requirement is that the SC diff file exist somewhere in the
  19. search path.  The search path is either the search path in effect
  20. in the SHELL invoked from if invoked from the SHELL, or the search
  21. path in effect when Workbench loads if invoked from the Workbench.
  22.  
  23. To execute AXDiff from the Workbench, select the tool types desired.
  24. They are all in the "info" display, but unused ones contain
  25. parentheses around them.  The available tool types are:
  26.  
  27. FONT=<font-name>, used to select a specific font to use instead of the
  28. default.  System font and size used by default.
  29.  
  30. FONT_SIZE=#, used to select the point size of the font.
  31.  
  32. MERGE=<filename>, used to specify the file which to merge the result
  33. to.
  34.  
  35. LOCK_VERT=<TRUE/FALSE>, locks the left and right files in the vertical
  36. dimension so that when you move the slider of the left or right file,
  37. both files are affected and will move by similar line counts unless
  38. impossible to do because of file size differences..  By default TRUE.
  39.  
  40. LOCK_HORIZ=<TRUE/FALSE>, locks the left and right files in the
  41. horizontal dimension.  By default TRUE.
  42.  
  43. LINE_NUM=<TRUE/FALSE>, displays or does not display the line numbers
  44. of the bounds of the difference sections.  By default true.
  45.  
  46. WINDOW=<number>, specifies # of pixels high the window should be when
  47. opened.  If out of bounds (<minimum, >maximum), window will open with
  48. minimum height or maximum height, whichever is closer.  Default = 400.
  49.  
  50. LOCK_SELECT=<TRUE/FALSE>, locks (synchronizes) the selection of
  51. difference blocks between the left and right files.  If on, selecting
  52. the left difference block will deselect the right difference block,
  53. while deselecting the left block, will select the right block.  The
  54. same goes for operations made to the right difference block.  If off,
  55. each difference block may be selected or deselected independent of the
  56. difference block on the other side.
  57.  
  58. IGNORE_WHITE=<TRUE/FALSE>, tells AXDiff to ignore all white-space
  59. differences between the files and display white-space as one space.
  60. This is the default.
  61.  
  62. All of the above options except for "WINDOW" can be changed once the
  63. program is running.  "IGNORE_WHITE" requires the "Compare" button to
  64. be hit again to take effect, although the display change of the
  65. white-space on the lines takes effect immediately.  The window can
  66. resized in the vertical dimension via the size gadget in the lower
  67. right of the window.
  68.  
  69. The format for running the program from CLI is as follows:
  70.  
  71. AXDiff [options] [left_filename] [options] [right_filename] [options]
  72.  
  73. Options are as follows:
  74.  
  75. -f <font_name>,    specify the name of the font to use for display
  76. +f <font_name>,    same.
  77.  
  78. -fs <number, point size of font to use.
  79. +fs <number, same
  80.  
  81. -m <merge_filename>, specify the name of the merge file to use.  Note
  82.                      space between "-m" and "filename"
  83. +m <merge_filename>, same as above
  84.  
  85. -l  do not display line #s
  86. +l  display line #s (default)
  87.  
  88. -v  do not lock the left and right vertical sliders
  89. +v  lock the left and right vertical sliders (default)
  90.  
  91. -h  do not lock the left and right horizontal sliders
  92. +h  lock the left and right horizontal sliders (default)
  93.  
  94. -i  do not ignore white-space differences.
  95. +i  ignore white-space differences, display all white-space as one
  96.     space. (default)
  97.  
  98. -s  do not lock the difference select between left and right files.
  99. +s  lock the difference select between left and right files. (default)
  100.  
  101. -w  <number>, set the window height to <number>.  If less than minimum,
  102.     window height will be set to minimum.  If more than maximum, window
  103.     height will be set to maximum.  Minimum allows for one line in the
  104.     display area of text of default font.  Maximum is screen height.
  105.     Default is 400.
  106. +w  <number>, same as above
  107.  
  108. ?   By itself, with not other arguments, will print out usage text.
  109.  
  110. If no options are specified, the defaults will be used. This is the
  111. same as specifying:
  112.  
  113. AXDiff +l +v +h +s -w 400 +i
  114.  
  115. The left and right filenames may also be specified.  They may be given
  116. anywhere on the command line.  Either no filenames can be specified,
  117. or both.  One filename, or more than two are not allowed.  If two are
  118. given, then the first filename specified will be the left filename and
  119. the second filename specified will be the right filename.
  120.  
  121. Operation
  122. =========
  123.  
  124. Files may be loaded into AXDiff via the shift-select method from the
  125. Workbench.  Simply select two icons of files to be compared while
  126. holding the shift key down and double-click on the AXDiff icon while
  127. still holding the shift key down.  The two files will now be loaded
  128. into AXDiff and used with the left file being the first file selected
  129. and the right file being the second file selected.  If only one, or
  130. more than two files are shift-selected, an error indicating the wrong
  131. number of arguments will be displayed.
  132.  
  133. Once the program is running, new filenames may be given for the Left,
  134. Right, and Output (or Merge) files.  The "Compare" gadget must be hit
  135. to begin the compare if new filenames are given, or if started from
  136. the Workbench.  If both the left and the right filenames are given on
  137. the command line, or via the shift-select method, the compare will
  138. begin immediately without having to to hit the "Compare" gadget.
  139.  
  140. The main part of the window is the text/file area which shows the left
  141. file on the left side and the right file on the right side, seperated
  142. by a central area which connects the two sides.
  143.  
  144. There are two menus, a "Project" menu, and a "Preferences" menu.  The
  145. "Project" menu allows you quit the program.  You may also quit by
  146. clicking on the window close gadget.  The "Preferences" menu allows
  147. you to turn on or off certain options which tailors the program
  148. operation to your liking.  The "Preferences" items which are described
  149. below are:
  150.  
  151. Linked Horizontal Sliders
  152. Linked Vertical Sliders
  153. Line Numbers
  154. Ignore White Space
  155. Linked L/R Select
  156. Font Selection
  157.  
  158. AXDiff uses the following conventions.  Text is either pen 1 (Black)
  159. or pen 2 (White).  The Black indicating either text which is the same
  160. between files, or text which is selected to be sent to the merge file.
  161. Text which is the same between files will be written to the merge file
  162. also.  The white text indicates text which is not selected to be sent
  163. to the merge file and will only appear in a difference section.
  164.  
  165. A pen 0 (Grey) background indicates there is no difference between the
  166. text of the left and right files.  A pen 3 (Blue) background indicates
  167. that the left and right files differ on these lines.  This is a
  168. difference section.  The blue rectange of the left file is connected
  169. to the blue rectange of the right file by a blue polygon, showing
  170. exactly where the differences occur and how that difference section
  171. corresponds to the other file.
  172.  
  173. If selected, line numbers will appear in the center section showing
  174. the first and last line numbers of the difference section, or the line
  175. number before which inserted lines go.  Line numbers will always
  176. appear midway between text lines unless the number is at the top or
  177. bottom of the text display area.  Note that line numbers always
  178. indicate the line number below the number.
  179.  
  180. Only lines which differ between files will be written on a blue
  181. background.  One exception: If lines appear in one file but not the
  182. other file (they are inserted, not changed), then one line of the file
  183. where the lines would be inserted is on a blue background.  The
  184. central area will show a blue triange comming to a point just prior to
  185. the one line highlighted in blue, signifying all the text from the
  186. other file gets inserted "here".  This is done to make it easier to
  187. see the line before which the text is inserted.
  188.  
  189. Clicking on "First", "Prev", "Next", or "Last" will position the
  190. respecitve difference at the top of the display area, unless the
  191. beginning or end of the file prevents it.  The beginning of the file
  192. will never appear below the top line, and the end of the file will
  193. never appear above the bottom line.  The one exception to this is if
  194. the entire file is smaller than the display area.
  195.  
  196. Also, the lines are appended to the end of a file, and the end of the
  197. file is being displayed, the line number will not be displayed on the
  198. file which does not have the appended lines.
  199.  
  200. To select or deselect text, merely click the mouse pointer on the text
  201. you wish to select or deselect.  Do not click on the center area, you
  202. must click on the text areas.  The state will then change from
  203. selected to deselected, or from deselected to selected.  If "Linked
  204. L/R Select" is on, you select either the left, or the right section,
  205. but not both.  Selecting one side deselects the other, and vice-versa.
  206. If "Linked L/R Select" is off, the left side can be selected or
  207. deselected independently from the right side.  You can have neither,
  208. both, or either of the sides selected.  Note that you cannot change
  209. the selected status of the text which is highlighted in blue to show
  210. lines being inserted.
  211.  
  212. Click on the Merge button to perform the merge.  The merge is done as
  213. follows.  All lines which are common between the left and right files
  214. are written once to the merge file.  A section highlighted in blue
  215. will have the left side text written first (if selected), followed by
  216. the right side (if selected).  Proper order is maintained.  The
  217. default selection is set up so that the merge file will be a copy of
  218. the right file unless you change the selection status of one or more
  219. difference sections.
  220.  
  221. The sliders around the text area move the text around so that you can
  222. see the entire line and the entire file.  Most likely, the entire line
  223. will not fit into the small space provided, so this allows you to see
  224. the whole line.
  225.  
  226. Both the horizontal and vertical sliders can be locked (default), or
  227. not.  By unlocking the left side from the right side, you can slide
  228. the left or right file around independently from the other.  Locking
  229. the sliders attempts to keep the display of the files in sync.  You
  230. can lock or unlock the horizontal and vertical sliders independently.
  231.  
  232. You can change the font and size if desired so that more or less
  233. characters will appear on screen.  Note that tabs will not be
  234. expanded, they will appear as whatever the font's tab character is,
  235. unless "Ignore White Space" is selected, in which case they will
  236. appear as a single space..  AXDiff also supports use of the styles
  237. "Bold", and "Italic".
  238.  
  239. Quitting is done by selecting "Quit" from the menu, typeing A-Q, or by
  240. hitting the window close button in the upper left.
  241.  
  242. Hints
  243. =====
  244.  
  245. Be careful about merging when "Ignore White Space" option is on.
  246. Lines which do not differ between the left and right files are taken
  247. from the left file.  So, if white space is being ignored, the lines
  248. from the left file are copied to the merge file and may differ from
  249. those in the right file by number of spaces, tabs, etc.
  250.  
  251. Be careful on binary files.  I've tried to filter them out and give
  252. warning to the user before doing a compare, but there may be some
  253. files which look like text, but are binary in fact.  Attempting to
  254. compare binary files will likely crash the computer.
  255.  
  256. Registration
  257. ============
  258.  
  259. To register, please use the registration form enclosed.  Fill in the
  260. requested informatoin and enclose $12 for the registration fee. Also
  261. enclose a text string you wish to use as your username, eg.  "lawrie".
  262. Please enclose the string in quotes as above so there will be no
  263. mistake.  I will then send you a registration number.  To then make
  264. use of the full facilities of the program, you must create a file in
  265. the s: directory called "AXDiff.reg" containing one line of the format
  266. <username>=<registration number>.  For example, a file may read:
  267. username=01482.
  268.  
  269. Send to:
  270.  
  271. Jim Lawrie
  272. 10 Holly Dr.
  273. Norwood, MA 02062-3011
  274.  
  275. I will either send you a note to the address you request, or I can
  276. EMail you.  Either your Internet address or Compuserve ID is fine.
  277.  
  278. Problems & Futures
  279. ==================
  280.  
  281. If you have a problem with the program, you may send me a note to the
  282. above address, or EMail me.  Send to either my Internet address
  283. "lawrie@merlin.dev.cdx.mot.com", or my Compuserve ID: Jim Lawrie
  284. (72517,2340).  Internet is better.
  285.  
  286. Also, I want to make the program more useful.  Items such as removing
  287. the restriction on needing SAS's "diff", IFF and AREXX support seem
  288. useful to me.  If you have an idea, please send me a note, or two,
  289. telling me what would be useful, and I'll try to oblige.
  290.