diff --git a/doc/tldr/README.md b/doc/tldr/README.md index a55097192..4e0ffb651 100644 --- a/doc/tldr/README.md +++ b/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. is an online (& offline) tldr viewer, where you can search for [hledger command examples](https://tldr.inbrowser.app/search?query=hledger+). diff --git a/doc/tldr/hledger-accounts.md b/doc/tldr/hledger-accounts.md deleted file mode 120000 index 47dd93023..000000000 --- a/doc/tldr/hledger-accounts.md +++ /dev/null @@ -1 +0,0 @@ -../../../tldr/pages/common/hledger-accounts.md \ No newline at end of file diff --git a/doc/tldr/hledger-accounts.md b/doc/tldr/hledger-accounts.md new file mode 100644 index 000000000..82cf3498b --- /dev/null +++ b/doc/tldr/hledger-accounts.md @@ -0,0 +1,36 @@ +# hledger accounts + +> List account names. +> More information: . + +- 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` diff --git a/doc/tldr/hledger-add.md b/doc/tldr/hledger-add.md deleted file mode 120000 index f80167a60..000000000 --- a/doc/tldr/hledger-add.md +++ /dev/null @@ -1 +0,0 @@ -../../../tldr/pages/common/hledger-add.md \ No newline at end of file diff --git a/doc/tldr/hledger-add.md b/doc/tldr/hledger-add.md new file mode 100644 index 000000000..8e61e09c6 --- /dev/null +++ b/doc/tldr/hledger-add.md @@ -0,0 +1,24 @@ +# hledger add + +> Record new transactions with interactive prompting in the console. +> More information: . + +- 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` diff --git a/doc/tldr/hledger-aregister.md b/doc/tldr/hledger-aregister.md deleted file mode 120000 index c76b3db22..000000000 --- a/doc/tldr/hledger-aregister.md +++ /dev/null @@ -1 +0,0 @@ -../../../tldr/pages/common/hledger-aregister.md \ No newline at end of file diff --git a/doc/tldr/hledger-aregister.md b/doc/tldr/hledger-aregister.md new file mode 100644 index 000000000..80a97975f --- /dev/null +++ b/doc/tldr/hledger-aregister.md @@ -0,0 +1,20 @@ +# hledger aregister + +> Show the transactions and running balances in one account. +> More information: . + +- 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` diff --git a/doc/tldr/hledger-balance.md b/doc/tldr/hledger-balance.md new file mode 100644 index 000000000..6dcd62889 --- /dev/null +++ b/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: . + +- 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}}` diff --git a/doc/tldr/hledger-balancesheet.md b/doc/tldr/hledger-balancesheet.md deleted file mode 120000 index e5688c33d..000000000 --- a/doc/tldr/hledger-balancesheet.md +++ /dev/null @@ -1 +0,0 @@ -../../../tldr/pages/common/hledger-balancesheet.md \ No newline at end of file diff --git a/doc/tldr/hledger-balancesheet.md b/doc/tldr/hledger-balancesheet.md new file mode 100644 index 000000000..c3769b6e5 --- /dev/null +++ b/doc/tldr/hledger-balancesheet.md @@ -0,0 +1,32 @@ +# hledger balancesheet + +> Show the end balances in asset and liability accounts. +> More information: . + +- 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` diff --git a/doc/tldr/hledger-import.md b/doc/tldr/hledger-import.md deleted file mode 120000 index 74732d748..000000000 --- a/doc/tldr/hledger-import.md +++ /dev/null @@ -1 +0,0 @@ -../../../tldr/pages/common/hledger-import.md \ No newline at end of file diff --git a/doc/tldr/hledger-import.md b/doc/tldr/hledger-import.md new file mode 100644 index 000000000..d1d7a82ce --- /dev/null +++ b/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: . + +- 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` diff --git a/doc/tldr/hledger-incomestatement.md b/doc/tldr/hledger-incomestatement.md deleted file mode 120000 index bb1dca72d..000000000 --- a/doc/tldr/hledger-incomestatement.md +++ /dev/null @@ -1 +0,0 @@ -../../../tldr/pages/common/hledger-incomestatement.md \ No newline at end of file diff --git a/doc/tldr/hledger-incomestatement.md b/doc/tldr/hledger-incomestatement.md new file mode 100644 index 000000000..f6af0a043 --- /dev/null +++ b/doc/tldr/hledger-incomestatement.md @@ -0,0 +1,20 @@ +# hledger incomestatement + +> Show revenue inflows and expense outflows during the report period. +> More information: . + +- 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` diff --git a/doc/tldr/hledger-print.md b/doc/tldr/hledger-print.md deleted file mode 120000 index cb3e5c830..000000000 --- a/doc/tldr/hledger-print.md +++ /dev/null @@ -1 +0,0 @@ -../../../tldr/pages/common/hledger-print.md \ No newline at end of file diff --git a/doc/tldr/hledger-print.md b/doc/tldr/hledger-print.md new file mode 100644 index 000000000..af3f0e5b8 --- /dev/null +++ b/doc/tldr/hledger-print.md @@ -0,0 +1,32 @@ +# hledger print + +> Show full journal entries, representing transactions. +> More information: . + +- 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}}` diff --git a/doc/tldr/hledger-ui.md b/doc/tldr/hledger-ui.md deleted file mode 120000 index f45f77b2c..000000000 --- a/doc/tldr/hledger-ui.md +++ /dev/null @@ -1 +0,0 @@ -../../../tldr/pages/common/hledger-ui.md \ No newline at end of file diff --git a/doc/tldr/hledger-ui.md b/doc/tldr/hledger-ui.md new file mode 100644 index 000000000..bd2a7f5ae --- /dev/null +++ b/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: . + +- 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` diff --git a/doc/tldr/hledger-web.md b/doc/tldr/hledger-web.md deleted file mode 120000 index da9f29ba5..000000000 --- a/doc/tldr/hledger-web.md +++ /dev/null @@ -1 +0,0 @@ -../../../tldr/pages/common/hledger-web.md \ No newline at end of file diff --git a/doc/tldr/hledger-web.md b/doc/tldr/hledger-web.md new file mode 100644 index 000000000..76f1c1063 --- /dev/null +++ b/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: . + +- 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` diff --git a/doc/tldr/hledger.md b/doc/tldr/hledger.md deleted file mode 120000 index de929ba7d..000000000 --- a/doc/tldr/hledger.md +++ /dev/null @@ -1 +0,0 @@ -../../../tldr/pages/common/hledger.md \ No newline at end of file diff --git a/doc/tldr/hledger.md b/doc/tldr/hledger.md new file mode 100644 index 000000000..585c84f19 --- /dev/null +++ b/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: . + +- 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`