simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-12-25 19:31:44 +03:00
Code Issues Projects Releases Wiki Activity

;doc:journal:description/payee/note: clarify

Browse Source
This commit is contained in:
Simon Michael 2024-02-18 14:51:32 -10:00
parent de3209a2fb
commit 3f6c400ddb
1 changed files with 25 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
hledger/hledger.m4.md
View File

@ -1038,16 +1038,34 @@ or reference number.
## Description
A transaction's description is the rest of the line following the date and status mark (or until a comment begins).
Sometimes called the "narration" in traditional bookkeeping, it can be used for whatever you wish,
or left blank. Transaction descriptions can be queried, unlike [comments](#transaction-comments).
After the date, status mark and/or code fields, the rest of the line (or until a comment is begun with `;`) is the transaction's description.
Here you can describe the transaction (called the "narration" in traditional bookkeeping),
or you can record a payee/payer name,
or you can leave it empty.
Transaction descriptions show up in [print](#print) output and in [register](#register) reports,
and can be listed with the [descriptions](#descriptions) command.
You can [query](#queries) by description with `desc:DESCREGEX`,
or [pivot](#pivoting) on description with `--pivot desc`.
### Payee and note
You can optionally include a `|` (pipe) character in descriptions to subdivide the description
into separate fields for payee/payer name on the left (up to the first `|`) and an additional note
field on the right (after the first `|`). This may be worthwhile if you need to do more precise
[querying](#queries) and [pivoting](#pivoting) by payee or by note.
Sometimes people want a dedicated payee/payer field that can be queried and checked more strictly.
If you want that, you can write a `|` (pipe) character in the description.
This divides it into a "payee" field on the left, and a "note" field on the right.
(Either can be empty.)
You can query these with `payee:PAYEEREGEX` and `note:NOTEREGEX`,
list their values with the [payees](#payees) and [notes](#notes) commands,
or pivot on `payee` or `note`.
Note: in transactions with no `|` character, description, payee, and note all have the same value.
Once a `|` is added, they become distinct.
(If you'd like to change this behaviour, please propose it on the mail list.)
If you want more strict error checking, you can declare the valid payee names with `payee` directives, and then enforce these with `hledger check payees`.
Note: because of the above, for this you'll need to ensure every transaction description contains a `|` and therefore a checkable payee name (even if it's empty).
## Transaction comments