doc: journal: meaning of --uncleared, matching tips (#553)

[ci skip]

hledger-lib/doc/hledger_journal.5

@@ -229,8 +229,9 @@ When reporting, you can filter by status using the
 This feature is optional, but can be helpful for reconciling with
 real\-world accounts.
 What "uncleared", "pending", and "cleared" actually mean is up to you.
-My recommendation: use cleared (\f[C]*\f[]) to mark transactions that
-are "complete", ie:
+.PP
+A suggestion: use cleared (\f[C]*\f[]) to mark transactions that are
+"complete", ie:
 .IP \[bu] 2
 they have cleared with the bank, or the cash has been handed over
 .IP \[bu] 2
@@ -248,9 +249,13 @@ you\[aq]ll see the most up\-to\-date state of your finances.
 I don\[aq]t use pending (\f[C]!\f[]), but perhaps it is useful in very
 tricky reconciliations, as a temporary marker for transactions matched
 so far, allowing you start over more easily.
+Note, the \-\-uncleared flag matches both uncleared and pending things
+("everything not definitely cleared").
+Currently, to match pending things only, use \f[C]status:!\f[], and to
+match uncleared things only, \f[C]not:status:!\ not:status:*\f[]
+(\f[C]status:\f[] seems buggy).
 .PP
-Tip: some editor modes highlight entries differently based on their
-status.
+Some editor modes highlight entries differently based on their status.
 In Emacs ledger\-mode, you can toggle transaction status with
 \f[C]C\-c\ C\-e\f[], or posting status with \f[C]C\-c\ C\-c\f[].
 .SS Account names

hledger-lib/doc/hledger_journal.5.info

@@ -245,8 +245,10 @@ character:
 
    This feature is optional, but can be helpful for reconciling with
 real-world accounts.  What "uncleared", "pending", and "cleared"
-actually mean is up to you.  My recommendation: use cleared ('*') to
-mark transactions that are "complete", ie:
+actually mean is up to you.
+
+   A suggestion: use cleared ('*') to mark transactions that are
+"complete", ie:
 
    * they have cleared with the bank, or the cash has been handed over
    * you are satisfied they are recorded accurately in the journal
@@ -261,9 +263,13 @@ most up-to-date state of your finances.
 
    I don't use pending ('!'), but perhaps it is useful in very tricky
 reconciliations, as a temporary marker for transactions matched so far,
-allowing you start over more easily.
+allowing you start over more easily.  Note, the -uncleared flag matches
+both uncleared and pending things ("everything not definitely cleared").
+Currently, to match pending things only, use 'status:!', and to match
+uncleared things only, 'not:status:! not:status:*' ('status:' seems
+buggy).
 
-   Tip: some editor modes highlight entries differently based on their
+   Some editor modes highlight entries differently based on their
 status.  In Emacs ledger-mode, you can toggle transaction status with
 'C-c C-e', or posting status with 'C-c C-c'.
 
@@ -1054,67 +1060,67 @@ Node: Posting dates6826
 Ref: #posting-dates6957
 Node: Status8331
 Ref: #status8455
-Node: Account names10018
-Ref: #account-names10158
-Node: Amounts10645
-Ref: #amounts10783
-Node: Virtual Postings12884
-Ref: #virtual-postings13045
-Node: Balance Assertions14265
-Ref: #balance-assertions14442
-Node: Assertions and ordering15338
-Ref: #assertions-and-ordering15526
-Node: Assertions and included files16226
-Ref: #assertions-and-included-files16469
-Node: Assertions and multiple -f options16802
-Ref: #assertions-and-multiple--f-options17058
-Node: Assertions and commodities17190
-Ref: #assertions-and-commodities17427
-Node: Assertions and subaccounts18123
-Ref: #assertions-and-subaccounts18357
-Node: Assertions and virtual postings18878
-Ref: #assertions-and-virtual-postings19087
-Node: Balance Assignments19229
-Ref: #balance-assignments19398
-Node: Prices20517
-Ref: #prices20652
-Node: Transaction prices20703
-Ref: #transaction-prices20850
-Node: Market prices23006
-Ref: #market-prices23143
-Node: Comments24103
-Ref: #comments24227
-Node: Tags25340
-Ref: #tags25460
-Node: Implicit tags26889
-Ref: #implicit-tags26997
-Node: Directives27514
-Ref: #directives27629
-Node: Account aliases27822
-Ref: #account-aliases27968
-Node: Basic aliases28572
-Ref: #basic-aliases28717
-Node: Regex aliases29407
-Ref: #regex-aliases29577
-Node: Multiple aliases30292
-Ref: #multiple-aliases30466
-Node: end aliases30964
-Ref: #end-aliases31106
-Node: account directive31207
-Ref: #account-directive31389
-Node: apply account directive31685
-Ref: #apply-account-directive31883
-Node: Multi-line comments32542
-Ref: #multi-line-comments32734
-Node: commodity directive32862
-Ref: #commodity-directive33048
-Node: Default commodity33920
-Ref: #default-commodity34095
-Node: Default year34632
-Ref: #default-year34799
-Node: Including other files35222
-Ref: #including-other-files35381
-Node: EDITOR SUPPORT35778
-Ref: #editor-support35898
+Node: Account names10265
+Ref: #account-names10405
+Node: Amounts10892
+Ref: #amounts11030
+Node: Virtual Postings13131
+Ref: #virtual-postings13292
+Node: Balance Assertions14512
+Ref: #balance-assertions14689
+Node: Assertions and ordering15585
+Ref: #assertions-and-ordering15773
+Node: Assertions and included files16473
+Ref: #assertions-and-included-files16716
+Node: Assertions and multiple -f options17049
+Ref: #assertions-and-multiple--f-options17305
+Node: Assertions and commodities17437
+Ref: #assertions-and-commodities17674
+Node: Assertions and subaccounts18370
+Ref: #assertions-and-subaccounts18604
+Node: Assertions and virtual postings19125
+Ref: #assertions-and-virtual-postings19334
+Node: Balance Assignments19476
+Ref: #balance-assignments19645
+Node: Prices20764
+Ref: #prices20899
+Node: Transaction prices20950
+Ref: #transaction-prices21097
+Node: Market prices23253
+Ref: #market-prices23390
+Node: Comments24350
+Ref: #comments24474
+Node: Tags25587
+Ref: #tags25707
+Node: Implicit tags27136
+Ref: #implicit-tags27244
+Node: Directives27761
+Ref: #directives27876
+Node: Account aliases28069
+Ref: #account-aliases28215
+Node: Basic aliases28819
+Ref: #basic-aliases28964
+Node: Regex aliases29654
+Ref: #regex-aliases29824
+Node: Multiple aliases30539
+Ref: #multiple-aliases30713
+Node: end aliases31211
+Ref: #end-aliases31353
+Node: account directive31454
+Ref: #account-directive31636
+Node: apply account directive31932
+Ref: #apply-account-directive32130
+Node: Multi-line comments32789
+Ref: #multi-line-comments32981
+Node: commodity directive33109
+Ref: #commodity-directive33295
+Node: Default commodity34167
+Ref: #default-commodity34342
+Node: Default year34879
+Ref: #default-year35046
+Node: Including other files35469
+Ref: #including-other-files35628
+Node: EDITOR SUPPORT36025
+Ref: #editor-support36145
 
 End Tag Table

hledger-lib/doc/hledger_journal.5.m4.md

@@ -197,7 +197,8 @@ or the `status:` query.
 
 This feature is optional, but can be helpful for reconciling with real-world accounts.
 What "uncleared", "pending", and "cleared" actually mean is up to you.
-My recommendation: use cleared (`*`) to mark transactions that are "complete", ie: 
+
+A suggestion: use cleared (`*`) to mark transactions that are "complete", ie: 
 
 - they have cleared with the bank, or the cash has been handed over
 - you are satisfied they are recorded accurately in the journal
@@ -209,8 +210,11 @@ and with neither flag (the default) you'll see the most up-to-date state of your
 
 I don't use pending (`!`), but perhaps it is useful in very tricky reconciliations,
 as a temporary marker for transactions matched so far, allowing you start over more easily. 
+Note, the --uncleared flag matches both uncleared and pending things ("everything not definitely cleared").
+Currently, to match pending things only, use `status:!`,
+and to match uncleared things only, `not:status:! not:status:*` (`status:` seems buggy). 
 
-Tip: some [editor modes](#editor-support) highlight entries differently based on their status.
+Some [editor modes](#editor-support) highlight entries differently based on their status.
 In Emacs ledger-mode, you can toggle transaction status with `C-c C-e`, or posting status with `C-c C-c`.  
 
 ## Account names

hledger-lib/doc/hledger_journal.5.txt

@@ -184,8 +184,10 @@ FILE FORMAT
 
        This feature is optional, but  can  be  helpful  for  reconciling  with
        real-world  accounts.  What "uncleared", "pending", and "cleared" actu-
-       ally mean is up to you.  My recommendation: use  cleared  (*)  to  mark
-       transactions that are "complete", ie:
+       ally mean is up to you.
+
+       A suggestion: use cleared (*) to mark transactions that are "complete",
+       ie:
 
        o they have cleared with the bank, or the cash has been handed over
 
@@ -202,11 +204,15 @@ FILE FORMAT
 
        I don't use pending (!), but perhaps it is useful in very tricky recon-
        ciliations,  as  a  temporary  marker  for transactions matched so far,
-       allowing you start over more easily.
+       allowing you start  over  more  easily.   Note,  the  --uncleared  flag
+       matches  both  uncleared and pending things ("everything not definitely
+       cleared").  Currently, to match pending things only, use status:!,  and
+       to  match  uncleared  things  only,  not:status:! not:status:* (status:
+       seems buggy).
 
-       Tip: some editor modes highlight entries  differently  based  on  their
-       status.   In  Emacs ledger-mode, you can toggle transaction status with
-       C-c C-e, or posting status with C-c C-c.
+       Some editor modes highlight entries differently based on their  status.
+       In  Emacs  ledger-mode, you can toggle transaction status with C-c C-e,
+       or posting status with C-c C-c.
 
    Account names
        Account names typically have several parts separated by a  full  colon,
@@ -801,7 +807,6 @@ EDITOR SUPPORT
                           lime-Text
        Textmate           https://github.com/ledger/ledger/wiki/Using-Text-
                           Mate-2
-
        Text Wrangler      https://github.com/ledger/ledger/wiki/Edit-
                           ing-Ledger-files-with-TextWrangler