Index of /tcl/ftparchive/sorted/apps/artts-1.0

      Name                   Last modified     Size  Description


[DIR] Parent Directory       29-Jan-99 12:23      -  
[   ] README                 01-Mar-95 03:33    11k  

README file for artts (anal retentive time tracking software)

This file documents artts version 1.0 and arpt 1.0.

Please send comments, suggestions, bug-reports, etc. to

	pcoad@crl.com

Any feedback is welcome.

Legal Stuff:

Copyright 1994, 1995, Paul E Coad
The author disclaims all warranties with regard to this software, including
all implied warranties of merchantability and fitness.  In no event
shall the author be liable for any special, indirect or consequential
damages or any damages whatsoever resulting from loss of use, data or
profits, whether in an action of contract, negligence or other
tortuous action, arising out of or in connection with the use or
performance of this software.

This package is being released under the terms of Larry Wall's
"Artistic license".  A copy of the license is in this distribution 
in a file with the name Artistic.

Files:

README		this file
artts		the time tracker
arpt		the time reporter
Artistic	Larry Wall's "Artistic license"
arttsrc		sample configuration file
arttsdb		sample database file

General:

Are you anal retentive?  Is your boss?  Do you wonder how your time is being
spent?  artts might be the answer to your problems.  artts helps to track
the amount of time spent on various tasks.  artts is useful for tracking
billable hours, actual project time, etc.  A simple command line report 
generator is included.

Requirements:
artts requires tcl 7.3 and tk 3.6 or tcl 7.4 and tk 4.0.  arpt requires tcl 
7.3 or tcl 7.4.  Both artts and arpt run correctly under both sets of 
versions.  The date(1) command is also required.  artts and arpt have been 
tested on: 
	SVR3.2 (ISC 3.0) 
	SVR4.2 (UnixWare 1.1) 
	linux 1.1.88 
	BSD 4.3? (SunOS 4.1.3_U1)  
They should work on any real operating system that has a working 
(unix-compatible) date(1) command.

WARNING:

(1)
I am releasing this software in the hope that INDIVIDUALS will find it useful.
If you can use it to track the hours you work on contracts, I will be 
happy.  I do not want artts to be forced upon anyone.  If you think that 
your boss might force you or someone else to use it, SAVE YOURSELF, and
delete all of the associated files. 

(2)
artts uses the unix date(1) command for obtaining the current date(1) and
time.  The date(1) command is run at semi-regular intervals.  The amount of 
time between executions of the date(1) command depends on the settings in your 
.arttsrc file.  Running the date(1) command puts some load on your system.  If 
date(1) is putting too much load on your system, try decreasing the frequency 
at which the command is run.  See artts(update_rate) in The .arttsrc File 
section below.

Installation:

Make sure the first line of the artts and arpt files contains a correct path.
Copy the artts and arpt files into a directory in your path.  
Copy the file arttsrc into your home directory and rename it .arttsrc  
Copy the file arttsdb into your home directory and rename it .arttsdb  

Use:

The goal of artts is to help track time.  artts tracks the amount of time 
spent on various tasks.  Switching tasks is done by selecting an option
from a menu.  Simple reports can be generated via the command line using
the arpt program.  One of the design goals for artts was to minimize the
amount of screen real estate needed.  On small screens the artts window may 
still take up too much room.  Specifying a smaller font for the artts(fixed)
and artts(prop) values will result in a smaller window.

Skip the following description for a while.  Try out artts.  The only 
tricky parts are: until a task is switched no output is written to the
.arttsdb file, the "+" button shows an additional row of buttons, and arpt
needs a minimum of one flag, try arpt -s -d.

Window Description:

The artts window consists of three areas: display of the current task time,
display of the current task, and a button area.

	XX:XX:XX
The top area in the artts window is a display of the current amount time of
time on the current task.  The display is in hours, minutes and seconds.
The rate at which the time is updated is determined by the artts(update_time)
option in the .arttsrc file.  See below for an explanation of the .arttsrc
file.  artts is initially set up to get the current time every 10 seconds.

	ABCDEFG
The middle area in the artts window is a display of the current task.

	Buttons
The bottom of the artts window consists of two rows of buttons.  When artts
is first started, a single row of buttons is displayed.  The buttons are:
Tasks, Stop, New, and +.  An additional row of buttons is displayed when 
the + button is selected.  The second row of buttons consists of: Delete,
Report, Quit, and -.

	Tasks
The Tasks button is a menu button which when selected, displays a list of
the currently available tasks.  Selecting one of the tasks causes the selected
task to become the current task.  The new task is displayed in the Task: area
in the middle of the artts window and the Current: task time to be reset to
00:00:00.  The old task is recorded along with its elapsed, start and stop
times.

	Stop
Selecting the Stop button sets the current task to NONE, stops the 
accumulation of time on the current task and the old task to be recorded
along with its elapsed, start and stop times.

	New
Selecting the New button will open the New Task window. The New Task window
can be used for adding a new task to those that appear in the Tasks button
menu.  Once a new task has been added, it will be available for selection on
the Tasks button menu even if artts is quit and restarted.

	+
Selecting the + button causes the Artts window to expand to display an 
additional row of buttons.  These buttons include Delete, Report, Quit, and -.

	Delete
Selecting the Delete button causes a menu of the currently available tasks
to be displayed.  Selecting one of the tasks will remove the task from the
Delete button menu and from the Tasks button menu.  Once a task is deleted
it is no longer available for selection, even if artts is quit and restarted.
(If a task is accidentally deleted, it can be added to the available list of
tasks by selecting the New button and adding the task as a new task.)

	Report
Selecting the Report button causes the Artts report window to be displayed.
The Artts Report window displays a graph consisting of bars which represent
the relative amounts of time spent on each task today.  Above each bar
is the name of a task, the elapsed time for the task in hours, minutes,
and seconds, and the percent of time spend on the task.  The graph is updated
at the same rate as the current task time.

	Quit
Selecting the Quit button quits artts.  If a task is currently accumulating
time, it will be recorded with the elapsed, start, and stop times.

	-
Selecting the - button causes the artts window to shrink and hide the second
row of buttons.  The second row of buttons can be displayed again by selecting
the + button.

This all sounds much harder than it really is.  Try it.  It's simple.

Report Generator: arpt

arpt can be used to generate simple reports.  arpt can take any of the
following command line options: -h, -l, -d, -s, and -t.
-h	displays a short usage message.
-l	displays a long usage message.
-d	displays a report of daily totals (each task is totaled for each day.)
-s	displays a report of all totals (all tasks are totaled over the span 
	  of days in the .arttsdb file.
-t	displays a report of time spent on tasks today.

The options can be specified in any order, but cannot be smashed together. This
means that -s -b is not the same as -sb.

The .arttsrc File

The .arttsrc file is the obligatory .rc file which holds configuration and
customization information for artts and arpt.

artts(update_rate)	This option can be used to specify the rate at which
			the date command is run.  The value specified indicates
			the number of mili-seconds between runs of the date
			command.  (10000 = 10 seconds)  Setting the value to 
			larger values effects the amount of time between
			refreshes of the current task time display area and 
			the report window.  Switching tasks causes the date 
			command to be run to determine the time spend on the 
			current task.

artts(tasks)		This option can be used to specify the tasks which
			should be available for selection in the Tasks and
			Delete button menus.  artts appends a new option to
			the .arttsrc file when it exits if one or more tasks
			are added or deleted during its run.

artts(start_task)	This option can be used to specify the task which
			begins accumulating time when artts is started.  If
			no task is specified or "NONE" is specified, NONE
			will be displayed and no task will accumulate time
			until a task is selected.

artts(x_pos)		The initial x position of the artts window measured
			in pixels from the upper left corner of the screen.

artts(y_pos)		The initial y position of the artts window measured
			in pixels from the upper left corner of the screen.

artts(rpt_x)		The x position of the artts report window measured
			in pixels from the upper left corner of the screen.

artts(rpt_y)		The y position of the artts report window measured
			in pixels from the upper left corner of the screen.

artts(fixed)		This option sets the font to be used for the current
			task time display.  The format matches the standard
			X font specification.

artts(prop)		This option sets the font to be used for all text
			other than the current task time display.  The format
			matches the standard X font specification.

arpt(separator)		This option can be used to specify a string to separate
			days when daily reports are generated by arpt.

arpt(tot_line)		This option can be used to specify a string to separate
			the task listings from the total lines in all reports.

arpt(exclude)		This option can be used to specify a list of tasks 
			which should not contribute to the total time in all 
			reports.  

The .arttsdb File
The .arttsdb file is used to record information about tasks.  The information
includes: task name, elapsed time, start date/time, and stop date/time.  Each
entry in the .arttsdb file has the format:

yy mm dd hh mm ss yy mm dd hh mm ss secs task_name

The first yy mm dd hh mm ss is the start date/time, the second is the stop
date/time, secs is the elapsed time, and task name is the name of the task.

It is suggested that the .arttsdb file be renamed once a week.  This will have
the benefit that running arpt with the -s option will display the accumulated
time on tasks for the current week.

THANKS

Jay Brownfield for being the first real user of artts.  Erik Sincoff for 
doing the Spanish Inquisition thing and stress testing. The Teknowledge 
Corporation bigwigs for not invoking the "intellectual property" clause on 
this freeware package.  (Great guys even if they do wear ties.) Tess for her 
infinite patience.