commit aa1aa7a85196777b269e3453cc72f9fc98a4c1d1
Author: Oscar Benedito <oscar@oscarbenedito.com>
Date: Wed, 21 Oct 2020 20:30:48 +0200
Initial commit
Diffstat:
| A | README.md | | | 96 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 96 insertions(+), 0 deletions(-)
diff --git a/README.md b/README.md
@@ -0,0 +1,96 @@
+# Timesheet file format
+
+The goal of this project is to define a file format that allows the user to
+record the time spent on tasks (a timesheet). The design is inspired by Tim
+Weber's [timesheet.txt][ts].
+
+## Motivation
+
+The motivation behind this project is personal usage. I wanted to be able to
+track time easily in a system that was durable. This project pretends to specify
+a file format that is easy to parse (by a machine) and read (by a human).
+
+The requirements to work with such format should only be access to a text
+editor, although there will be a script that lets the user view and edit such a
+file from the command line.
+
+Why plain text? Because it is easy to read and write, and you don't need any
+special program to access your data. On top of that, it is easy to parse, so
+anyone a bit familiar with programming will be able to create a parser that
+works exactly how they want. Even if you don't, hopefully my parser is easy to
+understand, and it should take an interested user less than half an hour to get
+familiar with the code.
+
+## Specification
+
+A bit more formally. In a timesheet file, each line fits in one of the following
+categories:
+
+- Whitespace: blank line or line with whitespace characters only.
+- Date change: a line that specifies a change in the date. Format:
+ `YYYY-MM-DD:`.
+- Task change: a change in the current task. This lines can be divided in the
+ following subcategories:
+ - Start task: stop last task and start a new one. Format: `HHMM[SS]
+ description`.
+ - Stop task: stop current task. Format: `HHMM[SS].`.
+ - Continue last task: continue the task previous to the current one (see
+ examples). Format: `HHMM[SS]^`.
+ - Continue task by start time: continue a task specifying it's start time.
+ Format: `HHMM[SS]^[YYYY-DD-MMT]HHMM[SS]`.
+
+The definition of the format symbols:
+
+- On the date change, `YYYY`, `MM` and `DD` stand for the year, month and day,
+ respectively.
+- On task changes, `HH`, `MM` and `SS` stand for hour, minute and second,
+ respectively. Note that on the subcategory "continue task by start time", the
+ `T` represents the character `T`, not a variable.
+- Square brackets (`[`, `]`) delimit an optional value.
+- `description` is a task description. It is a non-empty string without a
+ newline or a `#` character surrounded by whitespace. Any word started with the
+ `#` character is considered a tag for the task, and should not be considered
+ part of the description message, a description doesn't need to have any other
+ text if it already has a tag, a tag must only contain letters (lowercase or
+ uppercase), numbers and underscores.
+- A space (` `) stands for non-zero amount of spaces and/or tabs.
+- Any other character stands for the literal value of the character.
+
+On top of that, any line can start and/or end with any amount of spaces and/or
+tabs (which should be ignored by the parser). Any line can have comments at the
+end, which start with a `#` surrounded by spaces (or end of line characters) and
+end at the end of the line.
+
+When parsing the description of a task, tags will be substituted by a space in
+the description, and then any leading or trailing spaces will be deleted.
+Therefore, any tags appearing at the start or end of the description will be
+completely deleted, while tags in between description text will be substituted
+by a space.
+
+All entries must be in chronological order and there must not be two entries
+starting at the same time. If no second is specified for the start time of a
+task, the default value is 0.
+
+If no day is specified when continuing a task by start time, then the current
+day is used (the day specified on last date change).
+
+### Examples
+
+An example of a file would be:
+
+```
+TODO
+```
+
+## Note
+
+I hope to end up with a file without any ambiguities. If you have a question
+that is not answered, please [contact me][c] or open an issue.
+
+## TODO
+
+- License
+- Examples
+
+[ts]: <https://github.com/scy/timesheet.txt>
+[c]: <https://oscarbenedito.com/contact/>
