;doc: journal: more cleanups to intro, secondary dates

[ci skip]

hledger-lib/hledger_journal.5

@@ -26,17 +26,14 @@ It\[aq]s safe, and encouraged, to run both hledger and ledger on the
 same journal file, eg to validate the results you\[aq]re getting.
 .PP
 You can use hledger without learning any more about this file; just use
-the add or web commands to create and update it.
+the add or web or import commands to create and update it.
-Many users, though, also edit the journal file directly with a text
-editor, perhaps assisted by the helper modes for emacs or vim.
 .PP
-Helper modes exist for popular text editors, which make working with
+Many users, though, edit the journal file with a text editor, and track
-journal files easier.
+changes with a version control system such as git.
-They add colour, formatting, tab completion, and helpful commands, and
+Editor addons such as ledger-mode or hledger-mode for Emacs, vim-ledger
-are quite recommended if you edit your journal with a text editor.
+for Vim, and hledger-vscode for Visual Studio Code, make this easier,
-They include ledger-mode or hledger-mode for Emacs, vim-ledger for Vim,
+adding colour, formatting, tab completion, and useful commands.
-hledger-vscode for Visual Studio Code, and others.
+See Editor configuration at hledger.org for the full list.
-See the Editor configuration at hledger.org for the latest information.
 .SH FILE FORMAT
 .PP
 Here\[aq]s a description of each part of the file format (and
@@ -95,18 +92,18 @@ dates documented in the hledger manual.)
 .PP
 Real-life transactions sometimes involve more than one date - eg the
 date you write a cheque, and the date it clears in your bank.
-When you want to model this, eg for more accurate balances, you can
+When you want to model this, for more accurate daily balances, you can
 specify individual posting dates.
 .PP
-Or, you can use the older \f[I]secondary date\f[R] feature.
+Or, you can use the older \f[I]secondary date\f[R] feature (Ledger calls
-(Ledger calls it auxiliary date or effective date.) But I would
+it auxiliary date or effective date).
-recommend avoiding this feature; posting dates are almost always clearer
+Note: we support this for compatibility, but I usually recommend
-and simpler.
+avoiding this feature; posting dates are almost always clearer and
-We support it mainly for compatibility.
+simpler.
 .PP
 A secondary date is written after the primary date, following an equals
 sign.
-The primary date\[aq]s year will be used if the year is omitted.
+If the year is omitted, the primary date\[aq]s year is assumed.
 When running reports, the primary (left) date is used by default, but
 with the \f[C]--date2\f[R] flag (or \f[C]--aux-date\f[R] or
 \f[C]--effective\f[R]), the secondary (right) date will be used instead.

hledger-lib/hledger_journal.info

@@ -23,16 +23,14 @@ as well.  It's safe, and encouraged, to run both hledger and ledger on
 the same journal file, eg to validate the results you're getting.
 
    You can use hledger without learning any more about this file; just
-use the add or web commands to create and update it.  Many users,
+use the add or web or import commands to create and update it.
-though, also edit the journal file directly with a text editor, perhaps
-assisted by the helper modes for emacs or vim.
 
-   Helper modes exist for popular text editors, which make working with
+   Many users, though, edit the journal file with a text editor, and
-journal files easier.  They add colour, formatting, tab completion, and
+track changes with a version control system such as git.  Editor addons
-helpful commands, and are quite recommended if you edit your journal
+such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and
-with a text editor.  They include ledger-mode or hledger-mode for Emacs,
+hledger-vscode for Visual Studio Code, make this easier, adding colour,
-vim-ledger for Vim, hledger-vscode for Visual Studio Code, and others.
+formatting, tab completion, and useful commands.  See Editor
-See the Editor configuration at hledger.org for the latest information.
+configuration at hledger.org for the full list.
 
    Here's a description of each part of the file format (and hledger's
 data model).  These are mostly in the order you'll use them, but in some
@@ -125,17 +123,17 @@ File: hledger_journal.info,  Node: Secondary dates,  Next: Posting dates,  Prev:
 
 Real-life transactions sometimes involve more than one date - eg the
 date you write a cheque, and the date it clears in your bank.  When you
-want to model this, eg for more accurate balances, you can specify
+want to model this, for more accurate daily balances, you can specify
 individual posting dates.
 
-   Or, you can use the older _secondary date_ feature.  (Ledger calls it
+   Or, you can use the older _secondary date_ feature (Ledger calls it
-auxiliary date or effective date.)  But I would recommend avoiding this
+auxiliary date or effective date).  Note: we support this for
-feature; posting dates are almost always clearer and simpler.  We
+compatibility, but I usually recommend avoiding this feature; posting
-support it mainly for compatibility.
+dates are almost always clearer and simpler.
 
    A secondary date is written after the primary date, following an
-equals sign.  The primary date's year will be used if the year is
+equals sign.  If the year is omitted, the primary date's year is
-omitted.  When running reports, the primary (left) date is used by
+assumed.  When running reports, the primary (left) date is used by
 default, but with the '--date2' flag (or '--aux-date' or '--effective'),
 the secondary (right) date will be used instead.
 
@@ -1727,116 +1725,116 @@ rules will have these tags added:
 
 Tag Table:
 Node: Top76
-Node: Transactions2033
+Node: Transactions1875
-Ref: #transactions2125
+Ref: #transactions1967
-Node: Dates3314
+Node: Dates3156
-Ref: #dates3413
+Ref: #dates3255
-Node: Simple dates3478
+Node: Simple dates3320
-Ref: #simple-dates3604
+Ref: #simple-dates3446
-Node: Secondary dates4113
+Node: Secondary dates3955
-Ref: #secondary-dates4267
+Ref: #secondary-dates4109
-Node: Posting dates5601
+Node: Posting dates5445
-Ref: #posting-dates5730
+Ref: #posting-dates5574
-Node: Status7102
+Node: Status6946
-Ref: #status7223
+Ref: #status7067
-Node: Description8931
+Node: Description8775
-Ref: #description9065
+Ref: #description8909
-Node: Payee and note9385
+Node: Payee and note9229
-Ref: #payee-and-note9499
+Ref: #payee-and-note9343
-Node: Comments9834
+Node: Comments9678
-Ref: #comments9960
+Ref: #comments9804
-Node: Tags11130
+Node: Tags10974
-Ref: #tags11245
+Ref: #tags11089
-Node: Postings12638
+Node: Postings12482
-Ref: #postings12766
+Ref: #postings12610
-Node: Virtual Postings13792
+Node: Virtual Postings13636
-Ref: #virtual-postings13909
+Ref: #virtual-postings13753
-Node: Account names15215
+Node: Account names15059
-Ref: #account-names15356
+Ref: #account-names15200
-Node: Amounts15843
+Node: Amounts15687
-Ref: #amounts15982
+Ref: #amounts15826
-Node: Digit group marks16915
+Node: Digit group marks16759
-Ref: #digit-group-marks17064
+Ref: #digit-group-marks16908
-Node: Amount display format18002
+Node: Amount display format17846
-Ref: #amount-display-format18159
+Ref: #amount-display-format18003
-Node: Transaction prices19184
+Node: Transaction prices19028
-Ref: #transaction-prices19350
+Ref: #transaction-prices19194
-Node: Balance Assertions21616
+Node: Balance Assertions21460
-Ref: #balance-assertions21796
+Ref: #balance-assertions21640
-Node: Assertions and ordering22829
+Node: Assertions and ordering22673
-Ref: #assertions-and-ordering23017
+Ref: #assertions-and-ordering22861
-Node: Assertions and included files23717
+Node: Assertions and included files23561
-Ref: #assertions-and-included-files23960
+Ref: #assertions-and-included-files23804
-Node: Assertions and multiple -f options24293
+Node: Assertions and multiple -f options24137
-Ref: #assertions-and-multiple--f-options24549
+Ref: #assertions-and-multiple--f-options24393
-Node: Assertions and commodities24681
+Node: Assertions and commodities24525
-Ref: #assertions-and-commodities24913
+Ref: #assertions-and-commodities24757
-Node: Assertions and prices26069
+Node: Assertions and prices25913
-Ref: #assertions-and-prices26283
+Ref: #assertions-and-prices26127
-Node: Assertions and subaccounts26723
+Node: Assertions and subaccounts26567
-Ref: #assertions-and-subaccounts26952
+Ref: #assertions-and-subaccounts26796
-Node: Assertions and virtual postings27276
+Node: Assertions and virtual postings27120
-Ref: #assertions-and-virtual-postings27518
+Ref: #assertions-and-virtual-postings27362
-Node: Assertions and precision27660
+Node: Assertions and precision27504
-Ref: #assertions-and-precision27853
+Ref: #assertions-and-precision27697
-Node: Balance Assignments28120
+Node: Balance Assignments27964
-Ref: #balance-assignments28294
+Ref: #balance-assignments28138
-Node: Balance assignments and prices29459
+Node: Balance assignments and prices29303
-Ref: #balance-assignments-and-prices29631
+Ref: #balance-assignments-and-prices29475
-Node: Directives29855
+Node: Directives29699
-Ref: #directives30014
+Ref: #directives29858
-Node: Comment blocks35693
+Node: Comment blocks35537
-Ref: #comment-blocks35838
+Ref: #comment-blocks35682
-Node: Including other files36014
+Node: Including other files35858
-Ref: #including-other-files36194
+Ref: #including-other-files36038
-Node: Default year36602
+Node: Default year36446
-Ref: #default-year36771
+Ref: #default-year36615
-Node: Declaring commodities37178
+Node: Declaring commodities37022
-Ref: #declaring-commodities37361
+Ref: #declaring-commodities37205
-Node: Default commodity39022
+Node: Default commodity38866
-Ref: #default-commodity39198
+Ref: #default-commodity39042
-Node: Market prices39832
+Node: Market prices39676
-Ref: #market-prices39997
+Ref: #market-prices39841
-Node: Declaring accounts40838
+Node: Declaring accounts40682
-Ref: #declaring-accounts41014
+Ref: #declaring-accounts40858
-Node: Account comments41939
+Node: Account comments41783
-Ref: #account-comments42102
+Ref: #account-comments41946
-Node: Account subdirectives42526
+Node: Account subdirectives42370
-Ref: #account-subdirectives42721
+Ref: #account-subdirectives42565
-Node: Account types43034
+Node: Account types42878
-Ref: #account-types43218
+Ref: #account-types43062
-Node: Account display order44860
+Node: Account display order44704
-Ref: #account-display-order45030
+Ref: #account-display-order44874
-Node: Rewriting accounts46181
+Node: Rewriting accounts46025
-Ref: #rewriting-accounts46366
+Ref: #rewriting-accounts46210
-Node: Basic aliases47092
+Node: Basic aliases46936
-Ref: #basic-aliases47238
+Ref: #basic-aliases47082
-Node: Regex aliases47942
+Node: Regex aliases47786
-Ref: #regex-aliases48114
+Ref: #regex-aliases47958
-Node: Combining aliases48832
+Node: Combining aliases48676
-Ref: #combining-aliases49010
+Ref: #combining-aliases48854
-Node: end aliases50286
+Node: end aliases50130
-Ref: #end-aliases50434
+Ref: #end-aliases50278
-Node: Default parent account50535
+Node: Default parent account50379
-Ref: #default-parent-account50701
+Ref: #default-parent-account50545
-Node: Periodic transactions51585
+Node: Periodic transactions51429
-Ref: #periodic-transactions51784
+Ref: #periodic-transactions51628
-Node: Periodic rule syntax53656
+Node: Periodic rule syntax53500
-Ref: #periodic-rule-syntax53862
+Ref: #periodic-rule-syntax53706
-Node: Two spaces between period expression and description!54566
+Node: Two spaces between period expression and description!54410
-Ref: #two-spaces-between-period-expression-and-description54885
+Ref: #two-spaces-between-period-expression-and-description54729
-Node: Forecasting with periodic transactions55569
+Node: Forecasting with periodic transactions55413
-Ref: #forecasting-with-periodic-transactions55874
+Ref: #forecasting-with-periodic-transactions55718
-Node: Budgeting with periodic transactions57900
+Node: Budgeting with periodic transactions57744
-Ref: #budgeting-with-periodic-transactions58139
+Ref: #budgeting-with-periodic-transactions57983
-Node: Auto postings / transaction modifiers58588
+Node: Auto postings / transaction modifiers58432
-Ref: #auto-postings-transaction-modifiers58800
+Ref: #auto-postings-transaction-modifiers58644
-Node: Auto postings and dates61029
+Node: Auto postings and dates60873
-Ref: #auto-postings-and-dates61286
+Ref: #auto-postings-and-dates61130
-Node: Auto postings and transaction balancing / inferred amounts / balance assertions61461
+Node: Auto postings and transaction balancing / inferred amounts / balance assertions61305
-Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61836
+Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61680
-Node: Auto posting tags62214
+Node: Auto posting tags62058
-Ref: #auto-posting-tags62453
+Ref: #auto-posting-tags62297
 
 End Tag Table
 

hledger-lib/hledger_journal.m4.md

@@ -27,9 +27,17 @@ hledger and ledger on the same journal file, eg to validate the results
 you're getting.
 
 You can use hledger without learning any more about this file; just
-use the [add](#add) or [web](#web) commands to create and update it.
+use the [add](#add) or [web](#web) or [import](#import) commands to
-Many users, though, also edit the journal file directly with a text
+create and update it.
-editor, perhaps assisted by the helper modes for emacs or vim.
+
+Many users, though, edit the journal file with a text editor,
+and track changes with a version control system such as git.
+Editor addons such as
+ledger-mode or hledger-mode for Emacs, 
+vim-ledger for Vim, 
+and hledger-vscode for Visual Studio Code,
+make this easier, adding colour, formatting, tab completion, and useful commands.
+See [Editor configuration](editors.html) at hledger.org for the full list.
 
 <!--
 Here's an example:
@@ -64,14 +72,6 @@ Here's an example:
 ```
 -->
 
-Helper modes exist for popular text editors, which make working with
-journal files easier. They add colour, formatting, tab completion, and
-helpful commands, and are quite recommended if you edit your journal
-with a text editor. They include ledger-mode or hledger-mode for
-Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
-others. See the [Editor configuration](editors.html) at hledger.org
-for the latest information.
-
 _man_({{
 # FILE FORMAT
 }})
@@ -127,19 +127,20 @@ dates](hledger.html#smart-dates) documented in the hledger manual.)
 
 Real-life transactions sometimes involve more than one date - eg the date
 you write a cheque, and the date it clears in your bank.  When you want to
-model this, eg for more accurate balances, you can specify individual
+model this, for more accurate daily balances, you can specify individual
 [posting dates](#posting-dates).
 
-Or, you can use the older *secondary date* feature. 
+Or, you can use the older *secondary date* feature
-(Ledger calls it auxiliary date or effective date.)
+(Ledger calls it auxiliary date or effective date).
-But I would recommend avoiding this feature; posting dates are almost
+Note: we support this for compatibility, but I usually recommend
-always clearer and simpler. We support it mainly for compatibility.
+avoiding this feature; posting dates are almost always clearer and
+simpler.
 <!-- (Secondary dates require you to remember to use them consistently in -->
 <!-- your journal, and to choose them or not for each report.) -->
 
 A secondary date is written after the primary date, following an
-equals sign. The primary date's year will be used if the year is
+equals sign. If the year is omitted, the primary date's year is
-omitted. When running reports, the primary (left) date is used by
+assumed. When running reports, the primary (left) date is used by
 default, but with the `--date2` flag (or `--aux-date` or
 `--effective`), the secondary (right) date will be used instead.