home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / xbase / tools / clipdoc / doc.man < prev   
Text File  |  1992-04-02  |  22KB  |  611 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.                                        DOC
  17.  
  18.                      Source Code Documenter for Clipper 5.0x
  19.  
  20.                                   Version 2.00
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.                                Copyright (C) 1991
  32.                           Clarity Computer Consultants
  33.                                  1831 - 13th St.
  34.                                 Moline, IL 61265
  35.                                  (309) 797-0906
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.                                         1
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.                                     OVERVIEW
  69.  
  70.         DOC, the Source Code Documenter for Clipper 5.0x code, will read
  71.         your Clipper source code files and rewrite them into another
  72.         directory, indenting the code to show program control structures,
  73.         inserting a file header listing all the functions and procedures
  74.         in the file and a function header preceding each function and
  75.         procedure listing all the other functions which call or are
  76.         called by this function, lists the parameters and provides space
  77.         for the programmer to insert comments for each parameter and to
  78.         state the function's purpose, output and assumptions.  These
  79.         programmer comments in the headers are supported by DOC in that
  80.         each time DOC documents your source code it saves any existing
  81.         comments and reinserts them in the new header.  DOC saves the
  82.         name of the parameter with the parameter comments so that even if
  83.         the parameter order has been changed DOC will keep the comment
  84.         with the correct parameter.
  85.  
  86.         DOC can also send your source code files to the printer, or print
  87.         to disk.  The printed source code files have page headers in-
  88.         serted at the top of each page and a Table of Contents, listing
  89.         the page on which each function and parameter starts.  DOC can
  90.         optionally also insert line numbers in printed source code files.
  91.         DOC will optionally also create an action diagram for each source
  92.         code file with lines marking the program control structures.  The
  93.         printed action diagrams also have page headers, Table of Contents
  94.         and, optionally, line numbers inserted.
  95.  
  96.         DOC can create a list of source code files to be documented
  97.         automatically from a make file or any ASCII text file in which
  98.         the names of the source code files appear.  Clipper library
  99.         functions and other functions can be listed in KEY files, identi-
  100.         fying them to DOC.  For each KEY file you can tell DOC whether or
  101.         not the functions in that library should be listed in the headers
  102.         and reports.
  103.  
  104.         DOC optionally also creates a Function and Procedure Report
  105.         listing each function and procedure in the source code files in
  106.         either alphabetical or order read or both.  Each function and
  107.         procedure is listed with a list of functions called, the func-
  108.         tion's parameters and comments and the other programmers com-
  109.         ments.
  110.  
  111.         DOC creates a Index and a Table of Contents document listing all
  112.         the functions and procedures in the system with the page number
  113.         and name of the name of the source code file for each.  The Index
  114.         document lists the functions and procedures in alphabetical order
  115.         and the Table of Contents lists them in the order read.
  116.  
  117.         DOC, in conjunction with a Norton guide compiler and linker such
  118.         as those that are supplied with Expert Help, can create a Norton
  119.         Guide database for all the functions and procedures in the system
  120.  
  121.  
  122.                                         2
  123.  
  124.  
  125.  
  126.         using the parameter list for the syntax and the programmer's
  127.         comments for the text.  DOC creates the NGC compile file, the NGL
  128.         link file and a batch file which, when run, automatically com-
  129.         piles and links the guide.
  130.  
  131.  
  132.  
  133.                                    Running DOC
  134.  
  135.         If the file DOC.EXE resides in a directory in your path you can
  136.         invoke DOC from any DOS prompt.  Just type
  137.  
  138.                                    DOC <ENTER>
  139.  
  140.         To force monochrome screen colors on a computer which returns .T.
  141.         to the ISCOLOR() function you would type
  142.  
  143.                                  DOC B/W <ENTER>
  144.  
  145.         When DOC loads it displays an title page and then the Enter
  146.         System Variables Screen.
  147.  
  148.  
  149.  
  150.                              Enter System Variables
  151.  
  152.         MAKE FILE AND SOURCE CODE PATH
  153.         The Source Code Path is the directory in which DOC looks for
  154.         source code files which are listed without a path, where it looks
  155.         for the make file and in which it saves and from which it re-
  156.         trieves its System Data.  If most of the source code files and
  157.         make file for each separate application to be documented are in
  158.         their own separate directories DOC can be run with the minimum of
  159.         hassle, but DOC has enough flexibility to work with any directory
  160.         structure.  If this field is left blank the current DOS directory
  161.         is the Source Code Path.
  162.  
  163.         SYSTEM DATA FILE NAME
  164.         The default name for the file in which DOC saves the System Data
  165.         is CONFIG.DOC.  If there already is a file with this name or you
  166.         want more than one configuration of DOC with the same Source Code
  167.         Path you can specify another name.
  168.  
  169.         MAKE FILE NAME
  170.         Type in the name of the make file, or ASCII text file, if you
  171.         will want DOC to create a list of files to document for you.  The
  172.         file must be in the Source Code directory and if no extension is
  173.         specified an extension of RMK is assumed.  If the file name has
  174.         no extension put a period at the end of the name.
  175.  
  176.         NAME OF APPLICATION, AUTHOR and COPYRIGHT HOLDER
  177.         The data typed in these 3 fields will be used in the headers of
  178.         all output files and reports.
  179.  
  180.         OUTPUT FILE PATH
  181.  
  182.  
  183.                                         3
  184.  
  185.  
  186.  
  187.         Specify a directory where the output source code files, action
  188.         diagrams, reports and print to disk files will be created.  This
  189.         must be different than the Source Code Path or other directories
  190.         where input source code files reside or there will be name con-
  191.         flicts between the input and output files.
  192.  
  193.         KEY FILE PATH
  194.         The drive and directory where DOC expects to find the key files
  195.         specified in the key file list.
  196.  
  197.  
  198.                               The Main Menu Screen
  199.  
  200.  
  201.         FILES
  202.         System Data <F1>
  203.         Pressing F1 brings up the System Data screen again.
  204.  
  205.         Key File List <F8>
  206.         Selecting this option places you in the Key File Names and Doc
  207.         Names screen.  Type in the names of your key files including
  208.         extension.  DOC will assume these files are in the key file
  209.         directory specified on the System Data screen.  If you leave the
  210.         Doc Name column blank the functions listed in that key file will
  211.         be ignored by DOC.  If you type in a Doc Name the functions in
  212.         that key file will included in the file headers and reports and
  213.         will be listed as being "from" that Doc Name.  Press ENTER to be
  214.         editing on the current line.  Press the down arrow key to add a
  215.         new line.  Press the ESC key when done.
  216.  
  217.         From Make File <F2>
  218.         Selecting this option causes DOC to read the make file and ex-
  219.         tract the names of all files with an extension of PRG or SCR
  220.         which it finds and creates the List of Files to be Documented. If
  221.         you do not have a file which lists your source code files or you
  222.         want to document source code files with non-standard extensions
  223.         just type in your list of files using the Edit File List proce-
  224.         dure.
  225.  
  226.         Edit File List <F3>
  227.         When you select this option you can edit the List of Files to be
  228.         Documented.  To add new source code file names use the down arrow
  229.         key to move to a blank line and type in the name.  Press the DEL
  230.         key to delete an existing name.  Be sure to specify the path for
  231.         any source code files which are not in the Source Code Path drive
  232.         and directory.  Press ESC key when done.
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.                                         4
  245.  
  246.  
  247.  
  248.         OUTPUT
  249.         Source Code <F4>
  250.         When this option is selected a screen pops up with the following
  251.         options.  On questions with non-numeric answers toggle through
  252.         the options by pressing any keys other than the arrow keys.  Use
  253.         the up and down arrow keys to move the cursor.
  254.  
  255.         9    Write SourceCode files to output path   YES/NO
  256.         If YES, each source code file in the File List is rewritten to
  257.         the Output Directory with headers inserted and indented.
  258.  
  259.              Print Source Code files                 YES/NO
  260.         If YES, each source code file is sent to a printer port or a disk
  261.         file with headers inserted, indented, page breaks and headers and
  262.         a Table of Contents.
  263.  
  264.              Send Printed Source Code to   LPT1/LPT2/LPT3/COM1/COM2/FILE
  265.         If FILE, the Source Code files are printed to a file with an
  266.         extension of *.PRN in the output directory.  Otherwise the print-
  267.         ed source code is sent to the printer port selected.
  268.  
  269.              Line numbers in printed source code       YES/NO
  270.         If YES, line numbers are inserted at the beginning of each line
  271.         of the printed file.
  272.  
  273.              Write action diagrams to output path       YES/NO
  274.         If YES, each source code file is rewritten to the Output Directo-
  275.         ry with an extension .ACT, headers, indenting and lines marking
  276.         the program control structures.
  277.  
  278.              Print action diagrams                      YES/NO
  279.         If YES, each action diagrams is sent to a printer port or printed
  280.         to disk with page breaks, headers and a Table of Contents.
  281.  
  282.              Send Printed Action diagrams to  LPT1/LPT2/.../COM2/FILE
  283.         If FILE, the action diagrams are printed to files in the output
  284.         directory with an extension of .APN.  Otherwise they are sent to
  285.         the selected printer port.
  286.  
  287.              Line numbers in printed action diagrams     YES/NO
  288.         If YES, line numbers are inserted at the beginning of each line
  289.         in the printed action diagrams.
  290.  
  291.              Use graphics in action diagrams             YES/NO
  292.         If YES, IBM upper ASCII box-drawing characters are used to mark
  293.         the control structures in action diagrams.  If your printer
  294.         cannot print these characters properly select NO.
  295.  
  296.              Final page eject in printed output           YES/NO
  297.         If NO, the page eject on the final page of printed output is
  298.         omitted.  This avoids extra blank pages when using utilities such
  299.         as LJBOOK after printing to disk.
  300.  
  301.              Spaces to indent comment lines        [Numeric input]
  302.         Number of spaces to indent file and function headers created by
  303.  
  304.  
  305.                                         5
  306.  
  307.  
  308.  
  309.         DOC.  If you want only FUNCTION and PROCEDURE declaration lines
  310.         to start in Column 0 in your source code enter a number other
  311.         than 0 here.
  312.  
  313.              Indent #if, #else, #endif                     YES/NO
  314.         If YES, #if #else and #endif are treated the same as IF, ELSE and
  315.         ENDIF in terms of indenting and in the action diagrams.  If NO,
  316.         they are not treated as program control structures.
  317.  
  318.              Number of char/line in printer output   [Numeric input]
  319.         Number of characters per line your printer can handle.  Lines
  320.         longer than this a counted as 2 lines in determining page breaks.
  321.  
  322.              Number of spaces to indent per level    [Numeric input]
  323.         Number of spaces to indent each control level.  Three seems to be
  324.         a standard.  I prefer the look of 2, personally.  Entering 0
  325.         tells DOC to retain the original indenting.
  326.  
  327.              (O)verwrite, (A)bort, enter (N)ew name or
  328.              (R)ename existing file if already exists       O/A/N/R
  329.         Determines what DOC does when it is about to create a file in the
  330.         Output directory and it discovers a file with the same name
  331.         already there.  If O, it ignores the problem and overwrites the
  332.         existing file.  (Careful! If you put O here and make the Output
  333.         directory and the Source Code directory the same your original
  334.         source files will be over-written.)  If A, it aborts processing.
  335.         If N, it prompts the user for a new name for the file it is about
  336.         to create.  If R, it prompts the user for a new name for the
  337.         existing file.
  338.  
  339.         Reports <F5>
  340.         When this option is selected the user is presented with a screen
  341.         containing the following options:
  342.  
  343.              Send printed reports to     LPT1/LPT2/LPT3/COM1/COM2/FILE
  344.         Determines where the reports are sent.
  345.  
  346.              Create Data Directory and CH files            YES/NO
  347.         If YES, creates a Data Directory data base and a report for all
  348.         the databases and indexes it finds in the Source Code directory
  349.         which are referred to the source code.  It also creates a CH
  350.         include file with some handy preprocessor defines for each data-
  351.         base.
  352.  
  353.              Create Index and TOC listing of functions      YES/NO
  354.         If YES, creates reports listing every function and procedure, the
  355.         source code file name in which it was found and the page number
  356.         in the source code where it starts.  (If neither source code
  357.         files or action diagrams are printed no page numbers are created
  358.         and all page numbers will be 0.)  The Index and Table of Contents
  359.         are identical except for the order in which the functions appear.
  360.  
  361.              Create Function report in read order            YES/NO
  362.         This is a report which lists all the functions and procedures in
  363.         the application along with all the information from its header,
  364.  
  365.  
  366.                                         6
  367.  
  368.  
  369.  
  370.         source code, line number and source code file name.
  371.  
  372.              Create Function report in alpha order            YES/NO
  373.         Same as above except the functions and procedures are listed in
  374.         alphabetical order.
  375.  
  376.              Create Norton Guide from headers info             YES/NO
  377.         If YES, the Norton guide compile file, linker file and a batch
  378.         file are created in the Output directory which, along with a
  379.         Norton Guide compiler and linker, such as those provided with
  380.         Expert Help, can create a Norton Guide for all the procedures and
  381.         functions in the application.
  382.  
  383.              Command to invoke Norton Guide compiler   [character input]
  384.         Type in the DOS command to invoke the Norton Guide compiler.  If
  385.         your Norton Guide compiler is in a directory in your DOS path
  386.         this would usually be "NGC".  Otherwise you would need to include
  387.         the path, ie "D:\EH\NGC".
  388.  
  389.              Command to invoke Norton Guide linker      [character input]
  390.         Type in the DOS command to invoke the Norton Guide linker, ie
  391.         "D:\EH\NGML".
  392.  
  393.  
  394.         WRITE
  395.         F6 - Read Configuration
  396.         When you select this option DOC tries to read in a previously
  397.         created System Data File from the currently specified Source Code
  398.         Directory.  If another name was not specified in the System Data
  399.         it looks for a file called "CONFIG.DOC".  If it finds the file it
  400.         reads it in, over-writing any existing entries.  The system data
  401.         includes all user input including the data in the System Data
  402.         screen, Output Data screen, Source Code File List and Key File
  403.         List.
  404.  
  405.         F7 - Write Configuration
  406.         When you select this option DOC saves all the System Data to a
  407.         file in the current Source Code directory with the name
  408.         "CONFIG.DOC" or other name as specified by the System Data File
  409.         name in System Data screen.
  410.  
  411.  
  412.         GO
  413.         F9 - Start Documenting
  414.         When the F9 key is pressed DOC starts to work using the current
  415.         settings.  You can abort by pressing the ESC key.
  416.  
  417.  
  418.         EXIT
  419.         Alt-G - Go Back
  420.         Go back to the Main Menu Screen.  Don't exit.
  421.  
  422.         F10 - Quit
  423.         Exits to DOS without doing anything.
  424.  
  425.  
  426.  
  427.                                         7
  428.  
  429.  
  430.  
  431.                        The DOCPATH Environmental Variable
  432.  
  433.         DOC creates a number of temporary databases while it is process-
  434.         ing which it erases before terminating.  DOC looks for an envi-
  435.         ronmental variable named DocPath.  If found it creates its tempo-
  436.         rary files in the drive and directory specified by this variable.
  437.         If there is no DocPath in the environment it looks for a variable
  438.         named TEMP and uses the drive and directory specified by it.  If
  439.         it finds neither it uses the current DOS directory for its tempo-
  440.         rary files.
  441.  
  442.         If you have a RAM drive that is big enough (2 or 3 MBytes should
  443.         be big enough if you are not documenting a HUGE application) set
  444.         DocPath to it.  Otherwise, it would be good to specify a directo-
  445.         ry where you have no permanent files to avoid any possibility of
  446.         a name collision.
  447.  
  448.  
  449.  
  450.  
  451.                           Support for SNAPCODE Comments
  452.  
  453.            DOC will document database and index files if their names are
  454.         used directly in USE and INDEX statements.  If the names of the
  455.         files are passed in variables, however, DOC will not know to
  456.         include them unless you use a SNAPCODE comment.  (Walter Kemmerer
  457.         suggested that DOC support SNAPCODE comments as a convenience to
  458.         the Clipper community.)  A SNAPCODE comment is a line starting
  459.         with an asterisk and then the word SNAPCODE.  Everything in the
  460.         line following the word SNAPCODE will be processed by DOC as
  461.         though it were code.
  462.            For example, if you have a generic function to open your
  463.         databases you might want to add a SNAPCODE comment following each
  464.         place in the code where it is called like this:
  465.  
  466.                   OpenDBFandNTX( "Customer", "CustIndx", cIndexExp )
  467.                   * SNAPCODE USE Customer INDEX CustIndx
  468.  
  469.         Another place to use SNAPCODE comments would be where a function
  470.         is called indirectly so that DOC knows that a function is being
  471.         called from the current function.  For example:
  472.  
  473.                   ACHOICE( nT, nL, nB, nR, acMenu, , "UserFunc" )
  474.                   * SNAPCODE UserFunc()
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.                                         8
  489.  
  490.  
  491.  
  492.                       Programmer's Comments in the Headers
  493.  
  494.         Doc creates a place in the file header and in each function
  495.         header for programmer's comments.  Each time DOC documents a
  496.         source code file existing header comments are saved and reinsert-
  497.         ed into the newly created headers.  These comments also appear in
  498.         the Function Report.  Future versions of DOC will use these
  499.         comments to help create Norton Guides databases.
  500.  
  501.         There are a couple of rules you must follow when inserting your
  502.         comments in the headers so that DOC can recognize them.  DOC uses
  503.         the following strings to recognize the beginning and ending point
  504.         of your comments.  Do not delete any spaces or otherwise alter
  505.         these strings in the headers or DOC will not be able to find your
  506.         comments.
  507.           *:  Comments :
  508.           *:  Procs & Funcs:
  509.           *!   Purpose :
  510.           *!   In      :
  511.           *!   Out     :
  512.           *!   Assumes :
  513.           *!************
  514.  
  515.         You can create multi-line comments by inserting lines.  Just be
  516.         sure to start each new line in the header with a *: (file header)
  517.         or *! (function header).
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.                                         9
  550.  
  551.  
  552.  
  553.                                  Registering DOC
  554.  
  555.         Thank you for taking a look at DOC.  If you have any questions
  556.         address them to David Barrett, or Hugh D. Barrett as I am known
  557.         on NANFORUM, at
  558.                                        CIS
  559.                                     72037,105
  560.  
  561.                                     telephone
  562.                        (309) 797-0906 evenings & weekends
  563.  
  564.                                       mail
  565.                           Clarity Computer Consultants
  566.                                 1831 13th Street
  567.                                 Moline, IL 61265
  568.                                      U.S.A.
  569.  
  570.         The registration fee is $35 or whatever you feel it is worth.
  571.         Send the registration fee to the above address.  If you are
  572.         registered I will treat any suggestions you have about the pro-
  573.         gram with great seriousness and try to solve any problems you
  574.         have promptly.  If you are not registered I reserve the right to
  575.         treat your problems and suggestions any way I feel like.
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.                                         10
  611.