From 7ca806c5b06a591ff4ed68d596de7c30944b4638 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Mon, 10 Nov 2014 13:38:05 -0800 Subject: [PATCH] site: content updates for the hakyll/pandoc site --- doc/developer-guide.md | 35 +++++++--- doc/manual.md | 85 ++++++++++------------- doc/site/download.md | 88 ++++++++++++++++++------ doc/site/faq.md | 18 ++--- doc/site/how-to-read-csv-files.md | 4 +- doc/site/how-to-use-account-aliases.md | 2 +- doc/site/index.md | 55 ++++++++++----- doc/site/installing.md | 2 + doc/site/more-docs.md | 32 ++++----- doc/site/old-screenshots.md | 18 ++--- doc/site/release-notes.md | 14 ++-- doc/site/step-by-step.md | 93 +++++++++----------------- 12 files changed, 243 insertions(+), 203 deletions(-) diff --git a/doc/developer-guide.md b/doc/developer-guide.md index ae032d5ec..f664782ee 100644 --- a/doc/developer-guide.md +++ b/doc/developer-guide.md @@ -1,17 +1,32 @@ +* toc + # Developer guide ## Quick links -^ hledger.org: ^ [[release notes|combined release notes]], [[download|pre-compiled binaries]] ^ -^ 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) ^ -^ 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) ^ -^ 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) ^ -^ 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) ^ -^ 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) ^ + + + +|-------------------------|----------------------------------------------------------------------------| +| IRC | Join [#hledger](http://hledger.org/irc) (see also [#ledger](http://webchat.freenode.net?channels=ledger&randomnick=1)) | +| Mail list | | +| Twitter | [#ledgercli](https://twitter.com/search?q=%23ledgercli&src=typd&f=realtime), @LedgerTips | +| 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)
[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) | +| 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) | +| 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) | +| 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) | +| 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) | - + +* toc + # hledger User Manual This reference manual is for hledger 0.23.98 (the latest pre-0.24 HEAD). and [hledger-web 0.23](http://hackage.haskell.org/package/hledger-web-0.23). - - -- [[#Introduction]] -- [[#Usage]] -- [[#Data format]] -- [[#Options]] -- [[#Query arguments]] -- [[#Commands]] -- [[#Known limitations]] -- [[#Troubleshooting]] + ## 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 double-entry accounting, inspired by and largely compatible with [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 - get accurate numbers for client billing and tax filing -hledger works on linux, mac and windows. People most often build the -latest release with cabal-install, like so: - - $ cabal update - $ cabal install hledger [hledger-web] - ... - $ hledger --version - hledger 0.22.1 - -For more help with this, and other install options, see the [[installing|Installation Guide]]. +hledger works on unix, mac and windows. +See [Download](download.html) for installation help. ## Usage @@ -56,7 +41,7 @@ Basic usage is: $ hledger COMMAND [OPTIONS] [ARGS] 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` 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, 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), -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, 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 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 assertions. If you have multiple postings to an account on the same 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. -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: @@ -413,7 +398,7 @@ Some examples: #### Tags 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) 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 [[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 ##### 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, 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 @@ -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.) 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: ; set £ as the default commodity @@ -749,7 +734,7 @@ Examples: ### Reporting interval 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 selected with one of `-D/--daily`, `-W/--weekly`, `-M/--monthly`, `-Q/--quarterly`, or `-Y/--yearly`. More complex intervals may be @@ -813,16 +798,16 @@ Examples: ### Depth limiting -With the `--depth N` option, commands like [[#account]], [[#balance]] -and [[#register]] will show only the uppermost accounts in the account +With the `--depth N` option, commands like [account](#account), [balance](#balance) +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. -## Query arguments +## Queries 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, 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 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 - `code:REGEX` - match by transaction code (eg check number) - `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 -- `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. -- `depth:N` - match (or display, depending on command) accounts at or above this [[#depth-limiting|depth]] +- `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](#depth-limiting) - `status:1` or `status:0` - match cleared/uncleared transactions - `real:1` or `real:0` - match real/virtual-ness - `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 are combined as follows: -- The [[#print]] command selects transactions which: +- The [print](#print) command selects transactions which: - match any of the description terms AND - have any postings matching any of the positive 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 account terms AND - 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. 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 @@ -917,18 +902,18 @@ Additional convenience features: descriptions, dates (`yesterday`, `today`, `tomorrow`). If the input 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. -- 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. - 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). -| **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). +`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 + + + + + + + + +
+**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 + +
+ +
+**[Gittip](https://www.gittip.com/simonmichael/)**, +paypal +
+Building, testing and supporting Windows and Mac 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 }}]] +## 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]`\ + + +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` + diff --git a/doc/site/faq.md b/doc/site/faq.md index 78ed96cf7..a11745f2a 100644 --- a/doc/site/faq.md +++ b/doc/site/faq.md @@ -1,3 +1,5 @@ +* toc + # Frequently asked questions ## 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 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). +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 +There is also a [ledger4](https://github.com/ledger/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. @@ -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. 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]]). +[historical prices](manual.html#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]]. +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 ? @@ -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 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. -- 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 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 + [fixed lot price](manual.html#fixed-lot-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). @@ -212,4 +214,4 @@ 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 +cases. diff --git a/doc/site/how-to-read-csv-files.md b/doc/site/how-to-read-csv-files.md index d608cc3fe..fa7271a1f 100644 --- a/doc/site/how-to-read-csv-files.md +++ b/doc/site/how-to-read-csv-files.md @@ -1,6 +1,6 @@ # 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: @@ -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/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 1 diff --git a/doc/site/how-to-use-account-aliases.md b/doc/site/how-to-use-account-aliases.md index b6ec0c915..4ccdd12f1 100644 --- a/doc/site/how-to-use-account-aliases.md +++ b/doc/site/how-to-use-account-aliases.md @@ -1,6 +1,6 @@ # 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`: diff --git a/doc/site/index.md b/doc/site/index.md index 4675e5b42..d23ff193e 100644 --- a/doc/site/index.md +++ b/doc/site/index.md @@ -4,30 +4,49 @@ 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) +It was inspired by and maintains substantial compatibility with [Ledger](faq.html#hledger-and-ledger). +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 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 +hledger is free software, available under the GNU GPLv3+, +created by [Simon Michael](http://joyful.com) and [contributors](CONTRIBUTORS.html). 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. +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, +but currently it is a bit more suited to techies. +I've been using (and improving) it since 2007 to: +- track spending and income +- see time reports by day/week/month/project +- get accurate numbers for client billing and tax filing +- track invoices + +To get started, you could +**[download](download.html)**, +read the **[tutorial](step-by-step.html)**, +or **[join the IRC channel](http://hledger.org/irc)** and ask questions. + + + + + + + +|-------------------------|----------------------------------------------------------------------------| +| IRC | [#hledger](http://hledger.org/irc) (see also [#ledger](http://webchat.freenode.net?channels=ledger&randomnick=1)) | +| Mail list   | [hledger.org/list](http://hledger.org/list) | +| Twitter | [#ledgercli](https://twitter.com/search?q=%23ledgercli&src=typd&f=realtime), @LedgerTips | + + + + +
- - +**[Gittip](https://www.gittip.com/simonmichael/)**, +paypal +
diff --git a/doc/site/installing.md b/doc/site/installing.md index 927a54dda..8f651be85 100644 --- a/doc/site/installing.md +++ b/doc/site/installing.md @@ -1,3 +1,5 @@ +* toc + # Installation Guide - [[#How to install]] diff --git a/doc/site/more-docs.md b/doc/site/more-docs.md index a05b89504..f426c7403 100644 --- a/doc/site/more-docs.md +++ b/doc/site/more-docs.md @@ -1,11 +1,13 @@ +* toc + # More docs... -[[old screenshots|Screenshots]] (old) +[Screenshots](old-screenshots.html) (old) ## How-tos -- [[How to read CSV files]] -- [[How to use account aliases]] +- [How to read CSV files](how-to-read-csv-files.html) +- [How to use account aliases](how-to-use-account-aliases.html) ## 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: -- [@LedgerTips](https://twitter.com/LedgerTips) Tips and tricks for Ledger, hledger, beancount, etc. +- @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]] + [Accounting](http://en.wikipedia.org/wiki/Accounting), + [Bookkeeping](http://en.wikipedia.org/wiki/Bookkeeping), + [Double-entry bookkeeping system](http://en.wikipedia.org/wiki/Double_entry_bookkeeping_system), + [General journal](http://en.wikipedia.org/wiki/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 @@ -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-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-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 -- https://gist.github.com/4172604 printing average expenses by month -- https://gist.github.com/4210558 calculating historical account balances -- More in [[code>extra/]] +- printing average expenses by month +- calculating historical account balances +- More in [extra/](https://github.com/simonmichael/hledger/tree/master/extra/) ## 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) - 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 - [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 +- Software Freedom Conservancy's [npo-acct](http://npoacct.sfconservancy.org) project diff --git a/doc/site/old-screenshots.md b/doc/site/old-screenshots.md index 2a6d0d946..e7f6fe207 100644 --- a/doc/site/old-screenshots.md +++ b/doc/site/old-screenshots.md @@ -6,32 +6,32 @@ 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 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) -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) -[[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) -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]]. +This minimal web interface was hledger 0.11pre with -fwebyesod, which became [hledger-web](http://hackage.haskell.org/package/hledger-web). +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) -## 2. USEFUL ACCOUNTING CONCEPTS +## 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: @@ -518,7 +488,7 @@ Accounting describes the status of a business, person or other entity at any poi - **Liabilities** - Things owed - **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). 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. ---- ### 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 Liabilities balances). ---- ### 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 like: -^ Account name ^ Account type ^ -| checking | ASSET | -| cash | ASSET | -| business income | REVENUE | -| gifts received | REVENUE | -| food | EXPENSE | -| rent | EXPENSE | -| supplies | EXPENSE | +``` + 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: @@ -610,7 +581,6 @@ In others, the tree structure is encoded as decimal account numbers, something l 5300 supplies ``` ---- ### Subaccounts in hledger With hledger, tree structure is implied by writing account names like `ACCOUNT:SUBACCOUNT`. @@ -679,7 +649,6 @@ $ hledger balance --depth 1 ``` ----