ColCom (COLlect COMments) 1.0 Readme
====================================

Copyright (c) 2003 dato Software

Author:
=======
  Jerinic Stasa: stasa.jerinic@dato.at

Idea:
=====
  Bernd Maierhofer: bernd.maierhofer@dato.at

Description:
============

ColCom (Collect Comments) is an application for extracting comments from files. It is a command-line tool and is meant to be used by programmers. ColComs main advantage is to transfers comments from the body source automatically to other destinations in code or to an external file.

You can use ColCom to copy comments from the body of source code to a history part at the beginning of the document, so a programmer just write comments at once.

Comments can be copied to defined locations in a file. Moreover one extern file will be applied (name of crawled file + .cvs), where the extracted comments will be saved, for quicker overview or for further processing. 

The comments to be processed by ColCom are either marked with {CVS* and can be multi line by ending the sign }, or they are marked with //CVS* or // CVS* and are only single-line. 

The comments are copied to the location defined by using the parameter INSERT. If the location doesnt exist, then only the comments in the external file are available.
The tag CVS* is by default removed, but it can be retained if parameter KeepCVS is set to + (in that case CVS* will be changed to CVS:).

  PARAMETERS:
  ===========

  Parameters that must be declared:
    /USER       : This switch supplies a user name, which will be written in comments.
    /FILE       : This switch sets the path and optionally the files witch ColCom should process.
                  Possible inputs: c:\projects\Order\fMain.pas or c:\projects\Order\*.txt or .\cOrder.*

  Other possible parameters:
    /INSERT     : If you start ColCom all defined comments will be copied to the place in the document,
		  which is marked with the tag of parameter "INSERT". INSERT is the tag which controls 
                  where the comments will copied to.
		  Also ColCom copies all comments into a external cvs- file.
		  If the tag "INSERT" is not defined in the document, only the external cvs- file will 
                  be created.
                  By default the value of the tag is CVSLOG, but can be overwritten by e.g. History:
    /RECURSIVE  : This switch turns on or off the recursive searching for files in subdirectories.
    /KEEPCVS    : By default the CVS* will be removed after copying.
		  If you set KEEPCVS to +, the comment line will be changed to "CVS: <USER> <DATE> <Comments>"
		  KEEPCVS is the switch and the + is the tag witch controls the function.
		  example: comment: 			     (// CVS* This is a test)
			   after starting ColCom by default: (// This is a test)
			   is KEEPCVS set to +:	 	     (// CVS: JES 2003.11.03 This is a test)
    /KEEPDATE   : This switch checks, whether the date shall remain unchanged in the evaluated comment.
                  If KEEPDATE is set to +, the opening comment will be changed to "<USER> <DATE> Comments", 
                  otherwise only the comments will remain.
    /REGISTER   : Register ColCom
    /?          : This switch gives an overview of all registered switches.
                  Immediately afterwards the application terminates.
    /RegOff     : This switch starts the readout from the registry in or out. Default value is '-'.
    /IniOff     : This switch starts the readout from the Ini file in or out. Default value is '-'.
    /CmdOff     : This switch starts the readout from the command line in or out. Default value is '-'.
    /RegPath    : This switch sets the path of the registry. 
                  Default is  Default value is '\Software\DATO\"Applicationname"\'.
    /IniPath    : This switch sets the path of the Ini file. Default value is "Application path".
    /IniFile    : This switch sets the names of the Ini file. Default value is '"Application name".ini'.
    /WriteIni   : This switch activates the writing of the registered switches into the Ini file.
                  Immediately afterwards the application terminates.
    /WriteReg   : This switch activates the writing of the registered switches into the registry.
                  Immediately afterwards the application terminates.
    /SHOWHIDDEN : This switch shows or hides the switches, which are registered with the special register method.
                  Default value is 'off'.


  Example:
  ========

    This is example of Borland Delphi Code.
    Following Code is the Code before running ColCom:

      { Description:
          This is the control unit for the order form.

        Author:
          JES Jerinic Stasa: stasa.jerinic@dato.at

        History:
          MAB 2003.09.19 added new functionality
          JES 2003.09.18 created                                 }
      unit cOrder;

      interface

      type
        TOrderFormController=class(TBaseController)
        private
          nCount: Integer; // Counts different users
        public
          // Create is method for ....
          constructor Create;
          // The method Load loads all chosen user values.
          procedure Load(const sUser: String);
          //CVS* The method Save saves the changes to database.
          //CVS* Not yet implemented.
          procedure Save;
        end;

      implementation

      constructor TOrderFormController.Create;
      begin
       nCount:= 0;
      end;

      procedure TOrderFormController.Load(const sUser: String);
      var
        sSQL: String;
      begin
        {CVS* Bug fixed in method Load:
              Query has to be cleared.
        }
        sSQL:= 'select * from tsyuser where username='+QuotedStr(sUser);
        fADOQuery.SQL.Add(sSQL);
        fADOQuery.Open;
      end;

      procedure TOrderFormController.Save;
      begin
        // TODO: insert into database
      end;

      end.


    After running ColCom on this Unit with following parameters 
    /User=JES /File=.\Order\cOrder.pas /Insert=History /KeepCVS=- /KeepDate=- 
    we get following result:

      { Description:
          This is control unit for order form.

        Author:
          JES Jerinic Stasa: stasa.jerinic@dato.at

        History:
          JES 2003.09.22 the method Save saves the changes to database.
                         Not yet implemented.
                         Bug fixed in method Load: Query has to be cleared.
          MAB 2003.09.19 added new functionality
          JES 2003.09.18 created                                 }
      unit cOrder;

      interface

      type
        TOrderFormController=class(TBaseController)
        private
          nCount: Integer; // Counts different users
        public
          // Create is method for ....
          constructor Create;
          // The method Load loads all chosen user values.
          procedure Load(const sUser: String);
          // The method Save saves the changes to database.
          // Not yet implemented.
          procedure Save;
        end;

      implementation

      constructor TOrderFormController.Create;
      begin
       nCount:= 0;
      end;

      procedure TOrderFormController.Load(const sUser: String);
      var
        sSQL: String;
      begin
        { Bug fixed in method Load:
              Query has to be cleared.
        }
        sSQL:= 'select * from tsyuser where username='+QuotedStr(sUser);
        fADOQuery.SQL.Add(sSQL);
        fADOQuery.Open;
      end;

      procedure TOrderFormController.Save;
      begin
        // TODO: insert into database
      end;

      end.


    Comment.cmd:
    ============

    This batch file can be used if you want to automate ColCom with your development environment. 
    For Borland Delphi these steps are necessary: Select Tools->Configure Tools->Add. 
    In the field Title write ColCom. Program Path+Comment.cmd. 
    Add two parameters in field Parameter $SAVE $EDNAME. 
    Good speed!
    

Examples of using ColCom:
===========================

ColCom /file=c:\projects\test\*.pas /user=JES /KeepDate=+ /KeepCVS=+
   This calling example allows searching of all files in c:\projects\test\ directory with file 
   ending pas. Searching in subfolders occurs too, because the parameter RECURSIVE is by 
   default set to true.
   The parameter USER must be inserted in the command line and put his value together with 
   extracted comments to insert location. By combination with parameters KEEPCVS or KEEPDATE, 
   the parameter value USER is also inserted in the evaluated comment.
   The parameter INSERT was not declared by this calling of ColCom and therefore the extracted 
   comments will be inserted on location CVSLOG (if existing) in the same file. Otherwise the 
   extracted comments will only exist in extern file.

   This calling example will produce from such comment line 
      //CVS* The method Save saves the changes to database.
   this result in the to evaluate line:
      //CVS: JES 2003.09.29 The method Save saves the changes to database.

ColCom /file=c:\projects\test\*.* /User=JES /KeepDate=- /KeepCVS=- /Insert=History: /Recursive=-
   This calling example scans all files in c:\projects\test\ directory. Scanning in 
   subdirectories doesnt occur, because the parameter RECURSIVE is set to false.
   The located comments will be inserted in the same file to location History:.
   In this example the parameters KEEPCVS and KEEPDATE switches the including of 
   "CVS: <USER> <DATE> to evaluated comments off.

   This calling example will produce from such comment line 
      //CVS* The method Save saves the changes to database.
   this result in the to evaluate line:
      // The method Save saves the changes to database.

ColCom /file=c:\projects\test\cOrder.pas /User=JES /KeepDate=+ /KeepCVS=- /Recursive=+
   This calling example scans only cOrder.pas file, as well in the c:\projects\test\ directory 
   as in their subdirectories (if any occurrence of this file is found).
   In this example are parameter KEEPDATE switched on and parameter KEEPCVS switched off, so 
   that the evaluated comment line will only include <USER> <DATE> and the comment.

   This calling example will produce from such comment line 
      //CVS* The method Save saves the changes to database.
   this result in the to evaluate line:
      //JES 2003.09.29 The method Save saves the changes to database.


Contact:
========

  For further ideas or if you have any problems with ColCom please write an e-mail to: stasa.jerinic@dato.at.
  Please visit our homepage: www.dato.at


  