TR(1) TR(1)
NAME
tr - time registration program.
SYNOPSIS
tr [-hd] [ date-specification | [start | stop] ]
DESCRIPTION
tr is a program to registrate the time spent on various
projects. The program can work in one of two modes: sin-
gle-entry mode and full-screen mode. In the full-screen
mode you can select a date to work with, add, edit,
(un)delete an entry or start or stop the timing of an
entry. In the single-entry mode, you can only add an entry
for the specified date, or start or stop an entry for
`today'.
For each day, a separate datafile is created. These
datafiles can be used to generate a quarterly report with
the batch program myreport. To obtain the number of days
spent on a certain project, you can use the batch program
prjtime.
This section is divided into the following subsections:
Initialization, Single-entry mode, Full-screen mode, Full-
screen mode commands, Full-screen mode cursor movements,
Date specification, Time specification, Project, group and
category selection, Entering date, time and description,
Example profile, Example datafile, Syntax of profile, Syn-
tax of datafile, Options and Program exit status.
Initialization
When tr is started, it first determines the user's datadi-
rectory and checks if it exists (see also section ENVIRON-
MENT). If it does not exist, tr asks if it should create
the datadirectory. If the user profile does not exist, tr
creates an empty one.
Then tr reads the system-wide profile and the profile in
the user's datadirectory. The contents of these profiles
specify the number of working hours for each day, what
kind of working groups and project categories there are
and what projects there are to choose from and defaults
for these values (see also section Syntax of profile).
Single-entry mode
If a date or start or stop is specified on the command-
line, the program runs in single-entry mode. In this mode
you can only stop a running entry or start a new entry for
`today' or add a new entry for the specified date.
14 Mar 1995Elektronische Afdeling, Huygens Laboratorium 1
TR(1) TR(1)
A typical single-entry session looks as follows.
C:\>tr .
Fri 17 Feb 1995 2:00/8:00 (6:00) m:\-tr\19950307.dat [TR v1.0]
Time: 9:30-10:15
Project: [pcad-guide] P-cad User and Library Guides
Description: P-cad User and Library Guides, groundplane
C:\>
The headerline shows the date for the entry you are adding
(Fri 17 Feb 1995), the time already registrated (2:00),
the time to registrate for this day of the week (8:00),
the time still to registrate (6:00), the name of the
datafile (m:\-tr\19950307.dat) and the version of the
timeregistration program ([TR v1.0]).
See subsections `Date specification', `Time specifica-
tion', `Project, group and category selection' and `Enter-
ing date, time and description' to learn how to fill-in
your information.
Full-screen mode
When no date and no start or stop is specified on the com-
mandline, the program runs in full-screen mode. The screen
looks as follows (without the numeric border lines).
10 20 30 40 50 60 70
12345678901234567890123456789012345678901234567890123456789012345678901234567890
1 Fri 17 Feb 1995 3:15/8:00 (4:45) m:\-tr\19950217.dat [TR v1.0]
2
3-> D 1 0:15 BF RS-ASS support ...
4
5
6
7
8
9
10
11
12 R 10 1:30 EA PRJ-ML omschrijving
13
14 pre(v)ious, n)ext, da(t)e, s(y)nchronize
15 a)dd, d)elete, u)ndelete, e)dit, s)tart, sto(p),
16 h)elp, q)uit, e(x)it
17
18 Command: Add
19 Time: 9:30-10:15
20 Group: [NVT] niet van toepassing
21 Category: [ADM] Administratie
22Description: tijdschrijven_
23
14 Mar 1995Elektronische Afdeling, Huygens Laboratorium 2
TR(1) TR(1)
24 Message: ...
25 Help: ...
12345678901234567890123456789012345678901234567890123456789012345678901234567890
10 20 30 40 50 60 70
The screen is divided into five regions.
1. Title title line with date, time, file and pro-
gram version information,
2. Data datawindow with up to 10 data-entries,
3. Menu three line menu region,
4. Input command and data-entry region, and
5. Message message and help region.
The title line is the same as described for the single-
entry mode (see there).
Each record in the datawindow has the following fields.
Cursor the active record contains the -> cursor,
for the other records this field is empty,
Status the status of a record can be D, R or none
of these; this means delete entry when sav-
ing data to file (D), this is a running
entry (R), or this is a `normal' entry.
Number the sequence number of this record,
Elapsed time the elapsed time registrated for this
entry,
Group the group this entry is for,
Category the category of the entry,
Description a description of the project, work.
In the inputwindow you enter the commands and enter and
edit data of the records. Time and description are typed
in, project or group and category are selected from a list
of possibilities. See `Time specification', `Entering
date, time and description' and `Project, group and cate-
gory selection'.
When some error arises or the helpsystem is used, error
messages and help messages are displayed in the Message
and Help fields.
14 Mar 1995Elektronische Afdeling, Huygens Laboratorium 3
TR(1) TR(1)
Full-screen mode commands
In full-screen mode, tr works with one-letter commands.
Most of these commands are listed in the three menulines
on the screen; beside the listed commands there are
`quick' versions for the synchronize, quit and exit com-
mand, that do not ask you to confirm the action.
v, - select day preceding the day currently selected
n, + select day following the day currently selected
t ask for new date specification and select that date
y ask for confirmation and save database to file
Y save database to file without asking for confirmation
(quick synchronize)
a add a new entry
d mark an entry for deletion
u remove tag for deletion
e edit an entry
s start a new entry in the running state
p stop the running entry
h start online help mode
q ask for confirmation to save database and exit
Q save database and exit (quick quit)
x ask for confirmation to exit without saving database
and exit
X exit program without saving database (quick exit)
number
select the entry with the specified number
Full-screen mode cursor movements
In full-screen mode, you can select an entry with the fol-
lowing keys.
Arrow-up previous entry
Arrow-down next entry
14 Mar 1995Elektronische Afdeling, Huygens Laboratorium 4
TR(1) TR(1)
Arrow-left, PgUp first entry of previous page
Arrow-right, PgDn, Space first entry of next page
Home first entry
End last entry
Date specification
A date specified on the commandline or with the date-
command, can have various forms. These are best illus-
trated with some examples.
. alias for today
tomorrow tomorrow
yesterday yesterday
wednesday last wednesday, also last wednesday
next tuesday next tuesday
1-2 first of February, this year; year may be
specified as 95 or 1995
+3 three days from currently selected day
(today for single-entry mode)
.-3 three days back from today
The specification of a date is case-insensitive. It is
sufficient to use the least number of characters that make
the specification unambiguous.
Time specification
When adding, starting, stopping or editing an entry, you
have the opportunity to enter a time specification. The
time can be specified in several ways. This is best shown
with some examples.
1h duration of one hour
1:23 duration of one hour and 23 minutes
1h23m duration of one hour and 23 minutes
13:23-14:45 time between 23 minutes past one p.m. and
15 minutes to three p.m. (one hour and 22
minutes)
14 Mar 1995Elektronische Afdeling, Huygens Laboratorium 5
TR(1) TR(1)
Project, group and category selection
When you select a project, group or category entry, one
item is presented at a time. To move through the project,
group and category items you can use the following keys.
Home, 'd' select default item,
Arrow-down, space select next item,
Arrow-up, 'b' select previous item,
Arrow-left, PgUp select first item,
Arrow-right, PgDn select last item,
Esc select default item and leave this
selection,
^C interrupt execution of current com-
mand.
To select an item, press the Return-key.
Entering date, time and description
When you enter a date, time or description, the following
editing keys are available.
Insert switch between override mode and insert
mode,
Delete delete character under cursor,
Home goto start of line,
End goto end of line,
Arrow-right move cursor one character right,
Arrow-left move cursor one character left.
^C interrupt execution of current command.
NOTE: don't use doubles quotes (") in a description,
unless preceded directly by a backslash (\).
Example profile
A typical system profile looks as follows.
#
# bin/tr.pro - system wide profile for time registration program tr.exe.
#
14 Mar 1995Elektronische Afdeling, Huygens Laboratorium 6
TR(1) TR(1)
day sun = 0h
day mon = 8h
day tue = 8h
day wed = 8h
day thu = 8h
day fri = 8h
day sat = 0h
group AD = "Algemene Dienst"
group BF = "Biofysica"
group EA = "Elektronische Afdeling"
group MN = "Moleculaire Natuurkunde"
group MAT = "Moleculen in de Aangeslagen Toestand"
group MFQO = "Molecuul Fysica Quantum Optica"
group NVT = "niet van toepassing"
category PRJ-GR = "Projekt groot"
category PRJ-ML = "Projekt middel"
category PRJ-OW = "Projekt onderwijs"
category PRJ-3N = "Projekt derden"
category RS-ASS = "Research assistentie"
category BESTEL = "Bestelling voorbereiden"
category STUDIE = "Studie"
category CURSUS = "Cursus"
category WRKOVL = "Intern werkoverleg"
category WRKPL = "Werkplaats"
category ADM = "Administratie"
category BHV = "BHV"
category VERLOF = "Verlof"
category FEEST = "Feestdagen"
category ZIEK = "Ziektedagen"
#
# End of file
#
An example of a user profile looks as follows.
#
# m:\-tr\tr.pro - user profile
#
project pcad-manual = EA PRJ-GR "P-cad Manual"
project RB-Lockin = BF PRJ-GR "Rulbus Lockin"
defaultGroup = EA
14 Mar 1995Elektronische Afdeling, Huygens Laboratorium 7
TR(1) TR(1)
defaultCategory = RS-ASS
defaultProject = pcad-manual
#
# End of file
#
NOTE: when you specify a project description, specify the
first part of it in such a way that it can be used with
command prjtime to uniquely refer to that project.
Example datafile
The name of each datafile has the form yyyymmdd.dat, where
yyyy is the number of the year, mm is the number of the
month and dd is the number of the day of the month. The
contents of the datafile consists of empty lines, comment-
lines and records of the form: time group category
description.
#
# date: Tue 07 Mar 1995
# modified: Wed Mar 08 08:36:17 1995
#
7:30-8:00 BF ADM "ELA lijst, nieuwe projekten"
8:00-8:40 BF PRJ-GR "Rulbus Lockin, controle GAL RB9405"
8:40-13:30 EA PRJ-ML "Urenverantwoording automatisering (TR)"
13:26-13:45 BF RS-ASS "CCOD issue 07 is er niet (Marjan); gehaald"
13:44-14:20 NVT STUDIE "Review of Scientific Instruments Vol. 64"
14:20-16:45 EA PRJ-ML "Urenverantwoording automatisering (TR), manual page"
16:45-17:00 MN RS-ASS "C programmeer advies, datastructuur"
#
# End of file
#
Syntax of profile
The syntax of the profiles is shown below. Note that both
English and Dutch are covered in the definitions. The def-
initions of the profiles are case-insensitive. Whitespace,
except newline, is ignored.
line ::= empty
| definition? comment
| definition $
empty ::= ^$
comment ::= # [printable]* $
14 Mar 1995Elektronische Afdeling, Huygens Laboratorium 8
TR(1) TR(1)
definition ::= daydef
| projectdef
| groupdef
| categorydef
| defprojectdef
| defgroupdef
| defcategorydef
daydef ::= day dayname '=' time
projectdef ::= project prj-identifier '='
grp-identifier cat-
identifier description
groupdef ::= group grp-identifier '='
description
catdef ::= category cat-identifier '='
description
defprojectdef ::= defaultproject '=' prj-
identifier
defgroupdef ::= defaultgroup '=' grp-identifier
defcategorydef ::= defaultcategory '=' cat-
identifier
day ::= 'day'
| 'dag'
project ::= 'project'
| 'projekt'
group ::= 'group'
| 'groep'
category ::= 'category'
| 'categorie'
defaultproject ::= 'defaultproject'
| 'defaultprojekt'
defaultgroup ::= 'defaultgroup'
| 'defaultgroep'
defaultcategory::= 'defaultcategory'
| 'defaultcategorie'
dayname ::= 'sunday'
| 'monday'
| 'tuesday'
| 'wednesday'
| 'thursday'
14 Mar 1995Elektronische Afdeling, Huygens Laboratorium 9
TR(1) TR(1)
| 'friday'
| 'saturday'
| 'zondag'
| 'maandag'
| 'dinsdag'
| 'woensdag'
| 'donderdag'
| 'vrijdag'
| 'zaterdag'
time ::= abstime
| laptime
laptime ::= abstime '-' abstime
| abstime '-' '@'
abstime ::= hour [:hHuU] ( min [mM]? )?
| min [mM]?
hour ::= 0..23
min ::= 0..59
prj-identifier ::= identifier
grp-identifier ::= identifier
cat-identifier ::= identifier
identifier ::= [-_a-zA-Z][-_a-z-A-Z0-9]*
description ::= '"' [printable]* '"'
NOTE: double quotes (") in a description must be quoted
(preceded) by a backslash (\).
Syntax of datafile
The syntax of the datafile is shown below. The definition
of the datafile is case-insensitive. Whitespace, except
newline, is ignored.
line ::= empty
| record? comment
| record $
record ::= time grp-identifier cat-identifier description
See `Syntax of profile' for the definition of comment,
time, grp-identifier, cat-identifier and description.
Options
tr can be executed with the following options:
14 Mar 1995Elektronische Afdeling, Huygens Laboratorium 10
TR(1) TR(1)
-h short help line,
-d print debugging information.
Program exit status
When a file cannot be found, or the file cannot be prop-
erly processed, the program stops and issues an error mes-
sage. The failure to process a file is reflected in the
programs exit status (see DIAGNOSTICS below).
ENVIRONMENT
HOME homedirectory for current user, used to
determine datadirectory. The datadirectory
is home\-tr,
LOGNAME name for current user, used to determine
datadirectory when HOME is not specified.
The datadirectory is c:\-tr\logname,
USER name for current user, used to determine
datadirectory when LOGNAME is not speci-
fied. The datadirectory is c:\-tr\user.
FILES
bin\tr.pro system-wide profile, in same directory as
tr.exe,
datadir\tr.pro profile in datadirectory,
datadir\yyyymmdd.dat
data file for date year yyyy, month mm and
day dd,
DIAGNOSTICS
tr can return the following exit values:
0 success: program execution has been successfully com-
pleted,
1 commandline error: an invalid option is specified,
2 processing error: a file could not be opened or closed,
an error occurred while writing to an output file,
3 interruption: the user interrupted the program,
4 internal error: an unexpected situation in program
behaviour occurred.
14 Mar 1995Elektronische Afdeling, Huygens Laboratorium 11
TR(1) TR(1)
SEE ALSO
users myreport(1), prjtime(1) trpack(1), trun-
pack(1),
programmers sumtime(1), trreport(1), trweek(1).
EXAMPLE
tr start
BUGS
The size of the database is limited to 100 records.
AUTHOR
M.J. Moene
14 Mar 1995Elektronische Afdeling, Huygens Laboratorium 12