# NAME
Format - Description of the timelog.txt file format.
# VERSION
This document describes version 2 of the timelog.txt file format.
# HISTORY
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.
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.
# DESCRIPTION
Each time entry resides on a line by itself. Each line is made up of an
optional marker and two parts separated by a marker character, usually a space:
a time/date stamp and a task description. There should be no leading or
trailing white space on the lines.
The format also supports comments defined as having a `#` as the first character
on the line.
## Time/Date Stamp
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 unambiguously parsed, and
sorts nicely.
## Entry
The entry 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 the
name of the task. Any remaining text is treated as further detail on the task.
If no task name is specified, all of the event string except the project is
treated as the task name. The task name is optional because not everyone will
find it useful to define consistent tasks for reporting.
There is one special case. An entry of `stop` stops timing the current task
without starting a new task.
## Examples
The following examples should make the format clear.
### Full Featured Entry Line
A full entry 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 name is `Docment`, which means I am documenting something
on the project. The string 'File Format' specifies more detail on what I am
documenting.
This task began just after 10:01 on July 1st.
### Entry With No Detail
This following entry contains both a project and a task, but with no extra
detail.
2013-07-01 08:05:14 +Admin @Email
In this case, I'm just checking my email for the morning. There is really no
need for any more detail than that. Although not a real project, grouping
miscellaneous tasks through the day into a `Admin` pseudo-project simplifies
tracking administrative tasks.
### Entry with No Explicit Task
2013-07-01 13:05:45 +Timelog Submit to crates.io
In this case, the task would be 'Submit to crates.io' because I haven't separated
the task name from the details.
## Special Entries
Special entries are points in time that do not feed in to the normal time processing.
All special entries have a special character replacing the space after the date stamp
that indicates which type of marked entry it is. These entries are not required to
perform useful tracking of your time, but they have been found to be useful in later
uses of the `timelog` tool.
All special entries are ignored when reporting on times.
### Ignored Entries
If the mark character after the time stamp is `!`, the entry is marked as _ignored_. This
means that an task would have started, but was later ignored.
2013-07-01 10:01:23!+Timelog @Meeting File Format
A good example would be when a task or meeting is supposed to start, but
after just after you mark the time, it gets canceled. Since you won't spend any
time in that task, you don't want to track it. However the _ignored entry_
marks that it happened, even if it was not actually used in time tracking.
### Zero Duration Events
If the mark character after the time stamp is `^`, the entry is a _zero duration_
event (or _event_ for short). An event marks something happening at a point in
time, rather than an entry for at one end of a span of time.
2013-07-01 10:01:23^+Timelog System restart
For example, you might use a event to indicate when an alert happens, or to mark
when during the day that some irregular event occurs.
# AUTHOR
G. Wade Johnson `<rust@gwadej.org>`
# LICENSE AND COPYRIGHT
Copyright (c) 2022, G. Wade Johnson "<rust@gwadej.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](https://opensource.org/licenses/Artistic-2.0).