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.