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

site: content updates for the hakyll/pandoc site

Browse Source
This commit is contained in:
Simon Michael 2014-11-10 13:38:05 -08:00
parent 05474d9a9f
commit 7ca806c5b0
12 changed files with 243 additions and 203 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
doc/developer-guide.md
View File

@ -1,17 +1,32 @@
<!-- hledger repo and http://hledger.org versions of this document are periodically bidirectionally synced --> <!-- hledger repo and http://hledger.org versions of this document are periodically bidirectionally synced -->
* toc
# Developer guide # Developer guide
## Quick links ## Quick links
^ hledger.org: ^ [[release notes|combined release notes]], [[download|pre-compiled binaries]] ^ <style>
^ Github: ^ [code](http://github.com/simonmichael/hledger), [commits](http://github.com/simonmichael/hledger/commits), [COMMITS](http://starlogs.net/#simonmichael/hledger) (turn up your volume) \\ [commits only in master](https://github.com/simonmichael/hledger/compare/0.23...master), [commits only in release branch](https://github.com/simonmichael/hledger/compare/master...0.23) \\ [build status (hydra)](http://hydra.cryp.to/jobset/hledger/master#tabs-jobs) \\ [open bugs](https://github.com/simonmichael/hledger/issues?direction=desc&labels=BUG&page=1&sort=created&state=open), [all bugs](https://github.com/simonmichael/hledger/issues?direction=desc&labels=BUG&page=1&sort=created), [open issues](https://github.com/simonmichael/hledger/issues?direction=desc&labels=&page=1&sort=created&state=open), [all issues](https://github.com/simonmichael/hledger/issues?direction=desc&labels=&page=1&sort=created) ^ tr {
^ Hackage: ^ [hledger-lib](http://hackage.haskell.org/package/hledger-lib), [hledger](http://hackage.haskell.org/package/hledger), [hledger-web](http://hackage.haskell.org/package/hledger-web), [hledger-interest](http://hackage.haskell.org/package/hledger-interest), [hledger-irr](http://hackage.haskell.org/package/hledger-irr), [hledger-vty](http://hackage.haskell.org/package/hledger-vty), [hledger-chart](http://hackage.haskell.org/package/hledger-chart), [*hledger*](http://hackage.haskell.org/packages/search?terms=hledger) \\ reverse dependencies: [hledger-lib](http://packdeps.haskellers.com/reverse/hledger-lib), [hledger](http://packdeps.haskellers.com/reverse/hledger), [outdated dependencies](http://packdeps.haskellers.com/feed/?needle=hledger) \\ [download activity](http://best-haskell.herokuapp.com/#/category/Finance) ^ /*vertical-align:top;*/
^ Stackage: ^ [hledger entry](https://github.com/fpco/stackage/blob/master/Stackage/Config.hs#L449-450), [issues](https://github.com/fpco/stackage/search?q=hledger&ref=cmdform&type=Issues) \\ [build status (jenkins)](http://jenkins.stackage.org/job/Stackage/), last build output: [7.4](http://jenkins.stackage.org/job/Stackage/ghcversion=7.4.2/lastBuild/console), [7.6](http://jenkins.stackage.org/job/Stackage/ghcversion=7.6.3/lastBuild/console), [7.8](http://jenkins.stackage.org/job/Stackage/ghcversion=7.8.2/lastBuild/console) ^ border-top:thin solid #bbb;
^ Debian: ^ source packages \\ [haskell-hledger-lib](http://packages.qa.debian.org/h/haskell-hledger-lib.html), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=haskell-hledger-lib), [haskell-hledger](http://packages.qa.debian.org/h/haskell-hledger.html), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=haskell-hledger), [haskell-hledger-web](http://packages.qa.debian.org/h/haskell-hledger-web.html), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=haskell-hledger-web) \\ binary packages \\ testing: [hledger](https://packages.debian.org/testing/hledger), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger;dist=testing), [hledger-web](https://packages.debian.org/testing/hledger-web), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger-web;dist=testing) \\ unstable: [hledger](https://packages.debian.org/unstable/hledger), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger;dist=unstable), [hledger-web](https://packages.debian.org/unstable/hledger-web), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger-web;dist=unstable) \\ all: [*hledger*](https://packages.debian.org/search?searchon=names&keywords=hledger) \\ popularity stats: [hledger](https://qa.debian.org/popcon.php?package=haskell-hledger), [hledger-web](https://qa.debian.org/popcon.php?package=haskell-hledger-web) \\ [PTS help](https://www.debian.org/doc/manuals/developers-reference/resources.html#pkg-tracking-system) ^ }
^ Ubuntu: ^ source packages \\ [haskell-hledger-lib](https://launchpad.net/ubuntu/+source/haskell-hledger-lib), [bugs](https://bugs.launchpad.net/ubuntu/+source/haskell-hledger-lib), [haskell-hledger](https://launchpad.net/ubuntu/+source/haskell-hledger), [bugs](https://bugs.launchpad.net/ubuntu/+source/haskell-hledger), [haskell-hledger-web](https://launchpad.net/ubuntu/+source/haskell-hledger-web), [bugs](https://bugs.launchpad.net/ubuntu/+source/haskell-hledger-web) \\ binary packages \\ [*hledger*](http://packages.ubuntu.com/search?suite=all&searchon=names&keywords=hledger) ^ </style>
^ Gentoo: ^ [hledger](http://gpo.zugaina.org/dev-haskell/hledger), [hledger-web](http://gpo.zugaina.org/dev-haskell/hledger-web), [*hledger*](http://gpo.zugaina.org/Search?search=hledger) ^ <!-- | hledger.org&nbsp;&nbsp; | [combined release notes](release notes), [pre-compiled binaries](download) | -->
^ Fedora: ^ [hledger](https://apps.fedoraproject.org/packages/hledger), [*hledger*](https://apps.fedoraproject.org/packages/s/hledger) ^ <!-- [web ui demo](http://demo.hledger.org/register?q=inacct%3Aassets%3Abank%3Achecking+sym%3A\%24) -->
|-------------------------|----------------------------------------------------------------------------|
| IRC | Join [#hledger](http://hledger.org/irc) (see also [#ledger](http://webchat.freenode.net?channels=ledger&randomnick=1)) |
| Mail list | <http://hledger.org/list> |
| Twitter | [#ledgercli](https://twitter.com/search?q=%23ledgercli&src=typd&f=realtime), <a href="https://twitter.com/ledgertips">@LedgerTips</a> |
| hledger-web demo | [demo.hledger.org](http://demo.hledger.org) |
| Trello | [planning board](http://hledger.org/trello) |
| Github | [code](http://github.com/simonmichael/hledger), [commits](http://github.com/simonmichael/hledger/commits), [COMMITS](http://starlogs.net/#simonmichael/hledger) (turn up your volume) <br> [commits only in master](https://github.com/simonmichael/hledger/compare/0.23...master), [commits only in release branch](https://github.com/simonmichael/hledger/compare/master...0.23) <br> [build status (hydra)](http://hydra.cryp.to/jobset/hledger/master#tabs-jobs) <br> [open bugs](https://github.com/simonmichael/hledger/issues?direction=desc&labels=BUG&page=1&sort=created&state=open), [all bugs](https://github.com/simonmichael/hledger/issues?direction=desc&labels=BUG&page=1&sort=created), [open issues](https://github.com/simonmichael/hledger/issues?direction=desc&labels=&page=1&sort=created&state=open), [all issues](https://github.com/simonmichael/hledger/issues?direction=desc&labels=&page=1&sort=created) |
| Hackage | [hledger-lib](http://hackage.haskell.org/package/hledger-lib), [hledger](http://hackage.haskell.org/package/hledger), [hledger-web](http://hackage.haskell.org/package/hledger-web), [hledger-interest](http://hackage.haskell.org/package/hledger-interest), [hledger-irr](http://hackage.haskell.org/package/hledger-irr), [hledger-vty](http://hackage.haskell.org/package/hledger-vty), [hledger-chart](http://hackage.haskell.org/package/hledger-chart), [*hledger*](http://hackage.haskell.org/packages/search?terms=hledger) <br> reverse dependencies: [hledger-lib](http://packdeps.haskellers.com/reverse/hledger-lib), [hledger](http://packdeps.haskellers.com/reverse/hledger), [outdated dependencies](http://packdeps.haskellers.com/feed/?needle=hledger) <br> [download activity](http://best-haskell.herokuapp.com/#/category/Finance) |
| Stackage | [hledger entry](https://github.com/fpco/stackage/blob/master/Stackage/Config.hs#L449-450), [issues](https://github.com/fpco/stackage/search?q=hledger&ref=cmdform&type=Issues) <br> [build status (jenkins)](http://jenkins.stackage.org/job/Stackage/), last build output: [7.4](http://jenkins.stackage.org/job/Stackage/ghcversion=7.4.2/lastBuild/console), [7.6](http://jenkins.stackage.org/job/Stackage/ghcversion=7.6.3/lastBuild/console), [7.8](http://jenkins.stackage.org/job/Stackage/ghcversion=7.8.2/lastBuild/console) |
| Debian | source packages <br> [haskell-hledger-lib](http://packages.qa.debian.org/h/haskell-hledger-lib.html), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=haskell-hledger-lib), [haskell-hledger](http://packages.qa.debian.org/h/haskell-hledger.html), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=haskell-hledger), [haskell-hledger-web](http://packages.qa.debian.org/h/haskell-hledger-web.html), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=haskell-hledger-web) <br> binary packages <br> testing: [hledger](https://packages.debian.org/testing/hledger), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger;dist=testing), [hledger-web](https://packages.debian.org/testing/hledger-web), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger-web;dist=testing) <br> unstable: [hledger](https://packages.debian.org/unstable/hledger), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger;dist=unstable), [hledger-web](https://packages.debian.org/unstable/hledger-web), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger-web;dist=unstable) <br> all: [*hledger*](https://packages.debian.org/search?searchon=names&keywords=hledger) <br> popularity stats: [hledger](https://qa.debian.org/popcon.php?package=haskell-hledger), [hledger-web](https://qa.debian.org/popcon.php?package=haskell-hledger-web) <br> [PTS help](https://www.debian.org/doc/manuals/developers-reference/resources.html#pkg-tracking-system) |
| Ubuntu | source packages <br> [haskell-hledger-lib](https://launchpad.net/ubuntu/+source/haskell-hledger-lib), [bugs](https://bugs.launchpad.net/ubuntu/+source/haskell-hledger-lib), [haskell-hledger](https://launchpad.net/ubuntu/+source/haskell-hledger), [bugs](https://bugs.launchpad.net/ubuntu/+source/haskell-hledger), [haskell-hledger-web](https://launchpad.net/ubuntu/+source/haskell-hledger-web), [bugs](https://bugs.launchpad.net/ubuntu/+source/haskell-hledger-web) <br> binary packages <br> [*hledger*](http://packages.ubuntu.com/search?suite=all&searchon=names&keywords=hledger) |
| Gentoo | [hledger](http://gpo.zugaina.org/dev-haskell/hledger), [hledger-web](http://gpo.zugaina.org/dev-haskell/hledger-web), [*hledger*](http://gpo.zugaina.org/Search?search=hledger) |
| Fedora | [hledger](https://apps.fedoraproject.org/packages/hledger), [*hledger*](https://apps.fedoraproject.org/packages/s/hledger) |
<!-- list the debian packages for clarity: <!-- list the debian packages for clarity:
3 source: 3 source:
@ -37,7 +52,7 @@ libghc-hledger-lib-prof
<!-- [heap](http://hledger.org/profs/latest.ps) --> <!-- [heap](http://hledger.org/profs/latest.ps) -->
<!-- [developer notes](http://github.com/simonmichael/hledger/NOTES.org)\ --> <!-- [developer notes](http://github.com/simonmichael/hledger/NOTES.org)\ -->
<!-- [browse dev API docs](http://hledger.org/api/frames.html) --> <!-- [browse dev API docs](http://hledger.org/api/frames.html) -->
<!-- [[developer-guide#set-up-for-development|How to clone it]] --> <!-- [How to clone it](developer-guide#set-up-for-development) -->
<!-- [hledger-web dev demo](http://demo.hledger.org:5001) --> <!-- [hledger-web dev demo](http://demo.hledger.org:5001) -->
<!-- hoogle search form <!-- hoogle search form
@ -247,7 +262,7 @@ It is a single-executable web application using the
[yesod](http://yesodweb.com) framework. It runs a built-in web server [yesod](http://yesodweb.com) framework. It runs a built-in web server
serving some views of the journal file, reading it at startup and serving some views of the journal file, reading it at startup and
again whenever it changes. It can also append new transactions to the journal file. again whenever it changes. It can also append new transactions to the journal file.
There are two main views, which can be filtered with [[manual#query-arguments|query arguments]]: There are two main views, which can be filtered with [query arguments](manual#query-arguments):
- [/journal](http://demo.hledger.org/journal), showing general journal entries (like `hledger print`) - [/journal](http://demo.hledger.org/journal), showing general journal entries (like `hledger print`)

85
doc/manual.md
View File

@ -1,25 +1,18 @@
<!-- hledger.org and hledger repo versions last synced: 2014/5/1 --> <!-- hledger.org and hledger repo versions last synced: 2014/5/1 -->
* toc
# hledger User Manual # hledger User Manual
This reference manual is for This reference manual is for
hledger 0.23.98 (the latest pre-0.24 HEAD). hledger 0.23.98 (the latest pre-0.24 HEAD).
<!-- [hledger 0.23](http://hackage.haskell.org/package/hledger-0.23) --> <!-- [hledger 0.23](http://hackage.haskell.org/package/hledger-0.23) -->
and [hledger-web 0.23](http://hackage.haskell.org/package/hledger-web-0.23). and [hledger-web 0.23](http://hackage.haskell.org/package/hledger-web-0.23).
<!-- Other versions: [[0.22/manual|0.22 Manual]]. --> <!-- Other versions: [0.22 Manual](0.22/manual). -->
- [[#Introduction]]
- [[#Usage]]
- [[#Data format]]
- [[#Options]]
- [[#Query arguments]]
- [[#Commands]]
- [[#Known limitations]]
- [[#Troubleshooting]]
## Introduction ## Introduction
[[home|hledger]] is a program for tracking money, time, [hledger](/) is a program for tracking money, time,
or any other commodity, using a simple, editable file format and or any other commodity, using a simple, editable file format and
double-entry accounting, inspired by and largely compatible with double-entry accounting, inspired by and largely compatible with
[ledger](http://ledger-cli.org). hledger is Free Software released [ledger](http://ledger-cli.org). hledger is Free Software released
@ -38,16 +31,8 @@ You can use it to, eg:
- track time and report by day/week/month/project - track time and report by day/week/month/project
- get accurate numbers for client billing and tax filing - get accurate numbers for client billing and tax filing
hledger works on linux, mac and windows. People most often build the hledger works on unix, mac and windows.
latest release with cabal-install, like so: See [Download](download.html) for installation help.
$ cabal update
$ cabal install hledger [hledger-web]
...
$ hledger --version
hledger 0.22.1
For more help with this, and other install options, see the [[installing|Installation Guide]].
## Usage ## Usage
@ -56,7 +41,7 @@ Basic usage is:
$ hledger COMMAND [OPTIONS] [ARGS] $ hledger COMMAND [OPTIONS] [ARGS]
Most [commands](#commands) query or operate on a Most [commands](#commands) query or operate on a
[journal file](#the-journal-file), which by default is `.hledger.journal` [journal file](#journal-files), which by default is `.hledger.journal`
in your home directory. You can specify a different file with the `-f` in your home directory. You can specify a different file with the `-f`
option or `LEDGER_FILE` environment variable, or standard input with `-f-`. option or `LEDGER_FILE` environment variable, or standard input with `-f-`.
@ -97,9 +82,9 @@ The journal file contains a number of transaction entries,
each describing a transfer of money (or any commodity) between two or more named accounts, each describing a transfer of money (or any commodity) between two or more named accounts,
in a simple format readable by both hledger and humans. in a simple format readable by both hledger and humans.
hledger's journal format is a compatible subset, [mostly](http://hledger.org/faq#file-format-differences), hledger's journal format is a compatible subset, [mostly](faq.html#file-format-differences),
of [ledger's journal format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format), of [ledger's journal format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format),
so hledger can work with [compatible](FAQ.html#what-are-the-file-format-differences) ledger journal files as well. so hledger can work with [compatible](faq.html#file-format-differences) ledger journal files as well.
It's safe, and encouraged, to run both hledger and ledger on the same journal file, It's safe, and encouraged, to run both hledger and ledger on the same journal file,
eg to validate the results you're getting. eg to validate the results you're getting.
@ -294,7 +279,7 @@ updating. This order dependence does bring an advantage: precise
control over the order of postings and assertions within a day, so you control over the order of postings and assertions within a day, so you
can assert intra-day balances. can assert intra-day balances.
With [[#including-other-files|included files]], things are a little With [included files](#including-other-files), things are a little
more complicated. Including preserves the ordering of postings and more complicated. Including preserves the ordering of postings and
assertions. If you have multiple postings to an account on the same assertions. If you have multiple postings to an account on the same
day, split across different files, and you also want to assert the day, split across different files, and you also want to assert the
@ -386,7 +371,7 @@ starts a transaction comment.
- With the `comment` and `end comment` keywords it is possible to have multiline comments. - With the `comment` and `end comment` keywords it is possible to have multiline comments.
Transaction and posting comments are displayed by [[#print]], can contain [[#tags]] and can be [[#queries|queried]]. Transaction and posting comments are displayed by [print](#print), can contain [tags](#tags) and can be [queried](#queries).
Some examples: Some examples:
@ -413,7 +398,7 @@ Some examples:
#### Tags #### Tags
You can include *tags* (labels), optionally with values, You can include *tags* (labels), optionally with values,
in transaction and posting comments, and then [[manual#query-arguments|query by tag]]. in transaction and posting comments, and then [query by tag](manual#queries).
This is like Ledger's [metadata](http://ledger-cli.org/3.0/doc/ledger3.html#Metadata) This is like Ledger's [metadata](http://ledger-cli.org/3.0/doc/ledger3.html#Metadata)
feature, except hledger's tag values are simple strings. feature, except hledger's tag values are simple strings.
@ -433,7 +418,7 @@ one, and all tags have values except TAG1:
In the journal file, a hledger tag value can contain: text, internal whitespace, or punctuation, but not: commas, newlines, or leading/trailing whitespace (putting quotes around it doesn't work, but probably should). In the journal file, a hledger tag value can contain: text, internal whitespace, or punctuation, but not: commas, newlines, or leading/trailing whitespace (putting quotes around it doesn't work, but probably should).
In [[manual#query-arguments|tag queries]], remember the tag name must match exactly, while the value part is the usual case-insensitive infix regular expression match. In [tag queries](manual#queries), remember the tag name must match exactly, while the value part is the usual case-insensitive infix regular expression match.
#### Directives #### Directives
##### Account aliases ##### Account aliases
@ -456,7 +441,7 @@ You can also specify aliases on the command line:
Journal directive aliases are applied first, then command-line aliases, Journal directive aliases are applied first, then command-line aliases,
and at most one of each will be applied to each account name. and at most one of each will be applied to each account name.
See also [[How to use account aliases]]. See also [How to use account aliases](how-to-use-account-aliases.html).
##### Default commodity ##### Default commodity
@ -466,7 +451,7 @@ The commodity (and the sample amount's display style) will be applied to all sub
(Note this is different from Ledger's default commodity directive.) (Note this is different from Ledger's default commodity directive.)
Also note the directive itself does not influence the commodity's default Also note the directive itself does not influence the commodity's default
[[#amount-display-styles|display style]], but the amount it is [display style](#amount-display-styles), but the amount it is
applied to might. Here's an example: applied to might. Here's an example:
; set £ as the default commodity ; set £ as the default commodity
@ -749,7 +734,7 @@ Examples:
### Reporting interval ### Reporting interval
A reporting interval can be specified so that commands like A reporting interval can be specified so that commands like
[[#register]], [[#balance]] and [[#activity]] will divide their [register](#register), [balance](#balance) and [activity](#activity) will divide their
reports into multiple report periods. The basic intervals can be reports into multiple report periods. The basic intervals can be
selected with one of `-D/--daily`, `-W/--weekly`, `-M/--monthly`, selected with one of `-D/--daily`, `-W/--weekly`, `-M/--monthly`,
`-Q/--quarterly`, or `-Y/--yearly`. More complex intervals may be `-Q/--quarterly`, or `-Y/--yearly`. More complex intervals may be
@ -813,16 +798,16 @@ Examples:
### Depth limiting ### Depth limiting
With the `--depth N` option, commands like [[#account]], [[#balance]] With the `--depth N` option, commands like [account](#account), [balance](#balance)
and [[#register]] will show only the uppermost accounts in the account and [register](#register) will show only the uppermost accounts in the account
tree, down to level N. Use this when you want a summary with less detail. tree, down to level N. Use this when you want a summary with less detail.
## Query arguments ## Queries
Part of hledger's usefulness is being able to report on just a precise subset of your data. Part of hledger's usefulness is being able to report on just a precise subset of your data.
Most commands accept an optional query expression, written as arguments after the command name, Most commands accept an optional query expression, written as arguments after the command name,
to filter the data by date, account name or other criteria. Query expressions are also used to filter the data by date, account name or other criteria. Query expressions are also used
in the [[#web|web ui]]'s search form. in the [web ui](#web)'s search form.
The query syntax is similar to a Google search expression: one or The query syntax is similar to a Google search expression: one or
more space-separated search terms, optional prefixes to match specific more space-separated search terms, optional prefixes to match specific
@ -833,10 +818,10 @@ A query term can be any of the following:
- `acct:REGEX` - same as above - `acct:REGEX` - same as above
- `code:REGEX` - match by transaction code (eg check number) - `code:REGEX` - match by transaction code (eg check number)
- `desc:REGEX` - match transaction descriptions - `desc:REGEX` - match transaction descriptions
- `date:PERIODEXPR` - match dates within the specified [[#period-expressions|period]]. *Actually, full period syntax is [[https://github.com/simonmichael/hledger/issues/141|not yet supported]].* - `date:PERIODEXPR` - match dates within the specified [period](#period-expressions). *Actually, full period syntax is [not yet supported](https://github.com/simonmichael/hledger/issues/141).*
- `date2:PERIODEXPR` - as above, but match secondary dates - `date2:PERIODEXPR` - as above, but match secondary dates
- `tag:NAME[=REGEX]` - match by (exact, case sensitive) [[#tags|tag]] name, and optionally match the tag value by regular expression. Note `tag:` will match a transaction if it or any its postings have the tag, and will match posting if it or its parent transaction has the tag. - `tag:NAME[=REGEX]` - match by (exact, case sensitive) [tag](#tags) name, and optionally match the tag value by regular expression. Note `tag:` will match a transaction if it or any its postings have the tag, and will match posting if it or its parent transaction has the tag.
- `depth:N` - match (or display, depending on command) accounts at or above this [[#depth-limiting|depth]] - `depth:N` - match (or display, depending on command) accounts at or above this [depth](#depth-limiting)
- `status:1` or `status:0` - match cleared/uncleared transactions - `status:1` or `status:0` - match cleared/uncleared transactions
- `real:1` or `real:0` - match real/virtual-ness - `real:1` or `real:0` - match real/virtual-ness
- `empty:1` or `empty:0` - match if amount is/is not zero - `empty:1` or `empty:0` - match if amount is/is not zero
@ -860,7 +845,7 @@ A query term can be any of the following:
hledger query expressions don't support full boolean logic. Instead, multiple query terms hledger query expressions don't support full boolean logic. Instead, multiple query terms
are combined as follows: are combined as follows:
- The [[#print]] command selects transactions which: - The [print](#print) command selects transactions which:
- match any of the description terms AND - match any of the description terms AND
- have any postings matching any of the positive account terms AND - have any postings matching any of the positive account terms AND
- have no postings matching any of the negative account terms AND - have no postings matching any of the negative account terms AND
@ -868,7 +853,7 @@ are combined as follows:
<!-- --> <!-- -->
- Other reporting commands (eg [[#register]] and [[#balance]]) select transactions/postings/accounts which match (or negatively match): - Other reporting commands (eg [register](#register) and [balance](#balance)) select transactions/postings/accounts which match (or negatively match):
- any of the description terms AND - any of the description terms AND
- any of the account terms AND - any of the account terms AND
- all the other terms. - all the other terms.
@ -877,7 +862,7 @@ are combined as follows:
On the command line, some of the query terms above can also be expressed as command-line flags. On the command line, some of the query terms above can also be expressed as command-line flags.
Generally you can mix and match query arguments and flags, and the resulting query will be their intersection. Generally you can mix and match query arguments and flags, and the resulting query will be their intersection.
Remember that a `-p` [[#period-expressions|period]] flag will cause any other `-b`, `-e` or `-p` flags on the command line to be ignored. Remember that a `-p` [period](#period-expressions) flag will cause any other `-b`, `-e` or `-p` flags on the command line to be ignored.
## Commands ## Commands
@ -917,18 +902,18 @@ Additional convenience features:
descriptions, dates (`yesterday`, `today`, `tomorrow`). If the input descriptions, dates (`yesterday`, `today`, `tomorrow`). If the input
area is empty, it will insert the default value. area is empty, it will insert the default value.
- If the journal defines a [[#default-commodity|default commodity]], - If the journal defines a [default commodity](#default-commodity),
it will be added to any bare numbers entered. it will be added to any bare numbers entered.
- A parenthesised transaction [[#entries|code]] may be entered following a date. - A parenthesised transaction [code](#entries) may be entered following a date.
- [[#comments|Comments]] and tags may be entered following a description or amount. - [Comments](#comments) and tags may be entered following a description or amount.
- If you make a mistake, enter `<` at any prompt to restart the transaction. - If you make a mistake, enter `<` at any prompt to restart the transaction.
- Input prompts are displayed in a different colour when the terminal supports it. - Input prompts are displayed in a different colour when the terminal supports it.
Here's [[step-by-step#record-a-transaction-with-hledger-add|an example]]. Here's [an example](step-by-step#record-a-transaction-with-hledger-add).
<!-- <!--
$ hledger add $ hledger add
(...) (...)
@ -1037,7 +1022,7 @@ The balance command displays accounts and their balances.
##### Simple balance reports ##### Simple balance reports
Simple balance reports have no [[#reporting-interval|reporting interval]]. Simple balance reports have no [reporting interval](#reporting-interval).
They show the sum of matched postings in each account. They show the sum of matched postings in each account.
(If postings are not date-restricted, this is usually the same as the ending balance). (If postings are not date-restricted, this is usually the same as the ending balance).
@ -1075,7 +1060,7 @@ This is very useful to summarise complex charts of accounts.
##### Multi balance reports ##### Multi balance reports
With a [[#reporting-interval|reporting interval]], multiple balance With a [reporting interval](#reporting-interval), multiple balance
columns will be shown, one for each report period. columns will be shown, one for each report period.
There are three types of multi-column balance report, showing different information: There are three types of multi-column balance report, showing different information:
@ -1261,7 +1246,7 @@ There are some tricks when specifying options:
Add-ons which are written in haskell can take advantage of hledger's library API Add-ons which are written in haskell can take advantage of hledger's library API
for journal parsing, reports, consistent command-line options etc. for journal parsing, reports, consistent command-line options etc.
One notable add-on is [[#web|hledger-web]], which is maintained along with One notable add-on is [hledger-web](#web), which is maintained along with
hledger and supported on the same major platforms. Other add-ons may hledger and supported on the same major platforms. Other add-ons may
have different release schedules and platform support. have different release schedules and platform support.
@ -1478,13 +1463,13 @@ preceding them. Eg hledger-web's `--server` flag must be used like so:
### -w/--width and --debug options must be written without whitespace ### -w/--width and --debug options must be written without whitespace
Up to hledger 0.23, these optional-value flags [[https://github.com/simonmichael/hledger/issues/149|did not work]] with whitespace between the flag and value. Up to hledger 0.23, these optional-value flags [did not work](https://github.com/simonmichael/hledger/issues/149) with whitespace between the flag and value.
IE these worked: `--debug`, `-w`, `--debug=2`, `-w100`, but these did not: `--debug 2`, `-w 100`. IE these worked: `--debug`, `-w`, `--debug=2`, `-w100`, but these did not: `--debug 2`, `-w 100`.
From 0.24, a value is required and the whitespace does not matter. From 0.24, a value is required and the whitespace does not matter.
### Not all of Ledger's journal file syntax is supported ### Not all of Ledger's journal file syntax is supported
See [[faq#file-format-differences|file format differences]]. See [file format differences](faq#file-format-differences).
### balance is less speedy than Ledger's on large data files ### balance is less speedy than Ledger's on large data files

88
doc/site/download.md
View File

@ -1,31 +1,75 @@
# Download # Download
\\
**I want to download and get started quickly !**\\
<!-- <sub>(If the download is out of date or doesn't run on my system, I might troubleshoot or donate to fund improvements)</sub> -->
| **I'm on Debian or Ubuntu**\\ `apt-get install hledger[-web]` \\ \\ **I'm on Gentoo**\\ `emerge hledger[-web]` <!-- \\ --> <!-- \\ --> <!-- **I'm on another GNU/Linux\\<small>(or can run Linux binaries)</small>**\\ --> <!-- <\\!-- [hledger.linux-32.zip]()\\ -\\-> --> <!-- <\\!-- [hledger-web.linux-32.zip]()\\ -\\-> --> <!-- <\\!-- [hledger.linux-64.zip]()\\ -\\-> --> <!-- <\\!-- [hledger-web.linux-64.zip]()\\ -\\-> --> <!-- Use cabal --> <!-- </td> --> \\ \\ **I'm on Red Hat/Fedora/CentOS**\\ `yum install hledger` \\ \\ **I'm on NixOS**\\ `nix-env -iA nixpkgs.haskellPackages.hledger` | **I'm on Windows**\\ <!-- [windows install guide](windows-install.html)\\ --> 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**\\ <!-- **I'm on Mac OSX 10.9+**\\ --> <!-- [mac install guide](mac-install.html)\\ --> <!-- [hledger.mac.zip]()\\ --> <!-- [hledger-web.mac.zip]()\\ --> 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]`\\ |
<!-- [cabal install guide](cabal-install.html) -->
**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 hledger is shipped as two executables: `hledger` (the command-line
tool) and `hledger-web` (the web interface). If you install tool) and `hledger-web` (the web interface). If you install
`hledger-web`, `hledger` will also be installed automatically (except on Windows). `hledger-web`, `hledger` is also installed automatically (except on Windows).
Building, testing and supporting cross-platform binaries is costly, so ## I want to download and run
<!-- <sub>(If the download is out of date or doesn't run on my system, I might troubleshoot or donate to fund improvements)</sub> -->
<table>
<tr valign="top">
<td width="33%">
**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 another GNU/Linux\<small>(or can run Linux binaries)</small>**
[hledger.linux-32.zip]()
[hledger-web.linux-32.zip]()
[hledger.linux-64.zip]()
[hledger-web.linux-64.zip]()
Use cabal
-->
</td>
<td width="33%">
**I'm on Windows**\
<!-- [windows install guide](windows-install.html)\ -->
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)
</td>
<td width="33%">
**I'm on Mac**\
<!-- [mac install guide](mac-install.html)\ -->
<!-- [hledger.mac.zip]()\ -->
<!-- [hledger-web.mac.zip]()\ -->
Use cabal
</td>
</tr>
</table>
<div style="margin-left:1em; float:right;">
**[Gittip](https://www.gittip.com/simonmichael/)**,
<a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=5J33NLXYXCYAY"><img border=0 src="https://www.paypal.com/en_US/i/btn/x-click-but04.gif" alt="paypal"></a>
</div>
Building, testing and supporting Windows and Mac binaries is costly, so
it's demand-driven - you can indicate demand by making a project 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. 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! 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 }}]] ## 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]`\
<!-- [cabal install guide](cabal-install.html) -->
The [Installation Guide](installing.html) describes how to install using cabal in more detail.
## I want to build the [latest development code](http://hledger.org/code)
`git clone https://github.com/simonmichael/hledger; cd hledger; make sandbox install`

16
doc/site/faq.md
View File

@ -1,3 +1,5 @@
* toc
# Frequently asked questions # Frequently asked questions
## hledger and ledger ## hledger and ledger
@ -35,11 +37,11 @@ can often use both tools on the same data file.
Summary: hledger is a friendly, co-evolving, compatible rewrite of Ledger Summary: hledger is a friendly, co-evolving, compatible rewrite of Ledger
in Haskell, lacking some of ledger's power features and raw performance, in Haskell, lacking some of ledger's power features and raw performance,
and focussing on robustness, usability, ease of development, and and focussing on robustness, usability, ease of development, and
experimental add-ons such as the [web interface](MANUAL.html#web). experimental add-ons such as the [web interface](manual.html#web).
### And ledger 4 ? ### And ledger 4 ?
There is also a [[https://github.com/ledger/ledger4|ledger4]] on github; this is There is also a [ledger4](https://github.com/ledger/ledger4) on github; this is
John's own rewrite of the core of John's own rewrite of the core of
ledger 3 in haskell. It's an early library prototype, not a usable tool. 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. Perhaps some day hledger or something like it would use this as its foundation.
@ -51,10 +53,10 @@ Generally, it's easy to keep a journal file that works with both hledger
and ledger if you avoid ledger's most specialised syntax. and ledger if you avoid ledger's most specialised syntax.
Some ledger syntax is parsed but ignored (such as 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 [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]]). [historical prices](manual.html#historical-prices)).
Some features are not currently parsed and will cause an error, eg Some features are not currently parsed and will cause an error, eg
ledger's more recent top-level directives. There can also be subtle 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]]. differences in parser behaviour, eg [hledger comments](manual.html#comments) vs [ledger comments](http://ledger-cli.org/3.0/doc/ledger3.html#Commenting-on-your-Journal).
### Feature differences ? ### Feature differences ?
@ -191,16 +193,16 @@ entry DATE PAYEE AMT output a derived entry, based on the arguments
- hledger generates a description for timelog sessions, instead of - hledger generates a description for timelog sessions, instead of
taking it from the clock-out entry taking it from the clock-out entry
- hledger's [include directive](MANUAL.html#including-other-files) does not support - hledger's [include directive](manual.html#including-other-files) does not support
shell glob patterns (eg `include *.journal` ), which ledger does. shell glob patterns (eg `include *.journal` ), which ledger does.
- when checking [balance assertions](MANUAL.html#balance-assertions) - when checking [balance assertions](manual.html#balance-assertions)
hledger sorts the account's postings first by date and then (for hledger sorts the account's postings first by date and then (for
postings with the same date) by parse order. ledger goes strictly by postings with the same date) by parse order. ledger goes strictly by
parse order. parse order.
- ledger allows amounts to have a - ledger allows amounts to have a
[fixed lot price](MANUAL.html#prices) and a regular price in any [fixed lot price](manual.html#fixed-lot-prices) and a regular price in any
order (and uses whichever appears first). hledger requires the fixed order (and uses whichever appears first). hledger requires the fixed
lot price to come last (and ignores it). lot price to come last (and ignores it).

4
doc/site/how-to-read-csv-files.md
View File

@ -1,6 +1,6 @@
# How to read CSV files # How to read CSV files
Here's a quick example of [[manual#csv-files|converting a CSV file]]. Here's a quick example of [converting a CSV file](manual.html#csv-files).
Say we have downloaded `checking.csv` from a bank for the first time: Say we have downloaded `checking.csv` from a bank for the first time:
@ -8,7 +8,7 @@ Say we have downloaded `checking.csv` from a bank for the first time:
"2012/3/22","DEPOSIT","50.00" "2012/3/22","DEPOSIT","50.00"
"2012/3/23","TRANSFER TO SAVINGS","-10.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: We tell hledger how to intepret this with a file named `checking.csv.rules`, using the [CSV rules syntax](manual.html#csv-files). Eg:
# skip the first CSV line (headings) # skip the first CSV line (headings)
skip 1 skip 1

2
doc/site/how-to-use-account-aliases.md
View File

@ -1,6 +1,6 @@
# How to use account aliases # How to use account aliases
Here's an example of using [[manual#account-aliases|account aliases]]. Here's an example of using [account aliases](manual.html#account-aliases).
Say a sole proprietor has a `personal.journal`: Say a sole proprietor has a `personal.journal`:

41
doc/site/index.md
View File

@ -4,30 +4,49 @@
hledger is a computer program for easily tracking money, time, or other commodities, hledger is a computer program for easily tracking money, time, or other commodities,
on unix, mac and windows. on unix, mac and windows.
It was inspired by and maintains substantial compatibility with [Ledger](faq.html#hledger-and-ledger).
It is first a command-line tool, but there is also a [web interface](manual.html#web) hledger 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 and a [Haskell library](http://hackage.haskell.org/package/hledger-lib) for
building your own programs and [scripts](more-docs.html#scripting-examples) building your own programs and [scripts](more-docs.html#scripting-examples)
(hledger is written in Haskell). (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 GPLv3+,
hledger is free software available under the GNU General Public License v3+. created by [Simon Michael](http://joyful.com) and [contributors](CONTRIBUTORS.html).
hledger aims to help both computer experts and regular folks Though limited in features, hledger is lightweight, usable and reliable.
For some, it is a simple, flexible, future-proof alternative to Quicken or GnuCash.
It aims to help both computer experts and regular folks
to gain clarity and control in their finances and time management, to gain clarity and control in their finances and time management,
but currently it is a bit more suited to techies. but currently it is a bit more suited to techies.
I use it every day to: I've been using (and improving) it since 2007 to:
- track spending and income - track spending and income
- see time reports by day/week/month/project - see time reports by day/week/month/project
- get accurate numbers for client billing and tax filing - get accurate numbers for client billing and tax filing
- track invoices - track invoices
Though limited in features, hledger is lightweight, usable and reliable. To get started, you could
For some, it is a simpler, less distracting, more future-proof alternative to Quicken or GnuCash. **[download](download.html)**,
To get started, see the navigation links. read the **[tutorial](step-by-step.html)**,
or **[join the IRC channel](http://hledger.org/irc)** and ask questions.
<!-- <style> -->
<!-- tr { -->
<!-- /*vertical-align:top;*/ -->
<!-- border-top:thin solid #bbb; -->
<!-- } -->
<!-- </style> -->
|-------------------------|----------------------------------------------------------------------------|
| IRC | [#hledger](http://hledger.org/irc) (see also [#ledger](http://webchat.freenode.net?channels=ledger&randomnick=1)) |
| Mail list&nbsp;&nbsp; | [hledger.org/list](http://hledger.org/list) |
| Twitter | [#ledgercli](https://twitter.com/search?q=%23ledgercli&src=typd&f=realtime), <a href="https://twitter.com/ledgertips">@LedgerTips</a> |
<!-- | web UI demo | [demo.hledger.org](http://demo.hledger.org) | -->
<!-- [web ui demo](http://demo.hledger.org/register?q=inacct%3Aassets%3Abank%3Achecking+sym%3A\%24) -->
<div style="margin-top:2em; text-align:right; float:right;">
<!-- Has hledger saved you or your employer money, time or peace of mind ? --> <!-- Has hledger saved you or your employer money, time or peace of mind ? -->
<!-- Donations: --> <!-- Donations: -->
<!-- **[Gittip](https://www.gittip.com/simonmichael/)**, --> **[Gittip](https://www.gittip.com/simonmichael/)**,
<!-- [https://www.paypal.com/en_US/i/btn/x-click-but04.gif](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=5J33NLXYXCYAY) --> <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=5J33NLXYXCYAY"><img border=0 src="https://www.paypal.com/en_US/i/btn/x-click-but04.gif" alt="paypal"></a>
<!-- Also testimonials, examples, blogging, packaging, and patches. --> <!-- Also testimonials, examples, blogging, packaging, and patches. -->
</div>

2
doc/site/installing.md
View File

@ -1,3 +1,5 @@
* toc
# Installation Guide # Installation Guide
- [[#How to install]] - [[#How to install]]

32
doc/site/more-docs.md
View File

@ -1,11 +1,13 @@
* toc
# More docs... # More docs...
[[old screenshots|Screenshots]] (old) [Screenshots](old-screenshots.html) (old)
## How-tos ## How-tos
- [[How to read CSV files]] - [How to read CSV files](how-to-read-csv-files.html)
- [[How to use account aliases]] - [How to use account aliases](how-to-use-account-aliases.html)
## Blog posts & articles ## Blog posts & articles
@ -41,16 +43,16 @@ Here are some good intros, which also serve as a good orientation for hledger:
See also the two Twitter feeds: See also the two Twitter feeds:
- [@LedgerTips](https://twitter.com/LedgerTips) Tips and tricks for Ledger, hledger, beancount, etc. - <a href="https://twitter.com/LedgerTips">@LedgerTips</a> 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 - [#ledgercli](https://twitter.com/search?q=%23ledgercli&src=typd&f=realtime) Search for latest mentions of the `#ledgercli` hash tag
## Accounting ## Accounting
- -
[[wp>Accountancy]], [Accounting](http://en.wikipedia.org/wiki/Accounting),
[[wp>Bookkeeping]], [Bookkeeping](http://en.wikipedia.org/wiki/Bookkeeping),
[[wp>Double-entry bookkeeping system]], [Double-entry bookkeeping system](http://en.wikipedia.org/wiki/Double_entry_bookkeeping_system),
[[wp>General journal]] [General journal](http://en.wikipedia.org/wiki/General_journal)
etc. at Wikipedia etc. at Wikipedia
- [Accounting For Dragons](http://podcastle.org/2009/10/09/pc-miniature-38-accounting-for-dragons) why you should know accounting - [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 - [Bean Counter](http://www.dwmbeancounter.com/) - tutorials, such as
@ -77,20 +79,20 @@ See also the two Twitter feeds:
- [hledger-interest](http://hackage.haskell.org/package/hledger-interest) generates various kinds of interest transaction - [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) - [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 - [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-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) - [hledger-vty](http://hackage.haskell.org/package/hledger-vty) a simple curses-style UI (unmaintained)
- More in [[code>extra/]] - More in [extra/](https://github.com/simonmichael/hledger/tree/master/extra/)
## Scripting examples ## Scripting examples
- https://gist.github.com/4172604 printing average expenses by month - <https://gist.github.com/4172604> printing average expenses by month
- https://gist.github.com/4210558 calculating historical account balances - <https://gist.github.com/4210558> calculating historical account balances
- More in [[code>extra/]] - More in [extra/](https://github.com/simonmichael/hledger/tree/master/extra/)
## Similar projects ## Similar projects
In addition to hledger and Ledger, there are other [[ledgerwiki>Ports|Ledger ports]] and Ledger-likes, incompatible but similar in concept: In addition to hledger and Ledger, there are other [Ledger ports](ledgerwiki>Ports) and Ledger-likes, incompatible but similar in concept:
- Martin Blais' [beancount](https://furius.ca/beancount/) (python) - Martin Blais' [beancount](https://furius.ca/beancount/) (python)
- Harshad RJ's [Abandon](https://github.com/hrj/abandon) (scala) - Harshad RJ's [Abandon](https://github.com/hrj/abandon) (scala)
@ -104,5 +106,5 @@ Other things of interest:
- [debts](http://darcsden.com/ozamosi/debts) - small debt tracking web 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 - [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/) - [You Need A Budget](http://www.youneedabudget.com/)
- Software Freedom Conservancy's [[http://npoacct.sfconservancy.org|npo-acct]] project - Software Freedom Conservancy's [npo-acct](http://npoacct.sfconservancy.org) project

18
doc/site/old-screenshots.md
View File

@ -6,32 +6,32 @@
Showing the journal format, a register report, and a balance report: 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}} ![Basic command-line reports, like ledger](http://hledger.org/images/hledger-screen-1.png)
## Time dashboard in emacs ## 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. 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.}} ![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)
## Pie charts (hledger-chart) ## 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. Viewing a year of monthly expense charts in emacs. These were generated by hledger 0.10 with -fchart, which became [hledger-chart](http://hackage.haskell.org/package/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).}} ![Viewing a year of monthly expense charts in emacs (hledger 0.10 with -fchart).](http://hledger.org/images/hledger-charts-2.png)
## Curses-style interface (hledger-vty) ## Curses-style interface (hledger-vty)
[[http://hackage.haskell.org/package/hledger-vty|hledger-vty]], currently unmaintained. [hledger-vty](http://hackage.haskell.org/package/hledger-vty), currently unmaintained.
{{http://hledger.org/images/sshot.png|The vty (curses-style) interface}} ![The vty (curses-style) interface](http://hledger.org/images/sshot.png)
## Web interface (hledger-web) ## 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]]. This minimal web interface was hledger 0.11pre with -fwebyesod, which became [hledger-web](http://hackage.haskell.org/package/hledger-web).
Here's the [[http://demo.hledger.org|latest interface]]. Here's the [latest interface](http://demo.hledger.org).
{{http://hledger.org/images/hledger-web-journal.png|The web interface (hledger 0.11pre with -fwebyesod).}} ![The web interface (hledger 0.11pre with -fwebyesod).](http://hledger.org/images/hledger-web-journal.png)
<!-- <!--

14
doc/site/release-notes.md
View File

@ -1,3 +1,5 @@
* toc
# Release notes # Release notes
Based on the Based on the
@ -189,7 +191,7 @@ Improved:
**New:** **New:**
- balance: with a reporting interval (monthly, yearly etc.), the - balance: with a reporting interval (monthly, yearly etc.), the
[balance command](MANUAL.html#balance) will now show a multi-column report, showing either [balance command](manual.html#balance) will now show a multi-column report, showing either
the per-period changes in balance (by default), the per-period changes in balance (by default),
the period ending balances starting from zero (`--cumulative`), the period ending balances starting from zero (`--cumulative`),
or the actual period ending balances (`--historical`). or the actual period ending balances (`--historical`).
@ -314,7 +316,7 @@ Marko Kocić, Max Bolingbroke, and a big welcome to first-time committer John Wi
**CSV reading:** **CSV reading:**
- CSV conversion rules have a simpler, more flexible [syntax](MANUAL.html#csv-files). - CSV conversion rules have a simpler, more flexible [syntax](manual.html#csv-files).
Existing rules files will need to be updated manually: Existing rules files will need to be updated manually:
- the filename is now `FILE.csv.rules` instead of `FILE.rules` - 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) - `FIELD-field N` is now `FIELD %N+1` (or set them all at once with a `fields` rule)
@ -452,11 +454,11 @@ Marko Kocić, Max Bolingbroke, and a big welcome to first-time committer John Wi
## 2012/5/29 hledger 0.18 ## 2012/5/29 hledger 0.18
* web: hledger-web is now based on yesod 1.0 * 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: fix js error breaking second use of add form ([#72](http://bugs.hledger.org/72))
* web: make `yesod devel` work * web: make `yesod devel` work
* the command-line now supports a more powerful [query language](MANUAL.html#queries), consistent with the web UI * 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 * 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) * new [commands](manual.html#incomestatement) `incomestatement`, `balancesheet`, and `cashflow` provide basic financial statements under certain conditions
* format conversion is now done on demand, and the convert command has been dropped. So instead of * 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. `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. You can also pipe any supported format into `hledger -f- CMD` and hledger will try to do the right thing.

93
doc/site/step-by-step.md
View File

@ -1,51 +1,41 @@
# hledger Step by Step (draft) * toc
*(c) Simon Michael, 2014* # hledger step by step
Welcome! Here you can learn hledger (and a little double-entry Here you can learn hledger (and a little double-entry accounting) by
accounting) by practicing, one hands-on exercise at a time, in the practicing, one hands-on exercise at a time (similar to the
style of the "Learn X the Hard Way" books. Exercises are grouped into "Learn X the Hard Way" books.)
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. 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 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), If you get stuck, or have any other feedback, report it on IRC or the mail list, or send a pull request for this page.
or right on this page (click the pencil on the right).
You'll need: You'll need:
1. hledger, installed using the [[installing|Installation Guide]]. These exercises were last tested with: hledger 0.23dev-20140212. 1. A basic understanding of the command line, text file editing, and regular expressions. Or, the ability to ask for help on the IRC channel.
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. 2. hledger (see [Download](download.html)). These exercises were last tested with: hledger 0.23dev-20140212.
--- ## SETUP
## 0. SETUP
---
### Check your hledger ### Check your hledger
Get a command prompt, and run hledger to check the version. It should be reasonably [[release-notes|up to date]].: Get a command prompt, and run hledger to check the version. It should be reasonably [up to date](release-notes.html):
``` ```
$ hledger --version $ hledger --version
hledger 0.23 hledger 0.23
``` ```
--- ## BASIC DATA ENTRY & REPORTING
## 1. BASIC DATA ENTRY & REPORTING
---
### Locate your journal file with "hledger stats" ### Locate your journal file with "hledger stats"
hledger reads financial transactions from a "journal file" (so named because it represents a [[wp>General Journal]]). hledger reads financial transactions from a "journal file" (so named because it represents a [General Journal](http://en.wikipedia.org/wiki/General_Journal)).
The default journal file is in your home directory; check its path using the [[manual#stats|stats]] command. The default journal file is in your home directory; check its path using the [stats](manual.html#stats) command.
You should see something like: You should see something like:
``` ```
$ hledger stats $ hledger stats
@ -58,10 +48,9 @@ Most hledger commands read this file but can not change it; the `add` and `web`
(If `stats` reports that the file exists, eg because you previously created it, move it out of the way temporarily for these exercises.) (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" ### Record a transaction with "hledger add"
Follow the help and use the [[manual#add|add]] command to record your first transaction, Follow the help and use the [add](manual.html#add) command to record your first transaction,
an imaginary purchase at the supermarket. an imaginary purchase at the supermarket.
We'll go through this in detail. Later you'll learn other ways to enter data. We'll go through this in detail. Later you'll learn other ways to enter data.
@ -176,10 +165,9 @@ Accounts : 2 (depth 1)
Commodities : 1 ($) Commodities : 1 ($)
``` ```
---
### Show transactions with "hledger print" ### Show transactions with "hledger print"
The [[manual#print|print]] command shows a tidied-up view of the transaction entries in your journal. The [print](manual.html#print) command shows a tidied-up view of the transaction entries in your journal.
Since there's just one so far, you should see: Since there's just one so far, you should see:
``` ```
@ -189,7 +177,6 @@ $ hledger print
assets $-10 assets $-10
``` ```
---
### Examine your journal file ### Examine your journal file
List and print the journal file (on Windows, use `dir` and `type` and the file path from `hledger stats`): List and print the journal file (on Windows, use `dir` and `type` and the file path from `hledger stats`):
@ -204,7 +191,6 @@ $ cat ~/.hledger.journal
assets assets
``` ```
---
### A convenience: inferred amounts ### A convenience: inferred amounts
Why is the amount missing from the assets posting above ? Why is the amount missing from the assets posting above ?
@ -214,7 +200,6 @@ For consistency, `add` uses the same convention when it writes an entry.
(But `print` shows the inferred amount, for clarity.) (But `print` shows the inferred amount, for clarity.)
Only one missing amount is allowed in each transaction. Only one missing amount is allowed in each transaction.
---
### Edit the journal file ### Edit the journal file
Since the journal file is plain text, you can edit it directly with any text editor. Since the journal file is plain text, you can edit it directly with any text editor.
@ -245,7 +230,6 @@ hledger: could not balance this transaction (can't have more than one missing am
All hledger commands expect the journal to be well-formed, and will report an error and exit otherwise. All hledger commands expect the journal to be well-formed, and will report an error and exit otherwise.
---
### Two spaces ### Two spaces
Notice the last part of that error message: "`... remember to put 2 or more spaces before amounts)`". Notice the last part of that error message: "`... remember to put 2 or more spaces before amounts)`".
@ -262,7 +246,6 @@ Since account names may contain spaces, hledger thinks the first
posting is to an account named "`expenses $10`", with a missing posting is to an account named "`expenses $10`", with a missing
amount. So remember: two or more spaces. amount. So remember: two or more spaces.
---
### Unbalanced transactions ### Unbalanced transactions
Edit the file to look like this: Edit the file to look like this:
@ -289,7 +272,6 @@ That makes sense. (It calls them "real" postings because there are some other ki
Correct the mistake by adding the minus sign, or just removing the assets amount entirely, and verify Correct the mistake by adding the minus sign, or just removing the assets amount entirely, and verify
that `print` works again. that `print` works again.
---
### Record a transaction by editing ### Record a transaction by editing
Edit the file again and manually add a second purchase transaction. Edit the file again and manually add a second purchase transaction.
@ -321,10 +303,9 @@ $ hledger print
``` ```
---
### Show postings and a running total with "hledger register" ### 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. The [register](manual.html#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. 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: Run `register` and compare with the output of `print` above. You should see:
@ -341,7 +322,6 @@ The transaction's date and description is displayed only for the first posting i
Next we see the posted account's name and the amount posted. Next we see the posted account's name and the amount posted.
The final column is a running total of the posted amounts. The final column is a running total of the posted amounts.
---
### Show a per-account register report ### Show a per-account register report
Notice how the running total above keeps resetting to 0. Notice how the running total above keeps resetting to 0.
@ -368,11 +348,10 @@ $ hledger register assets
2014/02/13 forgot the bread assets $-5 $-15 2014/02/13 forgot the bread assets $-5 $-15
``` ```
---
### Query expressions ### Query expressions
The account name argument above is an example of a 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. [query expression](manual.html#queries), a search pattern which restricts a report to a subset of the data.
In this way you can make very precise queries. 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. Note that it is a case-insensitive regular expression which matches anywhere inside the account name.
@ -406,10 +385,9 @@ $ hledger register date:2014/2/13- 'es$'
Note how the account-matching pattern `es$` needs to be quoted here, 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. because it contains the regular expression metacharacter `$` which would otherwise be interpreted by the unix shell.
---
### Show accounts and their balances with "hledger balance" ### Show accounts and their balances with "hledger balance"
The third of hledger's three core reporting commands is [[manual#balance|balance]]. The third of hledger's three core reporting commands is [balance](manual.html#balance).
Use it to list all the accounts posted to, and their ending 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: You should see account balances agreeing with the final running total in the register reports above:
@ -430,7 +408,6 @@ $ hledger balance assets
$-15 $-15
``` ```
---
### balance shows the sum of matched posting amounts ### balance shows the sum of matched posting amounts
Here's a balance report based only on the postings dated 2013/2/13: Here's a balance report based only on the postings dated 2013/2/13:
@ -453,8 +430,6 @@ $ hledger register date:2014/2/13
assets $-5 0 assets $-5 0
``` ```
---
### Review ### Review
You have learned: You have learned:
@ -479,8 +454,6 @@ You have learned:
- how to list accounts and their current balance, or the sum of their postings in some period, with `hledger balance` - how to list accounts and their current balance, or the sum of their postings in some period, with `hledger balance`
---
<!-- <!--
### Test yourself ### Test yourself
@ -502,14 +475,11 @@ You don't need to categorise, you don't need to track anything other than the am
Can you complete this challenge ? Keep at it! :) Can you complete this challenge ? Keep at it! :)
I couldn't do this when I started using hledger, but I can now. Build that muscle. I couldn't do this when I started using hledger, but I can now. Build that muscle.
---
--> -->
## 2. USEFUL ACCOUNTING CONCEPTS ## USEFUL ACCOUNTING CONCEPTS
---
### Assets, Liabilities and Equity ### 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: Accounting describes the status of a business, person or other entity at any point in time in terms of three amounts:
@ -518,7 +488,7 @@ Accounting describes the status of a business, person or other entity at any poi
- **Liabilities** - Things owed - **Liabilities** - Things owed
- **Equity** - The amount invested by owners/shareholders - **Equity** - The amount invested by owners/shareholders
The foundation of double-entry accounting is the [[wp>accounting equation]], which says The foundation of double-entry accounting is the [accounting equation](http://en.wikipedia.org/wiki/accounting_equation), which says
that Equity is always equal to Assets minus Liabilities (or, Net Assets). that Equity is always equal to Assets minus Liabilities (or, Net Assets).
This is also written as: Assets = Liabilities + Equity. This is also written as: Assets = Liabilities + Equity.
@ -526,7 +496,6 @@ Another way to say it: what the entity owns is funded either by debt or by the c
These three are called the Balance Sheet accounts. Their balances summarise the overall financial status at some point in time. These three are called the Balance Sheet accounts. Their balances summarise the overall financial status at some point in time.
---
### Revenue and Expenses ### Revenue and Expenses
@ -544,7 +513,6 @@ accumulate during some period of time indicate the inflows and
outflows during that period (which will affect the Assets and outflows during that period (which will affect the Assets and
Liabilities balances). Liabilities balances).
---
### Chart of Accounts ### Chart of Accounts
@ -584,14 +552,17 @@ In some organisations and accounting systems (eg, QuickBooks), the
tree structure is de-emphasised, so the above is represented more tree structure is de-emphasised, so the above is represented more
like: like:
^ Account name ^ Account type ^ ```
| checking | ASSET | Account name Account type
| cash | ASSET | -------------------------------
| business income | REVENUE | checking ASSET
| gifts received | REVENUE | cash ASSET
| food | EXPENSE | business income REVENUE
| rent | EXPENSE | gifts received REVENUE
| supplies | EXPENSE | food EXPENSE
rent EXPENSE
supplies EXPENSE
```
In others, the tree structure is encoded as decimal account numbers, something like this: In others, the tree structure is encoded as decimal account numbers, something like this:
@ -610,7 +581,6 @@ In others, the tree structure is encoded as decimal account numbers, something l
5300 supplies 5300 supplies
``` ```
---
### Subaccounts in hledger ### Subaccounts in hledger
With hledger, tree structure is implied by writing account names like `ACCOUNT:SUBACCOUNT`. With hledger, tree structure is implied by writing account names like `ACCOUNT:SUBACCOUNT`.
@ -679,7 +649,6 @@ $ hledger balance --depth 1
``` ```
---