home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_300 / 329_02 / xcxref.doc < prev    next >
Text File  |  1990-06-12  |  12KB  |  246 lines
  1.  
  2.  
  3.  
  4.                       XCXREF  -  A 'C' Concordance Utility
  5.                     ========================================
  6.         
  7.         'XCXREF'  is  a  cross-reference  utility for 'C' programs.  It 
  8.         is derived from another program named  'XC' developed as indicat-
  9.         ed below.
  10.         
  11.              Option flags support the following features:
  12.         
  13.              - Routing of list output to any combination of disk, printer 
  14.                and video.
  15.              - Cross-referencing of reserved words.
  16.              - Processing of nested include files.
  17.              - Proper processing of nested comments.
  18.              - Generation of program listing only.
  19.              - Variable output page width.
  20.              - Indirect and direct file name input.
  21.              - Alternate path direction.
  22.         
  23.                Usage: xcxref <filename> ...  <flag(s)>
  24.         
  25.         All files selected are cross-referenced together. The variable 
  26.         listing will show every occurance, for  example, of 'var' in 
  27.         every file.
  28.         
  29.               Flags: -e            = Write program data to log file.
  30.                      -g            = Ignore missing files.
  31.                      -i            = Enable #include processing.
  32.                      -l            = Generate listing only - no xref.
  33.                      -o <outfile>  = Write output to named file.
  34.                      -p            = Write output to line printer LPT1.
  35.                      -r            = Cross-reference 'C' reserved words.
  36.                      -s            = Write output to video screen.
  37.                      -w width      = Width of output page; default = 78
  38.                                                            max     = 150.
  39.              Flags MUST FOLLOW all input file names.
  40.         
  41.              Separate any flag parameters from the flag by at least
  42.              one space.
  43.         
  44.                Examples:
  45.         
  46.                  xcxref file1.c
  47.         
  48.                  xcxref main.c file1.c file2.c file3.c -o xref.lst -w 120
  49.         
  50.                  xcxref @xfile file3.c file4.c -o xref.lst -w 120
  51.                     xfile contains...  file1.c file2.c
  52.         
  53.  
  54.                History:
  55.         
  56.                XC - version 1.0 January, 1982
  57.                Copyright (c) 1982 by Philip N. Hisley
  58.         
  59.                   Philip N. Hisley
  60.                   548H Jamestown Court
  61.                   Edgewood, Maryland 21040
  62.                   (301) 679-4606
  63.                   Released for non-commercial distribution only
  64.         
  65.                 Converted  to  IBM/PC  CI/C86  by David N. Smith, 
  66.                 May/June 1983 with enhancements and  Lattice  compiler 
  67.                 support in  December 1983.
  68.         
  69.                   David N. Smith
  70.                   44 Ole Musket Lane
  71.                   Danbury, CT 06810
  72.                   (203) 748-5934
  73.                   CompuServe: 73145,153
  74.                 Changes Copyright (c) 1983 by David N. Smith
  75.                 Permission granted to copy for non-commercial purposes.
  76.         
  77.                   PC Enhancements include:
  78.                    1)  Nested #INCLUDE statements
  79.                    2)  Single spaced cross-reference list
  80.                    3)  Removal of tabbing on output device
  81.                        (Since many printers don't support it)
  82.                    4)  #INCLUDE statements with both "--" and <-->
  83.                        syntax and with a full fileid in the quotes.
  84.                        (Paths are not supported.)
  85.                    5)  Multiple input filenames on command line.
  86.         
  87.                The  current  PC  version only supports Lattice. 
  88.                Conversion to others should be relatively  easy  but  see
  89.                the compile time variable "Lattice" for compiler specific
  90.                sections.
  91.         
  92.                XCXREF - Version 1.0;   May, 1990
  93.         
  94.                   Martin D. Winnick
  95.                   5301 El Arbol Drive
  96.                   Carlsbad, CA  92008
  97.                   (619) 438-8154
  98.                   CompuServe: 71665,456
  99.                Changes Copyright (c) 1990 by Martin D. Winnick.
  100.                Permission granted to copy for non-commercial purposes.
  101. 
  102.  
  103.                  The following is a brief summary of the XCXREF changes:
  104.         
  105.                   Converted to IBM/PC Microsoft QuickC.  Program renamed 
  106.                   to 'XCXREF' due to extensive code and functional 
  107.                   changes.
  108.         
  109.                   The source code has been reformatted into a more read-
  110.                   able style, variable names have been changed to a 
  111.                   meaningful word rather than a coded acronym and the 
  112.                   program modified (I  hope)  to conform to the new ANSI 
  113.                   standards.  Additional comments have been added where I 
  114.                   felt they were needed.  Dead code has been removed, 
  115.                   including all conditional compilation code.
  116.         
  117.                  The number of referenced symbols raised to 5000 from 749.
  118.                  Although this is still a memory bounded program for the
  119.                  cross reference data.  I have tested it on an IBM PC/XT, 
  120.                  640KB, CGA, 30MB hard disk.  The largest cross reference 
  121.                  I have tried included 15+ programs consisting of 30,000 
  122.                  lines of code, producing 350+ output pages with 2000+ 
  123.                  referenced symbols.
  124.         
  125.                  The accompanying xc.exe is compiled as a 'compact' 
  126.                  model.  This or any other large data model is necessary
  127.                  to accomodate the increased number of symbol references.
  128.         
  129.               Command line Flags usage:
  130.               -e            = Write program data to log file
  131.                   Key program variable data will be written to a log 
  132.                   file, XCXREF.LOG, in the event of either a recoverable 
  133.                   error condition or abnormal error program exit.  Any 
  134.                   partial cross reference created to the  abnormal exit 
  135.                   is retained.  Upon a successful program completion the 
  136.                   ending values of these program variables will also be 
  137.                   written to the log file.
  138.         
  139.               -g            = Ignore missing files
  140.                   If this flag is not entered any file selected and not 
  141.                   found by the program will cause termination of the 
  142.                   process.  If it is entered the not-found condition will 
  143.                   be ignored, a message will be displayed, and processing 
  144.                   will continue with the next file.
  145.         
  146.               -i            = Enable #include processing
  147.                   If this flag is not entered all #include files will be 
  148.                   ignored, a message will be displayed, and processing 
  149.                   will continue.
  150.         
  151.               -l            = Generate listing only - no xref
  152.                   The program(s) will be listed to the output types 
  153.                   specified.  No cross reference will be created.
  154. 
  155.  
  156.               -o <outfile>  = Write output to named file
  157.                   All program output will be written to the named disk 
  158.                   file.  This may be in addition to other types of pro-
  159.                   gram output such as the printer and video screen.  Do 
  160.                   not enclose the file name in the '<>' brackets.
  161.         
  162.               -p            = Write output to line printer LPT1
  163.                   The -p command line flag will direct the program and 
  164.                   crossreference listing to the line printer, LPT1.  This 
  165.                   is in addition to any other directed output.  Printing 
  166.                   is accomplished by direct calls to the operating system 
  167.                   BIOS.  This has the (undesirable ?) side effect of 
  168.                   tying this version to PCs using MS/PC-DOS.
  169.         
  170.                   It is suggested that when using this option that you 
  171.                   set '-w 132' on the command line and set your printer 
  172.                   to condensed, 17.5 CPI, print mode.  The program in-
  173.                   serts two index numbers at the beginning of each print 
  174.                   line.  These and long coded lines may cause the print 
  175.                   lines to be 'folded' making the listing difficult to 
  176.                   read.
  177.         
  178.               -r            = Cross-reference 'C' reserved words
  179.                   'C' reserved words are normally ignored.  This option 
  180.                   will cause them to be treated as normal variables and 
  181.                   they will be included in the cross reference.
  182.         
  183.               -s            = Write output to video screen
  184.                   The -s command line flag will direct the program and 
  185.                   crossreference listing to the video screen.  This is in 
  186.                   addition to any other directed output.  Display is 
  187.                   accomplished by direct calls to the operating system 
  188.                   BIOS.  This has the (undesirable ?) side effect of 
  189.                   tying this version to PCs using MS/PC-DOS.
  190.         
  191.               -w width      = Width of output page; default = 78
  192.                                                     max     = 150
  193.                   This option defines the width of a 'page' output line.  
  194.                   This is used for all three output media.
  195.         
  196.               Command line Program name usage:
  197.                   The programs to be cross referenced may be entered on 
  198.                   the command line with the option flags or in an indi-
  199.                   rect reference list file or a combination of these two 
  200.                   methods.
  201.         
  202.                   If the first character of a file name on the command 
  203.                   line is an @ it is a reference to an ASCII file con-
  204.                   taining a list of file names.  The program when it 
  205.                   encounters this will then get the program names, and 
  206.                   any additional paths from that file.  On file EOF 
  207.                   XCXREF will return to the command line.
  208.         
  209.                   NOTE: The first character of any file name in a list 
  210.                         file CANNOT be an @.
  211. 
  212.         
  213.                   A sample @file is included with this package.
  214.         
  215.                   In addition, the indirect file may contain up to four 
  216.                   alternate path designations for use in locating pro-
  217.                   grams entered.  
  218.         
  219.                   Each is expected as '#qpathn <dr:\path\path\>', the 'n' 
  220.                   may be 1 - 4.  There must be a space before the '<' and 
  221.                   the actual path must be enclosed in the "<>" brackets.  
  222.                   These may be anywhere in the file.  They will become 
  223.                   effective when encountered.
  224.         
  225.                   Qpaths may only be entered via the indirect list file, 
  226.                   they cannot be entered on the command line.  Once 
  227.                   entered the path will be retained unless cleared or 
  228.                   reentered.  
  229.                   To clear an alternate path enter as #qpathn <>.
  230.         
  231.                   Program names are expected to be without any path 
  232.                   designation.  They are normally expected to be in the 
  233.                   default logged directory.  If a program is not found 
  234.                   there then the four alternate paths, if any, are tried 
  235.                   in sequence.  If the program is still not found it is 
  236.                   processed according to the -g option flag.
  237.         
  238.                   If a fully qualified program name is entered it will 
  239.                   override the the use of the default and alternate 
  240.                   paths.  If it is not found these other paths will NOT 
  241.                   be tried.
  242.         
  243.  
  244.  
  245.  
  246.