home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 19 / CD_ASCQ_19_010295.iso / vrac / ne14.zip / NE.DOC < prev    next >
Text File  |  1994-11-05  |  9KB  |  255 lines
  1. Documentation for the NOTES EDIT Utility
  2.  
  3. Title:         NOTES EDIT Utility, Version 1.2 (May 4, 1993)
  4.  
  5. Keywords:      PAF NOTES EDIT PERSONAL ANCESTRAL FILE MS-DOS
  6.                IMPORT EXPORT
  7.  
  8. Summary:
  9.  
  10. EDIT NOTES consists of a pair of utility programs (GETNOTES.EXE
  11. and PUTNOTES.EXE) and a DOS .BAT file that permit the editing of
  12. Personal Ancestral File (PAF) NOTES2.DAT data using your favorite
  13. text editor.  These utilities can also be used as stand-alone
  14. programs for the import and export of notes text between
  15. NOTES2.DAT and DOS text files.
  16.  
  17.  
  18. Background:
  19.  
  20. The NOTES EDIT utilities were written in frustration with the PAF
  21. notes editor which lacks many features of a standard text editor. 
  22. Most damaging was the lack of a block move/copy command, the
  23. inability to insert a new line in the middle of a line of notes,
  24. the difficulty of importing external text files into the middle
  25. of a set of notes, and numerous other limitations.
  26.  
  27. I personally used a number of satisfactory editors in my daily
  28. work including WP (Word Perfect), PE (a scaled down version of
  29. WP), and the Microsoft editor.  I wished to be able use these to
  30. edit PAF notes. 
  31.  
  32. There are several useful notes manipulation utilities available
  33. as shareware on Compuserve.  These include PAFNOT and FRASC
  34. written by Steve Cannon, and IMPORT by Jack Chandler.  However,
  35. these do not support the full cycle of external PAF notes
  36. editing: retrieval, editing, and storage back in NOTES2.DAT.
  37.  
  38. Description of NOTES EDIT utilities:
  39.  
  40.  
  41.           +--------------------+
  42.           |   GETNOTES.EXE     |
  43.           |                    |
  44.           |  Read notes from   |
  45.           |  an individual     |
  46.           |  into a text file  |
  47.           |  with file name    |
  48.           |  equal to RIN      |
  49.           |                    |
  50.           +--------------------+
  51.                    |
  52.                    |
  53.                    |
  54.           +--------------------+
  55.           |    EDIT            |
  56.           |                    |
  57.           |  Edit those notes  |
  58.           |  using your        |
  59.           |  favorite text     |
  60.           |  editor            |
  61.           |                    |
  62.           +--------------------+
  63.                    |
  64.                    |
  65.                    |
  66.           +--------------------+
  67.           |    PUTNOTES.EXE    |
  68.           |                    |
  69.           |  Move the edited   |
  70.           |  file back into    |
  71.           |  NOTES2.DAT        |
  72.           |                    |
  73.           +--------------------+
  74.  
  75.  
  76. The NOTES EDIT Utilities consist of two programs:
  77.  
  78.      GETNOTES.EXE
  79.      PUTNOTES.EXE
  80.  
  81. The normal sequence of for using the NOTES EDIT Utilities is
  82. shown by the preceding block diagram. 
  83.  
  84.      Step 1:  The first step is the running the GETNOTES program
  85.      which will create a text file containing the notes for a
  86.      specific individual.  The RIN of that individual is entered
  87.      in as a parameter to the program.  
  88.  
  89.      Step 2:  The text file can then be opened and edited using
  90.      any text editor.  Once editing is complete, the information
  91.      MUST be written out as an ASCII file by the text editor.  It
  92.      must not be saved in a specialized word processor format or 
  93.      the results are unpredictable.  
  94.  
  95.      Step 3: The final step is to write the text file containing
  96.      the modified notes back to NOTES2.DAT using the PUTNOTES
  97.      program.  PUTNOTES will handle all processing related to
  98.      deleting the original notes, extending the NOTES2.DAT file
  99.      if necessary, reallocating previously deleted records, and
  100.      finally writing the new notes text to NOTES2.DAT.
  101.  
  102.  
  103.  
  104. NE Batch File:
  105.  
  106. To make the above sequence of programs easier to run, a batch
  107. program, NE.BAT (NOTES EDITOR Batch File), is provided.  This
  108. batch file (or script) permits the desired sequence of programs
  109. to be run from the entry of a single command. To edit the notes
  110. for an individual whose PAF RIN number is 254, type:
  111.  
  112.           NE 254
  113.  
  114. The result is that your editor will be initiated using a text
  115. file contain the specified note text.  When you exit from the
  116. editor (after saving the file you are editing, of course), the
  117. modified notes text is restored to the NOTES2.DAT file by the
  118. PUTNOTES program.
  119.  
  120. The NE batch file assumes that you are in the same directory as
  121. your PAF files.  In this is not the case, you must enter the NE
  122. command with two operands.  The second operand will be the name
  123. of the directory in which the PAF files are located.  For
  124. example:
  125.  
  126.  
  127.           NE 254 \smith\paf
  128.  
  129.  
  130.  
  131. Configuring NE to Reference Your Text Editor
  132.  
  133. You must modify customize NE to refer to your text editor.  To do
  134. this you must change the first line of the NE.BAT file.  This
  135. first line initially will look like this:
  136.  
  137.      set editor=EDIT
  138.  
  139. The example is configured to use the EDIT program, which on my
  140. machine invokes the Microsoft editor.  Using any text editor,
  141. change the word EDIT to the name of your text editor, for example
  142. to invoke the Microsoft WORD editor located in the UTILITY
  143. directory, the first line must be changed to:
  144.  
  145.      set editor=\UTILITY\WORD
  146.  
  147.  
  148.  
  149. A Helpful Hint: Setup a Hotkey or macro to Exit the Editor 
  150.  
  151. I found it useful to program my text editor with a "Hotkey"
  152. (single keystroke macro) which terminates my notes editing
  153. session by saving the notes as an ASCII file and exiting the
  154. editor.  
  155.  
  156.  
  157. Running GETNOTES and PUTNOTES Alone
  158.  
  159. The NOTES EDIT Utility programs can be run as individual
  160. programs.   GETNOTES will export a set of PAF notes into a text
  161. file.  PUTNOTES will store any text file as PAF notes.  These two
  162. utility programs have three parameters:
  163.  
  164.      1.   RIN number
  165.  
  166.      2.   PAF directory if different from current directory
  167.  
  168.      3.   Text File name if different from the RIN number is in a
  169.           different directory from the current directory.
  170.  
  171. An example:
  172.  
  173.      GETNOTES 11 \SMITH\PAF ROBERT.NOT
  174.  
  175.  
  176. REVISION HISTORY
  177.  
  178. Version 1.0:  Loaded 28 Feb 1993
  179.  
  180. Initial release.
  181.  
  182. Version 1.1:  Loaded March 19, 1993
  183.  
  184. Contains a minor fix to the NE.BAT file, line 6 where "goto putnote"
  185. should have been "goto putnotes".  Also the deletes of the 
  186. working files in lines 12 and 15 have been changed to delete all files 
  187. with a file name equal to the RIN.  This will delete a backup file copy
  188. of the notes if one was created during the editor session.
  189.  
  190. Version 1.2:   
  191.  
  192. This version contains fixes for a bug that caused invalid note chain 
  193. pointers and duplicate cross references.  This situation occurred 
  194. occasionally when notes were added that were smaller than those they 
  195. replaced.  This is a rare situation and I only received one mention of 
  196. this problem from a thoughtful user.  This problem, if it occurred, could
  197. be fixed by "frchk -f".
  198.  
  199. This version will also ingest a final note line without
  200. a line feed character following it. (GETNOTES)
  201.  
  202. This release contains logic to ensure that no unprintable characters in 
  203. the text file get loaded into NOTES2.DAT.  
  204.  
  205.  
  206. Version 1.3
  207.  
  208. This version corrects an error that somehow crept into the NE.BAT file.  
  209. The statement that executes the PUTNOTES program incorrectly referred to
  210. program PUTNOTE, which, of course, cannot be found causing a "Bad Command
  211. Or Filename" error.
  212.  
  213.  
  214. Version 1.4
  215.  
  216. This version ensures that the RIN number specified as the first parameter of
  217. either the GETNOTES and PUTNOTES command line is not greater than the biggest
  218. RIN in INDIV2.DAT.
  219.  
  220. A check is also made to determine if the specified individual has been 
  221. deleted.  If he/she has, the program is terminated. 
  222.  
  223.  
  224.  
  225. DISCLAIMER
  226.  
  227. The NOTES EDIT Utilities are offered without charge as freeware
  228. with no guarantee of reliable operation or any claims to that
  229. effect.  You use these programs at your own risk.  The PAF
  230. NOTES2.DAT file have a complex organization that can be easily
  231. damaged beyond repair by programs such as the NOTES EDIT
  232. Utilities.  The NOTES EDIT Utilities are new software, written in
  233. January of 1993.  It is recommended that at all times you make a
  234. backup copy of your .DAT files (at least NOTES2.DAT and
  235. INDIV2.DAT) prior to using the NOTES EDIT Utilities.  If your
  236. files are corrupted, your uncorrupted versions can be restored
  237. from the backups.
  238.  
  239. After all that negative talk, it should be said that these
  240. programs were written by a professional software developer, and
  241. have been tested carefully.  They have been in daily use on my
  242. own PAF database without problems for about a month (written Feb
  243. 21, 1993).  I got bored with taking backups and no longer do so. 
  244. If you can document any problem with these programs, I would like
  245. to hear about it along with copies of the PAF files concerned. 
  246. Please send me E-Mail on Compuserve, 71034,1301 or conventional
  247. mail to:
  248.  
  249.      Jonathan Paul
  250.      56 Calera Canyon
  251.      Salinas, CA 93908
  252.      (408) 375-6561
  253.  
  254. If you find these programs useful, I would appreciate hearing
  255. from you.