home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-385-Vol-1of3.iso / d / doc301.zip / CHANGES.301 next >
Text File  |  1992-12-15  |  18KB  |  400 lines
  1. DOC Version 3.01
  2.  
  3.    ------- Overview of DOC's Design Philosophy --------
  4. In order to understand why DOC works the way it does it would be
  5. helpful to know how I view DOC and how I intended that it be
  6. used. DOC assumes that a Clipper programmer wants to thoroughly
  7. document each function with comments in the source code. DOC also
  8. assumes that the programmer desires that these comments should
  9. immediately precede the function, that they should be in a
  10. standard format and that the programmer should only have to
  11. document a function once, changing his/her comments only when and
  12. as much as the function changes. DOC assists the programmer in
  13. accomplishing these goals by allowing the programmer to design
  14. the function comment header's appearance, creating the header in
  15. the source code when it does not exist, filling in all the
  16. information that it can glean from the source code, and
  17. preserving the programmer's inserted comments when they exist.
  18. DOC also assists the programmer by creating function reports and
  19. a Norton Guide database from these headers comments, multiplying
  20. the programmer's efforts to document his/her source code.
  21.  
  22. DOC can be used without typing comments into the function
  23. headers.  DOC will even create a Norton Guide database from source
  24. code without function header comments, although it will be a
  25. minimum sort of documentation -- all the functions will be lumped
  26. into one list, with only the function name, its calling syntax
  27. and its parameters detailed. However, to use all that DOC has to
  28. offer the user should run the source code through DOC a number of
  29. times, filling in the function headers with comments after DOC
  30. creates them, and changing the header comments when the function
  31. is modified. If the programmer does this and keeps rerunning DOC
  32. periodically as the source code is developed DOC can provide
  33. useful and up-to-date documention in headers in the source code,
  34. helpful indenting and capitalization and de-capitalization to
  35. make the source code easier to follow, source code print-outs
  36. with line numbering, page numbering and a Table of Contents,
  37. useful reports such as a Cross-Reference, Database/Index, Index
  38. and Function reports and an on-line database to save the
  39. programmer time and effort during programming.
  40.  
  41. ---------------------------------------------------------------------
  42.  
  43.        NEW FEATURES THIS VERSION
  44. 1.  Cross Reference and STATS reports.
  45. 2.  User configuration of Function headers.
  46. 3.  Improved Norton Guide database creation, including user configuration
  47.     of the NG menu structure and See Also : support.
  48. 4.  Database path seperate from Source Code path.
  49. 5.  Command line parameters for running DOC from batch or make files.
  50.  
  51.   This READ.ME file documents all the changes between DOC version
  52. 2.12 and 3.01. If you have used and are familiar with DOC 2.12
  53. you should only need to read this file to get up to speed with
  54. version 3.01. If you have not used previous versions of DOC you
  55. should read the User's Manual.
  56.  
  57.   Note : If you have configuration files (these are files in the
  58. Source Code directory named CONFIG.DOC unless you supplied a
  59. different name) created by previous versions of DOC you must
  60. delete them before running Version 3.01. The number of new
  61. variables which DOC now writes to the configuration file made it
  62. impossible to allow DOC to read the files created by previous
  63. versions.
  64.  
  65.  
  66.      ---------- Command Line Parameters -------------
  67.   These were added to allow DOC to be called from a batch or make
  68. file for unattended operation. This can only be done after DOC
  69. has been run at least once interactively for a particular
  70. programming project, the user has typed in all the information
  71. and selected the desired configuration in the menus and saved the
  72. configuration to a configuration file. Once the configuration is
  73. set so that the user only needs to type in the Source Code path
  74. (if it is not the default DOS directory) and the Configuration
  75. File Name (if it is not CONFIG.DOC) and then tell DOC to Go then
  76. the user is ready run DOC unattended using the Command Line
  77. Parameters.
  78.  
  79. -S<path>    Sets the Source Code Path (the directory containing
  80. the configuration file and the make file).  If the DOS default
  81. directory is set to the Source Code Path before DOC is run this
  82. is not needed.
  83.  
  84. -C<file name>  Sets the Configuration File name to something other
  85. than the default CONFIG.DOC.  If several programming
  86. projects share a source code directory only one of them can use
  87. the default name of CONFIG.DOC for its configuration file and the
  88. others must specify a different name whenever DOC is started.
  89.  
  90. -G   Causes DOC to skip the menus and start documenting.
  91.  
  92. FOR EXAMPLE :
  93. The following line in a batch file:
  94.          DOC -sD:\CLIPPER5\SOURCE\MYAPP -cMYAPP.CFG -g
  95. would run DOC unattended assuming there was a DOC configuration
  96. file named MYAPP.CFG in the directory D:\CLIPPER5\SOURCE\MYAPP.
  97. The following lines in a batch file:
  98.          D:
  99.          CD \CLIPPER5\SOURCE\MYAPP
  100.          DOC -G
  101. would run DOC unattended assuming there was a DOC configuration
  102. file named CONFIG.DOC in directory D:\CLIPPER5\SOURCE\MYAPP.
  103.  
  104.  
  105.  
  106.    ---------- Cross Reference Listing ----------
  107. DOC can now create a cross reference listing.  The only options,
  108. selected in the Report Output Screen, are whether or not to
  109. create the listing (which does lengthen DOC's processing time and
  110. increases the size of the temporary databases significantly) and
  111. whether or not to include key file function names in the listing.
  112.  
  113.    ---------- Stats Report ----------------
  114. This is a report, which DOC will from now on always create, which
  115. lists the number of lines of code, number of lines of headers and
  116. number of lines total and number of functions for each source
  117. file documented and totals for the entire application.  It is a
  118. small report which does not add noticeably to DOC's processing
  119. time or temporary file size.
  120.  
  121. ------ Function Header Configuration -------------
  122. Two new input screens have been added in the "Output" section -
  123. Function Headers and Norton Guide Creation.
  124.  
  125. The Function Headers input screen looks like this:
  126.  
  127.              Enter Function Header Options
  128.  
  129.   (Read) Purpose Heading           "   Purpose :"
  130.   (Write) Purpose Heading          "   Purpose :"
  131.   (Read) Out Heading               "   Out     :"
  132.   (Write) Out Heading              "   Out     :"
  133.   (Read) Comment 1 Heading         "   Assumes :"
  134.   (Write) Comment 1 Heading        "   Assumes :"
  135.   (Read) Comment 2 Heading         "   Author  :"
  136.   (Write) Comment 2 Heading        "   Author  :"
  137.   (Read) See Also Heading          "  See Also :"
  138.   (Write) See Also Heading         "  See Also :"
  139.   (Read) Ngo File Heading          "   NgoFile :"
  140.   (Write) Ngo File Heading         "   NgoFile :"
  141.   (Read) First Header line         "*!*********************"
  142.   (Write) First Header line        "*!*************************************"
  143.   (Read) Last Header line          "*!*********************"
  144.   (Write) Last Header line         "*!*************************************"
  145.   (Read) Header left edge          "*!   "
  146.   (Write) Header left edge         "*!   "
  147.   Blank lines between sections       "Y"
  148.  
  149.  
  150.    The default answers correspond to the style headers previous
  151. versions of DOC created.
  152.    The (Read) variables are used when DOC is extracting
  153. programmer comments from the code it is reading.  The (Write)
  154. variables determine how the headers look in the output code,
  155. action diagrams, function reports and Norton Guides.  Therefore,
  156. if you have programmer comments in DOC created headers that you
  157. want to retain you need to set the (Read) variables the way the
  158. matching (Write) variables were set the last time DOC was run.
  159.  
  160.   For example, if you wish your headers to look like this :
  161.  
  162. /* -------------------------
  163. |     Function Main
  164. |  Calls : MyFunc()
  165. |        : MyFunc2()
  166. | Overview : This is the main menu routine  Sets defaults.
  167. |            Sets screen color defaults based on ISCOLOR()
  168. |            unless given a B/W command line parameter.
  169. | In       : Param1 - first command line parameter.
  170. |          : Param2 - second command line parameter.
  171. | Returns  : Nothing
  172. | Comments : Expects MYDATA.DBF to be in the default directory.
  173. -------------------------- */
  174.  
  175.   and the code contains these comments in a header created by a
  176. previous version of DOC you would set the variables like this:
  177.  
  178.  
  179.   (Read) Purpose Heading           "   Purpose :"
  180.   (Write) Purpose Heading          "  Overview :"
  181.   (Read) Out Heading               "   Out     :"
  182.   (Write) Out Heading              "   Returns :"
  183.   (Read) Comment 1 Heading         "   Assumes :"
  184.   (Write) Comment 1 Heading        "  Comments :"
  185.   (Read) Comment 2 Heading         "           :"
  186.   (Write) Comment 2 Heading        "           :"
  187.   (Read) See Also Heading          "           :"
  188.   (Write) See Also Heading         "           :"
  189.   (Read) Ngo File Heading          "           :"
  190.   (Write) Ngo File Heading         "           :"
  191.   (Read) First Header line         "*!************"
  192.   (Write) First Header line        "/* ---------------------------"
  193.   (Read) Last Header line          "*!************"
  194.   (Write) Last Header line         "---------------------------- */"
  195.   (Read) Header left edge          "*!   "
  196.   (Write) Header left edge         "|    "
  197.   Blank lines between sections       "N"
  198.  
  199.  
  200.  
  201. If the next time you run DOC you have changed your mind and you
  202. want the headers to look like this:
  203.  
  204.  
  205. /* =======================
  206. ||
  207. ||     Function Main
  208. ||
  209. ||  Calls : MyFunc()
  210. ||        : MyFunc2()
  211. ||
  212. || Overview : This is the main menu routine  Sets defaults.
  213. ||            Sets screen color defaults based on ISCOLOR()
  214. ||            unless given a B/W command line parameter.
  215. ||
  216. || In       : Param1 - first command line parameter.
  217. ||          : Param2 - second command line parameter.
  218. ||
  219. || Returns  : Nothing
  220. ||
  221. || Comments : Expects MYDATA.DBF to be in the default directory.
  222. ||
  223. ============================ */
  224.  
  225.  you would set the variables like this:
  226.  
  227.   (Read) Purpose Heading           "  Overview :"
  228.   (Write) Purpose Heading          "  Overview :"
  229.   (Read) Out Heading               "   Returns :"
  230.   (Write) Out Heading              "   Returns :"
  231.   (Read) Comment 1 Heading         "  Comments :"
  232.   (Write) Comment 1 Heading        "  Comments :"
  233.   (Read) Comment 2 Heading         "           :"
  234.   (Write) Comment 2 Heading        "           :"
  235.   (Read) See Also Heading          "           :"
  236.   (Write) See Also Heading         "           :"
  237.   (Read) Ngo File Heading          "           :"
  238.   (Write) Ngo File Heading         "           :"
  239.   (Read) First Header line         "/* -----------"
  240.   (Write) First Header line        "/* ============================"
  241.   (Read) Last Header line          "--------------"
  242.   (Write) Last Header line         "============================ */"
  243.   (Read) Header left edge          "|   "
  244.   (Write) Header left edge         "||   "
  245.   Blank lines between sections       "Y"
  246.  
  247.  
  248.   You must make absolutely sure that no other lines in you code
  249. match the First and Last Header line variables.  You also must be
  250. aware that if you do not have the "(Read) Purpose Heading"
  251. variable set correctly, (it does not match the existing headers )
  252. DOC will not find you comments and that if you do not have the
  253. "(Read) Last Header Line" variable set correctly DOC will treat
  254. your entire source code like a comment and not document anything
  255. [this does, however, speed up the processing <g>].
  256.  
  257.   DOC rtrims these variables so spaces on the left are
  258. significant, but spaces on the right are ignored.
  259.  
  260.  
  261.    --- See Also Heading and NGO File Heading ---
  262.   Any programmer's comments placed in See Also and NGO file
  263. sections of the function headers have special meanings to DOC
  264. when it creates the Norton Guide database. If a Norton Guide
  265. database is not to be created then these sections can be retitled
  266. and used for something else, such as "History :" or "Changes :".
  267.  
  268.   If DOC finds one or more function names in the See Also section
  269. of the header it creates a "See Also" or "Related Topics"
  270. reference from that entry to the specified other entries in the
  271. database.
  272.  
  273.   The Ngo File parameter in the headers allows the programmer to
  274. set up multiple function lists and menus in the Norton Guide
  275. database created by DOC. The way it works is if the user wants
  276. the Norton Guide create by DOC to list the functions in multiple
  277. lists selected from a menu rather than the default of all the
  278. functions in one big list then the user needs to do some
  279. planning.
  280.  
  281.  1. Divide up all the functions in the application into a number
  282. of groups.
  283.  
  284.  2. For each group select a menu name and a Ngo File name. The
  285. Ngo File name must be a valid DOS base file name of up to 8
  286. characters.
  287.  
  288.  3. Label each function with the Ngo File name of the group to
  289. which it belongs. This can be done either by typing it into the
  290. function header created by DOC following the Ngo File : prompt or
  291. by by using a NgoFile comment line.  You can place NgoFile
  292. comments anywhere in your source code except inside function or
  293. file headers.  These comment lines must start with *, // or &&
  294. (not /* ... */ style comments).  The first word must be NGOFILE
  295. followed by a valid, up to 8 character, DOS base file name.  All
  296. the functions following that line (until the next NgoFile comment
  297. or the end of the source code file) that do not have a group (Ngo
  298. File name) specified in the function header will be assigned to
  299. that function group.
  300.  
  301.  4. When DOC is next run it will create a seperate .NGC (or .EHC)
  302. file for each Ngo File name and will create the lines in the
  303. MAKENG.BAT file to compile them.
  304.  
  305.  5. DOC will also create a link file with a defualt menu
  306. structure. This link file can be used as is, or the programmer
  307. can edit it with a text editor to change the menu wording or
  308. organization if desired before running the MAKENG batch file to
  309. compile and link the Norton Guide database.
  310.  
  311.   For example: if you have put references to the following
  312. NgoFiles in your source code : ARRAY, BROWSE, COLOR, DATABASE,
  313. DISPLAY, DRIVPATH, MENU, PRINTER, STRING and you specfied MISC as
  314. the default NgoFile, you have accepted NGO as the object file
  315. extension, and "My Personal Library" as the Long Name, then DOC
  316. will create the following link file:
  317.  
  318. !name: My Personal Library
  319. !menu: Functions1
  320.       ARRAY   ARRAY.NGO
  321.       BROWSE   BROWSE.NGO
  322.       COLOR   COLOR.NGO
  323.       DATABASE   DATABASE.NGO
  324.       DISPLAY   DISPLAY.NGO
  325. !menu: Functions2
  326.       DRIVPATH   DRIVPATH.NGO
  327.       MENU   MENU.NGO
  328.       MISC   MISC.NGO
  329.       PRINTER   PRINTER.NGO
  330.       STRING   STRING.NGO
  331.  
  332. You must not change the object file names but you can rearrange
  333. the lines, change the !menu: names and the menu names for the
  334. object files.  For example you could make the following changes
  335. before running MAKENG.BAT.
  336.  
  337. !name: My Personal Library
  338. !menu: User Interface
  339.       BROWSE      BROWSE.NGO
  340.       SCREEN_COLOR  COLOR.NGO
  341.       DISPLAY     DISPLAY.NGO
  342.       MENU        MENU.NGO
  343. !menu: Array & DBF
  344.       ARRAY       ARRAY.NGO
  345.       DATABASE    DATABASE.NGO
  346. !menu: DOS, Print & Misc
  347.       DRIVE/PATH  DRIVPATH.NGO
  348.       MISC        MISC.NGO
  349.       PRINTER     PRINTER.NGO
  350.       STRING      STRING.NGO
  351.  
  352.  
  353.  
  354.     -------- Norton Guide Creation Input Screen ----------
  355.   The input screen looks like this:
  356.  
  357.    Long Name     "My Personal Library                "
  358.    Norton Guide Short Name                  "mylib   "
  359.    Default NGO File                         "MISC    "
  360.    Norton Guide Compile File Extension           "NGC"
  361.    Norton Guide Object File Extension            "NGO"
  362.    Norton Guide Link File Extension              "NGL"
  363.    Command to invoke Norton Guide compiler
  364.     " NGC                                            "
  365.    Command to invoke Norton Guide linker
  366.     " NGML                                           "
  367.  
  368. Norton Guide Long Name - whatever is entered here is written as
  369. the !name parameter in the link file.  This is the name of the
  370. Norton Guide Database created from this application. It defaults
  371. to the name of the application as entered in the System Data
  372. menu.
  373.  
  374. Norton Guide Short Name - this must be a valid DOS base file name
  375. of up to 8 characters. This will be the base file name of the
  376. link file and the *.NG file.  It defaults to the base name of the
  377. make file entered in the System Data menu.
  378.  
  379. Default NGO file - the object file for any functions for which no
  380. NGO file was specified either in the header or by means of a
  381. NGOFile comment. If left blank, functions without a NGO file
  382. specified either through a NGOFILE comment or an entry in the
  383. NgoFile: section of the function header will not be included in
  384. the Norton Guide.
  385.  
  386. Norton Guide Compile File Extension - if you are using Expert
  387. Help you may wish to change this to "EHC".
  388.  
  389. Norton Guide Object File Extension - if you are using a version
  390. of the Expert Help linker which expects object files to have an
  391. extension of "EHO" you must enter that here.
  392.  
  393. Norton Guide Link File Extension - if you are using Expert Help
  394. you may wish to change this to "EHL".
  395.  
  396. Commands to invoke compiler and linker - if your Norton Guide
  397. Compiler and Linker are not in the DOS default directory or in a
  398. directory in the DOS path you must enter their full path names
  399. here.
  400.