;doc: update manuals

hledger/hledger.1

@@ -764,6 +764,21 @@ T}@T{
 -1, 0, 1 periods from the current period
 T}
 T{
+\f[C]in n days/weeks/months/quarters/years\f[R]
+T}@T{
+n periods from the current period
+T}
+T{
+\f[C]n days/weeks/months/quarters/years ahead\f[R]
+T}@T{
+n periods from the current period
+T}
+T{
+\f[C]n days/weeks/months/quarters/years ago\f[R]
+T}@T{
+-n periods from the current period
+T}
+T{
 \f[C]20181201\f[R]
 T}@T{
 8 digit YYYYMMDD with valid year month and day
@@ -1576,11 +1591,20 @@ hledger will assume this transaction is balanced, inferring that the
 conversion rate must be 1 EUR = 1.20 USD.
 You can see the inferred rate by using \f[C]hledger print -x\f[R].
 .PP
-Pro: - Easy, concise - hledger can do cost reporting
+Pro:
+.IP \[bu] 2
+Easy, concise
+.IP \[bu] 2
+hledger can do cost reporting
 .PP
-Con: - Less error checking - typos in amounts or commodity symbols may
+Con:
-not be detected - conversion rate is not clear - disturbs the accounting
+.IP \[bu] 2
-equation
+Less error checking - typos in amounts or commodity symbols may not be
+detected
+.IP \[bu] 2
+conversion rate is not clear
+.IP \[bu] 2
+disturbs the accounting equation
 .PP
 You can prevent accidental implicit conversions due to a mistyped
 commodity symbol, by using \f[C]hledger check commodities\f[R].
@@ -1602,10 +1626,19 @@ You can add the conversion rate using \[at] notation:
 Now hledger will check that 100 * 1.20 = 120, and would report an error
 otherwise.
 .PP
-Pro: - Still concise - makes the conversion rate clear - provides some
+Pro:
-error checking - hledger can do cost reporting
+.IP \[bu] 2
+Still concise
+.IP \[bu] 2
+makes the conversion rate clear
+.IP \[bu] 2
+provides some error checking
+.IP \[bu] 2
+hledger can do cost reporting
 .PP
-Con: - Disturbs the accounting equation
+Con:
+.IP \[bu] 2
+Disturbs the accounting equation
 .SS Equity conversion
 .PP
 In strict double entry bookkeeping, the above transaction is not
@@ -1627,12 +1660,21 @@ commodity, using an equity account:
 \f[R]
 .fi
 .PP
-Pro: - Preserves the accounting equation - keeps track of conversions
+Pro:
-and related gains/losses in one place - works in any double entry
+.IP \[bu] 2
-accounting system
+Preserves the accounting equation
+.IP \[bu] 2
+keeps track of conversions and related gains/losses in one place
+.IP \[bu] 2
+works in any double entry accounting system
 .PP
-Con: - More verbose - conversion rate is not clear - hledger can not do
+Con:
-cost reporting
+.IP \[bu] 2
+More verbose
+.IP \[bu] 2
+conversion rate is not clear
+.IP \[bu] 2
+hledger can not do cost reporting
 .SS Priced equity conversion
 .PP
 Another possible notation would be to record both the conversion rate
@@ -5330,6 +5372,8 @@ Valuation affects posting amounts but not balance assertion or balance
 assignment amounts, potentially causing those to fail.
 .IP \[bu] 2
 Auto postings can generate postings with too many missing amounts.
+.IP \[bu] 2
+Account aliases can generate bad account names.
 .PP
 Normally, the journal entry\[aq]s explicit or implicit amount style is
 preserved.
@@ -7881,8 +7925,10 @@ data entry and a less verbose journal
 .IP \[bu] 2
 adapting old journals to your current chart of accounts
 .IP \[bu] 2
-experimenting with new account organisations, like a new hierarchy or
+experimenting with new account organisations, like a new hierarchy
-combining two accounts into one
+.IP \[bu] 2
+combining two accounts into one, eg to see their sum or difference on
+one line
 .IP \[bu] 2
 customising reports
 .PP
@@ -7890,6 +7936,10 @@ Account aliases also rewrite account names in account directives.
 They do not affect account names being entered via hledger add or
 hledger-web.
 .PP
+Account aliases are very powerful.
+They are generally easy to use correctly, but you can also generate
+invalid account names with them; more on this below.
+.PP
 See also Rewrite account names.
 .SS Basic aliases
 .PP
@@ -8034,6 +8084,48 @@ journal so far, or defined on the command line) with this directive:
 end aliases
 \f[R]
 .fi
+.SS Aliases can generate bad account names
+.PP
+Be aware that account aliases can produce malformed account names, which
+could cause confusing reports or invalid \f[C]print\f[R] output.
+For example, you could erase all account names:
+.IP
+.nf
+\f[C]
+2021-01-01
+  a:aa     1
+  b
+\f[R]
+.fi
+.IP
+.nf
+\f[C]
+$ hledger print --alias \[aq]/.*/=\[aq]
+2021-01-01
+                   1
+\f[R]
+.fi
+.PP
+The above \f[C]print\f[R] output is not a valid journal.
+Or you could insert an illegal double space, causing \f[C]print\f[R]
+output that would give a different journal when reparsed:
+.IP
+.nf
+\f[C]
+2021-01-01
+  old    1
+  other
+\f[R]
+.fi
+.IP
+.nf
+\f[C]
+$ hledger print --alias old=\[dq]new  USD\[dq] | hledger -f- print
+2021-01-01
+    new             USD 1
+    other
+\f[R]
+.fi
 .SS Default parent account
 .PP
 You can specify a parent account which will be prepended to all accounts
@@ -9625,14 +9717,14 @@ if %out [1-9]
 .fi
 .RE
 .IP "3." 3
-\f[B]If you are stuck with hledger <1.17, or you want posting 2\[aq]s
+\f[B]If you want posting 2\[aq]s amount converted to cost:\f[R]
-amount converted to cost:\f[R]
 .PD 0
 .P
 .PD
 Assign to \f[C]amount\f[R] (or to \f[C]amount-in\f[R] and
 \f[C]amount-out\f[R]).
-(The old numberless syntax, which sets amount1 and amount2.)
+(This is the legacy numberless syntax, which sets amount1 and amount2
+and converts amount2 to cost.)
 .IP "4." 3
 \f[B]If the CSV has the balance instead of the transaction amount:\f[R]
 .PD 0
@@ -10171,7 +10263,7 @@ $ hledger help --help     # show more detailed help for the help command
 .fi
 .PP
 Find more docs, chat, mail list, reddit, issue tracker:
-https://hledger.org#help-feedback
+https://hledger.org/support.html-feedback
 .SS Constructing command lines
 .PP
 hledger has an extensive and powerful command line interface.

hledger/hledger.txt

@@ -560,6 +560,15 @@ TIME PERIODS
        last/this/next             -1, 0, 1 periods from the current period
        day/week/month/quar-
        ter/year
+       in                     n   n periods from the current period
+       days/weeks/months/quar-
+       ters/years
+       n                          n periods from the current period
+       days/weeks/months/quar-
+       ters/years ahead
+       n                          -n periods from the current period
+       days/weeks/months/quar-
+       ters/years ago
        20181201                   8 digit YYYYMMDD with valid year month and day
        201812                     6 digit YYYYMM with valid year and month
 
@@ -616,7 +625,6 @@ TIME PERIODS
        -p thismonth       all transactions in the current month
        date:2016/3/17..   the above written as  queries  instead  (..  can  also  be
                           replaced with -)
-
        date:..12/1
        date:thismonth..
        date:thismonth
@@ -753,8 +761,6 @@ TIME PERIODS
 
        -p "weekly from  2009/1/1   starts on 2008/12/29, closest preceding Mon-
        to 2009/4/1"                day
-
-
        -p      "monthly       in   starts on 2018/11/01
        2008/11/25"
        -p     "quarterly    from   starts  on  2009/04/01,  ends on 2009/06/30,
@@ -816,6 +822,8 @@ TIME PERIODS
        Examples:
 
 
+
+
        -p  "every  2nd  day  of   periods will go from Tue to Tue
        week"
        -p "every Tue"             same
@@ -823,7 +831,6 @@ TIME PERIODS
                                   month
        -p "every 2nd Monday"      period  boundaries will be on second Monday of
                                   each month
-
        -p "every 11/05"           yearly  periods  with  boundaries  on  5th  of
                                   November
        -p "every 5th November"    same
@@ -1071,11 +1078,20 @@ CONVERSION & COST
        conversion  rate  must  be  1 EUR = 1.20 USD.  You can see the inferred
        rate by using hledger print -x.
 
-       Pro: - Easy, concise - hledger can do cost reporting
+       Pro:
 
-       Con: - Less error checking - typos in amounts or commodity symbols  may
+       o Easy, concise
-       not  be detected - conversion rate is not clear - disturbs the account-
+
-       ing equation
+       o hledger can do cost reporting
+
+       Con:
+
+       o Less error checking - typos in amounts or commodity symbols  may  not
+         be detected
+
+       o conversion rate is not clear
+
+       o disturbs the accounting equation
 
        You  can prevent accidental implicit conversions due to a mistyped com-
        modity symbol, by using hledger check  commodities.   You  can  prevent
@@ -1092,10 +1108,19 @@ CONVERSION & COST
        Now hledger will check that 100 * 1.20 = 120, and would report an error
        otherwise.
 
-       Pro: - Still concise - makes the conversion rate clear - provides  some
+       Pro:
-       error checking - hledger can do cost reporting
 
-       Con: - Disturbs the accounting equation
+       o Still concise
+
+       o makes the conversion rate clear
+
+       o provides some error checking
+
+       o hledger can do cost reporting
+
+       Con:
+
+       o Disturbs the accounting equation
 
    Equity conversion
        In  strict  double entry bookkeeping, the above transaction is not bal-
@@ -1112,12 +1137,21 @@ CONVERSION & COST
                   equity:conversion  -120 USD
                   assets:cash         120 USD
 
-       Pro:  -  Preserves the accounting equation - keeps track of conversions
+       Pro:
-       and related gains/losses in one place  -  works  in  any  double  entry
-       accounting system
 
-       Con: - More verbose - conversion rate is not clear - hledger can not do
+       o Preserves the accounting equation
-       cost reporting
+
+       o keeps track of conversions and related gains/losses in one place
+
+       o works in any double entry accounting system
+
+       Con:
+
+       o More verbose
+
+       o conversion rate is not clear
+
+       o hledger can not do cost reporting
 
    Priced equity conversion
        Another  possible  notation would be to record both the conversion rate
@@ -1496,6 +1530,8 @@ VALUATION
        Related: #329, #1083.
 
 
+
+
        Report          -B, --cost     -V, -X         --value=then        --value=end    --value=DATE,
        type                                                                             --value=now
        -----------------------------------------------------------------------------------------------
@@ -1520,10 +1556,6 @@ VALUATION
        posting         cost           value     at   value at  posting   value     at   value      at
        amounts                        report    or   date                report    or   DATE/today
                                       journal end                        journal end
-
-
-
-
        summary post-   summarised     value     at   sum  of  postings   value     at   value      at
        ing   amounts   cost           period ends    in interval, val-   period ends    DATE/today
        with   report                                 ued  at  interval
@@ -1571,6 +1603,7 @@ VALUATION
        budget          like balance   like balance   like      balance   like    bal-   like  balance
        amounts         changes/end    changes/end    changes/end  bal-   ances          changes/end
        (--budget)      balances       balances       ances                              balances
+
        row   totals,   sums,  aver-   sums,  aver-   sums, averages of   sums,  aver-   sums,   aver-
        row  averages   ages of dis-   ages of dis-   displayed values    ages of dis-   ages of  dis-
        (-T, -A)        played  val-   played  val-                       played  val-   played values
@@ -1713,6 +1746,8 @@ OUTPUT
        balance       Y 1   Y 1   Y 1,2   Y
        bal-          Y 1   Y 1   Y 1     Y
        ancesheet
+
+
        bal-          Y 1   Y 1   Y 1     Y
        ancesheete-
        quity
@@ -2655,6 +2690,8 @@ COMMANDS
                   period end         ues  from  report   from     report    report   start
                                      start  to  period   start to period    to period end
                                      end                 end
+
+
        --his-     change      from   sum  of  posting-   period-end         DATE-value  of
        torical    journal start to   date  market val-   value of change    change    from
        /-H        period end (his-   ues from  journal   from    journal    journal  start
@@ -3756,6 +3793,8 @@ COMMANDS
 
        o Auto postings can generate postings with too many missing amounts.
 
+       o Account aliases can generate bad account names.
+
        Normally, the journal entry's explicit or implicit amount style is pre-
        served.  For example, when an amount is omitted in the journal, it will
        not appear in the output.   Similarly,  when  a  transaction  price  is
@@ -5591,8 +5630,10 @@ JOURNAL FORMAT
 
        o adapting old journals to your current chart of accounts
 
-       o experimenting with new account organisations, like a new hierarchy or
+       o experimenting with new account organisations, like a new hierarchy
-         combining two accounts into one
+
+       o combining two accounts into one, eg to see their sum or difference on
+         one line
 
        o customising reports
 
@@ -5600,6 +5641,10 @@ JOURNAL FORMAT
        do not affect account names being entered via hledger add  or  hledger-
        web.
 
+       Account aliases are very powerful.  They are generally easy to use cor-
+       rectly, but you can also generate invalid account names with them; more
+       on this below.
+
        See also Rewrite account names.
 
    Basic aliases
@@ -5706,6 +5751,32 @@ JOURNAL FORMAT
 
               end aliases
 
+   Aliases can generate bad account names
+       Be  aware  that  account  aliases  can produce malformed account names,
+       which could cause confusing reports or invalid print output.  For exam-
+       ple, you could erase all account names:
+
+              2021-01-01
+                a:aa     1
+                b
+
+              $ hledger print --alias '/.*/='
+              2021-01-01
+                                 1
+
+       The  above print output is not a valid journal.  Or you could insert an
+       illegal double space, causing print output that would give a  different
+       journal when reparsed:
+
+              2021-01-01
+                old    1
+                other
+
+              $ hledger print --alias old="new  USD" | hledger -f- print
+              2021-01-01
+                  new             USD 1
+                  other
+
    Default parent account
        You  can  specify  a  parent  account  which  will  be prepended to all
        accounts within a section of the journal.  Use the  apply  account  and
@@ -6907,10 +6978,10 @@ CSV FORMAT
                   if %out [1-9]
                    amount1 %out
 
-       3. If  you are stuck with hledger <1.17, or you want posting 2's amount
+       3. If you want posting 2's amount converted to cost:
-          converted to cost:
+       Assign to amount (or to amount-in and amount-out).  (This is the legacy
-       Assign to amount (or to amount-in and amount-out).  (The old numberless
+       numberless  syntax, which sets amount1 and amount2 and converts amount2
-       syntax, which sets amount1 and amount2.)
+       to cost.)
 
        4. If the CSV has the balance instead of the transaction amount:
        Assign to balanceN, which sets posting N's amount indirectly via a bal-
@@ -7292,7 +7363,7 @@ COMMON TASKS
               $ hledger help --help     # show more detailed help for the help command
 
        Find   more   docs,   chat,   mail   list,   reddit,   issue   tracker:
-       https://hledger.org#help-feedback
+       https://hledger.org/support.html-feedback
 
    Constructing command lines
        hledger  has  an  extensive  and  powerful  command line interface.  We