doc: tldr: copy tldr pages to the hledger repo for robustness

doc/tldr/README.md

@@ -4,9 +4,10 @@ tldr pages are short but high value, and a great counterbalance to PTA's verbose
 So they are worth prioritising and maintaining.
 gutjuri made the first hledger tldr page in 2022, and sm added more in 2024.
 
-This directory has convenient symlinks for accessing the [hledger-related tldr pages](https://github.com/search?q=repo%3Atldr-pages%2Ftldr%20hledger&type=code)
-(if tldr is cloned as a sibling to the hledger project directory).
-These docs are crafted first to suit tldr and its style rules, but we could also use them elsewhere when practical.
+This directory has local copies of all [hledger-related tldr pages](https://github.com/search?q=repo%3Atldr-pages%2Ftldr%20hledger&type=code)
+The tldr-pages repo has the master copies, so they should be copied here periodically (eg before release).
+These docs are crafted first to suit tldr and its style rules, but we'll reuse them where we can.
+Eg they are now embedded in the hledger tools and accessible with --tldr.
 
 <https://tldr.inbrowser.app> is an online (& offline) tldr viewer,
 where you can search for [hledger command examples](https://tldr.inbrowser.app/search?query=hledger+).

doc/tldr/hledger-accounts.md

@@ -1 +0,0 @@
-../../../tldr/pages/common/hledger-accounts.md

doc/tldr/hledger-accounts.md

@@ -0,0 +1,36 @@
+# hledger accounts
+
+> List account names.
+> More information: <https://hledger.org/hledger.html#accounts>.
+
+- Show all accounts used or declared in the default journal file:
+
+`hledger accounts`
+
+- Show accounts used by transactions:
+
+`hledger accounts --used`
+
+- Show accounts declared with account directives:
+
+`hledger accounts --declared`
+
+- Add new account directives, for accounts used but not declared, to the journal:
+
+`hledger accounts --undeclared --directives >> {{2024-accounts.journal}}`
+
+- Show accounts with `asset` in their name, and their declared/inferred types:
+
+`hledger accounts asset --types`
+
+- Show accounts of the `Asset` type:
+
+`hledger accounts type:A`
+
+- Show the first two levels of the accounts hierarchy:
+
+`hledger accounts --tree --depth 2`
+
+- Short form of the above:
+
+`hledger acc -t -2`

doc/tldr/hledger-add.md

@@ -1 +0,0 @@
-../../../tldr/pages/common/hledger-add.md

doc/tldr/hledger-add.md

@@ -0,0 +1,24 @@
+# hledger add
+
+> Record new transactions with interactive prompting in the console.
+> More information: <https://hledger.org/hledger.html#add>.
+
+- Record new transactions, saving to the default journal file:
+
+`hledger add`
+
+- Add transactions to `2024.journal`, but also load `2023.journal` for completions:
+
+`hledger add --file {{path/to/2024.journal}} --file {{path/to/2023.journal}}`
+
+- Provide answers for the first four prompts:
+
+`hledger add {{today}} '{{best buy}}' {{expenses:supplies}} '{{$20}}'`
+
+- Show `add`'s options and documentation with `$PAGER`:
+
+`hledger add --help`
+
+- Show `add`'s documentation with `info` or `man` if available:
+
+`hledger help add`

doc/tldr/hledger-aregister.md

@@ -1 +0,0 @@
-../../../tldr/pages/common/hledger-aregister.md

doc/tldr/hledger-aregister.md

@@ -0,0 +1,20 @@
+# hledger aregister
+
+> Show the transactions and running balances in one account.
+> More information: <https://hledger.org/hledger.html#aregister>.
+
+- Show transactions and running balance in the `assets:bank:checking` account:
+
+`hledger aregister assets:bank:checking`
+
+- Show transactions and running balance in the first account named `*savings*`:
+
+`hledger aregister savings`
+
+- Show the checking account's cleared transactions, with a specified width:
+
+`hledger aregister checking --cleared --width {{120}}`
+
+- Show the checking register, including transactions from forecast rules:
+
+`hledger aregister checking --forecast`

doc/tldr/hledger-balance.md

@@ -0,0 +1,37 @@
+# hledger balance
+
+> A flexible, general purpose "summing" report that shows accounts with some kind of numeric data.
+> This can be balance changes per period, end balances, budget performance, unrealised capital gains, etc.
+> More information: <https://hledger.org/hledger.html#balance>.
+
+- Show the balance change in all accounts from all postings over all time:
+
+`hledger balance`
+
+- Show the balance change in accounts named `*expenses*`, as a tree, summarising the top two levels only:
+
+`hledger balance {{expenses}} --tree --depth {{2}}`
+
+- Show expenses each month, and their totals and averages, sorted by total; and their monthly budget goals:
+
+`hledger balance {{expenses}} --monthly --row-total --average --sort-amount --budget`
+
+- Similar to the above, shorter form, matching accounts by `Expense` type, as a two level tree without squashing boring accounts:
+
+`hledger bal type:{{X}} -MTAS --budget -t -{{2}} --no-elide`
+
+- Show end balances (including from postings before the start date), quarterly in 2024, in accounts named `*assets*` or `*liabilities*`:
+
+`hledger balance --historical --period '{{quarterly in 2024}}' {{assets}} {{liabilities}}`
+
+- Similar to the above, shorter form; also show zero balances, sort by total and summarise to three levels:
+
+`hledger bal -HQ date:{{2024}} type:{{AL}} -ES -{{3}}`
+
+- Show investment assets' market value in base currency at the end of each quarter:
+
+`hledger bal -HVQ {{assets:investments}}`
+
+- Show unrealised capital gains/losses from market price changes in each quarter, for non-cryptocurrency investment assets:
+
+`hledger bal --gain -Q {{assets:investments}} not:{{cryptocurrency}}`

doc/tldr/hledger-balancesheet.md

@@ -1 +0,0 @@
-../../../tldr/pages/common/hledger-balancesheet.md

doc/tldr/hledger-balancesheet.md

@@ -0,0 +1,32 @@
+# hledger balancesheet
+
+> Show the end balances in asset and liability accounts.
+> More information: <https://hledger.org/hledger.html#balancesheet>.
+
+- Show the current balances in `Asset` and `Liability` accounts, excluding zeros:
+
+`hledger balancesheet`
+
+- Show just the liquid assets (`Cash` account type):
+
+`hledger balancesheet type:C`
+
+- Include accounts with zero balances, and show the account hierarchy:
+
+`hledger balancesheet --empty --tree`
+
+- Show the balances at the end of each month:
+
+`hledger balancesheet --monthly`
+
+- Show the balances' market value in home currency at the end of each month:
+
+`hledger balancesheet --monthly -V`
+
+- Show quarterly balances, with just the top two levels of account hierarchy:
+
+`hledger balancesheet --quarterly --tree --depth 2`
+
+- Short form of the above, and generate HTML output in `bs.html`:
+
+`hledger bs -Qt -2 -o bs.html`

doc/tldr/hledger-import.md

@@ -1 +0,0 @@
-../../../tldr/pages/common/hledger-import.md

doc/tldr/hledger-import.md

@@ -0,0 +1,28 @@
+# hledger import
+
+> Import new transactions from one or more data files to the main journal.
+> More information: <https://hledger.org/hledger.html#import>.
+
+- Import new transactions from `bank.csv`, using `bank.csv.rules` to convert:
+
+`hledger import {{path/to/bank.csv}}`
+
+- Show what would be imported from these two files, without doing anything:
+
+`hledger import {{path/to/bank1.csv}} {{path/to/bank2.csv}} --dry-run`
+
+- Import new transactions from all CSV files, using the same rules for all:
+
+`hledger import --rules-file {{common.rules}} *.csv`
+
+- Show conversion errors or results while editing `bank.csv.rules`:
+
+`watchexec -- hledger -f {{path/to/bank.csv}} print`
+
+- Mark `bank.csv`'s current data as seen, as if already imported:
+
+`hledger import --catchup {{path/to/bank.csv}}`
+
+- Mark `bank.csv` as all new, as if not yet imported:
+
+`rm -f .latest.bank.csv`

doc/tldr/hledger-incomestatement.md

@@ -1 +0,0 @@
-../../../tldr/pages/common/hledger-incomestatement.md

doc/tldr/hledger-incomestatement.md

@@ -0,0 +1,20 @@
+# hledger incomestatement
+
+> Show revenue inflows and expense outflows during the report period.
+> More information: <https://hledger.org/hledger.html#incomestatement>.
+
+- Show revenues and expenses (changes in `Revenue` and `Expense` accounts):
+
+`hledger incomestatement`
+
+- Show revenues and expenses each month:
+
+`hledger incomestatement --monthly`
+
+- Show monthly revenues/expenses/totals, largest first, summarised to 2 levels:
+
+`hledger incomestatement --monthly --row-total --average --sort --depth 2`
+
+- Short form of the above, and generate HTML output in `is.html`:
+
+`hledger is -MTAS -2 -o is.html`

doc/tldr/hledger-print.md

@@ -1 +0,0 @@
-../../../tldr/pages/common/hledger-print.md

doc/tldr/hledger-print.md

@@ -0,0 +1,32 @@
+# hledger print
+
+> Show full journal entries, representing transactions.
+> More information: <https://hledger.org/hledger.html#print>.
+
+- Show all transactions in the default journal file:
+
+`hledger print`
+
+- Show transactions, with any implied amounts or costs made explicit:
+
+`hledger print --explicit --infer-costs`
+
+- Show transactions from two specified files, with amounts converted to cost:
+
+`hledger print --file {{path/to/2023.journal}} --file {{path/to/2024.journal}} --cost`
+
+- Show `$` transactions in `*food*` but not `*groceries*` accounts this month:
+
+`hledger print cur:\\$ food not:groceries date:thismonth`
+
+- Show transactions of amount 50 or more, with `whole foods` in their description:
+
+`hledger print amt:'>50' desc:'whole foods'`
+
+- Show cleared transactions, with `EUR` amounts rounded and with decimal commas:
+
+`hledger print --cleared --commodity '1000, EUR' --round hard`
+
+- Write transactions from `foo.journal` as a CSV file:
+
+`hledger print --file {{path/to/foo.journal}} --output-file {{path/to/output_file.csv}}`

doc/tldr/hledger-ui.md

@@ -1 +0,0 @@
-../../../tldr/pages/common/hledger-ui.md

doc/tldr/hledger-ui.md

@@ -0,0 +1,33 @@
+# hledger-ui
+
+> Terminal UI (TUI) to `hledger`.
+> A robust, friendly plain text accounting app.
+> More information: <https://hledger.org/hledger-ui.html>.
+
+- Start in the main menu screen, reading from the default journal file:
+
+`hledger-ui`
+
+- Start with a different color theme:
+
+`hledger-ui --theme {{terminal|greenterm|dark}}`
+
+- Start in the balance sheet accounts screen, showing hierarchy down to level 3:
+
+`hledger-ui --bs --tree --depth 3`
+
+- Start in this account's screen, showing cleared transactions, and reload on change:
+
+`hledger-ui --register {{assets:bank:checking}} --cleared --watch`
+
+- Read two journal files, and show amounts as current value when known:
+
+`hledger-ui --file {{path/to/2024.journal}} --file {{path/to/2024-prices.journal}} --value now`
+
+- Show the manual in Info format, if possible:
+
+`hledger-ui --info`
+
+- Display help:
+
+`hledger-ui --help`

doc/tldr/hledger-web.md

@@ -1 +0,0 @@
-../../../tldr/pages/common/hledger-web.md

doc/tldr/hledger-web.md

@@ -0,0 +1,33 @@
+# hledger-web
+
+> Web interface and API to `hledger`.
+> A robust, friendly plain text accounting app.
+> More information: <https://hledger.org/hledger-web.html>.
+
+- Start the web app, and a browser if possible, for local viewing and adding only:
+
+`hledger-web`
+
+- As above but with a specified file, and allow editing of existing data:
+
+`hledger-web --file {{path/to/file.journal}} --allow edit`
+
+- Start just the web app, and accept incoming connections to the specified host and port:
+
+`hledger-web --serve --host {{my.host.name}} --port 8000`
+
+- Start just the web app's JSON API, and allow only read access:
+
+`hledger-web --serve-api --host {{my.host.name}} --allow view`
+
+- Show amounts converted to current market value in your base currency when known:
+
+`hledger-web --value now --infer-market-prices`
+
+- Show the manual in Info format if possible:
+
+`hledger-web --info`
+
+- Display help:
+
+`hledger-web --help`

doc/tldr/hledger.md

@@ -1 +0,0 @@
-../../../tldr/pages/common/hledger.md

doc/tldr/hledger.md

@@ -0,0 +1,37 @@
+# hledger
+
+> A robust, friendly plain text accounting app.
+> See also: `hledger-ui` for TUI, `hledger-web` for web interface.
+> More information: <https://hledger.org/hledger.html>.
+
+- Record new transactions interactively, saving to the default journal file:
+
+`hledger add`
+
+- Import new transactions from `bank.csv`, using `bank.csv.rules` to convert:
+
+`hledger import {{path/to/bank.csv}}`
+
+- Print all transactions, reading from multiple specified journal files:
+
+`hledger print --file {{path/to/prices-2024.journal}} --file {{path/to/prices-2023.journal}}`
+
+- Show all accounts, as a hierarchy, and their types:
+
+`hledger accounts --tree --types`
+
+- Show asset and liability account balances, including zeros, hierarchically:
+
+`hledger balancesheet --empty --tree --no-elide`
+
+- Show monthly incomes/expenses/totals, largest first, summarised to 2 levels:
+
+`hledger incomestatement --monthly --row-total --average --sort --depth 2`
+
+- Show the `assets:bank:checking` account's transactions and running balance:
+
+`hledger aregister assets:bank:checking`
+
+- Show the amount spent on food from the `assets:cash` account:
+
+`hledger print assets:cash | hledger -f- -I aregister expenses:food`