update generated journal, csv manuals

[ci skip]
2024-12-26 03:42:25 +03:00 · 2019-01-19 15:29:23 -08:00 · 2019-01-19 15:29:23 -08:00 · d4fa546d27
commit d4fa546d27
parent 240406706a
6 changed files with 333 additions and 308 deletions
--- a/hledger-lib/hledger_csv.5
+++ b/hledger-lib/hledger_csv.5
@ -112,15 +112,15 @@ Examples:
 .IP
 .nf
 \f[C]
-#\ for\ dates\ like\ "6/11/2013":
-date\-format\ %\-d/%\-m/%Y
+#\ for\ dates\ like\ "11/06/2013":
+date\-format\ %m/%d/%Y
 \f[]
 .fi
 .IP
 .nf
 \f[C]
-#\ for\ dates\ like\ "11/06/2013":
-date\-format\ %m/%d/%Y
+#\ for\ dates\ like\ "6/11/2013"\ (note\ the\ \-\ to\ make\ leading\ zeros\ optional):
+date\-format\ %\-d/%\-m/%Y
 \f[]
 .fi
 .IP
--- a/hledger-lib/hledger_csv.info
+++ b/hledger-lib/hledger_csv.info
@ -113,12 +113,12 @@ File: hledger_csv.info,  Node: date-format,  Next: field list,  Prev: skip,  Up:
 DATEFMT is a strptime-like date parsing pattern, which must parse the
 date field values completely.  Examples:

-# for dates like "6/11/2013":
-date-format %-d/%-m/%Y
-
 # for dates like "11/06/2013":
 date-format %m/%d/%Y

+# for dates like "6/11/2013" (note the - to make leading zeros optional):
+date-format %-d/%-m/%Y
+
 # for dates like "2013-Nov-06":
 date-format %Y-%h-%d

@ -323,27 +323,27 @@ Node: skip2539
 Ref: #skip2633
 Node: date-format2805
 Ref: #date-format2932
-Node: field list3438
-Ref: #field-list3575
-Node: field assignment4280
-Ref: #field-assignment4435
-Node: conditional block4939
-Ref: #conditional-block5093
-Node: include5989
-Ref: #include6119
-Node: newest-first6350
-Ref: #newest-first6464
-Node: CSV TIPS6875
-Ref: #csv-tips6969
-Node: CSV ordering7087
-Ref: #csv-ordering7205
-Node: CSV accounts7386
-Ref: #csv-accounts7524
-Node: CSV amounts7778
-Ref: #csv-amounts7924
-Node: CSV balance assertions8699
-Ref: #csv-balance-assertions8881
-Node: Reading multiple CSV files9086
-Ref: #reading-multiple-csv-files9256
+Node: field list3482
+Ref: #field-list3619
+Node: field assignment4324
+Ref: #field-assignment4479
+Node: conditional block4983
+Ref: #conditional-block5137
+Node: include6033
+Ref: #include6163
+Node: newest-first6394
+Ref: #newest-first6508
+Node: CSV TIPS6919
+Ref: #csv-tips7013
+Node: CSV ordering7131
+Ref: #csv-ordering7249
+Node: CSV accounts7430
+Ref: #csv-accounts7568
+Node: CSV amounts7822
+Ref: #csv-amounts7968
+Node: CSV balance assertions8743
+Ref: #csv-balance-assertions8925
+Node: Reading multiple CSV files9130
+Ref: #reading-multiple-csv-files9300

 End Tag Table
--- a/hledger-lib/hledger_csv.txt
+++ b/hledger-lib/hledger_csv.txt
@ -88,12 +88,12 @@ CSV RULES
       is a strptime-like date parsing pattern,  which  must  parse  the  date
       field values completely.  Examples:

-              # for dates like "6/11/2013":
-              date-format %-d/%-m/%Y
-
              # for dates like "11/06/2013":
              date-format %m/%d/%Y

+              # for dates like "6/11/2013" (note the - to make leading zeros optional):
+              date-format %-d/%-m/%Y
+
              # for dates like "2013-Nov-06":
              date-format %Y-%h-%d

--- a/hledger-lib/hledger_journal.5
+++ b/hledger-lib/hledger_journal.5
@ -635,6 +635,13 @@ Balance assertions are checked against all postings, both real and
 virtual.
 They are not affected by the \f[C]\-\-real/\-R\f[] flag or
 \f[C]real:\f[] query.
+.SS Assertions and precision
+.PP
+Balance assertions compare the exactly calculated amounts, which are not
+always what is shown by reports.
+Eg a commodity directive may limit the display precision, but this will
+not affect balance assertions.
+Balance assertion failure messages show exact amounts.
 .SS Balance Assignments
 .PP
 Ledger\-style balance assignments are also supported.
@ -1514,21 +1521,20 @@ Partial or relative dates (M/D, D, tomorrow, last week) in the period
 expression can work (useful or not).
 They will be relative to today's date, unless a Y default year directive
 is in effect, in which case they will be relative to Y/1/1.
+.SS Two spaces after the period expression
 .PP
-Period expressions must be terminated by \f[B]two or more spaces\f[] if
-followed by additional fields.
-For example, the periodic transaction given below includes a transaction
-description \[lq]paycheck\[rq], which is separated from the period
-expression by a double space.
-If not for the second space, hledger would attempt (and fail) to parse
-\[lq]paycheck\[rq] as a part of the period expression.
+If the period expression is followed by a transaction description, these
+must be separated by \f[B]two or more spaces\f[].
+This helps hledger know where the period expression ends, so that
+descriptions can not accidentally alter their meaning, as in this
+example:
 .IP
 .nf
 \f[C]
-;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ or\ more\ spaces
-;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||
-;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ vv
-~\ every\ 2\ weeks\ from\ 2018/6/4\ to\ 2018/9\ \ paycheck
+;\ 2\ or\ more\ spaces\ needed\ here,\ so\ the\ period\ is\ not\ understood\ as\ "every\ 2\ months\ in\ 2020"
+;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||
+;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ vv
+~\ every\ 2\ months\ \ in\ 2020,\ we\ will\ review
 \ \ \ \ assets:bank:checking\ \ \ $1500
 \ \ \ \ income:acme\ inc
 \f[]
--- a/hledger-lib/hledger_journal.info
+++ b/hledger-lib/hledger_journal.info
@ -476,6 +476,7 @@ or for reading Ledger files.
 * Assertions and prices::
 * Assertions and subaccounts::
 * Assertions and virtual postings::
+* Assertions and precision::


 File: hledger_journal.info,  Node: Assertions and ordering,  Next: Assertions and included files,  Up: Balance Assertions
@ -599,7 +600,7 @@ $ hledger bal checking --flat
                   2


-File: hledger_journal.info,  Node: Assertions and virtual postings,  Prev: Assertions and subaccounts,  Up: Balance Assertions
+File: hledger_journal.info,  Node: Assertions and virtual postings,  Next: Assertions and precision,  Prev: Assertions and subaccounts,  Up: Balance Assertions

 1.9.7 Assertions and virtual postings
 -------------------------------------
@ -608,6 +609,17 @@ Balance assertions are checked against all postings, both real and
 virtual.  They are not affected by the '--real/-R' flag or 'real:'
 query.

+
+File: hledger_journal.info,  Node: Assertions and precision,  Prev: Assertions and virtual postings,  Up: Balance Assertions
+
+1.9.8 Assertions and precision
+------------------------------
+
+Balance assertions compare the exactly calculated amounts, which are not
+always what is shown by reports.  Eg a commodity directive may limit the
+display precision, but this will not affect balance assertions.  Balance
+assertion failure messages show exact amounts.
+

 File: hledger_journal.info,  Node: Balance Assignments,  Next: Transaction prices,  Prev: Balance Assertions,  Up: FILE FORMAT

@ -1342,30 +1354,34 @@ date must fall on a natural boundary of the interval.  Eg 'monthly from
 expression can work (useful or not).  They will be relative to today's
 date, unless a Y default year directive is in effect, in which case they
 will be relative to Y/1/1.
-
-   Period expressions must be terminated by *two or more spaces* if
-followed by additional fields.  For example, the periodic transaction
-given below includes a transaction description "paycheck", which is
-separated from the period expression by a double space.  If not for the
-second space, hledger would attempt (and fail) to parse "paycheck" as a
-part of the period expression.
-
-;                                2 or more spaces
-;                                      ||
-;                                      vv
-~ every 2 weeks from 2018/6/4 to 2018/9  paycheck
-    assets:bank:checking   $1500
-    income:acme inc
-
 * Menu:

+* Two spaces after the period expression::
 * Forecasting with periodic transactions::
 * Budgeting with periodic transactions::


-File: hledger_journal.info,  Node: Forecasting with periodic transactions,  Next: Budgeting with periodic transactions,  Up: Periodic transactions
+File: hledger_journal.info,  Node: Two spaces after the period expression,  Next: Forecasting with periodic transactions,  Up: Periodic transactions

-1.15.1 Forecasting with periodic transactions
+1.15.1 Two spaces after the period expression
+---------------------------------------------
+
+If the period expression is followed by a transaction description, these
+must be separated by *two or more spaces*.  This helps hledger know
+where the period expression ends, so that descriptions can not
+accidentally alter their meaning, as in this example:
+
+; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020"
+;               ||
+;               vv
+~ every 2 months  in 2020, we will review
+    assets:bank:checking   $1500
+    income:acme inc
+
+
+File: hledger_journal.info,  Node: Forecasting with periodic transactions,  Next: Budgeting with periodic transactions,  Prev: Two spaces after the period expression,  Up: Periodic transactions
+
+1.15.2 Forecasting with periodic transactions
 ---------------------------------------------

 With the '--forecast' flag, each periodic transaction rule generates
@ -1408,7 +1424,7 @@ disables forecast transactions on previous dates.)

 File: hledger_journal.info,  Node: Budgeting with periodic transactions,  Prev: Forecasting with periodic transactions,  Up: Periodic transactions

-1.15.2 Budgeting with periodic transactions
+1.15.3 Budgeting with periodic transactions
 -------------------------------------------

 With the '--budget' flag, currently supported by the balance command,
@ -1549,71 +1565,75 @@ Node: Virtual Postings15032
 Ref: #virtual-postings15191
 Node: Balance Assertions16411
 Ref: #balance-assertions16586
-Node: Assertions and ordering17508
-Ref: #assertions-and-ordering17694
-Node: Assertions and included files18394
-Ref: #assertions-and-included-files18635
-Node: Assertions and multiple -f options18968
-Ref: #assertions-and-multiple--f-options19222
-Node: Assertions and commodities19354
-Ref: #assertions-and-commodities19584
-Node: Assertions and prices20772
-Ref: #assertions-and-prices20984
-Node: Assertions and subaccounts21093
-Ref: #assertions-and-subaccounts21320
-Node: Assertions and virtual postings21841
-Ref: #assertions-and-virtual-postings22048
-Node: Balance Assignments22190
-Ref: #balance-assignments22371
-Node: Transaction prices23491
-Ref: #transaction-prices23660
-Node: Comments25928
-Ref: #comments26062
-Node: Tags27232
-Ref: #tags27350
-Node: Directives28752
-Ref: #directives28895
-Node: Comment blocks34502
-Ref: #comment-blocks34647
-Node: Including other files34823
-Ref: #including-other-files35003
-Node: Default year35411
-Ref: #default-year35580
-Node: Declaring commodities36003
-Ref: #declaring-commodities36186
-Node: Default commodity37413
-Ref: #default-commodity37589
-Node: Market prices38225
-Ref: #market-prices38390
-Node: Declaring accounts39231
-Ref: #declaring-accounts39407
-Node: Account types40364
-Ref: #account-types40513
-Node: Account comments41587
-Ref: #account-comments41772
-Node: Account display order42093
-Ref: #account-display-order42266
-Node: Rewriting accounts43388
-Ref: #rewriting-accounts43573
-Node: Basic aliases44307
-Ref: #basic-aliases44453
-Node: Regex aliases45157
-Ref: #regex-aliases45328
-Node: Multiple aliases46046
-Ref: #multiple-aliases46221
-Node: end aliases46719
-Ref: #end-aliases46866
-Node: Default parent account46967
-Ref: #default-parent-account47133
-Node: Periodic transactions48017
-Ref: #periodic-transactions48199
-Node: Forecasting with periodic transactions49902
-Ref: #forecasting-with-periodic-transactions50145
-Node: Budgeting with periodic transactions51832
-Ref: #budgeting-with-periodic-transactions52071
-Node: Transaction Modifiers52530
-Ref: #transaction-modifiers52693
-Node: EDITOR SUPPORT54674
-Ref: #editor-support54792
+Node: Assertions and ordering17537
+Ref: #assertions-and-ordering17723
+Node: Assertions and included files18423
+Ref: #assertions-and-included-files18664
+Node: Assertions and multiple -f options18997
+Ref: #assertions-and-multiple--f-options19251
+Node: Assertions and commodities19383
+Ref: #assertions-and-commodities19613
+Node: Assertions and prices20801
+Ref: #assertions-and-prices21013
+Node: Assertions and subaccounts21122
+Ref: #assertions-and-subaccounts21349
+Node: Assertions and virtual postings21870
+Ref: #assertions-and-virtual-postings22110
+Node: Assertions and precision22252
+Ref: #assertions-and-precision22443
+Node: Balance Assignments22710
+Ref: #balance-assignments22891
+Node: Transaction prices24011
+Ref: #transaction-prices24180
+Node: Comments26448
+Ref: #comments26582
+Node: Tags27752
+Ref: #tags27870
+Node: Directives29272
+Ref: #directives29415
+Node: Comment blocks35022
+Ref: #comment-blocks35167
+Node: Including other files35343
+Ref: #including-other-files35523
+Node: Default year35931
+Ref: #default-year36100
+Node: Declaring commodities36523
+Ref: #declaring-commodities36706
+Node: Default commodity37933
+Ref: #default-commodity38109
+Node: Market prices38745
+Ref: #market-prices38910
+Node: Declaring accounts39751
+Ref: #declaring-accounts39927
+Node: Account types40884
+Ref: #account-types41033
+Node: Account comments42107
+Ref: #account-comments42292
+Node: Account display order42613
+Ref: #account-display-order42786
+Node: Rewriting accounts43908
+Ref: #rewriting-accounts44093
+Node: Basic aliases44827
+Ref: #basic-aliases44973
+Node: Regex aliases45677
+Ref: #regex-aliases45848
+Node: Multiple aliases46566
+Ref: #multiple-aliases46741
+Node: end aliases47239
+Ref: #end-aliases47386
+Node: Default parent account47487
+Ref: #default-parent-account47653
+Node: Periodic transactions48537
+Ref: #periodic-transactions48719
+Node: Two spaces after the period expression49844
+Ref: #two-spaces-after-the-period-expression50089
+Node: Forecasting with periodic transactions50574
+Ref: #forecasting-with-periodic-transactions50864
+Node: Budgeting with periodic transactions52551
+Ref: #budgeting-with-periodic-transactions52790
+Node: Transaction Modifiers53249
+Ref: #transaction-modifiers53412
+Node: EDITOR SUPPORT55393
+Ref: #editor-support55511

 End Tag Table
--- a/hledger-lib/hledger_journal.txt
+++ b/hledger-lib/hledger_journal.txt
@ -472,6 +472,12 @@ FILE FORMAT
       Balance assertions are checked against all postings, both real and vir-
       tual.  They are not affected by the --real/-R flag or real: query.

+   Assertions and precision
+       Balance assertions compare the exactly calculated  amounts,  which  are
+       not  always  what  is  shown  by reports.  Eg a commodity directive may
+       limit the display precision, but this will not  affect  balance  asser-
+       tions.  Balance assertion failure messages show exact amounts.
+
   Balance Assignments
       Ledger-style  balance  assignments  are also supported.  These are like
       balance assertions, but with no posting amount on the left side of  the
@ -675,12 +681,6 @@ FILE FORMAT
                                                                                    in reports


-
-
-
-
-
-
       D                                             declare a commodity,  number   commodity: all com-
                                                     notation & display style for   modityless  entries
                                                     commodityless amounts          in all files;  num-
@ -1090,17 +1090,16 @@ FILE FORMAT
       date, unless a Y default year directive is in  effect,  in  which  case
       they will be relative to Y/1/1.

-       Period expressions must be terminated by two or more spaces if followed
-       by  additional  fields.   For  example,  the periodic transaction given
-       below includes a transaction description "paycheck", which is separated
-       from  the  period  expression by a double space.  If not for the second
-       space, hledger would attempt (and fail) to parse "paycheck" as  a  part
-       of the period expression.
+   Two spaces after the period expression
+       If  the  period  expression  is  followed by a transaction description,
+       these must be separated by two or more spaces.  This helps hledger know
+       where the period expression ends, so that descriptions can not acciden-
+       tally alter their meaning, as in this example:

-              ;                                2 or more spaces
+              ; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020"
              ;               ||
              ;               vv
-              ~ every 2 weeks from 2018/6/4 to 2018/9  paycheck
+              ~ every 2 months  in 2020, we will review
                  assets:bank:checking   $1500
                  income:acme inc