home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 17 / CD_ASCQ_17_101194.iso / vrac / timclk10.zip / TIMECLK.TXT < prev   
Text File  |  1994-09-04  |  13KB  |  266 lines
  1.                               TIMECLOCK 1.0
  2.                       Copyright 1994 Kenneth A. Reek
  3.                            All rights reserved.
  4.                          Internet: kar@cs.rit.edu
  5.  
  6.                  SHAREWARE VERSION
  7.  
  8. WHAT IS TIMECLOCK?
  9. ------------------
  10. TIMECLOCK is a Windows program that keeps track of time you've spent on your
  11. computer.  Time is charged to one or more "projects" from your list by
  12. "punching in" when you begin work on each project.  In addition, projects
  13. may be grouped into different "categories" (e.g. business and pleasure) that
  14. you specify.  To give one example, this will greatly simplify your compu-
  15. tation of the percentage of time your computer was used for business
  16. purposes, and thus the percentage of its value that you can depreciate or
  17. deduct as a business expense on your taxes.
  18.  
  19. REGISTERING TIMECLOCK
  20. ---------------------
  21. TIMECLOCK is copyrighted software.  It is not in the public domain, nor is
  22. it distributed for free.  The author retains all rights to this software.
  23.  
  24. TIMECLOCK is distributed as Shareware so you can try it out without risk
  25. to see if you like it.  Use it for two weeks.  If you don't like it,
  26. simply delete it and owe nothing.  If you continue to use TIMECLOCK after
  27. the two week trial period, you must register your copy.  For your conven-
  28. ience, the file REGISTER.TXT is included: it contains a registration form
  29. that you may use.  The fee for individuals wishing to register a single
  30. copy of TIMECLOCK is US$15.  The fee schedule for corporate users is shown
  31. in the REGISTER.TXT file.  Send the form with your payment to the author:
  32.  
  33.     Kenneth A. Reek
  34.     3090 Griffin Rd
  35.     Churchville, NY USA 14428-9512
  36.  
  37.  
  38. ADVANTAGES OF REGISTERING TIMECLOCK
  39. -----------------------------------
  40. The registered version of TIMECLOCK comes with a Windows-based report
  41. generator with options for more selective reporting than that provided in
  42. the shareware version.  A printed manual, which contains more detail than
  43. the shareware documentation, is also available.  Registered users will
  44. also receive the next upgrade to the program free of charge, and may call
  45. or write for information on the latest revision, to report bugs, or to
  46. make suggestions or other comments on TIMECLOCK.  I am particularly
  47. interested in your ideas for making TIMECLOCK a more useful program.  And,
  48. last but not least, you don't have to deal with the registration reminder
  49. screens any more!
  50.  
  51. DISCLAIMER
  52. ----------
  53. TIMECLOCK is supplied as is.  The author disclaims any and all warranties,
  54. expressed or implied, including but not limited to warranties of merchant-
  55. ability and of fitness for any purpose.  The author assumes no liabilities
  56. for any damages, direct or consequential, which may result from the use
  57. of TIMECLOCK.
  58.  
  59. INSTALLING TIMECLOCK
  60. --------------------
  61. Installation is easy.  First, you must unpack the archive file containing
  62. the distribution (if you're reading this, you have done that already).  You
  63. should have the following files:
  64.  
  65.     timeclk.exe        TIMECLOCK program (Windows)
  66.     report.exe        report generator (MS-DOS)
  67.     timeclk.ini        sample initialization file
  68.     project.txt        sample project file
  69.     timeclk.txt        the file you are reading now
  70.     register.txt        registration form
  71.     timeclk.log        sample log file to illustrate report pgm.
  72.  
  73. Copy all these files to any directory you wish; it is most convenient if
  74. they all reside in the same directory.  To see how it runs, open the File
  75. Manager and display the directory containing TIMECLOCK.  Now double-click
  76. the mouse pointer on "timeclk.exe".  The display that you see is based on
  77. the information in the sample project file; you will be modifying this
  78. file to suit your own needs.  Select one of the projects shown by clicking
  79. on it with the left mouse button; this "punches you in" on that project.
  80. Select another one; TIMECLOCK "punches you out" (nasty phrase!) of the old
  81. project before punching you into the new one.  Now click the right mouse
  82. button anywhere on the screen: this punches you out of the current project
  83. without punching you into a new one.
  84.  
  85. To see what the report generator produces, open a DOS window and change to
  86. the directory that you copied Timeclock into.  Then run the report program
  87. like this:
  88.  
  89.     c:\timeclk: report > report.txt
  90.  
  91. If you are punched into a project when you generate the report, you will
  92. see an error message telling you that the log file has a check-in entry
  93. with no corresponding check-out entry; you may ignore this error for now.
  94. Now you can examine the file that was produced using Notepad or any other
  95. editor.  The report format is described in more detail later.  NOTE:  Be
  96. sure to delete the "timeclk.log" file that came with the distribution
  97. before starting to use Timeclock to record your actual usage.  This sample
  98. log file was distributed only to demonstrate the output of the report
  99. generator.
  100.  
  101. Should you decide to register TIMECLOCK, you may wish to add it to the
  102. StartUp group in the Program Manager.  Here is how that is done:
  103.  
  104.     1) Open the StartUp group.
  105.     2) Select File|New from the Program Manager.
  106.     3) Verify that the box which appears says "New Program Item", and
  107.        click OK.
  108.     4) Enter the following values:
  109.         Description:    TimeClock
  110.         Command Line:    timeclk.exe
  111.         Working Directory: (the directory where you put TIMECLOCK)
  112.     5) Click the OK button.
  113.  
  114. Now TIMECLOCK will start automatically every time Windows is started.
  115.  
  116. HOW TO USE TIMECLOCK
  117. --------------------
  118. TIMECLOCK consists of two programs (timeclk.exe and report.exe), an optional
  119. initialization file (timeclk.ini), and your project description file
  120. (project.txt).  timeclk.exe creates a file (timeclk.log) containing an entry
  121. for each time you punch in or punch out of a project.  report.exe reads this
  122. log file and produces a report summarizing usage by project and by category.
  123.  
  124. The following sections describe these processes in more detail.
  125.  
  126. THE INITIALIZATION FILE: timeclk.ini
  127. ------------------------------------
  128. The initialization file contains information that affects the way in which
  129. TIMECLOCK runs.  The sample initialization file contains comments which
  130. describe each of the available entries.  Lines beginning with # are
  131. comments; some sample entries are shown as comments -- to enable them,
  132. remove the leading "# " from the line.
  133.  
  134. THE PROJECT FILE: project.txt
  135. -----------------------------
  136. The project file contains entries that identify each of the projects you
  137. wish to track, and the categories to which they belong.  The sample
  138. project file contains comments which describe the formats of these
  139. entries.  It also contains the sample entries which you saw when you first
  140. ran timeclock.
  141.  
  142. SELECTING COLORS
  143. ----------------
  144. The initialization file and the project file both allow you to select the
  145. colors that will be used on the timeclock screen.  This is done by giving
  146. intensities for red, green and blue as a three-value list, like this:
  147.  
  148.     0,255,0
  149.  
  150. Each value is a number in the range 0 - 255.  While it is possible to
  151. specify 16,777,216 different colors in this way, many Windows displays can
  152. show only 16.  Here are the different colors you can specify:
  153.  
  154. 255,255,255    White            128,128,128    Dark gray
  155. 192,192,192    Light gray        0,0,0        Black
  156. 255,0,0        Light red        128,0,0        Dark red
  157. 0,255,0        Light green        0,128,0        Dark green
  158. 0,0,255        Light blue        0,0,128        Dark blue
  159. 255,255,0    Light yellow        128,128,0    Dark yellow
  160. 255,0,255    Light magenta        128,0,128    Dark magenta
  161. 0,255,255    Light cyan        0,128,128    Dark cyan
  162.  
  163. PUNCHING IN AND OUT
  164. -------------------
  165. The timeclock displays your projects in lists, with one list for each
  166. category you have used.  To "punch in" to a project, simply point at the
  167. name of the project with the mouse and click the left mouse button.  The
  168. project name is shown in the title bar, the current entry is highlighted,
  169. and the elapsed time is shown for your convenience **.  
  170.  
  171. ** If you watch the elapsed time display for a while, you might see it skip
  172. a second every now and then.  This is nothing to worry about, as the log
  173. file entries record the start time and end time for each project rather than
  174. a count of the seconds used.  The anomaly in the display is caused by small
  175. differences between the system's clock and Windows' program scheduling
  176. mechanism.
  177.  
  178. To punch in to a different project, simply point to it and click the left
  179. mouse button.  The former project is automatically punched out, and the new
  180. project is punched in.  To punch out of a project without punching in to
  181. another one, click the right mouse button anywhere on the screen.
  182.  
  183. If a project is punched in when the timeclock program is terminated, it will
  184. automatically be punched out.  The same is true when Windows exits.  If the
  185. system crashes, though, the log file may be left with a "punch in" entry
  186. which has no corresponding "punch out" entry.  This problem can be fixed by
  187. editing the log file as described below.
  188.  
  189. THE TIMECLOCK LOG FILE: timeclk.log
  190. -----------------------------------
  191. The format of the log file is simple:
  192.  
  193.     Date Time      In/Out      Project-Category
  194.  
  195. The date is shown in yyyy/mm/dd format (to avoid any problems that two digit
  196. years might cause as we reach the year 2000), and the time is shown in
  197. hh:mm:ss format.  This is followed by a tab, and either the word "IN" or the
  198. word "OUT" to specify punching in or out.  This is followed by a tab, and
  199. the name and category of the project.  A sample entry is shown below:
  200.  
  201. 1994/02/25 13:12:57    IN    Retirement mgr-Business
  202.  
  203. Normally, you need never look at this raw data, as the reporting program
  204. produces summaries by project and by category.  The file is created as an
  205. ordinary text file for two reasons, however.  First, if you need an unusual
  206. report, a text file can be read by other programs or easily imported into
  207. a spreadsheet.  Second, if the file is corrupted (for example by a system
  208. crash), it can be edited with any text editor (such as Notepad; do NOT use
  209. a word processor such as Write or Word) to repair the damage.
  210.  
  211. THE REPORTING PROGRAM: report.exe
  212. ---------------------------------
  213. The reporting program in the shareware version is an MS-DOS program.  The
  214. registered version comes with a Windows reporting program that provides
  215. many options to tailor the report, such as user-specified date ranges,
  216. the ability to report on a single project or a single category, and so
  217. forth.  However, the shareware reporting program produces the same type of
  218. output as the registered version so that you can evaluate its usefulness.
  219.  
  220. The reporting program reads the initialization file to learn the name of the
  221. log file; it then reads the log file and prints an error message describing
  222. each error found in the log file.  It then prints a report to the standard
  223. output, which you will probably want to redirect to a file for later
  224. printing.  Here is an example of how it is run from the MS-DOS prompt:
  225.  
  226.     c:\timeclk> report > report.txt
  227.  
  228. Note that you must be in the TIMECLOCK directory when you run the report
  229. program.
  230.  
  231. The report contains two sections.  The first is a summary of usage by
  232. project.  A list is printed for each category showing the projects in that
  233. category.  The following values are shown:
  234.  
  235.     hours spent on the project,
  236.     the percentage of the total use that this project represents,
  237.     the percentage of the use in this category that this project represents,
  238.     the number of sessions for the project,
  239.     the average duration of each session, and
  240.     the project name.
  241.  
  242. At the end of each category's list is a line showing the totals for that
  243. category.
  244.  
  245. The second section is a summary of usage by category.  For each category,
  246. the following values are shown:
  247.  
  248.     hours spent on projects in the category,
  249.     the percentage of the total use that this category represents,
  250.     the number of sessions for the category,
  251.     the average duration of each session, and
  252.     the category name.
  253.  
  254. The report generator does not read the project file (project.txt), so
  255. there is no problem if the log file contains entries for old projects
  256. which no longer exist in the project file.
  257.     
  258.  
  259. Thank you for trying out TIMECLOCK, and I hope you find it to be useful.
  260. Remember to register the program if you decide to use it past the trial
  261. period!  Show your support of the shareware concept by registering the
  262. programs that you use -- this is the best way to ensure the continued
  263. development of new shareware software.
  264.  
  265.     K. Reek, 6/12/94
  266.