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

docs: manual updates

Browse Source
This commit is contained in:
Simon Michael 2010-07-24 22:10:21 +00:00
parent 3436a27e68
commit bc23f4495c
1 changed files with 84 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
MANUAL.markdown
View File

@ -43,52 +43,59 @@ released as Free Software under GPL version 3 or later.
### Installing ### Installing
hledger works on all major platforms; here are the [release hledger works on all major platforms. Here are the [release
notes](http://hledger.org/NEWS.html). One of these pre-built notes](http://hledger.org/NEWS.html), and pre-built
[binaries](http://hledger.org/binaries/) might work for you, but at [binaries](http://hledger.org/binaries/) you should be able to
present these are not very up-to-date, so the usual thing is to build download and run. If not, or if you prefer an up-to-date build,
with the cabal-install tool: open a shell/terminal/command window and:
1. If you don't already have the Glasgow Haskell Compiler and 1. **ensure you have GHC (6.10 or newer) and cabal-install**
cabal-install, download and install the
[Haskell Platform](http://hackage.haskell.org/platform/). Or, you may
be able to use platform packages; eg on Ubuntu Lucid, do `apt-get
install ghc6 cabal-install happy`.
2. Install hledger with cabal-install. Make sure ~/.cabal/bin is in your $ ghc --version
path; this is required while installing some cabal packages. Eg: $ cabal --version
export PATH=$PATH:~/.cabal/bin 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.
You can add the following options to the install command to build 2. **install hledger with cabal-install**
extra features (if you're new to cabal, I recommend you get the basic
install working first, then add these one at a time):
- `-fchart` builds the [chart](#chart) command, enabling simple $ cabal update
$ cabal install hledger
#### Install options
You can add the following options to the basic `cabal install hledger`
command to build extra features. I recommend you get the basic install
working first, then try these one at a time:
- `-fweb` builds the [web](#web) command, enabling a web-based user
interface. This requires GHC 6.12. If you are stuck with GHC 6.10,
you can use `-fweb610` instead, to build an older version of the web
interface.
- `-fvty` builds the [vty](#vty) command, enabling a basic
curses-style user interface. This does not work on microsoft
windows, unless possibly with cygwin.
- `-fchart` builds the [chart](#chart) command, enabling simple
balance pie chart generation. This requires additional GTK/GHC balance pie chart generation. This requires additional GTK/GHC
integration libraries (on ubuntu: `apt-get install libghc6-gtk-dev`) integration libraries (on ubuntu: `apt-get install libghc6-gtk-dev`)
and possibly other things - see the and possibly other things - see the
[gtk2hs install docs](http://code.haskell.org/gtk2hs/INSTALL). [gtk2hs install docs](http://code.haskell.org/gtk2hs/INSTALL).
At present this add a lot of build complexity for not much gain. At present this add a lot of build complexity for not much gain.
- `-fvty` builds the [vty](#vty) command, enabling a basic #### If you have trouble..
curses-style user interface. This does not work on microsoft
windows, unless possibly with cygwin.
- `-fweb` builds the [web](#web) command, enabling a web-based user proceed to [Troubleshooting](#troubleshooting) for help!
interface. This requires GHC 6.12. If you are stuck with GHC 6.10,
you can use `-fweb610` instead, to build an older version of the web
interface.
If you have any trouble, proceed at once to [Troubleshooting](#troubleshooting) for help!
### Basic usage ### Basic usage
Basic usage is: Basic usage is:
hledger [OPTIONS] [COMMAND [PATTERNS]] $ hledger [OPTIONS] [COMMAND [PATTERNS]]
[OPTIONS](#overview) may appear anywhere on the command line. [OPTIONS](#overview) may appear anywhere on the command line.
[COMMAND](#commands) is one of: add, balance, chart, convert, histogram, [COMMAND](#commands) is one of: add, balance, chart, convert, histogram,
@ -107,30 +114,39 @@ 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 enter a few transactions. Now you can try some of these commands, or read
on: on:
hledger --help # show command-line help $ hledger --help # show command-line help
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
hledger reg income # transactions to/from an income account $ hledger reg income # transactions to/from an income account
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 add # add some new transactions to the journal file
hledger vty # curses ui, if installed with -fvty $ hledger vty # curses ui, if installed with -fvty
hledger web # web ui, if installed with -fweb or -fweb610 $ hledger web # web ui, if installed with -fweb or -fweb610
hledger chart # make a balance chart, if installed with -fchart $ 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="file-format" />
### Journal file #### Journal file
hledger's data file, aka the journal, is a standard accounting hledger reads data from a plain text file, called a *journal* because
[general journal](http://en.wikipedia.org/wiki/General_journal) in a plain it represents a standard accounting [general
text format. It contains a number of transactions, each describing a journal](http://en.wikipedia.org/wiki/General_journal). It contains a
transfer of money (or another commodity) between two or more named number of transactions, each describing a transfer of money (or
accounts. Here's an example: 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. Most users, though, edit
the journal file directly with a text editor. This is a distinguishing
feature of hledger (and c++ ledger.) You can do this while the web
interface is running, too; it watches the file for changes.
Here's an example:
; A sample journal file. This is a comment. ; A sample journal file. This is a comment.
@ -168,9 +184,9 @@ 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 the minus sign next to the number (`$-1`), but it may also go before the
currency symbol/commodity name (`-$1`). currency symbol/commodity name (`-$1`).
hledger's file format aims to be compatible with c++ ledger, so you can hledger's file format aims to be compatible with c++ ledger, so you
use both tools. For more details, see can use both tools on your journal. For more details, see [File format
[File format compatibility](#file-format-compatibility). compatibility](#file-format-compatibility).
## Reference ## Reference
@ -953,7 +969,7 @@ sailing. Here are some known issues and things to try:
Eg: join the #hledger channel with your IRC client and type: "sm: I did ... and ... happened", then leave Eg: join the #hledger channel with your IRC client and type: "sm: I did ... and ... happened", then leave
that window open until you get helped. that window open until you get helped.
- **Did you cabal update ?** If you didn't already, ``cabal update`` and try again. - **Did you cabal update ?** If you didn't already, `cabal update` and try again.
- **Do you have a new enough version of GHC ?** hledger supports GHC 6.10 - **Do you have a new enough version of GHC ?** hledger supports GHC 6.10
and 6.12. Building with the `-fweb` flag requires 6.12 or greater. and 6.12. Building with the `-fweb` flag requires 6.12 or greater.
@ -970,12 +986,15 @@ sailing. Here are some known issues and things to try:
then try installing hledger again. then try installing hledger again.
- **Could not run trhsx.** - **Could not run trhsx.**
You are installing with `-fweb610`, which needs to run the ``trhsx`` executable. You are installing with `-fweb610`, which needs to run the `trhsx` executable.
It is installed by the hsx package in ~/.cabal/bin, which needs to be in It is installed by the hsx package in `~/.cabal/bin`, which needs to be in
your path. your path. Do something like:
$ echo 'export PATH=$PATH:~/.cabal/bin' >> ~/.bash_profile; source ~/.bash_profile
- **Could not run happy.** - **Could not run happy.**
A package (eg haskell-src-exts) needs to run the ``happy`` executable. A package (eg haskell-src-exts) needs to run the `happy` executable.
If not using the haskell platform, install the appropriate platform If not using the haskell platform, install the appropriate platform
package which provides it (eg apt-get install happy). package which provides it (eg apt-get install happy).
@ -1009,16 +1028,16 @@ sailing. Here are some known issues and things to try:
error. You could try installing the error. You could try installing the
[previous version](http://hackage.haskell.org/package/hledger): [previous version](http://hackage.haskell.org/package/hledger):
cabal install hledger-0.x $ cabal install hledger-0.x
or (preferably) the latest development version: install or (preferably) the latest development version: install
[darcs](http://darcs.net) and then: [darcs](http://darcs.net) and then:
darcs get --lazy http://joyful.com/repos/hledger $ darcs get --lazy http://joyful.com/repos/hledger
cd hledger/hledger-lib $ cd hledger/hledger-lib
cabal install $ cabal install
cd .. $ cd ..
cabal install [-f...] $ cabal install [-f...]
- **An error while building non-hledger packages.** - **An error while building non-hledger packages.**
Resolve these problem packages one at a time. Eg, cabal install pkg1. Resolve these problem packages one at a time. Eg, cabal install pkg1.