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

docs, site: streamline things, start a faq

Browse Source
This commit is contained in:
Simon Michael 2010-11-18 20:01:17 +00:00
parent 442a40d8ee
commit a0584e0e56
4 changed files with 165 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
DEVELOPMENT.rst
View File

@ -55,7 +55,7 @@ hledger is free software by `Simon Michael`_ & `co.`_, released under GNU GPLv3.
**Related projects** **Related projects**
- John Wiegley's ledger_ inspired hledger, and we try to stay compatible. You can often use both tools on the same journal file. - John Wiegley's ledger_ inspired hledger.
- Uwe Hollerbach's umm_ is another haskell tool inspired by h/ledger. - Uwe Hollerbach's umm_ is another haskell tool inspired by h/ledger.
- Tim Docker's ledger-reports_ uses hledger as a library to generate `html reports`_. - Tim Docker's ledger-reports_ uses hledger as a library to generate `html reports`_.
- I have a few older bits and pieces `here <http://joyful.com/Ledger>`_. - I have a few older bits and pieces `here <http://joyful.com/Ledger>`_.

17
DOWNLOAD.markdown
View File

@ -15,10 +15,14 @@ title: hledger downloads
} }
</style> </style>
Here are hledger binaries which might just work on your computer. Here are hledger binaries which should "just work" on your computer. For
Or, you could try <a href="http://hledger.org/MANUAL.html#installing">installing with cabal</a>. more help and alternatives, please see the <a
Please report any trouble (or success!) to <a href="http://hledger.org/DEVELOPMENT.html#support">Support</a>. href="../MANUAL.html#installing">installing doc</a>.
Errata: these binaries lack support files for the web interface, you must copy
[those files](http://joyful.com/repos/hledger/hledger-web/data/static/) to
`./data/web/static/` below the directory where you run hledger.
<table id="platformdocs"> <table id="platformdocs">
<tr> <tr>
<th><img src="../linux.png" /><br />GNU/Linux (x86)</th> <th><img src="../linux.png" /><br />GNU/Linux (x86)</th>
@ -33,8 +37,8 @@ Download the
Open a terminal window and go to your browser's download directory, then: Open a terminal window and go to your browser's download directory, then:
`$ gunzip hledger-*86*` `$ gunzip hledger-*86*`
`$ mv hledger-*86* hledger` `$ mv hledger-*86* hledger`
`$ chmod +x hledger` `$ chmod +x hledger`
`$ ./hledger` `$ ./hledger`
</td> </td>
<td> <td>
@ -64,6 +68,3 @@ may access your hledger web interface.
</tr> </tr>
</table> </table>
Errata:
- these binaries lack support files for the web interface, you must copy [them](http://joyful.com/repos/hledger/hledger-web/data/static/) to `./data/web/static/`

285
MANUAL.markdown
View File

@ -4,72 +4,64 @@ title: hledger manual
# hledger manual # hledger manual
This is the official hledger manual, for version 0.12.98. You may also ## About
want to visit the rest of [hledger.org](http://hledger.org), and for
background,
[c++ ledger's manual](http://joyful.com/repos/ledger/doc/ledger.html).
## User Guide
### Introduction
hledger is a program for tracking money, time, or any other commodity, hledger is a program for tracking money, time, or any other commodity,
using a plain text file format and the simple but powerful principles of using a directly editable file format and the simple but powerful
double-entry accounting. principles of double-entry accounting. It was inspired by [ledger](#faq).
It is modelled closely on hledger's basic function is to read a plain text file describing (eg)
[John Wiegley's ledger](http://wiki.github.com/jwiegley/ledger) (aka "c++ financial transactions, and quickly generate useful reports via the
ledger"), with some features removed and some new ones added. I wrote command line. It can also help you record transactions, or (via add-ons)
hledger because I wanted to build financial tools in the Haskell provide a local web interface for editing, or publish live financial data
programming language rather than in C++. on the web.
hledger's basic function is to generate register and balance reports from You can use it to, eg:
a plain text general journal file, at the command line or via the web or
curses interface. You can use it to, eg,
- track spending and income - track spending and income
- see time reports by day/week/month/project - track unpaid or due invoices
- 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
- track invoices
hledger aims to help both computer experts and every-day users gain hledger aims to help both computer experts and regular folks gain clarity
clarity in their finances and time management. For now though, it is most in their finances. For the moment, it may be a little more suited to
useful to technically-minded folks who are comfortable with command-line techies. Please give it a try and let me know how we're doing.
tools.
hledger is copyright (c) 2007-2009 Simon Michael hledger is copyright (c) 2007-2010
<[simon@joyful.com](mailto:simon@joyful.com)\> and contributors and [Simon&nbsp;Michael&nbsp;<simon@joyful.com>](mailto:simon@joyful.com) and
released as Free Software under GPL version 3 or later. contributors, and released as Free Software under GPL version 3 or later.
### Installing This is the manual for hledger 0.12.98.
hledger works on all major platforms. Here are the [release ## Installing
notes](http://hledger.org/NEWS.html), and pre-built
[binaries](http://hledger.org/binaries/) you should be able to
download and run. If not, or if you prefer an up-to-date build,
open a shell/terminal/command window and:
1. **ensure you have GHC (6.10 or newer) and cabal-install** hledger works on all major platforms. You can download and run current
release binaries from the [download page](DOWNLOAD.html).
$ ghc --version You can also build the current release from source using cabal-install.
$ cabal --version Ensure you have a working
[haskell environment](http://hackage.haskell.org/platform/), then:
If not, download and install the [Haskell $ cabal update
Platform](http://hackage.haskell.org/platform/). Or, you may be $ cabal install hledger
able to use your platform's packaging system, eg on ubuntu lucid
do `apt-get install ghc6 cabal-install zlib1g-dev`. Also make
sure `~/.cabal/bin` is in your PATH.
2. **install hledger with cabal-install** *(Until next release: add -fweb, -fvty, or -fchart to cabal install those
extra features.)*
$ cabal update *(With both of the methods above, running the web interface requires some
$ cabal install hledger extra support files - see the download page.)*
#### Install options Or, you can build the latest [development](DEVELOPMENT.html) version:
You can add the following options to the basic `cabal install hledger` $ darcs get --lazy http://joyful.com/repos/hledger
command to build extra features. I recommend you get the basic install $ cd hledger
working first, then try these one at a time: $ make install
If you have any trouble, please proceed to
[Troubleshooting](#troubleshooting) for help and/or seek
[Support](DEVELOPMENT.html#support).
<!--
- `-fweb` builds the [web](#web) command, enabling a web-based user - `-fweb` builds the [web](#web) command, enabling a web-based user
interface. This requires GHC 6.12 or greater. interface. This requires GHC 6.12 or greater.
@ -83,34 +75,27 @@ working first, then try these one at a time:
(on ubuntu: `apt-get install libghc6-gtk-dev`) and possibly [other (on ubuntu: `apt-get install libghc6-gtk-dev`) and possibly [other
things](http://code.haskell.org/gtk2hs/INSTALL). things](http://code.haskell.org/gtk2hs/INSTALL).
#### If you have trouble.. -->
proceed to [Troubleshooting](#troubleshooting) for help! ## Usage
### Basic usage hledger looks for data in a file named `.journal` in your home directory,
creating it if it doesn't exist. Or you can specify a different file with
the -f option or the `LEDGER` environment variable. Basic usage is:
Basic usage is: $ hledger [OPTIONS] COMMAND [PATTERNS]
$ hledger [OPTIONS] [COMMAND [PATTERNS]] where the command is one of the [commands](#commands) described below.
[Filter patterns](#filter-patterns) may be used to select a subset of the
journal data, eg to report only food-related transactions.
[Options](#overview) may appear anywhere on the command line.
[OPTIONS](#overview) may appear anywhere on the command line. To try it out, just run `hledger add` and [enter some transactions](#add).
[COMMAND](#commands) is one of: add, balance, chart, convert, histogram, (Or, you could save the [sample file](#journal-file) as `.journal` in your
print, register, stats, ui, web, test (defaulting to balance). The home directory.) Now try some of these commands:
optional [PATTERNS](#filter-patterns) are regular expressions which select
a subset of the journal data.
hledger looks for data in a journal file, usually `.journal` in your home
directory. You can specify a different file with the -f option (use - for
standard input) or `LEDGER` environment variable.
To get started, make yourself a journal file containing some
transactions. You can copy the sample file below (or
[sample.journal](http://joyful.com/repos/hledger/data/sample.journal)) and save
it as `.journal` in your home directory. Or, just run `hledger add` and
enter a few transactions. Now you can try some of these commands, or read
on:
$ hledger --help # show command-line help $ hledger --help # show command-line help
$ hledger add # add some new transactions to the journal file
$ hledger balance # all accounts with aggregated balances $ hledger balance # all accounts with aggregated balances
$ hledger bal --depth 1 # only top-level accounts $ hledger bal --depth 1 # only top-level accounts
$ hledger register # transaction register $ hledger register # transaction register
@ -118,73 +103,38 @@ on:
$ hledger reg checking # checking transactions $ hledger reg checking # checking transactions
$ hledger reg desc:shop # transactions with shop in the description $ hledger reg desc:shop # transactions with shop in the description
$ hledger histogram # transactions per day, or other interval $ hledger histogram # transactions per day, or other interval
$ hledger add # add some new transactions to the journal file
$ hledger vty # curses ui, if installed with -fvty
$ hledger web # web ui, if installed with -fweb
$ hledger chart # make a balance chart, if installed with -fchart
You'll find more examples below. You'll find more examples below.
<a name="file-format" /> <a name="faq" />
#### Journal file ## Frequently asked questions
hledger reads data from a plain text file, called a *journal* because - **How does hledger relate to John Wiegley's ledger project ?**
it represents a standard accounting [general
journal](http://en.wikipedia.org/wiki/General_journal). It contains a
number of transactions, 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.
You can use hledger without learning any more about this file; just hledger was inspired by and modelled closely on
use the [add](#add) or [web](#web) commands. [ledger](http://wiki.github.com/jwiegley/ledger) (called "c++ ledger"
in these docs.) The two projects (indeed the whole family of
Many users, though, edit the journal file directly with a text ledger-inspired projects) collaborate freely, and we share ledger's
editor. This is a distinguishing feature of hledger (and c++ ledger.) IRC channel.
You can even do this while the web interface is running, and see the
changes right away.
Here's an example:
; A sample journal file. This is a comment.
2008/01/01 income ; <- transaction's first line starts in column 0, contains date and description After using and contributing to c++ ledger for a while, I wrote
assets:bank:checking $1 ; <- posting lines start with whitespace, each contains an account name hledger because I wanted to develop financial tools in the Haskell
income:salary $-1 ; followed by at least two spaces and an amount programming language and ecosystem, whose advantages I believe are
compelling.
2008/06/01 gift I have also tried to make hledger a little more simple, user-friendly,
assets:bank:checking $1 ; <- at least two postings in a transaction installable, and documented, and to offer additional user interfaces
income:gifts $-1 ; <- their amounts must balance to 0 (add, vty, web) and other things that I find useful.
2008/06/02 save C++ ledger has more command-line power-user features (periodic
assets:bank:saving $1 transactions, budgets, capital gains tracking, value expressions,
assets:bank:checking ; <- one amount may be omitted; here $-1 is inferred custom output formats, ...) and remains faster and more memory
efficient on large data sets.
2008/06/03 eat & shop ; <- description can be anything We try to stay compatible with c++ ledger as far as possible; it's
expenses:food $1 intended that you can use both tools on the same journal file. Here
expenses:supplies $1 ; <- this transaction debits two expense accounts is [more detail about compatibility](#compatibility-with-c-ledger).
assets:cash ; <- $-2 inferred
2008/12/31 * pay off ; <- an optional * after the date means "cleared" (or anything you want)
liabilities:debts $1
assets:bank:checking
Each transaction has a date, optional description, and two or more
postings, of some amount to some account. The amounts within a transaction must balance,
ie add up to 0. Or, you can leave one amount blank and it will be inferred.
Note that account names may contain single spaces, while the amount must
be separated from the account name by at least two spaces.
An amount is a number, with an optional currency symbol or commodity name
on either the left or right. Commodity names which contain more than just
letters should be enclosed in double quotes. Negative amounts usually have
the minus sign next to the number (`$-1`), but it may also go before the
currency symbol/commodity name (`-$1`).
hledger's file format aims to be compatible with c++ ledger, so you
can use both tools on your journal. For more details, see [File format
compatibility](#file-format-compatibility).
## Reference ## Reference
@ -260,6 +210,67 @@ Here is the command-line help:
--help-options show command-line options --help-options show command-line options
-H --help-all show command-line usage and options -H --help-all show command-line usage and options
<a name="file-format" />
### Journal file
hledger reads data from a plain text file, called a *journal* because
it represents a standard accounting [general
journal](http://en.wikipedia.org/wiki/General_journal). It contains a
number of transactions, 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.
You can use hledger without learning any more about this file; just
use the [add](#add) or [web](#web) commands.
Many users, though, edit the journal file directly with a text
editor. This is a distinguishing feature of hledger (and c++ ledger.)
You can even do this while the web interface is running, and see the
changes right away.
Here's an example:
; A sample journal file. This is a comment.
2008/01/01 income ; <- transaction's first line starts in column 0, contains date and description
assets:bank:checking $1 ; <- posting lines start with whitespace, each contains an account name
income:salary $-1 ; followed by at least two spaces and an amount
2008/06/01 gift
assets:bank:checking $1 ; <- at least two postings in a transaction
income:gifts $-1 ; <- their amounts must balance to 0
2008/06/02 save
assets:bank:saving $1
assets:bank:checking ; <- one amount may be omitted; here $-1 is inferred
2008/06/03 eat & shop ; <- description can be anything
expenses:food $1
expenses:supplies $1 ; <- this transaction debits two expense accounts
assets:cash ; <- $-2 inferred
2008/12/31 * pay off ; <- an optional * after the date means "cleared" (or anything you want)
liabilities:debts $1
assets:bank:checking
Each transaction has a date, optional description, and two or more
postings, of some amount to some account. The amounts within a transaction must balance,
ie add up to 0. Or, you can leave one amount blank and it will be inferred.
Note that account names may contain single spaces, while the amount must
be separated from the account name by at least two spaces.
An amount is a number, with an optional currency symbol or commodity name
on either the left or right. Commodity names which contain more than just
letters should be enclosed in double quotes. Negative amounts usually have
the minus sign next to the number (`$-1`), but it may also go before the
currency symbol/commodity name (`-$1`).
hledger's file format aims to be compatible with c++ ledger, so you
can use both tools on your journal. For more details, see [File format
compatibility](#file-format-compatibility).
### Commands ### Commands
#### Reporting commands #### Reporting commands
@ -394,8 +405,7 @@ control-C when you are done.
add tries to be helpful, providing: add tries to be helpful, providing:
- Readline-style input: during data entry, the usual console editing keys - Sensible defaults
should work.
- (Selective) history awareness: if there are earlier transactions - (Selective) history awareness: if there are earlier transactions
approximately matching the description you enter, the best match will approximately matching the description you enter, the best match will
@ -403,11 +413,14 @@ add tries to be helpful, providing:
[filter pattern(s)](#filter-patterns) on the command line, only matching [filter pattern(s)](#filter-patterns) on the command line, only matching
transactions will be considered for defaults. transactions will be considered for defaults.
- Auto-completion: while entering account names, the tab key will - Readline-style input: during data entry, the usual editing keys should
auto-complete as far as possible. If pressed a second time it will show work.
a list of options.
- Default commodity: if the journal specifies a - Auto-completion for account names: while entering account names, the tab
key will auto-complete as far as possible, or list the available
options.
- Default commodity awareness: if the journal specifies a
[default commodity directive](#default-commodity), that will be applied [default commodity directive](#default-commodity), that will be applied
to any bare numbers entered. to any bare numbers entered.
@ -1154,3 +1167,11 @@ Here are some issues you might encounter when you run hledger:
$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
$ bash --login $ bash --login
## Other resources
- The rest of the [hledger.org](http://hledger.org) site.
- The [c++ ledger site](https://github.com/jwiegley/ledger/wiki).
Also the [c++ ledger 2.x manual](http://joyful.com/repos/ledger/doc/ledger.html)
is slightly outdated but informative.

4
site/site.tmpl
View File

@ -19,11 +19,11 @@
<!-- <a href="$root/"><img src="$root/logo.jpg" border="0" ALT="" /></a> --> <!-- <a href="$root/"><img src="$root/logo.jpg" border="0" ALT="" /></a> -->
</div> </div>
<div id="navigation"> <div id="navigation">
<a href="$root/README.html">Home</a> <a href="$root/README.html">About</a>
<a href="$root/DOWNLOAD.html">Download</a> <a href="$root/DOWNLOAD.html">Download</a>
<a href="$root/MANUAL.html">Docs</a>
<a href="$root/DEVELOPMENT.html">Development</a> <a href="$root/DEVELOPMENT.html">Development</a>
<a href="$root/NEWS.html">News</a> <a href="$root/NEWS.html">News</a>
<a href="$root/MANUAL.html">Manual</a>
<a href="$root/SCREENSHOTS.html">Screenshots</a> <a href="$root/SCREENSHOTS.html">Screenshots</a>
<a href="http://demo.hledger.org">Demo</a> <a href="http://demo.hledger.org">Demo</a>
</div> </div>