From f1f32e83415f3fc52fddb5f9000347219bee5838 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 22 Jan 2020 15:31:33 -0800 Subject: [PATCH] ;close: doc: cleanups, remove dangerous >> example (#1165) [ci skip] --- hledger/Hledger/Cli/Commands/Close.md | 14 +-- hledger/Hledger/Cli/Commands/Close.txt | 20 ++-- hledger/hledger.1 | 16 ++- hledger/hledger.info | 160 ++++++++++++------------- hledger/hledger.txt | 20 ++-- 5 files changed, 111 insertions(+), 119 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Close.md b/hledger/Hledger/Cli/Commands/Close.md index a858ecf25..867f5cd07 100644 --- a/hledger/Hledger/Cli/Commands/Close.md +++ b/hledger/Hledger/Cli/Commands/Close.md @@ -24,8 +24,8 @@ postings they balance, which makes troubleshooting easier. By default, transaction prices in the journal are ignored when generating the closing/opening transactions. -With `--show-costs`, this cost information is preserved, -so that `balance -B` reports will be unchanged after the transition. +With `--show-costs`, this cost information is preserved +(`balance -B` reports will be unchanged after the transition). Separate postings are generated for each cost in each commodity. Note this can generate very large journal entries, if you have many foreign currency or investment transactions. @@ -64,13 +64,13 @@ will probably always require --auto. Examples: -Carrying asset/liability balances into a new file for 2019, all from command line: - -*Warning: we use `>>` here to append; be careful not to type a single `>` which would wipe your journal!* +Carrying asset/liability balances into a new file for 2019: ```shell -$ hledger close -f 2018.journal -e 2019 assets liabilities --open >>2019.journal -$ hledger close -f 2018.journal -e 2019 assets liabilities --close >>2018.journal +$ hledger close -f 2018.journal -e 2019 assets liabilities --open + # (copy/paste the output to the start of your 2019 journal file) +$ hledger close -f 2018.journal -e 2019 assets liabilities --close + # (copy/paste the output to the end of your 2018 journal file) ``` Now: diff --git a/hledger/Hledger/Cli/Commands/Close.txt b/hledger/Hledger/Cli/Commands/Close.txt index cbf6ae94b..f030962f1 100644 --- a/hledger/Hledger/Cli/Commands/Close.txt +++ b/hledger/Hledger/Cli/Commands/Close.txt @@ -25,10 +25,10 @@ they balance, which makes troubleshooting easier. By default, transaction prices in the journal are ignored when generating the closing/opening transactions. With --show-costs, this -cost information is preserved, so that balance -B reports will be -unchanged after the transition. Separate postings are generated for each -cost in each commodity. Note this can generate very large journal -entries, if you have many foreign currency or investment transactions. +cost information is preserved (balance -B reports will be unchanged +after the transition). Separate postings are generated for each cost in +each commodity. Note this can generate very large journal entries, if +you have many foreign currency or investment transactions. close usage @@ -63,14 +63,12 @@ command with --auto, the balance assertions will probably always require Examples: -Carrying asset/liability balances into a new file for 2019, all from -command line: +Carrying asset/liability balances into a new file for 2019: -Warning: we use >> here to append; be careful not to type a single > -which would wipe your journal! - -$ hledger close -f 2018.journal -e 2019 assets liabilities --open >>2019.journal -$ hledger close -f 2018.journal -e 2019 assets liabilities --close >>2018.journal +$ hledger close -f 2018.journal -e 2019 assets liabilities --open + # (copy/paste the output to the start of your 2019 journal file) +$ hledger close -f 2018.journal -e 2019 assets liabilities --close + # (copy/paste the output to the end of your 2018 journal file) Now: diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 4d9b2833e..3aae72968 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -2735,8 +2735,8 @@ postings they balance, which makes troubleshooting easier. .PP By default, transaction prices in the journal are ignored when generating the closing/opening transactions. -With \f[C]--show-costs\f[R], this cost information is preserved, so that -\f[C]balance -B\f[R] reports will be unchanged after the transition. +With \f[C]--show-costs\f[R], this cost information is preserved +(\f[C]balance -B\f[R] reports will be unchanged after the transition). Separate postings are generated for each cost in each commodity. Note this can generate very large journal entries, if you have many foreign currency or investment transactions. @@ -2780,16 +2780,14 @@ will probably always require --auto. .PP Examples: .PP -Carrying asset/liability balances into a new file for 2019, all from -command line: -.PP -\f[I]Warning: we use \f[CI]>>\f[I] here to append; be careful not to -type a single \f[CI]>\f[I] which would wipe your journal!\f[R] +Carrying asset/liability balances into a new file for 2019: .IP .nf \f[C] -$ hledger close -f 2018.journal -e 2019 assets liabilities --open >>2019.journal -$ hledger close -f 2018.journal -e 2019 assets liabilities --close >>2018.journal +$ hledger close -f 2018.journal -e 2019 assets liabilities --open + # (copy/paste the output to the start of your 2019 journal file) +$ hledger close -f 2018.journal -e 2019 assets liabilities --close + # (copy/paste the output to the end of your 2018 journal file) \f[R] .fi .PP diff --git a/hledger/hledger.info b/hledger/hledger.info index df52ffb9e..031b9630d 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -2231,10 +2231,10 @@ postings they balance, which makes troubleshooting easier. By default, transaction prices in the journal are ignored when generating the closing/opening transactions. With '--show-costs', this -cost information is preserved, so that 'balance -B' reports will be -unchanged after the transition. Separate postings are generated for -each cost in each commodity. Note this can generate very large journal -entries, if you have many foreign currency or investment transactions. +cost information is preserved ('balance -B' reports will be unchanged +after the transition). Separate postings are generated for each cost in +each commodity. Note this can generate very large journal entries, if +you have many foreign currency or investment transactions. * Menu: @@ -2279,14 +2279,12 @@ require -auto. Examples: - Carrying asset/liability balances into a new file for 2019, all from -command line: + Carrying asset/liability balances into a new file for 2019: - _Warning: we use '>>' here to append; be careful not to type a single -'>' which would wipe your journal!_ - -$ hledger close -f 2018.journal -e 2019 assets liabilities --open >>2019.journal -$ hledger close -f 2018.journal -e 2019 assets liabilities --close >>2018.journal +$ hledger close -f 2018.journal -e 2019 assets liabilities --open + # (copy/paste the output to the start of your 2019 journal file) +$ hledger close -f 2018.journal -e 2019 assets liabilities --close + # (copy/paste the output to the end of your 2018 journal file) Now: @@ -3319,76 +3317,76 @@ Node: check-dupes76317 Ref: #check-dupes76441 Node: close76734 Ref: #close76848 -Node: close usage78377 -Ref: #close-usage78470 -Node: commodities81310 -Ref: #commodities81437 -Node: descriptions81519 -Ref: #descriptions81647 -Node: diff81828 -Ref: #diff81934 -Node: files82981 -Ref: #files83081 -Node: help83228 -Ref: #help83328 -Node: import84409 -Ref: #import84523 -Node: Importing balance assignments85416 -Ref: #importing-balance-assignments85564 -Node: incomestatement86213 -Ref: #incomestatement86346 -Node: notes87750 -Ref: #notes87863 -Node: payees87989 -Ref: #payees88095 -Node: prices88253 -Ref: #prices88359 -Node: print88700 -Ref: #print88810 -Node: print-unique93454 -Ref: #print-unique93580 -Node: register93865 -Ref: #register93992 -Node: Custom register output98164 -Ref: #custom-register-output98293 -Node: register-match99555 -Ref: #register-match99689 -Node: rewrite100040 -Ref: #rewrite100155 -Node: Re-write rules in a file102010 -Ref: #re-write-rules-in-a-file102144 -Node: Diff output format103354 -Ref: #diff-output-format103523 -Node: rewrite vs print --auto104615 -Ref: #rewrite-vs.-print---auto104794 -Node: roi105350 -Ref: #roi105448 -Node: stats106460 -Ref: #stats106559 -Node: tags107347 -Ref: #tags107445 -Node: test107739 -Ref: #test107823 -Node: ADD-ON COMMANDS108570 -Ref: #add-on-commands108680 -Node: Official add-ons109968 -Ref: #official-add-ons110108 -Node: ui110188 -Ref: #ui110275 -Node: web110329 -Ref: #web110418 -Node: Third party add-ons110464 -Ref: #third-party-add-ons110639 -Node: iadd110758 -Ref: #iadd110859 -Node: interest110941 -Ref: #interest111050 -Node: Experimental add-ons111145 -Ref: #experimental-add-ons111297 -Node: autosync111535 -Ref: #autosync111646 -Node: chart111885 -Ref: #chart111990 +Node: close usage78370 +Ref: #close-usage78463 +Node: commodities81276 +Ref: #commodities81403 +Node: descriptions81485 +Ref: #descriptions81613 +Node: diff81794 +Ref: #diff81900 +Node: files82947 +Ref: #files83047 +Node: help83194 +Ref: #help83294 +Node: import84375 +Ref: #import84489 +Node: Importing balance assignments85382 +Ref: #importing-balance-assignments85530 +Node: incomestatement86179 +Ref: #incomestatement86312 +Node: notes87716 +Ref: #notes87829 +Node: payees87955 +Ref: #payees88061 +Node: prices88219 +Ref: #prices88325 +Node: print88666 +Ref: #print88776 +Node: print-unique93420 +Ref: #print-unique93546 +Node: register93831 +Ref: #register93958 +Node: Custom register output98130 +Ref: #custom-register-output98259 +Node: register-match99521 +Ref: #register-match99655 +Node: rewrite100006 +Ref: #rewrite100121 +Node: Re-write rules in a file101976 +Ref: #re-write-rules-in-a-file102110 +Node: Diff output format103320 +Ref: #diff-output-format103489 +Node: rewrite vs print --auto104581 +Ref: #rewrite-vs.-print---auto104760 +Node: roi105316 +Ref: #roi105414 +Node: stats106426 +Ref: #stats106525 +Node: tags107313 +Ref: #tags107411 +Node: test107705 +Ref: #test107789 +Node: ADD-ON COMMANDS108536 +Ref: #add-on-commands108646 +Node: Official add-ons109934 +Ref: #official-add-ons110074 +Node: ui110154 +Ref: #ui110241 +Node: web110295 +Ref: #web110384 +Node: Third party add-ons110430 +Ref: #third-party-add-ons110605 +Node: iadd110724 +Ref: #iadd110825 +Node: interest110907 +Ref: #interest111016 +Node: Experimental add-ons111111 +Ref: #experimental-add-ons111263 +Node: autosync111501 +Ref: #autosync111612 +Node: chart111851 +Ref: #chart111956  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index d1be5a5e7..0a46dccaf 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -1967,10 +1967,10 @@ COMMANDS By default, transaction prices in the journal are ignored when generat- ing the closing/opening transactions. With --show-costs, this cost in- - formation is preserved, so that balance -B reports will be unchanged - after the transition. Separate postings are generated for each cost in - each commodity. Note this can generate very large journal entries, if - you have many foreign currency or investment transactions. + formation is preserved (balance -B reports will be unchanged after the + transition). Separate postings are generated for each cost in each + commodity. Note this can generate very large journal entries, if you + have many foreign currency or investment transactions. close usage If you split your journal files by time (eg yearly), you will typically @@ -2005,14 +2005,12 @@ COMMANDS Examples: - Carrying asset/liability balances into a new file for 2019, all from - command line: + Carrying asset/liability balances into a new file for 2019: - Warning: we use >> here to append; be careful not to type a single > - which would wipe your journal! - - $ hledger close -f 2018.journal -e 2019 assets liabilities --open >>2019.journal - $ hledger close -f 2018.journal -e 2019 assets liabilities --close >>2018.journal + $ hledger close -f 2018.journal -e 2019 assets liabilities --open + # (copy/paste the output to the start of your 2019 journal file) + $ hledger close -f 2018.journal -e 2019 assets liabilities --close + # (copy/paste the output to the end of your 2018 journal file) Now: