slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: The flattening: adapt to the site's depth-1 page TOCs

Browse Source 
and tweak command/screen headings.

This goes further in the direction of showing simple lists of topics
instead of outlines. mdbook-toc doesn't support configuring the TOC
depth this per page, so it has to be site wide.

Overall I feel this is better, see eg the hledger manual.  It hides a
lot of interesting topic names but a shorter, linear list is less
scary and clearer than a huge scrolling outline. Once you click in to
a section and find a subsection of interest, it's still easy to
bookmark/share those by clicking their heading.
This commit is contained in:
Simon Michael 2024-05-22 13:06:08 -10:00
parent af568f1ae2
commit 46b79079bf
5 changed files with 57 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
doc/CONTRIBUTING.md
View File

@ -11,27 +11,27 @@ We invite you to jump in, and thank you!
There are many ways to help. Browse the ideas below, There are many ways to help. Browse the ideas below,
and/or say hello in the [chat](support.md) and we'll help find you a useful job. and/or say hello in the [chat](support.md) and we'll help find you a useful job.
### Visitor / passer-by ? ## Visitor / passer-by ?
- Give feedback on the site and your impressions of the project, small or large, good or bad. This is valuable. - Give feedback on the site and your impressions of the project, small or large, good or bad. This is valuable.
### New user ? ## New user ?
- Report your new user experiences, small or large, good or bad. This is valuable. - Report your new user experiences, small or large, good or bad. This is valuable.
### Tech supporter ? ## Tech supporter ?
- Share what you've learned so far to help others. This is a quadruple win - - Share what you've learned so far to help others. This is a quadruple win -
it helps them, improves your own understanding, builds community, and frees up maintainer time! it helps them, improves your own understanding, builds community, and frees up maintainer time!
### Funder ? ## Funder ?
- Become a financial backer: [Sponsor hledger](sponsor.md) - Become a financial backer: [Sponsor hledger](sponsor.md)
- Contribute or pledge bounties on issues you care about - Contribute or pledge bounties on issues you care about
- Ask your organization to contribute - Ask your organization to contribute
- Work on project [finance](FINANCE.md) - accounting, fundraising, sustainability.. - Work on project [finance](FINANCE.md) - accounting, fundraising, sustainability..
### Tester ? ## Tester ?
- Test installation on platforms you have access to - Test installation on platforms you have access to
- Test examples, advice, and links in the docs - Test examples, advice, and links in the docs
@ -42,7 +42,7 @@ and/or say hello in the [chat](support.md) and we'll help find you a useful job.
- Test new releases, report regressions and collect regression finder bounties - Test new releases, report regressions and collect regression finder bounties
- Discuss and help analyse problems via chat/mail list/issue tracker - Discuss and help analyse problems via chat/mail list/issue tracker
### Bug wrangler ? ## Bug wrangler ?
- Respond to issue reports when needed, especially if they are from new reporters - Respond to issue reports when needed, especially if they are from new reporters
- Add appropriate labels to issues to categorise them - Add appropriate labels to issues to categorise them
@ -52,42 +52,42 @@ and/or say hello in the [chat](support.md) and we'll help find you a useful job.
- Improve issues urls & dashboard(s) - Improve issues urls & dashboard(s)
- Help ensure a consistently good bug-reporting and PR-contributing experience - Help ensure a consistently good bug-reporting and PR-contributing experience
### Bug fixer ? ## Bug fixer ?
- Get familiar with issue tracker, issue labels, shortcut urls, issue dashboards.. - Get familiar with issue tracker, issue labels, shortcut urls, issue dashboards..
- Review open bug reports - Review open bug reports
- Try to fix or help fix some - Try to fix or help fix some
- Fix regressions and collect regression fixer bounties - Fix regressions and collect regression fixer bounties
### Developer ? ## Developer ?
- Give feedback on your experience using the hledger packages - Give feedback on your experience using the hledger packages
- Suggest API improvements - Suggest API improvements
- See the [Developer FAQ](DEVFAQ.md) and other [Developer docs](dev.md). - See the [Developer FAQ](DEVFAQ.md) and other [Developer docs](dev.md).
### Technical writer ? ## Technical writer ?
- Get familiar with the documentation, website and online presence; review and test - Get familiar with the documentation, website and online presence; review and test
- Get familiar with the doc/site source files and generation process (see [Just, Make, Shake](JUST-MAKE-SHAKE.md)) - Get familiar with the doc/site source files and generation process (see [Just, Make, Shake](JUST-MAKE-SHAKE.md))
- Help improve user, contributor, process docs - Help improve user, contributor, process docs
### Web designer / webmaster ? ## Web designer / webmaster ?
- Review and help improve our web presence - Review and help improve our web presence
### Graphic designer ? ## Graphic designer ?
- Review and improve logos, graphics, design language - Review and improve logos, graphics, design language
- Contribute illustrations, diagrams, cartoons, mockups - Contribute illustrations, diagrams, cartoons, mockups
### Packager ? ## Packager ?
- Start/test/improve hledger's packaging on various platforms - Start/test/improve hledger's packaging on various platforms
- Find/assist/take over from existing packagers - Find/assist/take over from existing packagers
- Improve packaging-related docs/links - Improve packaging-related docs/links
- Develop mac or windows installers - Develop mac or windows installers
### Marketer / communicator ? ## Marketer / communicator ?
- Clarify project goals, value proposition, brand, mission, story - Clarify project goals, value proposition, brand, mission, story
- Monitor product-market fit - Monitor product-market fit
@ -95,18 +95,18 @@ and/or say hello in the [chat](support.md) and we'll help find you a useful job.
- Influence developer priorities - Influence developer priorities
- Spread the word! - Spread the word!
### Product designer ? ## Product designer ?
- Contribute design input to discussions in issue tracker and elsewhere - Contribute design input to discussions in issue tracker and elsewhere
- Develop your whole-system view of the hledger "product" (user software, docs, online presence, new user experience etc.) - Develop your whole-system view of the hledger "product" (user software, docs, online presence, new user experience etc.)
### Community builder/moderator ? ## Community builder/moderator ?
- Participate in [support](support.md) channels - Participate in [support](support.md) channels
- As a regular member or moderator, help to resolve/report incidents - As a regular member or moderator, help to resolve/report incidents
- Help uphold and improve our community structures and dynamics - Help uphold and improve our community structures and dynamics
### Project manager ? ## Project manager ?
- Monitor, report on project progress and performance - Monitor, report on project progress and performance
- Research, compare and report on successful projects, related projects - Research, compare and report on successful projects, related projects
@ -114,7 +114,7 @@ and/or say hello in the [chat](support.md) and we'll help find you a useful job.
- Assist with marketing, communication, outreach - Assist with marketing, communication, outreach
- Assist with maintainer tasks - Assist with maintainer tasks
### Maintainer / co-maintainer ? ## Maintainer / co-maintainer ?
- Manage and ship releases - Manage and ship releases
- Manage the project roadmap - Manage the project roadmap

10
doc/DEVFAQ.md
View File

@ -6,7 +6,7 @@ This is just getting started. It will absorb some of the other [Developer docs](
<!-- ## Developing hledger --> <!-- ## Developing hledger -->
### How do I get/build the hledger source ? ## How do I get/build the hledger source ?
```cli ```cli
$ git clone https://github.com/simonmichael/hledger $ git clone https://github.com/simonmichael/hledger
@ -15,7 +15,7 @@ $ stack build
You can specify `hledger`, `hledger-ui` or `hledger-web` as an argument to build just that executable. You can specify `hledger`, `hledger-ui` or `hledger-web` as an argument to build just that executable.
Please see [Install > Build from source](install.md#build-from-source) for more details and other build methods. Please see [Install > Build from source](install.md#build-from-source) for more details and other build methods.
### What other repos are there ? ## What other repos are there ?
There are three official repos: There are three official repos:
- <https://github.com/simonmichael/hledger> - the main hledger repo, for hledger, hledger-ui and hledger-web. Shortcut url: <https://code.hledger.org> - <https://github.com/simonmichael/hledger> - the main hledger repo, for hledger, hledger-ui and hledger-web. Shortcut url: <https://code.hledger.org>
@ -24,7 +24,7 @@ There are three official repos:
And third-party add-ons and tools (hledger-iadd, hledger-utils, full fledged hledger, hledger-flow, etc.) have their own repos. And third-party add-ons and tools (hledger-iadd, hledger-utils, full fledged hledger, hledger-flow, etc.) have their own repos.
### How do I run a build in place ? ## How do I run a build in place ?
After building with stack, After building with stack,
```cli ```cli
@ -36,7 +36,7 @@ Or after building with cabal,
$ cabal exec -- hledger [ARGS] $ cabal exec -- hledger [ARGS]
``` ```
### How do I install a build in PATH ? ## How do I install a build in PATH ?
```cli ```cli
$ stack install $ stack install
@ -52,7 +52,7 @@ It will install executables to `~/.cabal/bin`:
$ cabal install all:exes $ cabal install all:exes
``` ```
### How do I build/run with ghc-debug support ? ## How do I build/run with ghc-debug support ?
You might need to stop background builders like HLS, to avoid a fight over the build flag You might need to stop background builders like HLS, to avoid a fight over the build flag
(in VS Code, run the command "Haskell: Stop Haskell LSP server"). (in VS Code, run the command "Haskell: Stop Haskell LSP server").

16
hledger-ui/hledger-ui.m4.md
View File

@ -222,33 +222,33 @@ Or you can use `ESC` to return directly to the top menu screen.
You can also use a command line flag to specific a different startup screen You can also use a command line flag to specific a different startup screen
(`--cs`, `--bs`, `--is`, `--all`, or `--register=ACCT`). (`--cs`, `--bs`, `--is`, `--all`, or `--register=ACCT`).
## Menu ## Menu screen
This is the top-most screen. This is the top-most screen.
From here you can navigate to several screens listing accounts of various types. From here you can navigate to several screens listing accounts of various types.
Note some of these may not show anything until you have configured [account types](/hledger.html#account-types). Note some of these may not show anything until you have configured [account types](/hledger.html#account-types).
## Cash accounts ## Cash accounts screen
This screen shows "cash" (ie, liquid asset) accounts (like `hledger balancesheet type:c`). This screen shows "cash" (ie, liquid asset) accounts (like `hledger balancesheet type:c`).
It always shows balances (historical ending balances on the date shown in the title line). It always shows balances (historical ending balances on the date shown in the title line).
## Balance sheet accounts ## Balance sheet accounts screen
This screen shows asset, liability and equity accounts (like `hledger balancesheetequity`). This screen shows asset, liability and equity accounts (like `hledger balancesheetequity`).
It always shows balances. It always shows balances.
## Income statement accounts ## Income statement accounts screen
This screen shows revenue and expense accounts (like `hledger incomestatement`). This screen shows revenue and expense accounts (like `hledger incomestatement`).
It always shows changes (balance changes in the period shown in the title line). It always shows changes (balance changes in the period shown in the title line).
## All accounts ## All accounts screen
This screen shows all accounts in your journal (unless filtered by a query; like `hledger balance`). This screen shows all accounts in your journal (unless filtered by a query; like `hledger balance`).
It shows balances by default; you can toggle showing changes with the `H` key. It shows balances by default; you can toggle showing changes with the `H` key.
## Register ## Register screen
This screen shows the transactions affecting a particular account. This screen shows the transactions affecting a particular account.
Each line represents one transaction, and shows: Each line represents one transaction, and shows:
@ -292,7 +292,7 @@ unlike command-line hledger).
Press `RIGHT` to view the selected transaction in detail. Press `RIGHT` to view the selected transaction in detail.
## Transaction ## Transaction screen
This screen shows a single transaction, as a general journal entry, This screen shows a single transaction, as a general journal entry,
similar to hledger's print command and journal format (hledger_journal(5)). similar to hledger's print command and journal format (hledger_journal(5)).
@ -321,7 +321,7 @@ So eg to see the effect of using the `E` key, currently you must:
- press `g` to reload the file (or use `-w/--watch` mode) - press `g` to reload the file (or use `-w/--watch` mode)
- press `LEFT` then `RIGHT` to exit and re-enter the transaction screen. - press `LEFT` then `RIGHT` to exit and re-enter the transaction screen.
## Error ## Error screen
This screen will appear if there is a problem, such as a parse error, This screen will appear if there is a problem, such as a parse error,
when you press g to reload. Once you have fixed the problem, when you press g to reload. Once you have fixed the problem,

18
hledger/Hledger/Cli/Commands/commands.m4
View File

@ -4,12 +4,12 @@ m4_dnl Keep synced with Hledger.Cli.Commands.commandsList, hledger.m4.md.
m4_dnl The spaced colons avoid anchor/link collisions with similarly-named sections. m4_dnl The spaced colons avoid anchor/link collisions with similarly-named sections.
m4_define({{_commands_}}, m4_define({{_commands_}},
{{ {{
## HELP : # Help commands
_command_({{Help}}) _command_({{Help}})
_command_({{Demo}}) _command_({{Demo}})
## USER INTERFACES : # User interface commands
## ui ## ui
@ -20,12 +20,12 @@ Runs [hledger-ui](hledger-ui.md) (if installed).
Runs [hledger-web](hledger-web.md) (if installed). Runs [hledger-web](hledger-web.md) (if installed).
## ENTERING DATA : # Data entry commands
_command_({{Add}}) _command_({{Add}})
_command_({{Import}}) _command_({{Import}})
## BASIC REPORTS : # Basic report commands
_command_({{Accounts}}) _command_({{Accounts}})
_command_({{Codes}}) _command_({{Codes}})
@ -38,7 +38,7 @@ _command_({{Prices}})
_command_({{Stats}}) _command_({{Stats}})
_command_({{Tags}}) _command_({{Tags}})
## STANDARD REPORTS : # Standard report commands
_command_({{Print}}) _command_({{Print}})
_command_({{Aregister}}) _command_({{Aregister}})
@ -48,21 +48,21 @@ _command_({{Balancesheetequity}})
_command_({{Cashflow}}) _command_({{Cashflow}})
_command_({{Incomestatement}}) _command_({{Incomestatement}})
## ADVANCED REPORTS : # Advanced report commands
_command_({{Balance}}) _command_({{Balance}})
_command_({{Roi}}) _command_({{Roi}})
## CHARTS : # Chart commands
_command_({{Activity}}) _command_({{Activity}})
## GENERATING DATA : # Data generation commands
_command_({{Close}}) _command_({{Close}})
_command_({{Rewrite}}) _command_({{Rewrite}})
## MAINTENANCE : # Maintenance commands
_command_({{Check}}) _command_({{Check}})
_command_({{Diff}}) _command_({{Diff}})

36
hledger/hledger.m4.md
View File

@ -6021,22 +6021,22 @@ If you have installed more [add-on commands](../scripts.md), they also will be l
<!-- keep commands & descriptions synced with Hledger.Cli.Commands.commandsList, commands.m4 --> <!-- keep commands & descriptions synced with Hledger.Cli.Commands.commandsList, commands.m4 -->
**[HELP](#help-)** **[Help commands](#help-commands)**
- [help](#help) - show the hledger manual with info/man/pager - [help](#help) - show the hledger manual with info/man/pager
- [demo](#demo) - show small hledger demos in the terminal - [demo](#demo) - show small hledger demos in the terminal
**[USER INTERFACES](#user-interfaces-)** **[User interface commands](#user-interface-commands)**
- [ui](hledger-ui.html) - (if installed) run hledger's terminal UI - [ui](hledger-ui.html) - (if installed) run hledger's terminal UI
- [web](hledger-web.html) - (if installed) run hledger's web UI - [web](hledger-web.html) - (if installed) run hledger's web UI
**[ENTERING DATA](#entering-data-)** **[Data entry commands](#data-entry-commands)**
- [add](#add) - add transactions using terminal prompts - [add](#add) - add transactions using terminal prompts
- [import](#import) - add new transactions from other files, eg CSV files - [import](#import) - add new transactions from other files, eg CSV files
**[BASIC REPORTS](#basic-reports-)** **[Basic report commands](#basic-report-commands)**
- [accounts](#accounts) - show account names - [accounts](#accounts) - show account names
- [codes](#codes) - show transaction codes - [codes](#codes) - show transaction codes
@ -6049,7 +6049,7 @@ If you have installed more [add-on commands](../scripts.md), they also will be l
- [stats](#stats) - show journal statistics - [stats](#stats) - show journal statistics
- [tags](#tags-1) - show tag names - [tags](#tags-1) - show tag names
**[STANDARD REPORTS](#standard-reports-)** **[Standard report commands](#standard-report-commands)**
- [print](#print) - show transactions or export journal data - [print](#print) - show transactions or export journal data
- [aregister](#aregister) (areg) - show transactions in a particular account - [aregister](#aregister) (areg) - show transactions in a particular account
@ -6059,21 +6059,21 @@ If you have installed more [add-on commands](../scripts.md), they also will be l
- [cashflow](#cashflow) (cf) - show changes in liquid assets - [cashflow](#cashflow) (cf) - show changes in liquid assets
- [incomestatement](#incomestatement) (is) - show revenues and expenses - [incomestatement](#incomestatement) (is) - show revenues and expenses
**[ADVANCED REPORTS](#advanced-reports-)** **[Advanced report commands](#advanced-report-commands)**
- [balance](#balance) (bal) - show balance changes, end balances, budgets, gains.. - [balance](#balance) (bal) - show balance changes, end balances, budgets, gains..
- [roi](#roi) - show return on investments - [roi](#roi) - show return on investments
**[CHARTS](#charts-)** **[Chart commands](#chart-commands)**
- [activity](#activity) - show bar charts of posting counts per period - [activity](#activity) - show bar charts of posting counts per period
**[GENERATING DATA](#generating-data-)** **[Data generation commands](#data-generation-commands)**
- [close](#close) - generate balance-zeroing/restoring transactions - [close](#close) - generate balance-zeroing/restoring transactions
- [rewrite](#rewrite) - generate auto postings, like print --auto - [rewrite](#rewrite) - generate auto postings, like print --auto
**[MAINTENANCE](#maintenance-)** **[Maintenance commands](#maintenance-commands)**
- [check](#check) - check for various kinds of error in the data - [check](#check) - check for various kinds of error in the data
- [diff](#diff) - compare account transactions in two journal files - [diff](#diff) - compare account transactions in two journal files
@ -6099,7 +6099,7 @@ _commands_
Here are some quick examples of how to do some basic tasks with hledger. Here are some quick examples of how to do some basic tasks with hledger.
## Getting help # Getting help
Here's how to list commands and view options and command docs: Here's how to list commands and view options and command docs:
@ -6120,7 +6120,7 @@ $ hledger help --help # find out more about the help command
To view manuals and introductory docs on the web, visit <https://hledger.org>. To view manuals and introductory docs on the web, visit <https://hledger.org>.
Chat and mail list support and discussion archives can be found at <https://hledger.org/support>. Chat and mail list support and discussion archives can be found at <https://hledger.org/support>.
## Constructing command lines # Constructing command lines
hledger has a flexible command line interface. hledger has a flexible command line interface.
We strive to keep it simple and ergonomic, but if you run into one of We strive to keep it simple and ergonomic, but if you run into one of
@ -6133,7 +6133,7 @@ here are some tips that might help:
- if needed, also add a backslash to hide regular expression metacharacters from the shell - if needed, also add a backslash to hide regular expression metacharacters from the shell
- to see how a misbehaving command line is being parsed, add `--debug=2`. - to see how a misbehaving command line is being parsed, add `--debug=2`.
## Starting a journal file # Starting a journal file
hledger looks for your accounting data in a journal file, `$HOME/.hledger.journal` by default: hledger looks for your accounting data in a journal file, `$HOME/.hledger.journal` by default:
```cli ```cli
@ -6168,7 +6168,7 @@ Commodities : 0 ()
Market prices : 0 () Market prices : 0 ()
``` ```
## Setting LEDGER_FILE # Setting LEDGER_FILE
How to set `LEDGER_FILE` permanently depends on your setup: How to set `LEDGER_FILE` permanently depends on your setup:
@ -6200,7 +6200,7 @@ or try running these commands in a powershell window
> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" > SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal"
``` ```
## Setting opening balances # Setting opening balances
Pick a starting date for which you can look up the balances of some Pick a starting date for which you can look up the balances of some
real-world assets (bank accounts, wallet..) and liabilities (credit cards..). real-world assets (bank accounts, wallet..) and liabilities (credit cards..).
@ -6276,7 +6276,7 @@ If you're using version control, this could be a good time to commit the journal
$ git commit -m 'initial balances' 2023.journal $ git commit -m 'initial balances' 2023.journal
``` ```
## Recording transactions # Recording transactions
As you spend or receive money, you can record these transactions As you spend or receive money, you can record these transactions
using one of the methods above (text editor, hledger add) using one of the methods above (text editor, hledger add)
@ -6300,7 +6300,7 @@ and hledger.org for more ideas:
assets:bank:checking $1000 assets:bank:checking $1000
``` ```
## Reconciling # Reconciling
Periodically you should reconcile - compare your hledger-reported balances Periodically you should reconcile - compare your hledger-reported balances
against external sources of truth, like bank statements or your bank's website - against external sources of truth, like bank statements or your bank's website -
@ -6352,7 +6352,7 @@ If you're using version control, this can be another good time to commit:
$ git commit -m 'txns' 2023.journal $ git commit -m 'txns' 2023.journal
``` ```
## Reporting # Reporting
Here are some basic reports. Here are some basic reports.
@ -6500,7 +6500,7 @@ $ hledger activity -W
2023-01-06 **** 2023-01-06 ****
2023-01-13 **** 2023-01-13 ****
``` ```
## Migrating to a new file # Migrating to a new file
At the end of the year, you may want to continue your journal in a new file, At the end of the year, you may want to continue your journal in a new file,
so that old transactions don't slow down or clutter your reports, so that old transactions don't slow down or clutter your reports,