App::TimelogTxt::Manual - Overview of the App::TimelogTxt modules and timelog application.
timelog
This manual applies to App::TimelogTxt version 0.22.
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.
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:
One entry per line
pure text
minimal formatting
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.
The timelog program is how you manipulate your time log and generate reports. The program is executed with a command and optional arguments.
The timelog program supports a number of commands that manipulate or report on the time logged by the program.
The commands you will use the most involve adding events to the time log. The string {event description} is a text string that may have a +project and/or a @task. The first string of non-whitespace characters beginning with a '+' is treated as the 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 '@' is treated as a task.
{event description}
+
@
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.
Stop the current event and start timing a new event. Since timelog only tracks one event at a time, the current event is always stopped when starting a new event.
Stop timing the current event.
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 pop or drop.
Stop the current event and restart top event on stack. This also removes the event from the stack.
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 all is supplied, the stack is cleared.
The reporting commands generate a report of information from the timelog files. Many of these commands accept a date or pair of dates. The date is normally expected to be of the form YYYY-MM-DD. However, a small number of shortcuts are also allowed.
YYYY-MM-DD
The strings 'today' and 'yesterday' resolve to the obvious date. The days of the week are also allowed, each resolves to that day of the week prior to the current day. If the current day is Wednesday, monday resolves to two days ago, and thursday resolves to six days ago.
Any time you supply a pair of dates, the second must be later in time than the first.
The reporting commands are:
Display the hours worked for each of the appropriate days.
List events for the specified day. Default to today.
List known projects, one per line.
Display items on the stack. The top event on the stack is the one that is resumed by the pop command.
Display a report for the specified days.
This report is grouped by day, with each project grouped under the day. Each event for a project is displayed under the project. Accumulated times are displayed for each project and day.
Display a summary of the appropriate days' projects.
For each day, the list of projects active during that day is shown along with the aggregate time spent on that project.
The remaining commands do not necessarily fit into one of the other categories.
Prepare the system for use with timelog. First, it creates the directory where timelog stores its information, if that directory does not already exist. Then, the command creates and initializes the .timelogrc configuration file, in the user's home directory, with the information needed to run.
Open the timelog file in the current editor. The editor can be specified in the configuration file. If no editor is specified in the configuration, the program uses the value of the VISUAL environment variable. If VISUAL has no value, then the value of EDITOR is used instead. If neither environment variable has a value, then the program defaults to vim
VISUAL
EDITOR
vim
Execute commands as entered until quit.
This command starts an interactive mode where each line typed is a new command to timelog. Each string entered is just like the timelog command line, without the program name.
This mode continues in effect until you enter the string quit on a line by itself.
quit
A list of commands and/or aliases. The hint command is mostly intended as a quick syntax or command name reminder.
With no arguments, you get a list of the commands and aliases, one per line. The commands are listed with simple usage information. Each alias is listed with its definition.
Calling hint with an argument of 'commands' lists the hint information for just the commands. Calling hint with an argument of 'aliases' lists the hint information for just the aliases.
Any other argument is looked up in the command list and then the alias list and the first matching item is displayed.
Display help about commands and/or aliases. The help command gives more detailed help about the command or alias.
With no arguments, you get a list of the commands and aliases, each with its associated help text. The commands are each listed as a usage line with some explanatory text. Each alias is listed with its definition.
Calling help with an argument of 'commands' lists the help information for just the commands. Calling help with an argument of 'aliases' lists the help information for just the aliases.
The timelog program uses the file ~/.timelogrc if it exists.
The configuration file is expected to contain data in two major parts:
The first section defined general configuration information in a key=value format. The recognized keys are:
The editor to use when opening the timelog file with the edit command. If not specified, it will use the value of either the VISUAL or EDITOR environment variables. If non are found, it will default to vim.
edit
The directory in which to find the timelog data files. Defaults to the timelog directory in the user's home directory.
The default command to by used if none is supplied to timelog. By default, this is the 'stop' command.
The configuration file may also contain an '[alias]' section that defines command aliases. Each alias is defined as a shortname=expanded string.
[alias]
shortname=expanded string
For example, if you regularly need to make entries for reading email and triaging bug reports you might want the following in your configuration.
[alias] email = start +Misc @Email triage = start +BugTracker @Triage
G. Wade Johnson <gwadej@cpan.org>
<gwadej@cpan.org>
Copyright (c) 2013, G. Wade Johnson <gwadej@cpan.org>. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
To install App::TimelogTxt, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::TimelogTxt
CPAN shell
perl -MCPAN -e shell install App::TimelogTxt
For more information on module installation, please visit the detailed CPAN module installation guide.