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

[ci skip]
2024-12-26 20:02:27 +03:00 · 2020-01-29 08:42:04 -08:00 · 2020-01-29 08:42:04 -08:00 · c67ffedea5
commit c67ffedea5
parent 06a54f70b0
4 changed files with 484 additions and 493 deletions
--- a/hledger-lib/hledger_journal.5
+++ b/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.
-Many users, though, also edit the journal file directly with a text
-editor, perhaps assisted by the helper modes for emacs or vim.
+the add or web or import commands to create and update it.
 .PP
-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 at hledger.org for the latest information.
+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 at hledger.org for the full list.
 .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.
-(Ledger calls it auxiliary date or effective date.) But I would
-recommend avoiding this feature; posting dates are almost always clearer
-and simpler.
-We support it mainly for compatibility.
+Or, you can use the older \f[I]secondary date\f[R] feature (Ledger calls
+it auxiliary date or effective date).
+Note: we support this for compatibility, but I usually recommend
+avoiding this feature; posting dates are almost always clearer and
+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.
--- a/hledger-lib/hledger_journal.info
+++ b/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,
-though, also edit the journal file directly with a text editor, perhaps
-assisted by the helper modes for emacs or vim.
+use the add or web or import commands to create and update it.

-   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 at hledger.org for the latest information.
+   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 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
-auxiliary date or effective date.)  But I would recommend avoiding this
-feature; posting dates are almost always clearer and simpler.  We
-support it mainly for compatibility.
+   Or, you can use the older _secondary date_ feature (Ledger calls it
+auxiliary date or effective date).  Note: we support this for
+compatibility, but I usually recommend avoiding this feature; posting
+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
-omitted.  When running reports, the primary (left) date is used by
+equals sign.  If the year is omitted, the primary date's year is
+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
-Ref: #transactions2125
-Node: Dates3314
-Ref: #dates3413
-Node: Simple dates3478
-Ref: #simple-dates3604
-Node: Secondary dates4113
-Ref: #secondary-dates4267
-Node: Posting dates5601
-Ref: #posting-dates5730
-Node: Status7102
-Ref: #status7223
-Node: Description8931
-Ref: #description9065
-Node: Payee and note9385
-Ref: #payee-and-note9499
-Node: Comments9834
-Ref: #comments9960
-Node: Tags11130
-Ref: #tags11245
-Node: Postings12638
-Ref: #postings12766
-Node: Virtual Postings13792
-Ref: #virtual-postings13909
-Node: Account names15215
-Ref: #account-names15356
-Node: Amounts15843
-Ref: #amounts15982
-Node: Digit group marks16915
-Ref: #digit-group-marks17064
-Node: Amount display format18002
-Ref: #amount-display-format18159
-Node: Transaction prices19184
-Ref: #transaction-prices19350
-Node: Balance Assertions21616
-Ref: #balance-assertions21796
-Node: Assertions and ordering22829
-Ref: #assertions-and-ordering23017
-Node: Assertions and included files23717
-Ref: #assertions-and-included-files23960
-Node: Assertions and multiple -f options24293
-Ref: #assertions-and-multiple--f-options24549
-Node: Assertions and commodities24681
-Ref: #assertions-and-commodities24913
-Node: Assertions and prices26069
-Ref: #assertions-and-prices26283
-Node: Assertions and subaccounts26723
-Ref: #assertions-and-subaccounts26952
-Node: Assertions and virtual postings27276
-Ref: #assertions-and-virtual-postings27518
-Node: Assertions and precision27660
-Ref: #assertions-and-precision27853
-Node: Balance Assignments28120
-Ref: #balance-assignments28294
-Node: Balance assignments and prices29459
-Ref: #balance-assignments-and-prices29631
-Node: Directives29855
-Ref: #directives30014
-Node: Comment blocks35693
-Ref: #comment-blocks35838
-Node: Including other files36014
-Ref: #including-other-files36194
-Node: Default year36602
-Ref: #default-year36771
-Node: Declaring commodities37178
-Ref: #declaring-commodities37361
-Node: Default commodity39022
-Ref: #default-commodity39198
-Node: Market prices39832
-Ref: #market-prices39997
-Node: Declaring accounts40838
-Ref: #declaring-accounts41014
-Node: Account comments41939
-Ref: #account-comments42102
-Node: Account subdirectives42526
-Ref: #account-subdirectives42721
-Node: Account types43034
-Ref: #account-types43218
-Node: Account display order44860
-Ref: #account-display-order45030
-Node: Rewriting accounts46181
-Ref: #rewriting-accounts46366
-Node: Basic aliases47092
-Ref: #basic-aliases47238
-Node: Regex aliases47942
-Ref: #regex-aliases48114
-Node: Combining aliases48832
-Ref: #combining-aliases49010
-Node: end aliases50286
-Ref: #end-aliases50434
-Node: Default parent account50535
-Ref: #default-parent-account50701
-Node: Periodic transactions51585
-Ref: #periodic-transactions51784
-Node: Periodic rule syntax53656
-Ref: #periodic-rule-syntax53862
-Node: Two spaces between period expression and description!54566
-Ref: #two-spaces-between-period-expression-and-description54885
-Node: Forecasting with periodic transactions55569
-Ref: #forecasting-with-periodic-transactions55874
-Node: Budgeting with periodic transactions57900
-Ref: #budgeting-with-periodic-transactions58139
-Node: Auto postings / transaction modifiers58588
-Ref: #auto-postings-transaction-modifiers58800
-Node: Auto postings and dates61029
-Ref: #auto-postings-and-dates61286
-Node: Auto postings and transaction balancing / inferred amounts / balance assertions61461
-Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61836
-Node: Auto posting tags62214
-Ref: #auto-posting-tags62453
+Node: Transactions1875
+Ref: #transactions1967
+Node: Dates3156
+Ref: #dates3255
+Node: Simple dates3320
+Ref: #simple-dates3446
+Node: Secondary dates3955
+Ref: #secondary-dates4109
+Node: Posting dates5445
+Ref: #posting-dates5574
+Node: Status6946
+Ref: #status7067
+Node: Description8775
+Ref: #description8909
+Node: Payee and note9229
+Ref: #payee-and-note9343
+Node: Comments9678
+Ref: #comments9804
+Node: Tags10974
+Ref: #tags11089
+Node: Postings12482
+Ref: #postings12610
+Node: Virtual Postings13636
+Ref: #virtual-postings13753
+Node: Account names15059
+Ref: #account-names15200
+Node: Amounts15687
+Ref: #amounts15826
+Node: Digit group marks16759
+Ref: #digit-group-marks16908
+Node: Amount display format17846
+Ref: #amount-display-format18003
+Node: Transaction prices19028
+Ref: #transaction-prices19194
+Node: Balance Assertions21460
+Ref: #balance-assertions21640
+Node: Assertions and ordering22673
+Ref: #assertions-and-ordering22861
+Node: Assertions and included files23561
+Ref: #assertions-and-included-files23804
+Node: Assertions and multiple -f options24137
+Ref: #assertions-and-multiple--f-options24393
+Node: Assertions and commodities24525
+Ref: #assertions-and-commodities24757
+Node: Assertions and prices25913
+Ref: #assertions-and-prices26127
+Node: Assertions and subaccounts26567
+Ref: #assertions-and-subaccounts26796
+Node: Assertions and virtual postings27120
+Ref: #assertions-and-virtual-postings27362
+Node: Assertions and precision27504
+Ref: #assertions-and-precision27697
+Node: Balance Assignments27964
+Ref: #balance-assignments28138
+Node: Balance assignments and prices29303
+Ref: #balance-assignments-and-prices29475
+Node: Directives29699
+Ref: #directives29858
+Node: Comment blocks35537
+Ref: #comment-blocks35682
+Node: Including other files35858
+Ref: #including-other-files36038
+Node: Default year36446
+Ref: #default-year36615
+Node: Declaring commodities37022
+Ref: #declaring-commodities37205
+Node: Default commodity38866
+Ref: #default-commodity39042
+Node: Market prices39676
+Ref: #market-prices39841
+Node: Declaring accounts40682
+Ref: #declaring-accounts40858
+Node: Account comments41783
+Ref: #account-comments41946
+Node: Account subdirectives42370
+Ref: #account-subdirectives42565
+Node: Account types42878
+Ref: #account-types43062
+Node: Account display order44704
+Ref: #account-display-order44874
+Node: Rewriting accounts46025
+Ref: #rewriting-accounts46210
+Node: Basic aliases46936
+Ref: #basic-aliases47082
+Node: Regex aliases47786
+Ref: #regex-aliases47958
+Node: Combining aliases48676
+Ref: #combining-aliases48854
+Node: end aliases50130
+Ref: #end-aliases50278
+Node: Default parent account50379
+Ref: #default-parent-account50545
+Node: Periodic transactions51429
+Ref: #periodic-transactions51628
+Node: Periodic rule syntax53500
+Ref: #periodic-rule-syntax53706
+Node: Two spaces between period expression and description!54410
+Ref: #two-spaces-between-period-expression-and-description54729
+Node: Forecasting with periodic transactions55413
+Ref: #forecasting-with-periodic-transactions55718
+Node: Budgeting with periodic transactions57744
+Ref: #budgeting-with-periodic-transactions57983
+Node: Auto postings / transaction modifiers58432
+Ref: #auto-postings-transaction-modifiers58644
+Node: Auto postings and dates60873
+Ref: #auto-postings-and-dates61130
+Node: Auto postings and transaction balancing / inferred amounts / balance assertions61305
+Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61680
+Node: Auto posting tags62058
+Ref: #auto-posting-tags62297

 End Tag Table

--- a/hledger-lib/hledger_journal.m4.md
+++ b/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.
-Many users, though, also edit the journal file directly with a text
-editor, perhaps assisted by the helper modes for emacs or vim.
+use the [add](#add) or [web](#web) or [import](#import) commands to
+create and update it.
+
+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. 
-(Ledger calls it auxiliary date or effective date.)
-But I would recommend avoiding this feature; posting dates are almost
-always clearer and simpler. We support it mainly for compatibility.
+Or, you can use the older *secondary date* feature
+(Ledger calls it auxiliary date or effective date).
+Note: we support this for compatibility, but I usually recommend
+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
-omitted. When running reports, the primary (left) date is used by
+equals sign. If the year is omitted, the primary date's year is
+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.

--- a/hledger-lib/hledger_journal.txt
+++ b/hledger-lib/hledger_journal.txt
@ -22,17 +22,14 @@ DESCRIPTION
       ting.

       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,  though,
-       also  edit  the  journal  file directly with a text editor, perhaps as-
-       sisted by the helper modes for emacs or vim.
+       the add or web or import commands to create and update it.

-       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 at hledger.org for the latest in-
-       formation.
+       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 configura-
+       tion at hledger.org for the full list.

 FILE FORMAT
       Here's  a  description  of  each part of the file format (and hledger's
@ -83,16 +80,16 @@ FILE FORMAT
   Secondary dates
       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  in-
-       dividual posting dates.
+       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
-       auxiliary date or effective date.) But I would recommend avoiding  this
-       feature;  posting dates are almost always clearer and simpler.  We sup-
-       port it mainly for compatibility.
+       Or, you can use the older secondary date feature (Ledger calls it  aux-
+       iliary  date or effective date).  Note: we support this for compatibil-
+       ity, but I usually recommend avoiding this feature; posting  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 omitted.
+       sign.  If the year is omitted, the  primary  date's  year  is  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.
@ -664,6 +661,9 @@ FILE FORMAT
       tive       rective     rec-                                     2018/06)
                              tives
       ------------------------------------------------------------------------------------
+
+
+
       account                any       document account names,  de-   all entries in  all
                              text      clare  account  types & dis-   files,   before  or
                                        play order                     after
@ -672,11 +672,6 @@ FILE FORMAT
                                                                       tries  until end of
                                                                       current file or end
                                                                       directive
-
-
-
-
-
       apply      end apply             prepend  a  common parent to   following       in-
       account    account               account names                  line/included   en-
                                                                       tries until end  of