From faa5f00f1a7b8a155a990abc2725087c45ae80b6 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 17 Dec 2022 07:23:53 -1000 Subject: [PATCH] ;doc: cli: more guidance on comments --- hledger/hledger.m4.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index ddb55e2b1..bb4a38388 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -838,20 +838,26 @@ file comments, transactions, and/or directives ## File comments -Lines in the journal beginning with a semicolon (`;`), a hash (`#`) or -a star (`*`) are file-level comments, and will be ignored. -They are not attached to anything (even if right next to a transaction). +Lines in the journal will be ignored if they begin with a semicolon (`;`), a hash (`#`) or a star (`*`). +hledger will also ignore regions beginning with a `comment` line and ending with an `end comment` line (or file end). -(Star comments allow emacs users to view and fold/unfold long journals in org mode, -but nowadays regular comments and ledger mode + orgstruct mode may work better). +These four comment syntaxes are equivalent, but here's a suggestion: +- `#` for significant/top-level notes +- `;` for minor notes, eg on specific transactions, and for commenting out things temporarily +- `comment` for quickly commenting large regions (remember it's there, or you might get confused) +- `*` for emacs users managing big journals as org outlines (but orgstruct + ledger mode is probably better now) + +Eg: ```journal # a file comment ; another file comment -* also a file comment, useful in org/orgstruct mode +* a file comment and an org headline comment -A multiline file comment, continuing until an -"end comment" directive or the end of the current file. +A multi-line file comment block, + +continuing until "end comment" directive +or the end of the current file. end comment ```