From 60d6b1afcebd8108e3f593a6e1c40356734286f9 Mon Sep 17 00:00:00 2001 From: Erik Winter Date: Mon, 3 Oct 2022 16:17:51 +0200 Subject: [PATCH] mail format doc --- doc/mail-format.adoc | 54 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 doc/mail-format.adoc diff --git a/doc/mail-format.adoc b/doc/mail-format.adoc new file mode 100644 index 0000000..e224490 --- /dev/null +++ b/doc/mail-format.adoc @@ -0,0 +1,54 @@ += Mail format +2022-10-03 + +The mails that are sent back and forth are in plain text and contain key-value pairs, one per line: + +---- +key: value +---- + +The quote prefix `>` is stripped before evaluating. These keys are also valid: + +---- +> key1: value 1 +>> key2: value 2 +---- + +Lines are evaluated from bottom to top. If a key occors multiple times, later keys overwrite previous ones. So lines on top overwrite lines at the bottom. + +== Fields + +Recognized fields are: + +* `action` - a string. +* `project` - a string. It is not required that the project is defined or declared elsewhere. +* `due` - date string. See below. +* `recur` - recur string, See below. +* `done` - boolean. The word "true" evaluates to `true`, everything else evaluates to `false`. + +== Date string + +There are several options to specify a date. The general form is `YYYY-MM-DD`. In addition to that `today` and `tomorrow` are also understood, as are the days of the week: `monday`, `tuesday`, `wednesday`, `friday`, `saturday`, `sunday`. Those indicate the first occurence of that weekday _after_ the current day. Unrecognized values will erase the field. + + +== Recur string + +The recur string consists of two to three parts, separated by a comma. The first is the start date and follows the same semantics as a date string. The second specifies the period and the third can contain optional parameters. + +The date format as `YYYY-MM-DD (weekday)` is also permitted, to facilitate processing replies and forwards of tasks. The weekday will be ignored in that case. + +For the second part, the following periods are available: + +`daily` + +`every N days`, where N is an integer. + +`weekly`, with the weekdays specified in the third part, separated by `&` signs. For example, this recurrer starts today and recurs every Monday and Wednesday: `today, weekly, monday & wednesday`. + +`biweekly`, like `weekly`, but recurs only every other week. + +`every N weeks`, where N is an integer. + +`every N months`, where N is an integer. + +