From 97dfdf07688dfd0efdee94348f175bbde9c7b515 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 14 Apr 2013 18:16:26 -0700 Subject: [PATCH] docs: misc cleanups, expand commands list --- DOCS.md | 4 +-- INSTALL.md | 4 +-- MANUAL.md | 102 ++++++++++++++++++++++++++++++++--------------------- 3 files changed, 66 insertions(+), 44 deletions(-) diff --git a/DOCS.md b/DOCS.md index 2ccb38539..871735c1f 100644 --- a/DOCS.md +++ b/DOCS.md @@ -26,8 +26,8 @@ title: hledger docs **Related:** -[Accounting For Dragons](http://podcastle.org/2009/10/09/pc-miniature-38-accounting-for-dragons) *motivating!*\ -[ledger](http://ledger-cli.org) and its [manual](http://ledger-cli.org/3.0/doc/ledger3.html) *informative!*\ +[Accounting For Dragons](http://podcastle.org/2009/10/09/pc-miniature-38-accounting-for-dragons) *informative!*\ +[ledger](http://ledger-cli.org) and its [manual](http://ledger-cli.org/3.0/doc/ledger3.html) *explanatory!*\ [beancount](http://furius.ca/beancount/), [penny](https://github.com/massysett/penny), [UMM](http://hackage.haskell.org/package/UMM) diff --git a/INSTALL.md b/INSTALL.md index 699387912..692bff797 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -63,17 +63,17 @@ will also be available as hledger's `web` subcommand. Other add-on packages are available on Hackage, although some of these are unmaintained or work only on certain platforms: -- [hledger-vty](http://hackage.haskell.org/package/hledger-vty) - [hledger-chart](http://hackage.haskell.org/package/hledger-chart) - [hledger-interest](http://hackage.haskell.org/package/hledger-interest) - [hledger-irr](http://hackage.haskell.org/package/hledger-irr) +- [hledger-vty](http://hackage.haskell.org/package/hledger-vty) ## Install the latest development version To download and build the latest development version of hledger, ensure you have [git](http://git-scm.com) installed, then: - $ git clone http://github.com/simonmichael/hledger.git # or git@github.com:simonmichael/hledger.git + $ git clone http://github.com/simonmichael/hledger.git $ cd hledger $ cabal update $ cabal install ./hledger-lib ./hledger [./hledger-web] diff --git a/MANUAL.md b/MANUAL.md index 723315993..c008b43ab 100644 --- a/MANUAL.md +++ b/MANUAL.md @@ -27,10 +27,8 @@ You can use it to, eg: - track time and report by day/week/month/project - get accurate numbers for client billing and tax filing -hledger works on linux, mac and windows. You can fund ready-to-run -binaries of the latest release - see the [download page](DOWNLOAD.html). -Otherwise, fetch and build the latest release from Hackage with cabal-install. -Eg: +hledger works on linux, mac and windows. People most often build the +latest release with cabal-install, like so: $ cabal update $ cabal install hledger [hledger-web] @@ -38,7 +36,7 @@ Eg: $ hledger --version hledger 0.19.3 -For more help with this, see the [Installation Guide](INSTALL.html). +For more help with this, and other install options, see the [Installation Guide](INSTALL.html). ## Basic Usage @@ -76,7 +74,7 @@ enter some transactions. Or, save this $ hledger reg desc:shop # show postings with shop in the description $ hledger activity # show transactions per day as a bar chart -## Data formats +## Data format ### Journal files @@ -543,9 +541,10 @@ Most subcommands are built in to the core hledger package; more [add-on commands](#add-on-commands) will appear if you install additional hledger-* packages. You can also install your own subcommands by putting programs or scripts named `hledger-NAME` in your PATH. -### Misc commands +### Data entry -Here are some miscellaneous commands you might use to get started: +Many hledger users edit their journals directly with a text editor, or generate them from CSV. +For more interactive data entry, there is the `add` command and also the `web` add-on (below). #### add @@ -604,20 +603,8 @@ An example: Starting a new transaction. date ? [2013/04/09]: $ - -#### test -This command runs hledger's built-in unit tests and displays a quick -report. A pattern can be provided to filter tests by name. It's mainly -used in development, but it's also nice to be able to check hledger for -smoke at any time. - -Examples: - - $ hledger test - $ hledger test -v balance - -### Reporting commands +### Reporting These are the commands for querying your ledger. @@ -731,10 +718,25 @@ Examples: $ hledger stats $ hledger stats -p 'monthly in 2009' -### Add-on commands +### Utility + +#### test + +This command runs hledger's built-in unit tests and displays a quick +report. A pattern can be provided to filter tests by name. It's mainly +used in development, but it's also nice to be able to check hledger for +smoke at any time. + +Examples: + + $ hledger test + $ hledger test -v balance + +### Add-ons The following extra commands will be available if they have been -[installed](#installing) (run `hledger` by itself to find out): +[installed](INSTALL.html) (run `hledger --help` to find out). Some of +these add-on packages may be out of date or may not work on all platforms. #### web @@ -773,21 +775,25 @@ Examples: $ hledger-web -E -B --depth 2 -f some.journal $ hledger-web --port 5010 --base-url http://some.vhost.com --debug -#### vty +#### interest -The vty command (provided by the hledger-vty package) starts a simple -curses-style (full-screen, text) user interface, which allows interactive -navigation of the print/register/balance reports. This lets you browse -around and explore your numbers quickly with less typing. +[hledger-interest](http://hackage.haskell.org/package/hledger-interest) +computes interests for a given account. Using command line flags, +the program can be configured to use various schemes for day-counting, +such as act/act, 30/360, 30E/360, and 30/360isda. Furthermore, it +supports a (small) number of interest schemes, i.e. annual interest +with a fixed rate and the scheme mandated by the German BGB288 +(Basiszins für Verbrauchergeschäfte). See the package page for more. -vty-specific options: +#### irr - --debug-vty run with no terminal output, showing console - -Examples: - - $ hledger vty - $ hledger vty -BE food +[hledger-irr](http://hackage.haskell.org/package/hledger-irr) +computes the internal rate of return, also known as the effective +interest rate, of a given investment. After specifying what account +holds the investment, and what account stores the gains (or losses, or +fees, or cost), it calculates the hypothetical annual rate of fixed +rate investment that would have provided the exact same cash flow. +See the package page for more. #### chart @@ -824,6 +830,23 @@ Examples: $ hledger chart ^expenses -o balance.png --size 1000x600 --items 20 $ for m in 01 02 03 04 05 06 07 08 09 10 11 12; do hledger chart -p 2009/$m ^expenses --depth 2 -o expenses-2009$m.png --size 400x300; done +#### vty + +The vty command (provided by the hledger-vty package) starts a simple +curses-style (full-screen, text) user interface, which allows interactive +navigation of the print/register/balance reports. This lets you browse +around and explore your numbers quickly with less typing. + +vty-specific options: + + --debug-vty run with no terminal output, showing console + +Examples: + + $ hledger vty + $ hledger vty -BE food + + ## Reporting options The following additional features and options allow for fine-grained @@ -1056,12 +1079,11 @@ The default output format is `%20(total) %2(depth_spacer)%-(account)` ## Troubleshooting -Here are some issues you might encounter when you run hledger: -Please also seek -[support](DEVELOPMENT.html#support) from the +Here are some issues you might encounter when you run hledger +(and remember you can also seek help from the [IRC channel](irc://irc.freenode.net/#ledger), [mail list](http://hledger.org/list) or -[bug tracker](http://hledger.org/bugs). +[bug tracker](http://hledger.org/bugs)): #. **hledger installed, but running hledger says something like No command 'hledger' found** cabal installs binaries into a special directory, which should be added @@ -1069,7 +1091,7 @@ Please also seek ~/.cabal/bin. #. **hledger fails to parse some valid ledger files** - See [file format compatibility](#file-format-compatibility). + See [file format differences](FAQ.html#what-are-the-file-format-differences). #. **hledger gives "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors** In order to handle non-ascii letters and symbols (like £), hledger needs