Garmelon/today
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update README, todos and example

Browse source
This commit is contained in:
Joscha 2021-12-19 15:33:28 +01:00
parent 14525088f9
commit 3d9c4102b6
4 changed files with 25 additions and 151 deletions
Download patch file Download diff file Expand all files Collapse all files

126
README.md
View file

@ -1,127 +1,3 @@
# today
## Commands
### The `TASK` command
```
TASK title
(DATE annotation)*
[FROM annotation]
[UNTIL annotation]
(DONE annotation)*
long description
```
### The `NOTE` command
```
NOTE title
(DATE annotation)+
[FROM annotation]
[UNTIL annotation]
(DONE annotation)*
long description
```
### The `BIRTHDAY` command
```
BIRTHDAY name
BDATE annotation
```
## Annotations
### The `DATE` annotation
Most commands allow or require `DATE` annotations. They are roughly structured
like `DATE start [-- end]`. The `end` part can only contain time-related
information if the `start` specifies a time.
More specifically, there are three variants of the `DATE` annotation:
```
DATE date [delta] [time] [-- [date] [delta] [time]] [; delta]
DATE weekday [time] [-- [weekday] [delta] [time]]
DATE formula [delta] [time] [-- [delta] [time]]
```
In all three cases, the `end` must contain at least one of the optional elements
if it is present. Deltas in the `end` may represent fractional days (e. g.
`+3h`) as long as they are not immediately followed by a time and the `start`
includes a time. Other deltas may only represent whole-day intervals (they may
contain sub-day specifiers like `+24h` or `+25h-60m` as long as they sum to a
whole-day interval).
In the case of the `date` variant, a repetition delta can be specified following
a semicolon.
If multiple `DATE` annotations from a single command start on the same date, all
except the first are ignored.
### The `FROM` and `UNTIL` annotations
Commands that allow `DATE` annotations also allow the `FROM` and `UNTIL`
annotations. These can be used to restrict occurrences of entries.
The `FROM` annotation has the form `FROM date` and only keeps occurences that
end at or after the specified date. These occurences may begin before the
specified date.
The `UNTIL` annotation has the form `UNTIL date` and only keeps occurrences that
start at or before the specified date. These occurrences may extend past the
specified date.
### The `BDATE` annotations
This is a very simple date annotation for birthdays. It has the form
`BDATE date` where the year may optionally be replaced by a `?`.
If the year is specified, the person's current age is displayed in the birthday
occurrence title.
## Examples
```
NOTE Spielerunde
DATE sun 22:00 -- 24:00
DATE sun 22:00 -- 00:00
DATE sun 22:00 -- +2h
DATE (wd = sun) 22:00 -- 24:00
DATE 2021-11-07 22:00 -- 24:00; +w
DATE 2021-11-07 22:00 -- +2h; +w
NOTE daily
DATE *
DATE (true)
DATE 2021-11-07; +d
NOTE on weekends
DATE (wd = sat | wd = sun)
NOTE weekends
DATE sat -- sun
DATE 2021-11-06 -- 2021-11-07; +w
DATE 2021-11-06 -- +d; +w
DATE (wd = sat) -- +d
NOTE last of each month
DATE (m = 1) -d
BIRTHDAY Max
BDATE 1987-05-14
BIRTHDAY Martha
BDATE ?-09-21
NOTE Physics lecture
DATE wed 14:00 -- 15:30
DATE 2021-05-07 14:00 -- 15:30
FROM 2021-04-14
UNTIL 2021-07-28
EXCEPT 2021-05-06
This is a description of the event. It might mention further information
that doesn't fit into the title.
It may even contain multiple paragraphs, separated by an arbitrary amount
of empty lines, as long as every non-empty line is indented.
```
A program for specifying and tracking (recurring) dates and tasks.