App::TimelogTxt::Format - Description of the timelog.txt file format.
This document describes version 1 of the timelog.txt file format.
The format of this file was strongly influenced by the design of the todo.txt system created by Gina Trapani. The major idea was to have a format that could be easily read and modified by a human with a text editor. This format should be a simple as possible, and require no proprietary technology to read or write.
todo.txt
Some of the data stored in the file and the reporting of the data was influenced by years of use of the TEAK tool on the Palm. I wrote this tool to replace TEAK once it was obvious that the Palm was no more.
Each time entry resides on a line by itself. Each line is made up of two parts: a time/date stamp and an event. There should be no leading or trailing white space on the lines.
The time/date stamp is the first thing on each line and is set in the local timezone. Except where we cross from Daylight Saving Time to Standard Time or vice versa this should cause no problems.
The format of this part of the line is 'YYYY-MM-DD HH:MM:SS '. This format is relatively easy for a person to read, is easily and unambiuously parsed, and sorts nicely.
The event is just text that describes the task or event we are now beginning. To enhance reporting, there are two forms of metadata. The first string starting with a + is treated as a project. All events with the same project are reported together. The first string starting with @ is treated as a task. Any remaining text is treated as further detail on the task.
+
@
If no task is specified, all of the event string except the project is treated as the task. The task is optional because not everyone will find it useful to define consistent tasks for reporting.
There is one special case. An event of stop stops timing the current event without starting a new event.
stop
The following examples should make the format clear.
A full event using all of the features would look line this:
2013-07-01 10:01:23 +Timelog @Document File Format
The project in this case is Timelog, which specifies that I am working on this module. The task is Docment, which means I am documenting something on the project. The string 'File Format' specifies more detail on what I am documenting.
Timelog
Docment
This event began around 10:01 on July 1st.
This following event contains both a project and a task, but with no extra detail.
2013-07-01 08:05:14 +Misc @Email
In this case, I'm just checking my email for the morning. There is really no need for any more detail than that.
2013-07-01 13:05:45 +Timelog Submit to CPAN
In this case, the task would be 'Submit to CPAN' because I haven't separated the task from the details.
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.