slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc:timedot: cleanups

Browse Source
This commit is contained in:
Simon Michael 2023-11-23 11:21:31 -10:00
parent 96f9c1d2b2
commit 6a232e247a
1 changed files with 99 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

190
hledger/hledger.m4.md
View File

@ -4165,23 +4165,21 @@ To generate time logs, ie to clock in and clock out, you could:
`timedot` format is hledger's human-friendly time logging format. `timedot` format is hledger's human-friendly time logging format.
Compared to [`timeclock` format](#timeclock), it is Compared to [`timeclock` format](#timeclock), it is
more convenient for quick, approximate, and retroactive time logging,
- convenient for quick, approximate, and retroactive time logging and more human-readable (you can see at a glance where time was spent).
- readable: you can see at a glance where time was spent. A quick example:
A timedot file contains a series of day entries, which might look like this:
```timedot ```timedot
2023-05-01 2023-05-01
hom:errands .... .... ; two hours hom:errands .... .... ; two hours; the space is ignored
fos:hledger:timedot .. ; half an hour fos:hledger:timedot .. ; half an hour
per:admin:finance per:admin:finance ; no time spent yet
``` ```
hledger reads this as a transaction on this day with three (unbalanced) postings, hledger reads this as a transaction on this day with three
where each dot represents "0.25". No commodity is assumed, but normally we interpret (unbalanced) postings, where each dot represents "0.25".
it as hours, with each dot representing a quarter-hour. It's convenient, though No commodity symbol is assumed, but we typically interpret it as hours.
not required, to group the dots in fours for easy reading.
```shell ```shell
$ hledger -f a.timedot print # .timedot file extension (or timedot: prefix) is required $ hledger -f a.timedot print # .timedot file extension (or timedot: prefix) is required
@ -4191,53 +4189,62 @@ $ hledger -f a.timedot print # .timedot file extension (or timedot: prefix) is
(per:admin:finance) 0 (per:admin:finance) 0
``` ```
A transaction begins with a non-indented **[simple date](#simple-dates)** (Y-M-D, Y/M/D, or Y.M.D). A timedot file contains a series of transactions (usually one per day).
It can optionally be preceded by one or more stars and a space, for Emacs org mode compatibility. Each begins with a **[simple date](#simple-dates)** (Y-M-D, Y/M/D, or Y.M.D),
It can optionally be followed on the same line by a transaction description, optionally be followed on the same line by a transaction description,
and/or a transaction comment following a semicolon. and/or a transaction comment following a semicolon.
After the date line are zero or more time postings, consisting of: After the date line are zero or more time postings, consisting of:
- an **account name** - any hledger-style [account name](#account-names), optionally hierarchical, optionally indented. - **An account name** - any hledger-style [account name](#account-names), optionally indented.
- **two or more spaces** - a field separator, required if there is an amount (as in journal format).
- an optional **timedot amount** - dots representing quarter hours, or a number representing hours, optionally with a unit suffix.
- an optional **posting comment** following a semicolon.
Timedot amounts can be: - **Two or more spaces** - required if there is an amount (as in journal format).
- **dots**: zero or more period characters (`.`), each representing 0.25. - **A timedot amount**, which can be
Spaces are ignored and can be used for grouping.
Eg: `.... ..`
- or a **number**. Eg: `1.5` - empty (representing zero)
- or a **number immediately followed by a unit symbol** - a number, optionally followed by a unit `s`, `m`, `h`, `d`, `w`, `mo`, or `y`,
`s`, `m`, `h`, `d`, `w`, `mo`, or `y`. representing a precise number of seconds, minutes, hours, days weeks, months or years
These are interpreted as seconds, minutes, hours, days weeks, months or years, and converted to hours, assuming:\ (hours is assumed by default), which will be converted to hours according to
`60s` = `1m`, 60s = 1m,
`60m` = `1h`, 60m = 1h,
`24h` = `1d`, 24h = 1d,
`7d` = `1w`, 7d = 1w,
`30d` = `1mo`, 30d = 1mo,
`365d` = `1y`. 365d = 1y.
Eg `90m` is parsed as `1.5`.
- one or more dots (period characters), each representing 0.25.
These are the dots in "timedot".
Spaces are ignored and can be used for grouping/alignment.
- **An optional comment** following a semicolon (a hledger-style [posting comment](#posting-comments)).
There is some added flexibility to help with keeping time log data There is some flexibility to help with keeping time log data and notes in the same file:
in the same file as your notes, todo lists, etc.:
- Blank lines and lines beginning with `#` or `;` are ignored. - Blank lines and lines beginning with `#` or `;` are ignored.
- Before the first date line, lines beginning with `*` are ignored. - After the first date line, lines which do not contain a double space
are parsed as postings with zero amount.
(hledger's register reports will show these if you add -E).
- From the first date line onward, one or more `*`'s followed by a space - Before the first date line, lines beginning with `*` (eg org headings) are ignored.
at beginning of lines (ie, the headline prefix used by Emacs Org mode) is ignored. And from the first date line onward, Emacs org mode heading prefixes at the start of lines
This means the time log can be kept under an Org headline, (one or more `*`'s followed by a space) will be ignored.
and date lines or time transaction lines can be Org headlines. This means the time log can also be a org outline.
- Lines not ending with a double-space and amount are parsed as postings with zero amount. ## Timedot examples
Note hledger's register reports hide these by default (add -E to see them).
More examples: Numbers:
```timedot
2016/2/3
inc:client1 4
fos:hledger 3h
biz:research 60m
```
Dots:
```timedot ```timedot
# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
@ -4250,42 +4257,6 @@ biz:research .
inc:client1 .... .... inc:client1 .... ....
biz:research . biz:research .
``` ```
```timedot
2016/2/3
inc:client1 4
fos:hledger 3
biz:research 1
```
```timedot
* Time log
** 2023-01-01
*** adm:time .
*** adm:finance .
```
```timedot
* 2023 Work Diary
** Q1
*** 2023-02-29
**** DONE
0700 yoga
**** UNPLANNED
**** BEGUN
hom:chores
cleaning ...
water plants
outdoor - one full watering can
indoor - light watering
**** TODO
adm:planning: trip
*** LATER
```
Reporting:
```shell ```shell
$ hledger -f a.timedot print date:2016/2/2 $ hledger -f a.timedot print date:2016/2/2
2016-02-02 * 2016-02-02 *
@ -4311,16 +4282,36 @@ Balance changes in 2016-02-01-2016-02-03:
|| 7.75 2.25 8.00 || 7.75 2.25 8.00
``` ```
Org:
Using period instead of colon as account name separator: ```timedot
* 2023 Work Diary
** Q1
*** 2023-02-29
**** DONE
0700 yoga
**** UNPLANNED
**** BEGUN
hom:chores
cleaning ...
water plants
outdoor - one full watering can
indoor - light watering
**** TODO
adm:planning: trip
*** LATER
```
Using `.` as account name separator:
```timedot ```timedot
2016/2/4 2016/2/4
fos.hledger.timedot 4 fos.hledger.timedot 4h
fos.ledger .. fos.ledger ..
``` ```
```shell ```shell
$ hledger -f a.timedot --alias /\\./=: bal --tree $ hledger -f a.timedot --alias '/\./=:' bal -t
4.50 fos 4.50 fos
4.00 hledger:timedot 4.00 hledger:timedot
0.50 ledger 0.50 ledger
@ -4328,16 +4319,33 @@ $ hledger -f a.timedot --alias /\\./=: bal --tree
4.50 4.50
``` ```
A <!--
[sample.timedot](https://raw.github.com/simonmichael/hledger/master/examples/sample.timedot) Another sample, download from
file. https://raw.github.com/simonmichael/hledger/master/examples/sample.timedot and try:
<!-- to download and some queries to try: --> ```shell
$ hledger -f sample.timedot balance # current time balances
$ hledger -f sample.timedot register -p 2009/3 # sessions in march 2009
$ hledger -f sample.timedot register -p weekly --depth 1 --empty # time summary by week
```
```timedot
# sample.timedot
# This is a comment line
; Also a comment line
* Org headings before the first date are also comment lines
<!-- ```shell --> 2023-01-01 transaction description
<!-- $ hledger -f sample.timedot balance # current time balances --> biz:research ....
<!-- $ hledger -f sample.timedot register -p 2009/3 # sessions in march 2009 --> inc:client1 .... ..
<!-- $ hledger -f sample.timedot register -p weekly --depth 1 --empty # time summary by week -->
<!-- ``` --> 2023-01-01 different transaction, same day ; with a comment and transaction-tag:
; more transaction comment lines ? currently ignored
fos:haskell .... ; a posting comment and posting-tag:
; more posting comment lines ? currently ignored
per:admin ....
** 2023-01-02 ; dates are allowed to be org headings
```
-->
# PART 3: REPORTING CONCEPTS # PART 3: REPORTING CONCEPTS