view release on metacpan or  search on metacpan

lib/App/TimelogTxt/Manual.pod  view on Meta::CPAN

=head1 NAME

App::TimelogTxt::Manual - Overview of the L<App::TimelogTxt> modules and
C<timelog> application.

=head1 VERSION

This manual applies to L<App::TimelogTxt> version 0.22.

=head1 INTRODUCTION

In a job a long time ago, I found that I would regularly reach the end of a
long, tiring day and have no idea what I had done. Just as regularly, I found
that my most important projects were not progressing very rapidly. Many people
find themselves in the same position. I decided to do something about it, I
found an application on the Palm that tracked Clients, Projects, and Tasks (as
well as mileage and expenses) called TEAK.

I started tracking everything I did at work. After a few days, I had identified
many of the interruptions that prevented me from making progress. I had also
noted that some of my busiest, yet least productive days were almost all
interruptions. I used this information to improve my work and to keep people
updated with why my various projects were not progressing as expected. When I
needed to make faster progress, I had the data to help my manager redirect the
worst of the interruptions.

=head2 The Need for Change

This was wonderful. Unfortunately, the Palm platform did not survive in the
market. I continued to keep my Palm functional partially to use TEAK. But, I
eventually had to admit that I could not rely on my Palm to continue. By this
time I had an Android smart phone and I figured it would be pretty easy to find
something to replace TEAK. No such luck.

I had been using Gina Trapani's Todo.txt program for a while at this point.
It's main feature is the simplicity of its file format:

=over 4

=item * 

One entry per line

=item *

pure text

=item *

minimal formatting

=back

I decided that this would be a better basis for a new time logging program than
some binary format. So I wrote a quickie Perl script to allow me to start and
stop task timers and to generate simple reports.

As I used the program, I found other commands and reports that could be useful.
In the end, it was obvious that this tool needed to be cleaned up a re-written.
This module is the result of that rewrite.

=head1 The C<timelog> Program

The C<timelog> program is how you manipulate your time log and generate
reports. The program is executed with a command and optional arguments.

=head1 Supported Commands

The C<timelog> program supports a number of commands that manipulate or report
on the time logged by the program.

=head2 Adding Events

The commands you will use the most involve adding events to the time log. The
string C<{event description}> is a text string that may have a I<+project> and/or
a I<@task>. The first string of non-whitespace characters beginning with a 'C<+>'
is treated as the I<project> for this event. The project is only relevant when
using the reporting commands. Likewise, the first string of non-whitespace
characters beginning with a 'C<@>' is treated as a task.

If an event has no task, the non-project part of the event is treated as the
task. Otherwise, the non-project, non-task part of the event is treated as
detail information for the event.

=over 4

=item  start {event description}
     
Stop the current event and start timing a new event. Since C<timelog> only
tracks one event at a time, the current event is always stopped when starting
a new event.

=item stop

Stop timing the current event.

=item push {event description}

Save the current event on stack and start timing new event. The current event
is saved in the stack file in the timelog directory. You can manipulate the
saved event with B<pop> or B<drop>.

=item pop

Stop the current event and restart top event on stack. This also removes the
event from the stack.

=item drop [all|{n}]

Drop one or more events from top of event stack. If no arguments are supplied,
only the top item is dropped. If the argument is a number, that number of
events is dropped from the stack. If the argument I<all> is supplied, the stack
is cleared.

=back