diff: help tweaks (cf #981)

hledger/Hledger/Cli/Commands/Diff.hs

@@ -32,7 +32,7 @@ diffmode = hledgerCommandMode
   []
   [generalflagsgroup2]
   []
-  ([], Just $ argsFlag "[ACCOUNT] -f [JOURNAL1] -f [JOURNAL2]")
+  ([], Just $ argsFlag "-f FILE1 -f FILE2 FULLACCOUNTTNAME")
 
 data PostingWithPath = PostingWithPath {
                      ppposting :: Posting,
@@ -115,12 +115,12 @@ diff CliOpts{file_=[f1, f2], reportopts_=ReportOpts{query_=acctName}} _ = do
   let unmatchedtxn1 = unmatchedtxns L pp1 m
   let unmatchedtxn2 = unmatchedtxns R pp2 m
 
-  putStrLn "Unmatched transactions in the first journal:\n"
+  putStrLn "These transactions are in the first file only:\n"
   mapM_ (putStr . showTransaction) unmatchedtxn1
 
-  putStrLn "Unmatched transactions in the second journal:\n"
+  putStrLn "These transactions are in the second file only:\n"
   mapM_ (putStr . showTransaction) unmatchedtxn2
 
 diff _ _ = do
-  putStrLn "Specifiy exactly two journal files"
+  putStrLn "Please specify two input files. Usage: hledger diff -f FILE1 -f FILE2 FULLACCOUNTNAME"
   exitFailure

hledger/Hledger/Cli/Commands/Diff.md

@@ -1,35 +1,32 @@
 diff\
-Compares two journal files.  It looks at the transactions of a single
+Compares a particular account's transactions in two input files.
-account and prints out the transactions which are in one journal file but not
+It shows any transactions to this account which are in one file but
-in the other.
+not in the other.
 
-This is particularly useful for reconciling existing journals with bank
+More precisely, for each posting affecting this account in either
-statements.  Many banks provide a way to export the transactions between two
+file, it looks for a corresponding posting in the other file which
-given dates, which can be converted to ledger files using custom scripts or
+posts the same amount to the same account (ignoring date, description,
-read directly as CSV files.  With the diff command you can make sure that these
+etc.) Since postings not transactions are compared, this also works
-transactions from bank match up exactly with the transactions in your ledger
+when multiple bank transactions have been combined into a single
-file, and that the resulting balance is correct.  (One possible concrete
+journal entry.
-workflow is to have one ledger file per year and export the transactions for
-the current year, starting on January 1.)
 
-This command compares the postings of a single account (which needs to have the
+This is useful eg if you have downloaded an account's transactions
-same name in both files), and only checks the amount of the postings (not the
+from your bank (eg as CSV data). When hledger and your bank disagree
-name or the date of the transactions).  Postings are compared (instead of
+about the account balance, you can compare the bank data with your
-transactions) so that you can combine multiple transactions from the bank
+journal to find out the cause. 
-statement in a single transaction in the ledger file.
 
 _FLAGS_
 
 Examples:
 
 ```shell
-$ hledger diff assets:bank:giro -f 2014.journal -f bank.journal
+$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro 
-Unmatched transactions in the first journal:
+These transactions are in the first file only:
 
 2014/01/01 Opening Balances
     assets:bank:giro              EUR ...
     ...
     equity:opening balances       EUR -...
 
-Unmatched transactions in the second journal:
+These transactions are in the second file only:
 ```

hledger/Hledger/Cli/Commands/Diff.txt

@@ -1,35 +1,29 @@
 diff
-Compares two journal files. It looks at the transactions of a single
+Compares a particular account's transactions in two input files. It
-account and prints out the transactions which are in one journal file
+shows any transactions to this account which are in one file but not in
-but not in the other.
+the other.
 
-This is particularly useful for reconciling existing journals with bank
+More precisely, for each posting affecting this account in either file,
-statements. Many banks provide a way to export the transactions between
+it looks for a corresponding posting in the other file which posts the
-two given dates, which can be converted to ledger files using custom
+same amount to the same account (ignoring date, description, etc.) Since
-scripts or read directly as CSV files. With the diff command you can
+postings not transactions are compared, this also works when multiple
-make sure that these transactions from bank match up exactly with the
+bank transactions have been combined into a single journal entry.
-transactions in your ledger file, and that the resulting balance is
-correct. (One possible concrete workflow is to have one ledger file per
-year and export the transactions for the current year, starting on
-January 1.)
 
-This command compares the postings of a single account (which needs to
+This is useful eg if you have downloaded an account's transactions from
-have the same name in both files), and only checks the amount of the
+your bank (eg as CSV data). When hledger and your bank disagree about
-postings (not the name or the date of the transactions). Postings are
+the account balance, you can compare the bank data with your journal to
-compared (instead of transactions) so that you can combine multiple
+find out the cause.
-transactions from the bank statement in a single transaction in the
-ledger file.
 
 _FLAGS_
 
 Examples:
 
-$ hledger diff assets:bank:giro -f 2014.journal -f bank.journal
+$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro 
-Unmatched transactions in the first journal:
+These transactions are in the first file only:
 
 2014/01/01 Opening Balances
     assets:bank:giro              EUR ...
     ...
     equity:opening balances       EUR -...
 
-Unmatched transactions in the second journal:
+These transactions are in the second file only: