home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / UTILITY / WCMT10.ZIP / WCMT.DOC < prev    next >
Text File  |  1994-03-06  |  6KB  |  143 lines

  1. WCMT v1.00 by Ron L. Smith    (Mar 06 1994)
  2.  
  3. WCMT (WWIV Comment) is a program for registered users of WWIV Software's
  4. bulletin board system software, WWIV.  It is used for v4.22+ to add comments
  5. to the C source files for the external string files, so when modifying the
  6. source code, you can easily tell what will be displayed at any given time.
  7.  
  8. Usage: WCMT [-B] [-C] [-Q] [-F] path file
  9.  
  10.        -B  Do NOT create backup files
  11.        -C  Use C style comments instead of C++
  12.        -Q  Surround string with single quotes
  13.        -F  Include string filename on comment line
  14.      path  Location of string files
  15.      file  Listfile created by make (files to process)
  16.  
  17. Typing WCMT without parameters (or WCMT -?) will give you the help screen
  18. shown above. 
  19.  
  20. -B Normally, WCMT makes a backup of each .C file processed with an extension
  21.    of .BAK (WCMT copies the file, it does not rename it).  If the -B option
  22.    is given, backup files will be created for processing, but will be
  23.    removed once comments have been successfully added to the .C file.  If
  24.    some error occurs during processing of the .C file, the .BAK file will
  25.    still exist even if the -B option is given.  You can then restore the
  26.    original in case the new file is damaged or wasn't fully processed.
  27.  
  28. -C By default, WCMT uses C++ style commenting, i.e., // comment.
  29.    The -C option forces the use of standard C style commenting, /* comment */.
  30.    HOWEVER, if an external string has either /* or */ in it, a C++ style
  31.    comment will be FORCED in that case.  Otherwise, you would get an error,
  32.    as normally, nested commenting is not allowed by compilers.  If your
  33.    C compiler does not recognize the // comment style, you can either change
  34.    the string to remove the /* */ item(s), or manually change the line to
  35.    whatever format you want after WCMT has processed it.  (I am aware at this
  36.    time of only 2 cases in v4.23 source code that has this, in CONF.C, and
  37.    I don't believe 4.22 source has any stock strings with /* or */ in them).
  38.  
  39. -Q This switch tells WCMT to add ' characters around the string in the
  40.    comment, so it would look like   'This is string #1.  '
  41.    If you want to be able to see whitespace characters in the strings,
  42.    then use this option.
  43.  
  44. -F The normal format WCMT uses to comment the string is to include the
  45.    string number only.  This options also causes WCMT to add the string
  46.    file name next to the string number.
  47.  
  48. path REQUIRED!!  This is the path to your .STR files.  It doesn't matter
  49.    whether you use a trailing backslash or not.  If one is not there,
  50.    WCMT will add one.
  51.  
  52. file REQUIRED!!  This is the temporary file created by make which should
  53.    contain a the names of all files to be processed (normally a name like
  54.    MAKE0005.$$$ or similar, has the .obj filenames in it).
  55.  
  56. NOTES:
  57.  
  58.  1) If WCMT determines it is inside a comment in the source code, it will
  59.     not process any string file directives in that part of the code.
  60.  
  61.     Example:   /*  this get_stringx(1,100); will not be processed */
  62.  
  63.  2) If CR and or LF characters are in an external string, or CR/LF combos,
  64.     WCMT will not show those in the comment with the .C file.
  65.  
  66.  3) You can keep running WCMT on files you have already processed, it will
  67.     not put duplicate entries in, and if strings have changed, it will
  68.     update the comment (obvious, right?  Otherwise, quite useless...).
  69.  
  70.  4) Using WCMT outside of the makefile is not usually very helpful except
  71.     for getting a syntax screen.  However, you can do it manually if you
  72.     create your own linkfile (older versions of Borland's Make did not
  73.     create a linkfile, you had to do it yourself).
  74.  
  75.  5) No source line will be processed for commenting if it starts with
  76.     non-whitespace characters on the left margin.  If normal C indention
  77.     is used, then that means function calls, prototypes, etc. will not
  78.     be processed (normal), but all others will.  If you have code on the
  79.     left margin of the file you want processed, put 1 or more spaces and/or
  80.     tabs before the text starts on each line.
  81.  
  82.  
  83. Configuration:
  84.  
  85.   You can create a WCMT.CFG file to add additional functions to process.
  86.   By default, WCMT will only process get_stringx(strfileno,stringno)
  87.   function calls, and only for those which are set in BBSUTL.C.  Here is
  88.   the default WCMT.CFG:
  89.  
  90. 0 get_string(
  91.  
  92.   The format of the file is the string file number, then 1 space, then
  93.   the function name, up to but not including the string number location.
  94.   For example, if I make a BBSMODS.STR file, set it up in BBSUTL.C as
  95.   string file #4, and then make a function called mod_string() that mimics
  96.   get_string() except it accesses string file #4 instead of #0, then my
  97.   cfg file would look like:
  98.  
  99. 0 get_string(
  100. 4 mod_string(
  101.  
  102.   If you had more than one mod_string file, and the function call was
  103.   mod_stringx(fileno, stringno)
  104.   then my cfg file would look like:
  105.  
  106. 0 get_string(
  107. 4 mod_stringx(4,
  108. 5 mod_stringx(5,
  109. 6 mod_stringx(6,
  110.  
  111.   A configuration file is NOT necessary, but if it does not exist, none of
  112.   the get_string() function calls will be commented (i.e., only the
  113.   get_stringx() functions will be recognized.  In a CFG file is not found,
  114.   WCMT gives a warning, but you may ignore it.  It is just informative in
  115.   case you forgot to make one.
  116.  
  117.  
  118. Setup:
  119.  
  120.   To set up WCMT to run, modify your MAKEFILE.MAK.  Add these lines at the
  121.   end of your makefile:
  122.  
  123. wcmt: .\wcmt.exe
  124.   wcmt.exe -C -B c:\wwiv\gfiles &&^
  125. $(BBS_NRM) $(BBS_OVL)
  126. ^
  127.  
  128.  
  129.   Of course, substitute whatever command line switches you want to use for
  130.   the ones above.  No switches are required if not needed, i.e., only the
  131.   path to the string files and the make linkfile are required.
  132.  
  133.   After that, executing MAKE CMNT will comment your .C files.
  134.  
  135.   
  136. The Author:
  137.  
  138.    Ron L. Smith      Contact:  Hunter #11@5508.WWIVNET
  139.                                Spycom BBS, Alb., NM
  140.                                (505)-891-1455
  141.  
  142.   Address any comments, complaints, etc. to the above net address.
  143.