diff --git a/doc/site/developer-guide.md b/doc/site/developer-guide.md new file mode 120000 index 000000000..ecc4a32b3 --- /dev/null +++ b/doc/site/developer-guide.md @@ -0,0 +1 @@ +../developer-guide.md \ No newline at end of file diff --git a/doc/site/download.md b/doc/site/download.md new file mode 100644 index 000000000..32b489b11 --- /dev/null +++ b/doc/site/download.md @@ -0,0 +1,31 @@ +# Download + +\\ +**I want to download and get started quickly !**\\ + +| **I'm on Debian or Ubuntu**\\ `apt-get install hledger[-web]` \\ \\ **I'm on Gentoo**\\ `emerge hledger[-web]` \\ \\ **I'm on Red Hat/Fedora/CentOS**\\ `yum install hledger` \\ \\ **I'm on NixOS**\\ `nix-env -iA nixpkgs.haskellPackages.hledger` | **I'm on Windows**\\ Download, unzip, and run:\\ [hledger-0.23.3.win32.zip](http://hledger.org/downloads/hledger-0.23.3-windows-intel32.exe.zip)\\ [hledger-web-0.23.3.win32.zip](http://hledger.org/downloads/hledger-web-0.23.3-windows-intel32.exe.zip)\\ | **I'm on Mac**\\ Use cabal | + +**I want to build the +[latest release](http://hackage.haskell.org/package/hledger-web) with +[GHC](http://haskell.org/haskell) and +[cabal](http://haskell.org/cabal/download.html)...** +| `cabal sandbox init; cabal update; cabal install hledger[-web]`\\ | + + +**I want to build the [latest development code](http://hledger.org/code)...** +| `git clone https://github.com/simonmichael/hledger; cd hledger; make sandbox install`\\ | + +**I want more info...** + +The [[installing|Installation Guide]] describes how to install using cabal in more detail. + +hledger is shipped as two executables: `hledger` (the command-line +tool) and `hledger-web` (the web interface). If you install +`hledger-web`, `hledger` will also be installed automatically (except on Windows). + +Building, testing and supporting cross-platform binaries is costly, so +it's demand-driven - you can indicate demand by making a project +donation of any size. Binaries funded in this way will be linked here. +This is a quick way to help the project and your fellow users! + +[[https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=5J33NLXYXCYAY|{{https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif }}]] diff --git a/doc/site/faq.md b/doc/site/faq.md new file mode 100644 index 000000000..78ed96cf7 --- /dev/null +++ b/doc/site/faq.md @@ -0,0 +1,215 @@ +# Frequently asked questions + +## hledger and ledger + +### How does hledger relate to ledger ? + +hledger was inspired by and is partly a clone of John Wiegley's [ledger](http://ledger-cli.org), +specifically Ledger 3. + +I was a happy ledger user and contributor for some time; I still use it +occasionally. I wrote hledger because I wanted to develop financial tools +in the Haskell programming language and ecosystem, whose advantages I +believe are compelling. I have also tried to make hledger a little more +simple, usable, installable, documented, appealing to collaborators, and +to provide alternate user interfaces to make it more widely useful. + +ledger has more advanced power-user features on the command-line +(periodic and modifier transactions, budgets, capital gains tracking, +value expressions, custom output formats, etc.) and it remains faster +and more memory efficient (for now!)... + +hledger builds faster and has an up-to-date manual and an optional web +interface (which often works on ledger files too)... + +The two projects collaborate freely. We share the +[#ledger](irc://irc.freenode.net/#ledger) IRC channel but have +separate mail lists +([hledger list](http://groups.google.com/group/hledger/), +[ledger-cli list](http://groups.google.com/group/ledger-cli/)). I try +to give back by providing infrastructure +([ledger-cli.org](http://ledger-cli.org)) and IRC support. +hledger stays compatible with ledger wherever possible, so that you +can often use both tools on the same data file. + +Summary: hledger is a friendly, co-evolving, compatible rewrite of Ledger +in Haskell, lacking some of ledger's power features and raw performance, +and focussing on robustness, usability, ease of development, and +experimental add-ons such as the [web interface](MANUAL.html#web). + +### And ledger 4 ? + +There is also a [[https://github.com/ledger/ledger4|ledger4]] on github; this is +John's own rewrite of the core of +ledger 3 in haskell. It's an early library prototype, not a usable tool. +Perhaps some day hledger or something like it would use this as its foundation. + +### File format differences ? + +hledger's file format is mostly identical with ledger's, by design. +Generally, it's easy to keep a journal file that works with both hledger +and ledger if you avoid ledger's most specialised syntax. +Some ledger syntax is parsed but ignored (such as +[automated transactions](http://ledger-cli.org/3.0/doc/ledger3.html#Automated-Transactions), [periodic transactions](http://ledger-cli.org/3.0/doc/ledger3.html#Periodic-Transactions), and +[[manual#historical-prices|historical prices]]). +Some features are not currently parsed and will cause an error, eg +ledger's more recent top-level directives. There can also be subtle +differences in parser behaviour, eg [[manual#comments|hledger comments]] vs [[http://ledger-cli.org/3.0/doc/ledger3.html#Commenting-on-your-Journal|ledger comments]]. + +### Feature differences ? + +hledger mimics a subset of [ledger 3.x](http://ledger-cli.org), and adds some features of its own. + +We currently support: + +- ledger's journal format, mostly +- csv format +- timelog format +- regular journal transactions +- multiple commodities +- fixed prices +- virtual postings +- print, register & balance commands +- filtering by many criteria, with different query syntax +- display expressions containing just a simple date predicate +- some basic output formatting + +We do not support: + +- automated transactions +- value expressions +- fluctuating prices and historical price records +- display formats other than `d>[DATE]` or similar +- budget reports + +And we add these commands: + +- add +- balancesheet +- cashflow +- chart +- incomestatement +- irr +- interest +- vty +- web + +### Option/command differences ? + +ledger options and commands not supported include: +``` +Basic options: +-o, --output FILE write output to FILE +-i, --init-file FILE initialize ledger using FILE (default: ~/.ledgerrc) +-a, --account NAME use NAME for the default account (useful with QIF) + +Report filtering: +-c, --current show only current and past entries (not future) +--period-sort EXPR sort each report period's entries by EXPR +-L, --actual consider only actual (non-automated) transactions +--budget generate budget entries based on periodic entries +--add-budget show all transactions plus the budget +--unbudgeted show only unbudgeted transactions +--forecast EXPR generate forecast entries while EXPR is true +-l, --limit EXPR calculate only transactions matching EXPR +-t, --amount EXPR use EXPR to calculate the displayed amount +-T, --total EXPR use EXPR to calculate the displayed total + +Output customization: +-n, --collapse Only show totals in the top-most accounts. +-P, --by-payee show summarized totals by payee +-x, --comm-as-payee set commodity name as the payee, for reporting +--dow show a days-of-the-week report +-S, --sort EXPR sort report according to the value expression EXPR +--head COUNT show only the first COUNT entries (negative inverts) +--tail COUNT show only the last COUNT entries (negative inverts) +--pager PAGER send all output through the given PAGER program +-A, --average report average transaction amount +-D, --deviation report deviation from the average +-%, --percentage report balance totals as a percentile of the parent +--totals in the "xml" report, include running total +-j, --amount-data print only raw amount data (useful for scripting) +-J, --total-data print only raw total data +-y, --date-format STR use STR as the date format (default: %Y/%m/%d) +--balance-format --register-format --print-format +--plot-amount-format --plot-total-format --equity-format +--prices-format --wide-register-format + +Commodity reporting: +--price-db FILE sets the price database to FILE (def: ~/.pricedb) +-L, --price-exp MINS download quotes only if newer than MINS (def: 1440) +-Q, --download download price information when needed +-O, --quantity report commodity totals (this is the default) +-V, --market report last known market value +-g, --performance report gain/loss for each displayed transaction +-G, --gain report net gain/loss + +Commands: +xml [REGEXP]... print matching entries in XML format +equity [REGEXP]... output equity entries for matching accounts +prices [REGEXP]... display price history for matching commodities +entry DATE PAYEE AMT output a derived entry, based on the arguments +``` + +### Other functionality differences ? + +- hledger recognises description and negative patterns by "desc:" + and "not:" prefixes, unlike ledger 3's free-form parser + +- hledger does not require a space between command-line flags and their values, + eg `-fFILE` works as well as `-f FILE` + +- hledger's weekly reporting intervals always start on mondays + +- hledger shows start and end dates of the intervals requested, + not just the span containing data + +- hledger always shows timelog balances in hours + +- hledger splits multi-day timelog sessions at midnight by default (Ledger does this with an option) + +- hledger doesn't track the value of commodities with varying + price; prices are fixed as of the transaction date + +- hledger's output follows the decimal point character, digit grouping, + and digit group separator character used in the journal. + +- hledger print shows amounts for all postings, and shows unit prices for + amounts which have them. (This means that it does not currently print + multi-commodity transactions in valid journal format.) + +- hledger print ignores the --date2 flag, always showing both dates. + ledger print shows only the secondary date with --aux-date, but not + vice versa. + +- hledger's default commodity directive (D) sets the commodity to be + used for subsequent commodityless amounts, and also sets that + commodity's display settings if such an amount is the first + seen. ledger uses D only for commodity display settings and for the + entry command. + +- hledger generates a description for timelog sessions, instead of + taking it from the clock-out entry + +- hledger's [include directive](MANUAL.html#including-other-files) does not support + shell glob patterns (eg `include *.journal` ), which ledger does. + +- when checking [balance assertions](MANUAL.html#balance-assertions) + hledger sorts the account's postings first by date and then (for + postings with the same date) by parse order. ledger goes strictly by + parse order. + +- ledger allows amounts to have a + [fixed lot price](MANUAL.html#prices) and a regular price in any + order (and uses whichever appears first). hledger requires the fixed + lot price to come last (and ignores it). + +### Implementation differences ? + +ledger is written in C++, whereas hledger is written in [Haskell](http://haskell.org). +Haskell is a highly regarded up-and-coming programming language that enables +a coding style known as pure functional programming, offering the +promise of more bug-free and maintainable software built in fewer +lines of code. Haskell also provides a more abstracted, portable +platform which can make deployment and installation easier in some +cases. \ No newline at end of file diff --git a/doc/site/how-to-read-csv-files.md b/doc/site/how-to-read-csv-files.md new file mode 100644 index 000000000..d608cc3fe --- /dev/null +++ b/doc/site/how-to-read-csv-files.md @@ -0,0 +1,53 @@ +# How to read CSV files + +Here's a quick example of [[manual#csv-files|converting a CSV file]]. + +Say we have downloaded `checking.csv` from a bank for the first time: + + "Date","Note","Amount" + "2012/3/22","DEPOSIT","50.00" + "2012/3/23","TRANSFER TO SAVINGS","-10.00" + +We tell hledger how to intepret this with a file named `checking.csv.rules`, using the [[manual#csv-files|CSV rules syntax]]. Eg: + + # skip the first CSV line (headings) + skip 1 + + # use the first three fields in each CSV record as transaction date, description and amount respectively + fields date, description, amount + + # prepend $ to CSV amounts + currency $ + + # always set the first account to assets:bank:checking + account1 assets:bank:checking + + # if the CSV record contains ‘SAVINGS’, set the second account to assets:bank:savings + # (if not set, it will be expenses:unknown or income:unknown) + if ~ SAVINGS + account2 assets:bank:savings + +Now hledger can read this CSV file as journal data: + + $ hledger -f checking.csv print + using conversion rules file checking.csv.rules + 2012/03/22 DEPOSIT + income:unknown $-50.00 + assets:bank:checking $50.00 + + 2012/03/23 TRANSFER TO SAVINGS + assets:bank:savings $10.00 + assets:bank:checking $-10.00 + +We might save this output as `checking.journal`, and/or merge it (manually) into the main journal file. +We could also run other commands: + + $ hledger -f checking.csv balance + using conversion rules file checking.csv.rules + $50.00 assets:bank + $40.00 checking + $10.00 savings + $-50.00 income:unknown + -------------------- + 0 + diff --git a/doc/site/how-to-use-account-aliases.md b/doc/site/how-to-use-account-aliases.md new file mode 100644 index 000000000..b6ec0c915 --- /dev/null +++ b/doc/site/how-to-use-account-aliases.md @@ -0,0 +1,48 @@ +# How to use account aliases + +Here's an example of using [[manual#account-aliases|account aliases]]. + +Say a sole proprietor has a `personal.journal`: + + 2014/1/2 + expenses:food $1 + assets:cash + +and a `business.journal`: + + 2014/1/1 + expenses:office supplies $1 + assets:business checking + +So each entity (the business owner, and the business) has their own file with its own simple chart of accounts. +However, at tax reporting time we need to view these as a single entity (at least in the US). +In `unified.journal`, we include both files, and rewrite the personal +account names to fit into the business chart of accounts, + + alias expenses = equity:draw:personal + alias assets:cash = assets:personal cash + include personal.journal + end aliases + + include business.journal + +Now we can see the data from both files at once, and the personal account names have changed: + + $ hledger -f unified.journal print + 2014/01/01 # from business.journal - no aliases applied + expenses:office supplies $1 + assets:business checking $-1 + + 2014/01/02 # from personal.journal + equity:draw:personal:food $1 # <- was expenses:food + assets:personal cash $-1 # <- was assets:cash + +You can also specify aliases on the command line. This could be useful to +quickly rewrite account names when sharing a report with someone else, such as +your accountant: + + $ hledger --alias 'my earning=income:business' ... + +Note that +journal directive aliases are applied first, then command-line aliases, +and at most one of each will be applied to each account name. diff --git a/doc/site/index.md b/doc/site/index.md new file mode 100644 index 000000000..4675e5b42 --- /dev/null +++ b/doc/site/index.md @@ -0,0 +1,33 @@ +# hledger + +## lightweight, portable, dependable accounting tools + +hledger is a computer program for easily tracking money, time, or other commodities, +on unix, mac and windows. + +It is first a command-line tool, but there is also a [web interface](manual.html#web) +and a [Haskell library](http://hackage.haskell.org/package/hledger-lib) for +building your own programs and [scripts](more-docs.html#scripting-examples) +(hledger is written in Haskell). +hledger was inspired by and is largely compatible with [Ledger](faq.html#hledger-and-ledger). +hledger is free software available under the GNU General Public License v3+. + +hledger aims to help both computer experts and regular folks +to gain clarity and control in their finances and time management, +but currently it is a bit more suited to techies. +I use it every day to: + +- track spending and income +- see time reports by day/week/month/project +- get accurate numbers for client billing and tax filing +- track invoices + +Though limited in features, hledger is lightweight, usable and reliable. +For some, it is a simpler, less distracting, more future-proof alternative to Quicken or GnuCash. +To get started, see the navigation links. + + + + + + diff --git a/doc/site/installing.md b/doc/site/installing.md new file mode 100644 index 000000000..927a54dda --- /dev/null +++ b/doc/site/installing.md @@ -0,0 +1,263 @@ +# Installation Guide + +- [[#How to install]] +- [[#Troubleshooting]] + +## How to install + +hledger works on GNU/linux, mac and windows. +Here are several ways to install it: + +### a. With your system package manager + +If you have a system package manager that includes hledger, +this will be the quickest and easiest way to install, +if you don't need the very latest version. + +^ On distro/packaging system: ^ Run: ^ +| Debian & Ubuntu: | `apt-get install hledger [hledger-web]` | +| Red Hat, Fedora & CentOS (?): | `yum install hledger` | +| NixOS: | `nix-env -iA nixpkgs.haskellPackages.hledger` | + +### b. Download binaries from hledger.org + +Ready-to-run [[download|downloads]] for GNU/Linux, Mac OSX, and +Microsoft Windows are provided on a donation basis. These have not +been updated recently, but you can fix that by making a donation of +any size (see the page for more). + +These are simple compressed executables (not installers), so after downloading +you may need to decompress, adjust permissions, and rename the file. Eg: + + $ gunzip hledger-web-0.18.2-mac-x86_64.gz + $ chmod +x hledger-web-0.18.2-mac-x86_64 + $ mv hledger-web-0.18.2-mac-x86_64 /usr/local/bin/hledger-web + $ /usr/local/bin/hledger-web --version + +### c. Build released source from Hackage + +You can download and build the latest release yourself using [cabal](http://www.haskell.org/cabal/users-guide/), +the standard installer for Haskell software. +This is the most common way to install hledger, but not always the easiest; +use the troubleshooting tips below if needed. + +Ensure you have [GHC](http://haskell.org/ghc) or +the [Haskell Platform](http://haskell.org/platform) installed. +hledger requires GHC 7.2 or greater, and hledger-web requires GHC 7.4 or greater. + +Also note that some Haskell packages depend on C packages, and cabal +currently isn't able to install or identify those for you. A common +issue is not having all the ncurses C libraries installed. A quick way +to ensure you have all required C libs is to +[install hledger once with your system package manager](#install-with-your-system-package-manager) +before installing the latest version with cabal. + +Then install the hledger command-line tool: + + $ cabal update + $ cabal install hledger [--dry-run] + $ hledger --version + +You should see the proper version reported. +If you get "could not resolve dependencies", "hledger not found", +or any other problem, see [troubleshooting](#troubleshooting). +Also note, to use non-ascii characters like £ in your data, you might need to [configure a suitable locale](MANUAL.html#locale). + +#### Installing hledger-web + +To also install the web interface, in theory just do: + + $ cabal install hledger-web + +In practice, this is a real beast to keep working, so as of 2014/4/17 it's best to do it this way: + + $ cabal sandbox init # start with a clean cabal package db, requires cabal 1.18 + $ cabal update + $ cabal install -j alex happy # update to alex 3.1 and happy 1.19 + $ cabal install -j hledger-web # don't cabal install hledger first + +This installs hledger and hledger-web. hledger-web will appear as the `web` command in hledger's commands list. + +There are other [[start#add-on-commands|add-on packages]], hopefully compatible with the current hledger release and your platform. + +### d. Build latest source from git + +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 + $ cd hledger + $ cabal update + $ [optional: cabal sandbox init] + $ cabal install ./hledger-lib ./hledger [./hledger-web] + +The same [notes above](#install-from-hackage-with-cabal) about requirements and checking your installation apply. Note this time we mention `cabal sandbox`, a feature of cabal 1.18+ which can be used to reduce package dependency problems; it can be used when installing from Hackage as well. + +## Troubleshooting + +There are a lot of ways things can go wrong, especially if you are building from source. +Here are some known issues and things to try. Please also seek +[support](DEVELOPMENT.html#support) from the +[IRC channel](irc://irc.freenode.net/#ledger), +[mail list](http://hledger.org/list) or +[bug tracker](http://hledger.org/bugs). + +Starting from the top, consider whether each of these might apply to +you. Tip: blindly reinstalling/upgrading everything in sight probably +won't work, it's better to go in small steps and understand the problem, +or get help. + +### hledger not found ? +If cabal install succeeded but you get a message like "hledger not found" when you run hledger, +you should add cabal's bin directory to your PATH environment variable. +Eg on unix-like systems, something like: +``` +$ echo 'export PATH=$PATH:~/cabal/bin' >> ~/.bash_profile +$ source ~/.bash_profile +``` +On Ubuntu 14.04: +``` +$ echo 'export PATH=~/.cabal/bin:$PATH' >> ~/.bashrc +$ source ~/.bashrc +``` +Test your PATH-variable with: +``` +$ $PATH +``` +### hledger --version shows wrong version ? +Perhaps you have multiple versions of hledger in your PATH. Eg you installed with the system package manager +(to get C libs) and then with cabal (to get the latest version), but cabal's bin directory appears too late +in the PATH. Move it closer to the front. + +### Did you cabal update ? +If not, `cabal update` and try again. + +### Do you have a new enough version of GHC ? +Run `ghc --version`. hledger requires GHC 7.0 or greater +(and on [some platforms](#5551), 7.2.1+ can be helpful). + +### Do you have a new enough version of cabal ? +Avoid ancient versions, which are less capable and more confusing. +`cabal --version` should ideally report at least 1.16 (or if you want to +do sandboxed installs, 1.18). You may be able to upgrade it with: +``` +$ cabal update +$ cabal install cabal-install +``` + +### haskeline fails to install, requires Cabal >=1.16 + +Related to the above. haskeline, one of hledger's dependencies, claims +to require cabal-install version 1.16+, which is a problem if, say, +you are on Debian Wheezy and only have cabal-install version 0.14. +You can relax haskeline's version constraint like so: + +``` +cabal unpack haskeline +cd haskeline-X.Y +(edit haskeline.cabal, comment out the `Cabal-Version: >=1.16` line) +cabal install +(resume installing hledger) +``` + +### Are your installed GHC/cabal packages in good repair ? +Run `ghc-pkg check`. If it reports problems, some of your packages have +become inconsistent, and you should fix these first. +[ghc-pkg-clean](https://gist.github.com/1185421) is an easy way. + +### cabal says "rejecting: system-fileio-0.3.11, 0.3.10 (conflict: blah blah blah.." +system-fileio does not yet allow text 1.x, making cabal sweat. +If your cabal is modern enough, adding `--max-backjumps=10000` should help. +([more](https://groups.google.com/d/topic/hledger/FdWGTSAVzYU/discussion)). + +### cabal can't satisfy the new dependencies due to old installed packages +Cabal dependency failures become more likely as you install more +packages over time. If `cabal install hledger-web --dry` says it can't +satisfy dependencies, you have this problem. You can: + +- (a) try to understand which packages to remove (with `ghc-pkg unregister`) + or which constraints to add (with `--constraint 'PKG == ...'`) to help cabal + find a solution + +- (b) install into a fresh cabal sandbox, created with `cabal sandbox init`. + ([virthualenv](http://hackage.haskell.org/package/virthualenv) or + [cabal-dev](http://hackage.haskell.org/package/cabal-dev) also work). + +- or (c) (easiest) erase your installed packages with + [ghc-pkg-reset](https://gist.github.com/1185421) and try again. + +For more detail, see [How to cabal install](https://www.fpcomplete.com/user/simonmichael/how-to-cabal-install). + +### Dependency or compilation error in one of the new packages ? + If cabal starts downloading and building packages and then terminates + with an error, look at the output carefully and identify the problem + package(s). If necessary, add `-v2` or `-v3` for more verbose + output. You can install the new packages one at a time to troubleshoot, + but remember cabal is smarter when installing all packages at once. + + Often the problem is that you need to install a particular C library + using your platform's package management system. Or the dependencies + specified on a package may need updating. Or there may be a compilation + error. If you find an error in a hledger package, check the + [recent commits](http://github.com/simonmichael/hledger/commits) to + see if the [latest development version](#installing) might have a fix. + +### ExitFailure 11 +See +[http://hackage.haskell.org/trac/hackage/ticket/777](http://hackage.haskell.org/trac/hackage/ticket/777). +This means that a build process has been killed, usually because it grew +too large. This is common on memory-limited VPS's and with GHC 7.4.1. +Look for some memory-hogging processes you can kill, increase your RAM, +or limit GHC's heap size by doing `cabal install ... --ghc-options='+RTS +-M400m'` (400 megabytes works well on my 1G VPS, adjust up or down..) + +### Can't load .so/.DLL for: ncursesw (/usr/lib/libncursesw.so: file too short) +(or similar): cf [GHC bug #5551](http://hackage.haskell.org/trac/ghc/ticket/5551). +Upgrade GHC to 7.2.1, or try your luck with [this workaround](http://eclipsefp.github.com/faq.html). + +### Undefined iconv symbols on OS X +This kind of error: + + Linking dist/build/hledger/hledger ... + Undefined symbols: + "_iconv_close", referenced from: + _hs_iconv_close in libHSbase-4.2.0.2.a(iconv.o) + "_iconv", referenced from: + _hs_iconv in libHSbase-4.2.0.2.a(iconv.o) + "_iconv_open", referenced from: + _hs_iconv_open in libHSbase-4.2.0.2.a(iconv.o) + +probably means you are on a mac with macports libraries installed, cf +[http://hackage.haskell.org/trac/ghc/ticket/4068](http://hackage.haskell.org/trac/ghc/ticket/4068). +To work around temporarily, add this --extra-lib-dirs flag: + + $ cabal install hledger --extra-lib-dirs=/usr/lib + +or permanently, add this to ~/.cabal/config: + + extra-lib-dirs: /usr/lib + +### "invalid preprocessing directive" on OS X + +> "I'm trying to cabal install hledger-web on OS X, GHC 7.6, and getting error: invalid preprocessing directive #{mixedAmountAsHtml amt}". + +[Example](https://gist.github.com/miikka/8886233) + +Certain OS X and GHC versions do not work well together ([cabal #1496](https://github.com/haskell/cabal/issues/1496), [ghc #7678](https://ghc.haskell.org/trac/ghc/ticket/7678)). +There's a fix for this in hledger HEAD as of 2014/2/8 (it's not in 0.22.1). +If you find more cases, please report it. + +### Many warnings about "missing terminating ' character" on OS X + +Related to the above problem, can be ignored. + +### hledger-vty requires curses-related libraries +On Ubuntu, eg, you'll need the `libncurses5-dev` package. On Windows, +these are not available (unless perhaps via Cygwin.) + +### hledger-chart requires GTK-related libraries +On Ubuntu, eg, install the `libghc6-gtk-dev` package. See also [Gtk2Hs installation notes](http://code.haskell.org/gtk2hs/INSTALL). + +### error based on missing ncurses C libs on Ubuntu 14.04 trusty +The following solved my dependency-problem with ncurses (this was required even when I had installed hledger 0.22 via apt-get) + sudo apt-get install libghc-hscurses-dev libghc-ncurses-dev diff --git a/doc/site/ledgertips.md b/doc/site/ledgertips.md new file mode 100644 index 000000000..493085716 --- /dev/null +++ b/doc/site/ledgertips.md @@ -0,0 +1,5 @@ +{{https://pbs.twimg.com/profile_images/455396161352781824/efsKSkXH_bigger.png |}} +[[https://twitter.com/LedgerTips|@LedgerTips]] on twitter.com posts tips and tricks for all the [[https://github.com/ledger/ledger/wiki/Ports|Ledger ports and work-alikes]], in the spirit of [[https://twitter.com/HaskellTips|HaskellTips]]. + +All *ledger users are invited to post tips! Contact Simon (sm) on #ledger with suggestions, or to get login details to become a guest host. +Posts should include the `#ledgercli` hash tag. Links to longer tips are also welcome. diff --git a/doc/site/manual.md b/doc/site/manual.md new file mode 120000 index 000000000..3ac12d1c6 --- /dev/null +++ b/doc/site/manual.md @@ -0,0 +1 @@ +../manual.md \ No newline at end of file diff --git a/doc/site/more-docs.md b/doc/site/more-docs.md new file mode 100644 index 000000000..a05b89504 --- /dev/null +++ b/doc/site/more-docs.md @@ -0,0 +1,108 @@ +# More docs... + +[[old screenshots|Screenshots]] (old) + +## How-tos + +- [[How to read CSV files]] +- [[How to use account aliases]] + +## Blog posts & articles + +- Simon's hledger-tagged blog posts: + [Introducing hledger!](http://joyful.com/blog/2013-10-18-introducing-hledger.html), + [More on ledger](http://joyful.com/blog/2013-10-19-more-on-ledger.html), + [What is hledger ?](http://joyful.com/blog/2013-10-20-what-is-hledger.html), + [more...](http://joyful.com/tags/hledger.html) 2013- +- [Joey Hess: hledger](http://joeyh.name/blog/entry/hledger) 2012 +- [Magnus Henoch: monspuraj programoj](http://חנוך.se/diary/monspuraj_programoj/index.eo.html) ([english](http://translate.google.com/translate?hl=en&sl=eo&u=http://xn--9dbdkw.se/diary/monspuraj_programoj/index.eo.html)) 2012 +- [Sascha Welter: Doing my own accounting](http://betabug.ch/blogs/ch-athens/1221) 2011 +- [Clint Adams: Accounting at SFLC](http://www.softwarefreedom.org/blog/2011/sep/07/accounting-at-sflc/) 2011 +- [Christine Spang: [h]ledger rocks my world](http://blog.spang.cc/posts/hledger_rocks_my_world/) 2010 +- [Roman Cheplyaka: hledger](http://ro-che.blogspot.com/2010/02/hledger.html) 2010 +- [Fabrice Niessen on Ledger, hledger, beancount, CSV2Ledger](http://www.mygooglest.com/fni/ledger.html) 2010 +- [советы: Ledger — бухучёт в командной строке](http://s.arboreus.com/2009/05/personal-accounting-in-command-line.html) ([english](http://translate.google.com/translate?hl=en&sl=ru&u=http://s.arboreus.com/2009/05/personal-accounting-in-command-line.html)) 2009 + +## Related info + +John Wiegley's [Ledger](http://www.ledger-cli.org/) inspired hledger. +Here are some good intros, which also serve as a good orientation for hledger: + +- [Ledger CLI Accounting for Geeks](http://blog.loadingdata.nl/accounting-for-geeks/#/) slides by Daniël Bos, 2014 + (press space to advance) +- [ledger basics and habits](http://matthewturland.com/2014/03/29/ledger-basics-and-habits/) blog post by Matthew Turland, 2014 +- [Hacking Your Finances for Fun and Profit](http://matthewturland.com/slides/ledger-stats/) slides by Matthew Turland, 2013 +- [The accounting quest: Ledger](http://lwn.net/Articles/501681/) LWN.net, 2012 +- [Ledger: Command-line double-entry accounting](https://news.ycombinator.com/item?id=872244) Hacker News discussion, 2009 +- [Ledger's informative manual](http://ledger-cli.org/3.0/doc/ledger3.html), + and the [Ledger wiki](http://wiki.ledger-cli.org) +- [Non-Profit Accounting With Ledger CLI, A Tutorial](https://gitorious.org/ledger/npo-ledger-cli/source/npo-ledger-cli-tutorial.md) + describes Software Freedom Conservancy's setup, 2013 + +See also the two Twitter feeds: + +- [@LedgerTips](https://twitter.com/LedgerTips) Tips and tricks for Ledger, hledger, beancount, etc. +- [#ledgercli](https://twitter.com/search?q=%23ledgercli&src=typd&f=realtime) Search for latest mentions of the `#ledgercli` hash tag + +## Accounting + +- + [[wp>Accountancy]], + [[wp>Bookkeeping]], + [[wp>Double-entry bookkeeping system]], + [[wp>General journal]] + etc. at Wikipedia +- [Accounting For Dragons](http://podcastle.org/2009/10/09/pc-miniature-38-accounting-for-dragons) why you should know accounting +- [Bean Counter](http://www.dwmbeancounter.com/) - tutorials, such as + [So, you want to learn Bookkeeping!](http://www.dwmbeancounter.com/tutorial/Tutorial.html). + This has been recommended on the ledger list. +- [Accounting Basics](http://www.accountingverse.com/accounting-basics/) +- [Guru 99 Accounting Tutorials](http://www.guru99.com/accounting.html) +- [principlesofaccounting.com](http://www.principlesofaccounting.com) +- [Double Entry Bookkeeping](http://c2.com/cgi/wiki?DoubleEntryBookkeeping) discussion by software developers at the WikiWikiWeb +- [The Vanished Grandeur of Accounting](http://www.bostonglobe.com/ideas/2014/06/07/the-vanished-grandeur-accounting/3zcbRBoPDNIryWyNYNMvbO/story.html) (Boston Globe) & [discussion](https://news.ycombinator.com/item?id=7933746) +- [Winning Financially is Simple](http://directory.libsyn.com/episode/index/show/youneedabudget/id/2657122) and other good episodes from the [YNAB Podcast](http://directory.libsyn.com/shows/view/id/youneedabudget) +- [Back to the Stone Age: Low-Tech Expense Tracking](http://www.getrichslowly.org/blog/2011/02/28/back-to-the-stone-age-low-tech-expense-tracking/) Get Rich Slowly +- [Track Every Penny You Spend](http://www.getrichslowly.org/blog/2006/09/22/track-every-penny-you-spend/) Get Rich Slowly +- [I’ve Tracked My Expenses — Now What?](http://www.getrichslowly.org/blog/2011/04/08/ask-the-readers-ive-tracked-my-expenses-now-what/) Get Rich Slowly +- [A Slow-Tech Approach to Tracking Spending](http://mobile.nytimes.com/2014/05/12/your-money/household-budgeting/a-slow-tech-approach-to-tracking-spending.html) +- [Your Financial Network Map](http://www.bargaineering.com/articles/financial-network-map.html) +- [The Accountancy Model and The Accountancy Model Examples](http://timriley.net/appahost/accountancy_model.html) - two free books by Tim Riley +- [Gnucash and double entry accounting](http://www.austintek.com/gnucash/ncsa-gnucash-talk.html) - double entry accounting introduction with examples +- [Accounting for Computer Scientists](http://martin.kleppmann.com/2011/03/07/accounting-for-computer-scientists.html) +- [Closing Entries](http://www.cliffsnotes.com/more-subjects/accounting/accounting-principles-i/completion-of-the-accounting-cycle/closing-entries) +- [Tutorial on multiple currency accounting](http://www.mscs.dal.ca/~selinger/accounting/tutorial.html) by Peter Selinger + +## hledger add-ons + +- [hledger-interest](http://hackage.haskell.org/package/hledger-interest) generates various kinds of interest transaction +- [hledger-irr](http://hackage.haskell.org/package/hledger-irr) reports internal rate of return (effective interest rate) +- [[h]ledger-autosync](https://bitbucket.org/egh/ledger-autosync) downloads/converts/deduplicates OFX data +- [hledger-chart](http://hackage.haskell.org/package/hledger-chart) generates simple pie charts (unmaintained) +- [hledger-vty](http://hackage.haskell.org/package/hledger-vty) a simple curses-style UI (unmaintained) +- More in [[code>extra/]] + +## Scripting examples + +- https://gist.github.com/4172604 printing average expenses by month +- https://gist.github.com/4210558 calculating historical account balances +- More in [[code>extra/]] + +## Similar projects + +In addition to hledger and Ledger, there are other [[ledgerwiki>Ports|Ledger ports]] and Ledger-likes, incompatible but similar in concept: + +- Martin Blais' [beancount](https://furius.ca/beancount/) (python) +- Harshad RJ's [Abandon](https://github.com/hrj/abandon) (scala) +- dimonf's [ledger.pl](https://github.com/dimonf/ledger.pl) (perl) +- Omari Norman's [penny](https://github.com/massysett/penny) (haskell) +- Uwe Hollerbach's [umm](http://hackage.haskell.org/package/UMM) (haskell) + +Other things of interest: + +- [bill](http://darcsden.com/alex/bill), [bill-atomo](http://darcsden.com/alex/bill-atomo) - small time-tracking and billing app +- [debts](http://darcsden.com/ozamosi/debts) - small debt tracking web app +- [housetab-multi](http://darcsden.com/dbp/housetab-multi), [housetab.org](http://housetab.org) - a web app to manage expenses between a group of friends +- [You Need A Budget](http://www.youneedabudget.com/) +- Software Freedom Conservancy's [[http://npoacct.sfconservancy.org|npo-acct]] project + diff --git a/doc/site/old-screenshots.md b/doc/site/old-screenshots.md new file mode 100644 index 000000000..2a6d0d946 --- /dev/null +++ b/doc/site/old-screenshots.md @@ -0,0 +1,50 @@ +# Old screenshots + +--- + +## Basic command-line reports + +Showing the journal format, a register report, and a balance report: + +{{http://hledger.org/images/hledger-screen-1.png|Basic command-line reports, like ledger}} + +## Time dashboard in emacs + +The upper window displays today's time report every minute (using ansi-term, watch, a helper script, and hledger invoked via 'hours' symlink.) The lower window is viewing the timelog file, to tweak clock-ins/clock-outs made with C-x t i and C-x t o. + +{{http://hledger.org/images/watchhours.png|The upper window displays today's time report every minute (using ansi-term, watch, a helper script, and hledger invoked via 'hours' symlink.) The lower window is viewing the timelog file, to tweak clock-ins/clock-outs made with C-x t i and C-x t o.}} + +## Pie charts (hledger-chart) + +Viewing a year of monthly expense charts in emacs. These were generated by hledger 0.10 with -fchart, which became [[http://hackage.haskell.org/package/hledger-chart|hledger-chart]], presently unmaintained. + +{{http://hledger.org/images/hledger-charts-2.png|Viewing a year of monthly expense charts in emacs (hledger 0.10 with -fchart).}} + +## Curses-style interface (hledger-vty) + +[[http://hackage.haskell.org/package/hledger-vty|hledger-vty]], currently unmaintained. + +{{http://hledger.org/images/sshot.png|The vty (curses-style) interface}} + +## Web interface (hledger-web) + +This minimal web interface was hledger 0.11pre with -fwebyesod, which became [[http://hackage.haskell.org/package/hledger-web|hledger-web]]. +Here's the [[http://demo.hledger.org|latest interface]]. + +{{http://hledger.org/images/hledger-web-journal.png|The web interface (hledger 0.11pre with -fwebyesod).}} + + + diff --git a/doc/site/release-notes.md b/doc/site/release-notes.md new file mode 100644 index 000000000..489837276 --- /dev/null +++ b/doc/site/release-notes.md @@ -0,0 +1,1129 @@ +# Release notes + +Based on the +[hledger](http://hackage.haskell.org/package/hledger/changelog), +[hledger-web](http://hackage.haskell.org/package/hledger-web/changelog) & +[hledger-lib](http://hackage.haskell.org/package/hledger-lib/changelog) +change logs. +## hledger-web 0.23.3 (2014/9/12) + +- remove warp, wai-handler-launch upper bounds (fixes #205) + +## hledger 0.23.3 (2014/9/12) + +- allow text 1.2+ (fixes #207) + +## hledger-lib 0.23.3 (2014/9/12) + +- allow transformers 0.4* (fixes #204) + +## hledger 0.23.2 (2014/5/8) + +- register: also fix date sorting of postings (#184) + +## hledger 0.23.1 (2014/5/7) + +- register: fix a refactoring-related regression that the tests + missed: if transactions were not ordered by date in the journal, + register could include postings before the report start date in the + output. (#184) +- add: don't apply a default commodity to amounts on entry (#138) +- cli: options before the add-on command name are now also passed to it (#182) +- csv: allow the first name in a fields list to be empty (#178) +- csv: don't validate fields count in skipped lines (#177) + + +## hledger 0.23 (2014/5/1) + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.hledger/1028) + +Changes since 0.22.2: + +**Journal format:** + +- A # (hash) in column 0 is now also supported for starting a top-level journal comment, like Ledger. +- The "too many missing amounts" error now reminds about the 2-space rule. +- Fix: . (period) is no longer parsed as a valid amount. +- Fix: default commodity directives no longer limit the maximum display precision (#169). +- Fix: + before an amount is no longer parsed as part of the commodity (#181). + +**CLI:** + +- Command-line help cleanups, layout improvements. +- Descriptions are shown for known add-ons in the command list. +- Command aliases have been simplified. +- Add-ons can now have any of these file extensions: + none, hs, lhs, pl, py, rb, rkt, sh, bat, com, exe. +- Add-ons are displayed without their file extensions when possible. +- Add-ons with the same name as a built-in command or alias are ignored. +- Fix: add-on detection and invocation now works on windows. +- Fix: add-ons with digits in the name are now found. +- Fix: add-on arguments containing a single quote now work. +- Fix: when -- is used to hide add-on options from the main program, + it is no longer passed through as an add-on argument. + +**accounts:** + +- An accounts command has been added, similar to Ledger's, for listing account names + in flat or hierarchical mode. + +**add:** + +- Tab completion now works at all prompts, and will insert the default if the input area is empty. +- Account and amount defaults are more robust and useful. +- Transactions may also be completed by the enter key, when there are no more default postings. +- Input prompts are displayed in a different colour when supported. + +**balance:** + +- Balance reports in flat mode now always show exclusive (subaccount-excluding) balances. +- Balance reports in flat mode with --depth now aggregate deeper accounts at the depth limit instead of excluding them. +- Multicolumn reports in flat mode now support --drop. +- Multicolumn balance reports can now show the account hierarchy with --tree. +- Multicolumn report start/end dates are adjusted to encompass the displayed + report periods, so the first and last periods are "full" and comparable to the others. +- Fix: zero-balance leaf accounts below a non-zero-balance parent are no longer always shown (#170). +- Fix: multicolumn reports now support --date2 (cf #174). + +**balancesheet, cashflow, incomestatement:** + +- These commands now support --flat and --drop. + +**print:** + +- Tag queries (tag:) will now match a transaction if any of its postings match. + +**register:** + +- The --display option has been dropped. To see an accurate running total which + includes the prior starting balance, use --historical/-H (like balance). +- With a report interval, report start/end dates are adjusted to encompass the displayed + periods, so the first and last periods are "full" and comparable to the others. +- Fix: --date2 now works with report intervals (fixes #174). + +**Queries:** + +- The currency/commodity query prefix (sym:) has been renamed to cur:. +- Currency/commodity queries are applied more strongly in register and + balance reports, filtering out unwanted currencies entirely. Eg + hledger balance cur:'\$' now reports only the dollar amounts even if + there are multi-currency transactions or postings. +- Amount queries like amt:N, amt:N, where N is not 0, now do an unsigned + comparison of the amount and N. That is, they compare the absolute magnitude. + To do a signed comparison instead, write N with its sign (eg amt:+N, amt:<+N, amt:>-N). +- Fix: amount queries no longer give false positives on multi-commodity amounts. + +**Miscellaneous:** + +- Default report dates now derive from the secondary dates when --date2 is in effect. +- Default report dates now notice any posting dates outside the transaction dates' span. +- Debug output improvements. +- New add-on example: extra/hledger-rewrite.hs, adds postings to matched entries. +- Compatible with GHC 7.2 (#155) - GHC 7.8, shakespeare 2 + + +## hledger-web 0.23 (2014/5/1) + +Changes since 0.22.8: + +- The --static-root flag has been renamed to --file-url. +- hledger-web now builds with Cabal's default -O, not -O2, + so may be a little quicker/less memory-hungry to install. + + +## hledger-web 0.22.8 (2014/4/29) + +- allow shakespeare 2.* (#179) + +## hledger-web 0.22.7 (2014/4/17) + +- add Peter Simons' patch fixing Data.Conduit.Network HostIPv4 error (#171) + +## hledger-web 0.22.6 (2014/4/16) + +- depend on hledger[-lib] 0.22.2 + +## hledger 0.22.2 (2014/4/16) + +- display years before 1000 with four digits, not three +- avoid pretty-show to build with GHC < 7.4 +- allow text 1.1, drop data-pprint to build with GHC 7.8.x + +## hledger-web 0.22.5 (2014/4/15) + +- allow http-client 0.3.*, fixing cabal install again with GHC <= 7.6 (not yet 7.8) +- use pretty-show only with GHC 7.4+, fixing GHC 7.2 (fixes #155) +- allow warp 2.1, fixing cabal install + +## 2014/2/10 hledger-web 0.22.4 + +* web: include the right unminified version of jquery.url.js (1.1) to avoid js breakage + +## 2014/2/10 hledger-web 0.22.3 + +* web: fix version number reported by --version + +## 2014/2/10 hledger-web 0.22.2 + +New: + +* web: new option `--static-root` to set the base url for static files + +Improved: + +* web: include unminified source of all javascript to help packagers (fixes #161) +* web: work around clang-related build failures with OS X mavericks/XCode 5 +* web: allow blaze-html 0.7 (closes #159) + + +## 2014/1/6 hledger 0.22.1 + +- require the latest pretty-show so hledger installation no longer + needs an upgraded version of happy, and the docs build on hackage + +- require regex-tdfa directly instead of regex-compat-tdfa, + simplifying Debian packaging + +## 2013/12/13 hledger 0.22 + +**New:** + +- balance: with a reporting interval (monthly, yearly etc.), the + [balance command](MANUAL.html#balance) will now show a multi-column report, showing either + the per-period changes in balance (by default), + the period ending balances starting from zero (`--cumulative`), + or the actual period ending balances (`--historical`). + A more detailed specification of the balance command's behaviour + has been added to [Hledger.Cli.Balance](http://hackage.haskell.org/package/hledger/docs/Hledger-Cli-Balance.html). + +- csv: rules files can now include other rules files, useful for factoring out common rules + +- queries: `sym:REGEXP` matches commodity symbols + +- register: `--average/-A` shows a running average, like ledger + +- in period expressions, `-` (hyphen) can be used as a more compact + synonym for `from` and `to`. Eg: `-p 2012/12/1-2013/2/1` or `date:aug-`. + +- the add-on script examples in extra/ have been updated; get the + hledger source and add .../hledger/extra/ to your PATH to make them + available. They include: + + - `hledger-accountnames.hs` - print account names + - `hledger-balance-csv.hs` - print a balance report as CSV + - `hledger-equity.hs` - print an entry matching all account balances (like ledger) + - `hledger-print-unique.hs` - print only journal entries unique descriptions + - `hledger-register-csv.hs` - print a register report as CSV + +**Improved:** + +- balancesheet: now shows just assets and liabilities, not equity + +- print: comment positions (same line or next line) are now preserved + +- queries: `amt` now uses the = operator by default, eg `amt:50` is + equivalent to `amt:=50` + +- command line processing has been overhauled and made more + consistent, and now has tests and debug output. More flags now work + both before and after COMMAND: `-f`, `--rule-file`, `--alias`, + `--help`, `--debug`, `--version`. Command line help, command + aliases, API docs and code have been improved. + +- `--debug` now takes an optional numeric argument to set the debug level + higher than 1, for more verbose debug output in a few cases. + +**Fixed:** + +- csv: CSV data containing non-ascii characters is now supported + +- build with latest versions of dependencies (text, warp, http-conduit etc.) + +**Release contributors:** + +Marko Kocić, Max Bolingbroke, and a big welcome to first-time committer John Wiegley! :) + +## 2013/7/10 hledger-web 0.21.3 + + - drop yesod-platform dependency, it is not worthwhile. The other + yesod dependencies are currently without version ranges, so cabal + install might require --constraint to restrict them in some cases. + +## 2013/6/23 hledger 0.21.3 + + - csv: fix wrong application of multiple assignments in a conditional block + +## 2013/6/4 hledger 0.21.2 + + - web: fix a build failure + +## 2013/6/3 hledger 0.21.1 + + - web: show proper Y-values in register chart (fixes #122) + - web: avoid trailing commas in register chart values, in case of trouble with IE + +## 2013/6/1 hledger 0.21 + +**Bugs fixed:** + + - parsing: don't fail when a csv amount has trailing whitespace (fixes #113) + - web: don't show prices in the accounts sidebar (fixes #114) + - web: show one line per commodity in charts. Needs more polish, but fixes #109. + - web: bump yesod-platform dependency to avoid a cabal install failure + +**Journal reading:** + + - balance assertions are now checked after reading a journal + +**web command:** + + - web: support/require yesod 1.2 + - web: show zero-balance accounts in the sidebar (fixes #106) + - web: use nicer select2 autocomplete widgets in the add form + +**Documentation and infrastructure:** + + - add basic cabal test suites for hledger-lib and hledger + +## 2013/5/4 hledger 0.20.0.1 + + * web: require at least version 1.1.7 of yesod-core to avoid a potential build error + * Update the bug tracker and source repository links on hackage + +## 2013/5/1 hledger 0.20 + +**Bugs fixed:** + + * balance: a 0.19 regression which showed wrong total balance with `--flat` has been fixed (#94) + * register: when `--date2` is used, the register is now sorted by the secondary date + * web: some missing static & template files have been added to the package, fixing cabal-dev and hackage builds (#97, #98) + * web: some hardcoded static urls have been fixed + * Dependencies and code have been updated to support the latest + libraries and GHC versions. For now, hledger requires GHC 7.2+ + and hledger-web requires GHC 7.4+. + +**Journal reading:** + + - DOS-style line-endings are now also supported in journal and rules files. + - `!` is now accepted in the status field as well as `*`, like ledger + - The *actual date* and *effective date* terminology has changed to *primary date* and *secondary date*. + Use `--date2` to select the secondary date for reports. (`--aux-date` or `--effective` are also accepted + for ledger and backwards compatibility). + - Per-posting dates are supported, using hledger tags or ledger's posting date syntax + - Comment and tag handling has been improved + +**CSV reading:** + + - CSV conversion rules have a simpler, more flexible [syntax](MANUAL.html#csv-files). + Existing rules files will need to be updated manually: + - the filename is now `FILE.csv.rules` instead of `FILE.rules` + - `FIELD-field N` is now `FIELD %N+1` (or set them all at once with a `fields` rule) + - `base-currency` is now `currency` + - `base-account` is now `account1` + - account-assigning rules: + add `if` before the list of regexps, + add indented `account2 ` before the account name + - parenthesised amounts are parsed as negative + +**Querying:** + + - Use `code:` to match the transaction code (check number) field + - Use `amt:` followed by `<`, `=` or `>` and a number N to match + amounts by magnitude. Eg `amt:<0` or `amt:=100`. This works only + with single-commodity amounts (multi-commodity amounts are + always matched). + - `tag:` can now match (exact, case sensitive) tag values. Eg `tag:TAG=REGEXP`. + +**add comand:** + + - Transaction codes and comments (which may contain tags) can now be entered, following a date or amount respectively. (#45) + - The current entry may be restarted by entering `<` at any prompt. (#47) + - Entries are displayed and confirmed before they are written to the journal. + - Default values may be specified for the first entry by providing them as command line arguments. + - Miscellaneous UI cleanups + +**register command:** + + - The `--related`/`-r` flag shows the other postings in each transaction, like ledger. + - The `--width`/`-w` option increases or sets the output width. + +**web command:** + + - The web command now also starts a browser, and auto-exits when unused, by default ("local ui mode"). + With `--server`, it keeps running and logs requests to the console ("server mode"). + - Bootstrap is now used for styling and layout + - A favicon is served + - The search field is wider + - yesod devel is now supported; it uses `$LEDGER_FILE` or `~/.hledger.journal` + - the `blaze_html_0_5` build flag has been reversed and renamed to `blaze_html_0_4` + +**Add-ons:** + + - The hledger-interest and hledger-irr commands have been released/updated. + - hledger-chart and hledger-vty remain unmaintained and deprecated. + +**Documentation and infrastructure:** + + - The hledger docs and website have been reorganised and updated + - Manuals for past releases are provided as well as the latest dev version + - hledger has moved from darcs and darcs hub to git and github (!) + - The bug tracker has moved from google code to github + - Feature requests and project planning are now managed on trello + - A build bot builds against multiple GHC versions on each commit + +**Release contributors:** + +- Sascha Welter commissioned register enhancements (--related and --width) +- David Patrick contributed a bounty for add enhancements +- Joachim Breitner added support for ! in status field +- Xinruo Sun provided hledger-web build fixes +- Peter Simons provided hledger-web build fixes, and a build bot +- Marko Kocić provided hledger-web fixes + + + + + +## 2012/11/24 hledger-web 0.19.3 + + * web: fix "Prelude.read: no parse" errors with GHC >= 7.6 + * web & lib refactoring + +## 2012/11/16 hledger-web 0.19 + + * builds with yesod 1.1.3 + * obeys command-line query options at startup again + * the autogenerated session file is now a dot file + (.hledger-web_client_session.aes) + +## 2012/11/16 hledger 0.19.1 + + * [87](http://bugs.hledger.org/87): fix an arithmetic and transaction balancing bug with multiple + total-priced amounts ( @@ PRICE ) + * parsing: ignore ledger-style balance assertions ( = BAL ) and fixed + lot price declarations ( {= PRICE} ) + + +## 2012/10/21 hledger 0.19 + + * hledger, hledger-lib: support GHC 7.6 and latest cmdargs, haskeline, split + * balance report no longer has an O(n^2) slowdown with large numbers of accounts, + and is generally more speedy. Benchmark on a 2010 macbook: + + + +^ ^ hledger-0.18 ^ hledger-0.19 ^ ledger ^ +| -f data/100x100x10.journal balance | 0.21 | 0.07 | 0.09 | +| -f data/1000x1000x10.journal balance | 10.13 | 0.47 | 0.62 | +| -f data/1000x10000x10.journal balance | 40.67 | 0.67 | 1.01 | +| -f data/10000x1000x10.journal balance | 15.01 | 3.22 | 2.36 | +| -f data/10000x1000x10.journal balance aa | 4.77 | 4.40 | 2.33 | + + * build version is set with CPP instead of cabal-file-th + +## 2012/7/7 hledger 0.18.2 + + * web: fix compilation error with -fblaze_html_0_5 flag + * bump base lower bound to 4.3 to enforce GHC 7 requirement + +## 2012/6/29 hledger 0.18.1 + + * register, print: fix reverse ordering of same-day transactions + * balance: respect all query terms, not just acct + * combine command-line flags like --depth properly with non-flag query patterns + * web: don't auto-create a missing journal file at startup + * stats: list included journal files + * support tilde (~) in journal and rules file paths + * expose more utilities from CsvReader + * remove ensureRulesFile debug trace + +## 2012/5/29 hledger 0.18 + + * web: hledger-web is now based on yesod 1.0 + * web: fix js error breaking second use of add form ([#72](http://code.google.com/p/hledger/issues/detail?id=72)) + * web: make `yesod devel` work + * the command-line now supports a more powerful [query language](MANUAL.html#queries), consistent with the web UI + * hledger now fully supports [tags](MANUAL.html#tags) (aka metadata) on both transactions and postings, and querying by tag or tag value + * new commands `incomestatement`, `balancesheet`, and `cashflow` provide basic financial statements under certain [conditions](http://hledger.org/MANUAL.html#incomestatement) + * format conversion is now done on demand, and the convert command has been dropped. So instead of + `hledger convert FILE.csv` just do `hledger -f FILE.csv print` or any other command. + You can also pipe any supported format into `hledger -f- CMD` and hledger will try to do the right thing. + * support for GHC 6.12 has been dropped; this release has been tested with GHC 7.0.4, 7.2.2, and 7.4.1 + * unicode is now handled properly on all supported GHC versions + * API and internal cleanups + +## 2012/3/3 hledger-web 0.17.1 + + * set more upper bounds to fix cabal install issues with latest packages + +## 2012/2/1 hledger 0.17 + + * support HP 2011.4.0.0 + * support and require cmdargs 0.9 + * allow non-threaded builds, supporting more debian architectures + * parsing: give a clearer error when journal file path contains ~ + * parsing: -B/--cost now ignores P historical prices, like ledger + * parsing: inferred amounts now use the cost commodity if known, like ledger (#69) + * balance: report differently-priced lots in an account as a single amount, like ledger + * web: support and require yesod >= 0.9.4 + * web: use the main aeson package again + * web: fix a regression with dollar signs in hamlet templates + * web: add form allowed blank account names (#81) + * chart, vty: hledger-chart and hledger-vty demoted to non-maintained extras for now + +## 2011/10/26 hledger-web 0.16.5 + + * web: fix a ghc 6.12 incompatibility in Settings.hs + +## 2011/10/24 hledger-web 0.16.4 + + * web: yet another cabal install fix, fix AppConfig name clash + +## 2011/10/4 hledger-web 0.16.3 + + * web: another cabal install fix, disable favicon.ico since it's not easily embeddable + +## 2011/10/4 hledger-web 0.16.2 + + * web: more cabal install fixes (remove bad path, add routes and models) (#63) + +## 2011/10/4 hledger 0.16.1 + + * parsing: show correct line number for posting parse errors (#67) + * web: declare static files as extra-source-files to fix cabal install (#63) + * web: add a threaded flag for debian (#68) + * web: fewer build warnings by default + +## 2011/10/1 hledger 0.16 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.hledger/521) + + * cli: strip the -- when calling add-on commands, so their options work (#64) + * cli: hledger ADDON --version now shows add-on command's version + * cli: only the add and web commands auto-create the journal file + * cli: give a non-confusing error if LEDGER_FILE contains a literal tilde + * add: clearer prompts, more validation, use . to end also + * add: use unix line endings consistently, avoiding parse error on windows (#51) + * add: avoid excess whitespace between transactions (#46) + * balance: ledger compatibility fix: don't elide parent accounts with multiple displayed subaccounts + * convert: always order converted transactions by date + * convert: rename currency -> base-currency, in-field, out-field -> amount-in-field, amount-out-field + * convert: give an error, not a zero when date or amount-in-field/amount-out-field parsing fails + * register: show more useful range of intervals with --empty and a query pattern + * print, web: always show both dates, ignoring --effective (#42) + * web: production builds (the default with cabal) have all web content embedded (dev builds use ./static/) (#63) + * web: update to yesod 0.9 + * web: obey at least some of the general reporting options, like --cost + * web: adjust the default base url when a custom port is specified + * web: prevent an infinite redirect when custom base url has a trailing slash + * web: fix "not:'multi word'" patterns + * web: hide old title and search form when adding/editing + * web: adjust --help to indicate command-line arguments are not expected + * web: don't bother running cli unit tests at startup + +## 2011/9/12 hledger 0.15.2, hledger-web 0.15.3 + + * handle multiple filter patterns on the command-line again + * don't pass an add-on command's name to it as an extra argument + * don't give a confusing error with -f and no command + * fix a regression balancing a transaction containing different prices + * web: fix journal edit form + * web: fix wrong transaction amount in account register with virtual postings + * web: fix some invalid html + +## 2011/9/2 hledger 0.15.1, hledger-web 0.15.2 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.hledger/479) + + * fix a parsec 2 incompatibility + * web: add missing Hledger.Web.Options to cabal file + * web: tighten up dependencies to reduce build problems + +## 2011/9/1 hledger 0.15 + +[announcement](https://groups.google.com/forum/#!topic/hledger/-WCfnRFVaf0/discussion) + + * hledger's options are now modal, providing better help (using cmdargs) + * hledger now lists and runs any hledger-* add-ons found in the user's path + * case insensitivity of filter patterns has been fixed + * parsing: `alias`/`end aliases` directives, for renaming accounts, are supported, like ledger's but a bit more powerful; also an `--alias` option for renaming on the fly + * parsing: the `account` directive now preserves posting type (normal/virtual/balanced virtual) + * parsing: the `pop` directive is supported as an alias for `end tag`, like ledger + * parsing: `P` (historical price) directives can contain a (ignored) numeric time zone, like ledger + * parsing: the leading `!` in directives is now optional and deprecated, like ledger + * parsing: entries with a negative amount in the first posting now infer the correct balancing amount + * parsing: bad date checking is more accurate + * balance: collapsing of boring accounts to one line can be disabled with `--no-elide` + * balance: fix a wrong precision regression from last release + * convert: standard input can be converted + * convert: an alternate rules file can be specified with `--rules` + * convert: `account2-field` can be used when the CSV file specifies both accounts + * convert: `description-field` can have a custom format and combine multiple CSV fields + * convert: `in-field` and `out-field` support CSV files that use two amount columns + * convert: don't fail when there's no default journal file + * web: the web interface has been overhauled/cleaned up + * web: account register views are now transaction-based, like gnucash etc., and show accurate historical balances when possible + * web: simple balance charts are displayed (using flot) + * web: more expressive and consistent search patterns, using a new matching engine + * web: add form uses currently focussed account as default, redirects to itself, formats status messages better + * web: sidebar now shows empty/boring accounts too + * web: now uses warp and a newer yesod + * api simplifications + * importable Hledger, Hledger.Web, Hledger.Vty and Hledger.Chart modules + * the basic reports are now provided by hledger-lib for easier reuse + * new api use examples: `equity.hs`, `uniquify.hs` + * some old base 3 support has been dropped + * the old -s flag has been dropped + +## 2011/4/22 hledger 0.14 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.hledger/383) + + * remove the specific process dependency that caused too many cabal install problems + * treat arguments as possibly-encoded platform strings, do not assume UTF-8 + * hledger now always reads and writes data as UTF-8, ignoring the system locale (#34) + * look at the LEDGER_FILE env var for the journal path, otherwise LEDGER, like ledger + * handle a blank LEDGER_FILE or LEDGER value more gracefully (use the default file path) + * the default journal file path is now ~/.hledger.journal, to avoid breaking mac filevault (#41) + * amounts with different prices are now aggregated, like ledger + * zero amounts now have no sign or commodity, like ledger + * parsing: assume current year when transaction dates have no year and there is no default year + * parsing: more careful validation of eg leap years in transaction dates + * parsing: better international number format support, allowing comma as decimal point and flexible digit groups (#32) + * parsing: support @@ syntax specifying total price + * parsing: infer the conversion price in transactions involving two unpriced commodities + * parsing: support per-posting cleared status + * parsing: more reporting interval syntax: biweekly, bimonthly, every N days/weeks/months/quarters/years, every Nst/nd/rd/th day of month/week + * add: avoid offering account names for completion in inappropriate contexts + * add: remember default account even if user submits a different amount. + * convert: account-field directive specifies a field containing the base account name + * convert: effective-date-field directive specifies a field containing the effective date + * convert: date-format directive specifies custom date formats + * convert: allow amount fields containing "AMT @@ PRICE" + * histogram: honour the specified start or end dates + * print: don't show a trailing space when description is blank + * web: allow filter patterns with spaces if quoted, like command line + * web: make edit form more cross-browser compatible, fixing it in firefox (#38) + * web: move hidden add/edit/import forms below main content to help text-mode browsers a bit (#33) + +Release contributors: Simon Michael, Dmitry Astapov, Eric Kow, Max Bolingbroke, Omari Norman. +Stats: +137 days, 113 commits, 11 end-user features and 15 end-user bugfixes since last release. +189 unit & functional tests and 59% unit test coverage (hledger, hledger-lib packages). +5540 lines of code (all packages). + +## 2010/12/6 hledger 0.13 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.hledger/296) + + * move web, vty, chart commands into separate hledger-web, hledger-vty, + hledger-chart packages. This both simplifies (no more build flags) and + complicates (more room for dependency hassles), but I hope overall it + will be easier and more scalable. + * all packages but chart are now marked "beta", ie "not finished but + suitable for everyday use" + * parsing: ledger compatibility: support D default commodity directive + * parsing: ledger compatibility: ignore metadata tags on transactions and postings + * parsing: ledger compatibility: ignore cleared flags at the start of postings + * parsing: ledger compatibility: ignore C commodity conversion directives + * parsing: price precisions no longer affect commodities' display precisions + * add: readline-style editing + * add: tab-completion for account names + * add: add the default commodity, if any, to commodity-less amounts (#26) + * add: misc. commodity/precision/defaults-related bugfixes + * chart: give a meaningful error message for empty journals + * chart: update for current Chart lib (0.14) + * web: support files now live in ./.hledger/web/ and will be auto-created at startup + * web: page layout is more robust with wide content + * web: allow editing of included files + * web: handle multiple filter patterns correctly + * web: allow single- or double-quoted filter patterns containing spaces + * web: update for current yesod lib (0.6.*) + * transaction balancing is now based on display precision (#23) + * briefer, more informative usage error messages + +## 2010/9/6 hledger 0.12.1 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.hledger/272) + + * web: fix account filtering breakage + * installing: tighten up utf8-string dependency + +## 2010/9/5 hledger 0.12 + + * web: new, better web ui; accounts are now a permanent sidebar; add form uses auto-completing combo fields + * installing: fix a build error with parsec 3 (#22) + * installing: require exactly matching hledger-lib version for more robust builds + * installing: explicit data-object dependency to ensure hledger and hledger-lib use the same time version + * installing: explicit hamlet dependency for more robust building + * installing: build threaded and with warnings + * installing: drop -fweb610 flag + * installing: add gtk2hs-buildtools dependency needed to build with -fchart + * installing: require cabal 1.6 or greater + * add -D/--daily flag + * register: with --depth, clip account names or aggregate postings rather than excluding them + * fix !include with deeply nested directories (#21) + * fix obscured date parse errors with parsec 3 + * handle unicode better in errors + * fix a ghc 6.12.3 error when running interpreted + +Stats: 50 days and 90 commits since last release, now at 5741 +lines of code with 136 tests and 41% unit test coverage. + +## 2010/07/17 hledger 0.11.1 + + * fix --version output + +## 2010/07/17 hledger 0.11 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.hledger/253) + + * split --help, adding --help-options and --help-all/-H, and make + it the default command + * use "journal" instead of "ledger file"; default suffix is + .journal, default file is \~/.journal + * auto-create missing journal files rather than giving an error + * new format-detecting file reader (mixed journal transactions + and timelog entries are no longer supported) + * work around for first real-world rounding issue (test zero to 8 + decimal places instead of 10) + * when reporting a balancing error, convert the error amount to + cost + * parsing: support double-quoted commodity symbols, containing + anything but a newline or double quote + * parsing: allow minus sign before commodity symbol as well as + after (also fixes a convert bug) + * parsing: fix wrong parse error locations within postings + * parsing: don't let trailing whitespace in a timelog description + mess up account names + * add: allow blank descriptions + * balance: --flat provides a simple non-hierarchical format + * balance: --drop removes leading account name components from a + --flat report + * print, register, balance: fix layout issues with + mixed-commodity amounts + * print: display non-simple commodity names with double-quotes + * stats: layout tweaks, add payee/description count + * stats: don't break on an empty file + * stats: -p/--period support; a reporting interval generates + multiple reports + * test: drop verbose test runner and testpack dependency + * web: a new web ui based on yesod, requires ghc 6.12; old ghc + 6.10-compatible version remains as -fweb610 + * web: allow wiki-like journal editing + * web: warn and keep running if reloading the journal gives an + error + * web: --port and --base-url options set the webserver's tcp port + and base url + * web: slightly better browser opening on microsoft windows, + should find a standard firefox install now + * web: in a web-enabled build on microsoft windows, run the web + ui by default + +Stats: 55 days and 136 commits since last release. Now at 5552 +lines of code with 132 tests and 54% unit test coverage. + +## 2010/05/23 hledger 0.10 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.hledger/242) + + * fix too-loose testpack dependency, missing safe dependency + * fix ghc 6.12 compatibility with -fweb + * fix handling of non-ascii arguments with ghc 6.12 + * fix "0.8" in --version output + * fix an occasional stack overflow error due to infinite + recursion in Posting/Transaction equality tests + * the -fwebhappstack build flag is gone for now, to avoid a cabal + problem + * parsing: if there is no description, don't require a space + after the transaction date + * parsing: balance balanced-virtual postings separately, allow + them to have an implicit amount + * parsing: timelog entries now generate balanced transactions, + using virtual postings + * parsing: simpler high-level parse error message + * parsing: clearer bad date errors + * add: fix wrongful program exit on bad dates + * print: negative account patterns now exclude transactions + containing any posting to a matched account + * vty: rename the ui command to vty for consistency + * vty: fix restricted account scope when backing up to top level + * web: fix non-ascii handling with ghc 6.12 + * web: fix a bug possibly affecting reload-on-change + * consolidate module namespace under Hledger, api cleanups + +Stats: 44 days, 81 commits since last release. Now at 4904 lines of +code including tests, 144 tests, 53% coverage. + +## 2010/04/10 hledger 0.9 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.hledger/239) + + * ghc 6.12 support + * split off hledger-lib package, containing core types & utils + * parsing: ignore D, C, N, tag, end tag directives; we should now + accept any ledger 2.6 file + * parsing: allow numbers in commodities if double-quoted, like + ledger + * parsing: allow transactions with empty descriptions + * parsing: show a better error for illegal month/day numbers in + dates + * parsing: don't ignore trailing junk in a smart date, eg in web + add form + * parsing: don't ignore unparsed text following an amount + * parsing: @ was being treated as a currency symbol + * add: fix precision handling in default amounts (\#19) + * add: elide last amount in added transactions + * convert: keep original description by default, allow + backreferences in replace pattern + * convert: basic csv file checking, warn instead of dying when it + looks wrong + * convert: allow blank/comment lines at end of rules file + * print: always show zero amounts as 0, hiding any + commodity/decimal places/price, like ledger + * register: fix bad layout with years < 1000 + * register: fix a Prelude.head error with reporting interval, + --empty, and --depth + * register: fix a regression, register should not show posting + comments + * register: with --empty, intervals should continue to ends of + the specified period + * stats: better output when last transaction is in the future + * stats: show commodity symbols, account tree depth, reorder + slightly + * web: -fweb now builds with simpleserver; to get happstack, use + -fwebhappstack instead + * web: pre-fill the add form with today's date + * web: help links, better search form wording + * web: show a proper error for a bad date in add form (\#17) + * web: fix for unicode search form values + * web: fix stack overflow caused by regexpr, and handle requests + faster (\#14) + * web: look for more-generic browser executables + * web: more robust browser starting (\#6) + * error message cleanups + * more tests, refactoring, docs + +Stats: 58 days, 2 contributors, 102 commits since last release. Now +at 3983 lines of non-test code, 139 tests, 53% coverage. + +## 2010/02/11 hledger 0.8 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.hledger/210) + + * parsing: in date=date2, use first date's year as a default for + the second + * add: ctrl-d doesn't work on windows, suggest ctrl-c instead + * add: --no-new-accounts option disallows new accounts (Roman + Cheplyaka) + * add: re-use the previous transaction's date as default (Roman + Cheplyaka) + * add: a command-line argument now filters by account during + history matching (Roman Cheplyaka) + * chart: new command, generates balances pie chart (requires + -fchart flag, gtk2hs) (Roman Cheplyaka, Simon Michael) + * register: make reporting intervals honour a display expression + (\#18) + * web: fix help link + * web: use today as default when adding with a blank date + * web: re-enable account/period fields, they seem to be fixed, + along with file re-reading (\#16) + * web: get static files from the cabal data dir, or the current + dir when using make (\#13) + * web: preserve encoding during add, assuming it's utf-8 (\#15) + * fix some non-utf8-aware file handling (\#15) + * filter ledger again for each command, not just once at program + start + * refactoring, clearer data types + +Stats: 62 days, 2 contributors, 76 commits since last release. Now +at 3464 lines of non-test code, 97 tests, 53% test coverage. + +## 2009/12/11 hledger 0.7 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.hledger/193) + + * price history support (first cut): P directives now work, + though differently from ledger. Each posting amount takes its + fixed unit price from the price history (or + @) when available. This is simple and useful for things like + foreign currency expenses (but not investment tracking). Like + ledger, balance and register don't show amount prices any more, and + don't separate differently-priced amounts. Unlike ledger, print + shows all amount prices, and supports -B. + * --effective option, will use transactions' effective dates if + any + * convert: new rules file format, find/create rules file + automatically, more robust parsing, more useful --debug output + * print: always sort by date, fix long account name truncation, + align amounts, show end of line comments, show all amounts for + clarity (don't elide the final balancing amount) + * ui: use vty 4, fixes non-ascii and gnome terminal problems + (issues \#3, \#4) + * web: allow data entry, react to data file changes, better + layout, help links, remove histogram command and filter fields for + now, fix bad localhost redirect, filter form did not work in eg + firefox (issue \#7), reset link did not work in all browsers + * parsing: require whitespace between date and status code, allow + (and ignore) a time in price records, better error messages, + non-zero exit code on parse failure + * display non-ascii error messages properly (issue \#5) + * fix an arithmetic bug that occasionally rejected valid + transactions + * fix a regex bug in showtree + * don't break if HOME is undefined + * --debug now implies --verbose + * add functional tests like ledger's, use test-framework for + speedy running, release shelltestrunner as a separate package + * many hlint cleanups (Marko Kocić) + * many site and documentation updates + +Stats: 60 days, 1 contributor, 50 commits since last release. Now +at 3377 lines of non-test code, 97 tests, 53% test coverage. + +## 2009/06/22 hledger 0.6.1 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.hledger/156) + + * avoid use of exitSuccess which was breaking ghc 6.8/base 3 + compatibility (issue \#2) + +## 2009/06/13 hledger 0.6 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.general/1215) + + * now cabal-installable on unix, mac, and windows, with Haskell + Platform + * provide experimental platform binaries + * parsing: fix a silly failure to open ledger file paths + containing \~ + * parsing: show better errors for unbalanced transaction and + missing default year + * parsing: allow parentheses and brackets inside account names, + as ledger does + * parsing: fail on empty account name components, don't just + ignore + * add: description passed as arguments now affects first + transaction only + * add: better handling of virtual postings and default amounts + * print, register: show virtual accounts bracketed/parenthesised + * web: improved web ui supporting full patterns & period + expressions + * new "stats" command reports some ledger statistics + * many dev/doc/deployment infrastructure improvements + * move website into darcs repo, update home page + * move issue tracker to google code + +Release stats: + + * Contributors: Simon Michael + * Days since last release: 21 + * Commits: 94 + * Lines of non-test code: 2865 + * Tests: 82 + * Test coverage: 53% expressions + * Known errors: 3 (inconsistent eliding, vty-related failures) + * Performance: similar + (http://hledger.org/profs/200906131120.bench) + +## 2009/05/23 hledger 0.5.1 + + * two fixes: really disable vty flag by default, and include + ConvertCommand in cabal file + +## 2009/05/23 hledger 0.5 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.general/1181) + + * the vty flag is disabled by default again, to ease installation + on windows + * use ledger 3 terminology: a ledger contains transactions which + contain postings + * new "add" command prompts for transactions interactively and + adds them to the ledger + * new "convert" command transforms bank CSV exports to ledger + format, with rule-based cleanup + * new "histogram" command shows transaction counts per day or + other reporting interval + * most commands now work properly with UTF8-encoded text (Sergey + Astanin) + * invoking as "hours" is now less different: it just uses your + timelog, not your ledger + * ..quarterly/-Q option summarises by quarter + * ..uncleared/-U option looks only at uncleared transactions + * be more accurate about checking balanced amounts, don't rely on + display precision + * enforce balancing for bracketed virtual postings + * fix bug in eliding of posting amounts + * don't show trailing spaces on amountless postings + * parse null input as an empty ledger + * don't treat comments as part of transaction descriptions + * require some postings in ledger transactions + * require a non-empty description in ledger transactions + * don't fail when matching an empty pattern, as in "not:" + * make the web server handle the null path + * code, api and documentation updates + * add a contributor agreement/list + +Release stats: + + * Contributors: Simon Michael, Sergey Astanin + * Days since last release: 51 + * Commits: 101 + * Lines of non-test code: 2795 + * Tests: 76 + * Known errors: 0 + +## 2009/04/03 hledger 0.4 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.general/1097) + + * new "web" command serves reports in a web browser (install with + -f happs to build this) + * make the vty-based curses ui a cabal build option, which will + be ignored on MS windows + * drop the ..options-anywhere flag, that is now the default + * patterns now use not: and desc: prefixes instead of \^ and \^\^ + * patterns are now case-insensitive, like ledger + * !include directives are now relative to the including file (Tim + Docker) + * "Y2009" default year directives are now supported, allowing m/d + dates in ledger + * individual transactions now have a cleared status + * unbalanced entries now cause a proper warning + * balance report now passes all ledger compatibility tests + * balance report now shows subtotals by default, like ledger 3 + * balance report shows the final zero total when -E is used + * balance report hides the final total when ..no-total is used + * ..depth affects print and register reports (aggregating with a + reporting interval, filtering otherwise) + * register report sorts transactions by date + * register report shows zero-amount transactions when -E is used + * provide more convenient timelog querying when invoked as + "hours" + * multi-day timelog sessions are split at midnight + * unterminated timelog sessions are now counted. Accurate time + reports at last! + * the test command gives better ..verbose output + * ..version gives more detailed version numbers including + patchlevel for dev builds + * new make targets include: ghci, haddocktest, doctest, unittest, + view-api-docs + * a doctest-style framework for functional/shell tests has been + added + +Release stats: + + * Contributors: Simon Michael, Tim Docker; thanks to the HAppS, + happstack and testpack developers + * Days since release: 76 + * Commits: 144 + * Lines of non-test code: 2367 + * Tests: 56 + * Known errors: 0 + +## 2009/01/17 hledger 0.3 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.hledger/67) + + * count timelog sessions on the day they end, like ledger, for + now + * when options are repeated, use the last instead of the first + * builds with ghc 6.10 as well as 6.8 + * a simple ui for interactive report browsing: hledger ui + * accept smart dates everywhere (YYYYMMDD, Y/M/D, Y, M/D, D, jan, + today, last week etc.) + * ..period/-p flag accepting period expressions like "in 2008", + "weekly from last month".. + * -W/-M/-Y convenience flags to summarise register weekly, + monthly, yearly + * ..depth and -E flags also affect summarised register reports + (including depth=0) + * ..display/-d flag supporting date predicates (like "d<[DATE]", + "d\>=[DATE]") + * !include directive to include additional ledger files + * !account directive to set a default parent account + * Added support for reading historical prices from files + * timelog and ledger entries can be intermixed in one file + * modifier and periodic entries can appear anywhere (but are + still ignored) + * help and readme improvements + * runs much faster than 0.2 + +Release stats: + + * Contributors: Simon Michael, Nick Ingolia, Tim Docker; thanks + to Corey O'Connor & the vty team + * Lines of non-test code: 2123 + * Tests: 58 + * Known errors: 1 + +## 2008/11/23 hledger 0.2 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.general/826) + + * fix balance report totals when filtering by account + * fix balance report selection of accounts when filtering by + account + * fix a bug with account name eliding in balance report + * if we happen to be showing a not-yet-auto-balanced entry, hide + the AUTO marker + * fix print command filtering by account + * omit transactions with zero amount from register report + * Fix bug in parsing of timelogs + * rename ..showsubs to ..subtotal, like ledger + * drop ..usage flag + * don't require quickcheck + * priced amounts (eg "10h @ $50") and ..basis/..cost/-B flag to + show them with cost basis + * easy ..depth option, equivalent to ledger's -d 'l<=N' + * smarter y/m/d date parsing for -b and -e (any number of digits, + month and day default to 1, separator can be / - or .) + * -n flag for balance command + * ..empty/-E flag + * build a library, as well as the exe + * new home page url (http://joyful.com/hledger) + * publish html and pdf versions of README + * detect display preferences for each commodity like ledger + * support amounts with multiple currencies/commodities + * support ..real/-R flag + * support -C/..cleared flag to filter by entry status (not + transaction status) + * support virtual and balanced virtual transactions + * parse comment lines beginning with a space, as from M-; in + emacs ledger-mode + * allow any non-whitespace in account names, perhaps avoiding + misleading missing amounts errors + * clearer error message when we can't balance an entry + * when we fail because of more than one missing amount in an + entry, show the full entry + * document the built-in test runner in ..help + * add a ..verbose/-v flag, use it to show more test-running + detail + +Release stats: + + * Contributors: Simon Michael, Tim Docker + * Lines of non-test code: 1350 + * Tests: 43 + * Known errors: 0 + +## 2008/10/15 hledger 0.1 + +[announcement](http://thread.gmane.org/gmane.comp.finance.ledger.general/775) + +Release stats: + + * Contributors: Simon Michael diff --git a/doc/site/sidebar.md b/doc/site/sidebar.md new file mode 100644 index 000000000..87f49c0cc --- /dev/null +++ b/doc/site/sidebar.md @@ -0,0 +1,36 @@ +~~NOCACHE~~ + +[[Home]] + +[[Download]] + +[[Release Notes]] + +[[step-by-step|Tutorial]] + +[[Manual]] + +[[Developer Guide]] + +[[FAQ]] + +[[More docs]] + +--- + +[Code](http://hledger.org/code) + +[Bug tracker](http://hledger.org/bugs) & +[trello](http://hledger.org/trello) + +[Mail list](http://hledger.org/list) + +[#hledger IRC](http://hledger.org/irc) +(also [#ledger](http://webchat.freenode.net?channels=ledger&randomnick=1)) + +[[https://twitter.com/LedgerTips|@LedgerTips]], +[#ledgercli](https://twitter.com/search?q=%23ledgercli&src=typd&f=realtime) +(Twitter) + + + diff --git a/doc/site/site.tmpl b/doc/site/site.tmpl new file mode 100644 index 000000000..05c52db21 --- /dev/null +++ b/doc/site/site.tmpl @@ -0,0 +1,32 @@ + + + + + + $title$ + + + + + + + $body$ + + 2014/11/4: The site is going through some changes, for now please enjoy the old-school styling. + + + diff --git a/doc/site/step-by-step.md b/doc/site/step-by-step.md new file mode 100644 index 000000000..951f22157 --- /dev/null +++ b/doc/site/step-by-step.md @@ -0,0 +1,695 @@ +# hledger Step by Step (draft) + +*(c) Simon Michael, 2014* + +Welcome! Here you can learn hledger (and a little double-entry +accounting) by practicing, one hands-on exercise at a time, in the +style of the "Learn X the Hard Way" books. Exercises are grouped into +these chapters: + +- [[#0. SETUP]] +- [[#1. BASIC DATA ENTRY & REPORTING]] +- [[#2. USEFUL ACCOUNTING CONCEPTS]] + +You'll learn the most if you work through each small step in order. +If a step specifies no particular task, your task is to run the examples and understand it. + +If you get stuck, or have any other feedback, report it on IRC or the mail list (see the sidebar), +or right on this page (click the pencil on the right). + +You'll need: + +1. hledger, installed using the [[installing|Installation Guide]]. These exercises were last tested with: hledger 0.23dev-20140212. + +2. A basic understanding of the command line, text file editing, and regular expressions. Or, the ability to ask for help on the IRC channel. + + + +--- +## 0. SETUP + +--- +### Check your hledger + +Get a command prompt, and run hledger to check the version. It should be reasonably [[release-notes|up to date]].: + +``` +$ hledger --version +hledger 0.23 +``` + +--- +## 1. BASIC DATA ENTRY & REPORTING + +--- +### Locate your journal file with "hledger stats" + +hledger reads financial transactions from a "journal file" (so named because it represents a [[wp>General Journal]]). +The default journal file is in your home directory; check its path using the [[manual#stats|stats]] command. +You should see something like: +``` +$ hledger stats +The hledger journal file "/home/YOU/.hledger.journal" was not found. +Please create it first, eg with "hledger add" or a text editor. +Or, specify an existing journal file with -f or LEDGER_FILE. +``` + +Most hledger commands read this file but can not change it; the `add` and `web` commands can also write it. + +(If `stats` reports that the file exists, eg because you previously created it, move it out of the way temporarily for these exercises.) + +--- +### Record a transaction with "hledger add" + +Follow the help and use the [[manual#add|add]] command to record your first transaction, +an imaginary purchase at the supermarket. +We'll go through this in detail. Later you'll learn other ways to enter data. + +``` +$ hledger add +Adding transactions to journal file /home/YOU/.hledger.journal +Provide field values at the prompts, or press enter to accept defaults. +Use readline keys to edit, use tab key to complete account names. +A code (in parentheses) may be entered following transaction dates. +A comment may be entered following descriptions or amounts. +If you make a mistake, enter < at any prompt to restart the transaction. +To complete a transaction, enter . when prompted. +To quit, press control-d or control-c. + +Starting a new transaction. +date ? [2014/02/12]: +``` + +`add` prompts for each transaction field. The first is the date. +The value in square brackets is the suggested default (today's date). Press enter to accept it. + +``` +description ? : trip to the supermarket +``` + +Transactions have an optional description (a single line of text) to help you understand them. +You can describe the transaction here, or put a payee name, or leave it blank. +Type `trip to the supermarket` and press enter. + +``` +account 1 ? : expenses +``` + +Transactions have two or more accounts. Keep it simple; just enter `expenses` for the first one. + +If you're thinking "expenses sounds more like a category": it is, but double entry accounting calls those "accounts", too. +A purchase is a transfer of money from an asset account to an expense account. +An asset is something you own, like some money in a bank account or in your pocket. +Once the money has been "moved" to an expense, you no longer own it, but the increasing balance in the expense account reminds you where it went. + +``` +amount 1 ? : $10 +``` + +The amount being "moved" to `expenses`. In this case 10 US dollars. + +``` +account 2 ? : assets +``` + +Next, specify which account the money comes from. Just say `assets`. + +``` +amount 2 ? [$-10.0]: +``` + +Now you're asked for the amount to "move" to or from the `assets` account. +As the default, hledger offers the amount required to "balance" the postings entered so far. +The minus sign indicates the money is moving from this account. +(hledger uses positive and negative sign instead of accounting's traditional "debit" and "credit" terminology.) +In a balanced transaction, the sum of posted amounts is zero, in other words no money disappears into thin air. +hledger does not allow unbalanced transactions. +Press enter to accept the default. It has an extra decimal place, but never mind. + +``` +account 3 (or . to complete this transaction) ? : . +``` + +Type `.` (period) and press enter. + +``` +Transaction entered: +2014/02/12 trip to the supermarket + expenses $10 + assets $-10.0 + +Accept this transaction ? [y]: +``` + +You are given a chance to review the transaction just entered. +Here you see hledger's plain text data format for journal entries: +a non-indented YYYY/MM/DD date, space, and description, +followed by two or more indented posting lines, each containing an account name, +two or more spaces, and an amount. +(Account names can contain spaces, so at least two spaces are needed to separate them from the amount.) +Press enter. + +``` +Added to the journal. + +Starting a new transaction. +date ? [2014/02/12]: +$ +``` + +hledger has saved it to the journal file and is ready for the next +entry. Press control-d (on Windows, control-c) once to exit. + +`stats` should now report that your journal exists and contains one transaction: + +``` +$ hledger stats +Main journal file : /home/YOU/.hledger.journal +Included journal files : +Transactions span : 2014-02-12 to 2014-02-13 (1 days) +Last transaction : 2014-02-12 (0 days ago) +Transactions : 1 (1.0 per day) +Transactions last 30 days: 1 (0.0 per day) +Transactions last 7 days : 1 (0.1 per day) +Payees/descriptions : 1 +Accounts : 2 (depth 1) +Commodities : 1 ($) +``` + +--- +### Show transactions with "hledger print" + +The [[manual#print|print]] command shows a tidied-up view of the transaction entries in your journal. +Since there's just one so far, you should see: + +``` +$ hledger print +2014/02/12 trip to the supermarket + expenses $10 + assets $-10 +``` + +--- +### Examine your journal file + +List and print the journal file (on Windows, use `dir` and `type` and the file path from `hledger stats`): + +``` +$ ls -l ~/.hledger.journal +-rw-rw-r-- 1 YOU YOU 74 Feb 12 08:10 /home/YOU/.hledger.journal +$ cat ~/.hledger.journal + +2014/02/12 trip to the supermarket + expenses $10 + assets +``` + +--- +### A convenience: inferred amounts + +Why is the amount missing from the assets posting above ? +As a convenience to make manual data entry easier, if one amount is missing +hledger infers it so as to balance the transaction ($-10 in this case). +For consistency, `add` uses the same convention when it writes an entry. +(But `print` shows the inferred amount, for clarity.) +Only one missing amount is allowed in each transaction. + +--- +### Edit the journal file + +Since the journal file is plain text, you can edit it directly with any text editor. +Edit the file and change it to test whether two missing amounts is reported as an error. Eg: + +``` +$ emacs ~/.hledger.journal +``` + +Remove the expenses amount and save the file. It now looks like this: + +``` +2014/02/12 trip to the supermarket + expenses + assets +``` + +Running `print` again, you should see: + +``` +$ hledger print +hledger: could not balance this transaction (can't have more than one missing amount; remember to put 2 or more spaces before amounts) +2014/02/12 trip to the supermarket + expenses + assets + +``` + +All hledger commands expect the journal to be well-formed, and will report an error and exit otherwise. + +--- +### Two spaces + +Notice the last part of that error message: "`... remember to put 2 or more spaces before amounts)`". +Another cause of this error is forgetting to put two spaces before the +amount, like this: + +``` +2014/02/12 trip to the supermarket + expenses $10 ; <- only one space between expenses and $10 - need at least two + assets +``` + +Since account names may contain spaces, hledger thinks the first +posting is to an account named "`expenses $10`", with a missing +amount. So remember: two or more spaces. + +--- +### Unbalanced transactions + +Edit the file to look like this: + +``` +2014/02/12 trip to the supermarket + expenses $10 + assets $10 +``` + +Here, we wrote both posting amounts but got the sign wrong on one of them, so they don't add up to zero. +hledger should detect this mistake. Verify it by running some command, eg `print`. You should see: + +``` +$ hledger print +hledger: could not balance this transaction (real postings are off by $20) +2014/02/12 trip to the supermarket + expenses $10 + assets $10 +``` + +That makes sense. (It calls them "real" postings because there are some other kinds of posting you haven't learned about yet; they aren't important.) + +Correct the mistake by adding the minus sign, or just removing the assets amount entirely, and verify +that `print` works again. + +--- +### Record a transaction by editing + +Edit the file again and manually add a second purchase transaction. +It's often quickest to copy & paste a similar entry, then change it. +Make the file look like this: + +``` +2014/02/12 trip to the supermarket + expenses $10 + assets + +2014/02/13 forgot the bread + expenses $5 + assets +``` + +The blank line between transactions is customary, though not required. +Test your work with `print`. You should see: + +``` +$ hledger print +2014/02/12 trip to the supermarket + expenses $10 + assets $-10 + +2014/02/13 forgot the bread + expenses $5 + assets $-5 + +``` + +--- +### Show postings and a running total with "hledger register" + +The [[manual#register|register]] command shows transactions in a different format. More precisely, it shows postings. +Remember, a posting is an increase or decrease of some account by some amount, and a transaction contains two or more of them. +Run `register` and compare with the output of `print` above. You should see: + +``` +$ hledger register +2014/02/12 trip to the super.. expenses $10 $10 + assets $-10 0 +2014/02/13 forgot the bread expenses $5 $5 + assets $-5 0 +``` + +Postings are displayed one per line. +The transaction's date and description is displayed only for the first posting in each transaction. +Next we see the posted account's name and the amount posted. +The final column is a running total of the posted amounts. + +--- +### Show a per-account register report + +Notice how the running total above keeps resetting to 0. +This makes sense (since we know each transaction's postings add up to zero) but isn't very useful. +The register report is more useful when we restrict it to a subset of postings - +say, only the postings within a single account. +You can do this by specifying the account name as a command line argument. + +Run a register report for the `expenses` account. You should see: + +``` +$ hledger register expenses +2014/02/12 trip to the super.. expenses $10 $10 +2014/02/13 forgot the bread expenses $5 $15 +``` + +Now it's clear that your `expenses` balance - ie, the total amount spent - has increased to $15. + +Your `assets` balance should have dropped accordingly. Check it: + +``` +$ hledger register assets +2014/02/12 trip to the super.. assets $-10 $-10 +2014/02/13 forgot the bread assets $-5 $-15 +``` + +--- +### Query expressions + +The account name argument above is an example of a +[[manual#queries|query expression]], a search pattern which restricts a report to a subset of the data. +In this way you can make very precise queries. + +Note that it is a case-insensitive regular expression which matches anywhere inside the account name. +So "`e`" would match both `expenses` and `assets`. + +And if you had an account named `other assets`, "`assets`" would also match that, so to match only the `assets` +account you'd need a more precise pattern like "`^assets$`". +If this doesn't make sense, read a little about regular expressions. +In a regular expression `^` means "match at the beginning" and `$` means "match at the end". + +Multiple query arguments are ANDed and ORed together in a fixed way - follow the link for details. +Basically queries on the same field are ORed, and queries on different fields are ANDed. + +Run the following examples and make sure they make sense, consulting the manual as needed. + +Show only transactions whose description contains the regular expression "`bread`": + +``` +$ hledger print desc:bread +2014/02/13 forgot the bread + expenses $5 + assets $-5 +``` + +Show only postings on or after a certain date to an account whose name ends with "es": +``` +$ hledger register date:2014/2/13- 'es$' +2014/02/13 forgot the bread expenses $5 $5 +``` + +Note how the account-matching pattern `es$` needs to be quoted here, +because it contains the regular expression metacharacter `$` which would otherwise be interpreted by the unix shell. + +--- +### Show accounts and their balances with "hledger balance" + +The third of hledger's three core reporting commands is [[manual#balance|balance]]. +Use it to list all the accounts posted to, and their ending balance. +You should see account balances agreeing with the final running total in the register reports above: + +``` + $-15 assets + $15 expenses +-------------------- + 0 +``` + +The overall total of these balances is also shown. As with other reports, you can use a query expression to select a subset of the data to report on. +Eg: + +``` +$ hledger balance assets + $-15 assets +-------------------- + $-15 +``` + +--- +### balance shows the sum of matched posting amounts + +Here's a balance report based only on the postings dated 2013/2/13: +``` +$ hledger balance date:2014/2/13 + $-5 assets + $5 expenses +-------------------- + 0 +``` + +As you can see from this, `balance` does not always report the current +real-world account balance, rather it shows the sum of the postings +you have selected. +If you're not sure what those are, run a `register` report with the same arguments to see them: + +``` +$ hledger register date:2014/2/13 +2014/02/13 forgot the bread expenses $5 $5 + assets $-5 0 +``` + +--- + +### Review + +You have learned: + +- a simple plain text notation for recording financial transactions, used by hledger, Ledger and others + +- what is the journal file, where it is, and how to get statistics on it with `hledger stats` + +- how to record new transactions using `hledger add` + +- how to record transactions by editing the journal file + +- what the journal entry for a purchase looks like + +- how to detect some common errors, by eye or with hledger + +- how hledger selects data to report on, and how to select by account, description, or date + +- how to list transactions with `hledger print` + +- how to list postings and see an account's balance over time with `hledger register` + +- how to list accounts and their current balance, or the sum of their postings in some period, with `hledger balance` + +--- + + + + +## 2. USEFUL ACCOUNTING CONCEPTS + +--- +### Assets, Liabilities and Equity + +Accounting describes the status of a business, person or other entity at any point in time in terms of three amounts: + +- **Assets** - Things owned +- **Liabilities** - Things owed +- **Equity** - The amount invested by owners/shareholders + +The foundation of double-entry accounting is the [[wp>accounting equation]], which says +that Equity is always equal to Assets minus Liabilities (or, Net Assets). + +This is also written as: Assets = Liabilities + Equity. +Another way to say it: what the entity owns is funded either by debt or by the capital provided by its owners. + +These three are called the Balance Sheet accounts. Their balances summarise the overall financial status at some point in time. + +--- + +### Revenue and Expenses + +Two more amounts are used to describe changes in the above during a given period: + +- **Revenue** - Money flowing in +- **Expenses** - Money flowing out + +You may be accustomed to using the word Income instead Revenue. +That's fine, just remember that Income is sometimes used to mean Net +Income, which is Revenue - Expenses. + +These two are called the Income Statement accounts. The balances they +accumulate during some period of time indicate the inflows and +outflows during that period (which will affect the Assets and +Liabilities balances). + +--- + +### Chart of Accounts + +Five numbers does not give a lot of detail. If you want to know what +portion of expenses went to buy food, you could add up just the +transactions with (say) "supermarket" in their description. You know how to do this with hledger: + +``` +$ hledger register desc:supermarket expenses +2014/02/12 trip to the super.. expenses $10 $10 +``` + +But descriptions are irregular, and as you can see we missed the $5 purchase on the following day. + +Instead, the major "top-level" accounts above are subdivided into subaccounts which can be used +in transactions, thereby categorising them in a more structured way. +If needed, these subaccounts can be subdivided further. +This tree of accounts is called the Chart of Accounts. Here's a simple example +where `assets`, `revenue` and `expenses` each have a few subaccounts: + +``` +assets + checking + cash +liabilities +equity +revenue + business income + gifts received +expenses + food + rent + supplies +``` + +In some organisations and accounting systems (eg, QuickBooks), the +tree structure is de-emphasised, so the above is represented more +like: + +^ Account name ^ Account type ^ +| checking | ASSET | +| cash | ASSET | +| business income | REVENUE | +| gifts received | REVENUE | +| food | EXPENSE | +| rent | EXPENSE | +| supplies | EXPENSE | + +In others, the tree structure is encoded as decimal account numbers, something like this: + +``` +1000 assets +1100 checking +1200 cash +2000 liabilities +3000 equity +4000 revenue +4100 business income +4200 gifts received +5000 expenses +5100 food +5200 rent +5300 supplies +``` + +--- +### Subaccounts in hledger + +With hledger, tree structure is implied by writing account names like `ACCOUNT:SUBACCOUNT`. +Try it: edit your journal file and change the account names like so: + +``` +$ cat ~/.hledger.journal + +2014/02/12 trip to the supermarket + expenses:supplies $10 + assets:checking + +2014/02/13 forgot the bread + expenses:food $5 + assets:cash +``` + +hledger will infer the chart of accounts from these names, and `balance` will indent subaccounts to show the tree structure: + +``` +$ hledger balance + $-15 assets + $-5 cash + $-10 checking + $15 expenses + $5 food + $10 supplies +-------------------- + 0 +``` + +For clarity, the common part of the subaccount names is not displayed. +You can see the full account names used internally like this: + +``` +$ hledger balance --flat --empty + $-15 assets + $-5 assets:cash + $-10 assets:checking + $15 expenses + $5 expenses:food + $10 expenses:supplies +-------------------- + 0 +``` + +With `--flat`, the balance command shows full account names without indentation. +The `--empty` flag here requests that the accounts with no direct postings of their own be displayed. +Normally the balance report omits or elides such "uninteresting" accounts when they don't add much information. +(In the default indented view, they are included to clarify the structure.) + +As you can see, the balance reported for parent accounts includes the +balances of any subaccounts (it would also include any postings to the +parent account itself.) + +hledger accepts whatever account names you choose, so you can use as much or as little account hierarchy as you need. +Most users have at least two levels of accounts. +You can always limit the amount of detail in a balance report with `--depth`: + +``` +$ hledger balance --depth 1 + $-15 assets + $15 expenses +-------------------- + 0 +``` + + +--- + + + +