From e71ee0b534748d8ce0adf7a625786e311ca24b31 Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Tue, 23 Nov 2021 12:06:43 -1000
Subject: [PATCH] ;doc: templates: basic: inline docs, improvements

---
 examples/templates/basic/accounts.journal    | 16 +++++++--
 examples/templates/basic/commodities.journal | 32 ++++++++++++++++++
 examples/templates/basic/main.journal        | 34 +++++++++++++++++++-
 examples/templates/basic/payees.journal      | 18 +++++++++++
 4 files changed, 96 insertions(+), 4 deletions(-)

diff --git a/examples/templates/basic/accounts.journal b/examples/templates/basic/accounts.journal
index 68f5e1f57..c7158e4ad 100644
--- a/examples/templates/basic/accounts.journal
+++ b/examples/templates/basic/accounts.journal
@@ -1,6 +1,16 @@
+; Account declarations - these provide structure, auto-completions, and extra error checking.
+;
+; https://hledger.org/hledger.html#declaring-accounts
+; https://hledger.org/hledger.html#strict-checks
+;
+; Lower case account names are easiest to type; capitalise them if you wish.
+; https://hledger.org/hledger.html#account-names
+;
+; If you prefer it, replace all occurences of "revenues" with "income" below.
 
-; Top-level accounts, their types and display order.
-; Lower-case for easy typing, capitalise if you prefer.
+
+; Top-level accounts and their https://hledger.org/hledger.html#account-types.
+; The order here sets their https://hledger.org/hledger.html#account-display-order.
 
 account assets       ; type:A
 account liabilities  ; type:L
@@ -8,7 +18,7 @@ account equity       ; type:E
 account revenues     ; type:R
 account expenses     ; type:X
 
-; Second-level accounts. These and below are typically kept alphabetically ordered.
+; Second-level accounts.
 
 account assets:checking
 account assets:receivable
diff --git a/examples/templates/basic/commodities.journal b/examples/templates/basic/commodities.journal
index ba904decf..1a9902e21 100644
--- a/examples/templates/basic/commodities.journal
+++ b/examples/templates/basic/commodities.journal
@@ -1 +1,33 @@
+; Commodity declarations - these set amount display styles and provide extra error checking.
+;
+; https://hledger.org/hledger.html#declaring-commodities
+; https://hledger.org/hledger.html#strict-checks
+;
+; The amount part must always contain a decimal mark (a period or comma), 
+; even if there are no decimal digits after it.
+
+
+; Fiat currencies
+
 commodity $1000.00
+
+; Investment commodities
+
+
+
+; Cryptocurrencies
+
+
+
+; Other
+
+
+
+; Default commodity
+; A default commodity symbol (and display style) to apply to any bare numbers.
+
+;D $1000.00
+
+; This one can be useful if including timedot files: it adds the h
+; (hour) symbol, which is also the symbol used by timeclock data. 
+;D 1.0h
diff --git a/examples/templates/basic/main.journal b/examples/templates/basic/main.journal
index c8142e884..a7bd28618 100644
--- a/examples/templates/basic/main.journal
+++ b/examples/templates/basic/main.journal
@@ -1,13 +1,45 @@
+; The main file. This is the one to open with hledger, hledger-ui, hledger-web etc.
+;
+; https://hledger.org/hledger.html#journal-format
+; https://plaintextaccounting.org/quickref
+
+
+; Declarations, kept in their own files. You can inline them here if you prefer one big file.
+
 include accounts.journal
 include commodities.journal
 include payees.journal
 
+
+; Opening balances. 
+
+; Pick a start date for this journal, the assets (owned) and
+; liabilities (owed) to be tracked, and record their balances at the
+; start of this day.
 2021-01-01 opening balances
     assets:checking                               $0
     liabilities:credit card                       $0
     equity
 
-; If you prefer to hide equity, use this form instead (and comment out equity in accounts.journal):
+;; If you prefer not to see equity in reports, use this instead,
+;; and comment out equity in accounts.journal:
 ; 2021-01-01 opening balances
 ;     (assets:checking)                             $0
 ;     (liabilities:credit card)                     $0
+
+
+; Transactions. 
+;
+; It's not required, but a good idea, to keep them in date order, for
+; ease of finding things and to allow extra error checking.
+; You can also include them from other files, though it adds complexity.
+
+
+; 2021-01-02 received wages
+;     revenues:salary
+;     assets:checking                            $1000
+
+; 2021-01-03 Whole Foods | bought groceries
+;     assets:checking
+;     expenses:food                                $50
+
diff --git a/examples/templates/basic/payees.journal b/examples/templates/basic/payees.journal
index 5241634be..46c68fc6c 100644
--- a/examples/templates/basic/payees.journal
+++ b/examples/templates/basic/payees.journal
@@ -1,2 +1,20 @@
+; Payee and/or description declarations - these provide
+; auto-completions and can help detect errors, or act as a reference
+; for standardising your transaction descriptions.
+; You can also check payees/descriptions strictly, though most people don't.
+;
+; https://hledger.org/hledger.html#description
+; https://hledger.org/hledger.html#declaring-payees
+; https://hledger.org/hledger.html#other-checks
+
+
+; Transaction descriptions
+
 payee opening balances
 payee closing balances
+
+
+; Payee/payer names
+
+;payee Joe
+;payee Whole Foods