simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-11-07 21:15:19 +03:00
Code Issues Projects Releases Wiki Activity

docs: move most docs to the wiki

Browse Source 
I've moved the installation and developer guides, FAQ and how-tos from
hledger.org (yst & git) to hledger.org/wiki (dokuwiki) and tried to
integrate their navigation bars two as best I can. Using just one
or the other would be nice, but I don't think I can quite do that;
it seems the manual at least should be revision controlled along with the code.
This commit is contained in:
Simon Michael 2014-01-26 11:41:28 -08:00
parent a551b76a56
commit 9bf447184b
10 changed files with 37 additions and 873 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Makefile
View File

@ -555,7 +555,7 @@ cleandocs: cleansite
# Requires yst (cabal install yst)
.PHONY: site
site: olddocs
cd site; yst
-cd site; yst
cleansite: cleanolddocs
rm -rf site/site/*

49
doc/ALIASES.md
View File

@ -1,49 +0,0 @@
# How to use account aliases
Here's an example of using [account aliases](MANUAL.html#account-aliases).
Say a sole proprietor has a `personal.journal`:
2014/1/2
expenses:food $1
assets:cash
and a `business.journal`:
2014/1/1
expenses:office supplies $1
assets:business checking
So each entity (the business owner, and the business) has their own file with its own simple chart of accounts.
However, at tax reporting time we need to view these as a single entity (at least in the US).
In `unified.journal`, we include both files, and rewrite the personal
account names to fit into the business chart of accounts,
alias expenses = equity:draw:personal
alias assets:cash = assets:personal cash
include personal.journal
end aliases
include business.journal
Now we can see the data from both files at once, and the personal account names have changed:
$ hledger -f unified.journal print
2014/01/01 # from business.journal - no aliases applied
expenses:office supplies $1
assets:business checking $-1
2014/01/02 # from personal.journal
equity:draw:personal:food $1 # <- was expenses:food
assets:personal cash $-1 # <- was assets:cash
You can also specify aliases on the command line. This could be useful to
quickly rewrite account names when sharing a report with someone else, such as
your accountant:
$ hledger --alias 'my earning=income:business' ...
Command-line alias options are applied after any alias directives in the
journal. At most one alias directive and one alias option will be applied
to each account name.

52
doc/CSV.md
View File

@ -1,52 +0,0 @@
# How to read CSV files
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:
"Date","Note","Amount"
"2012/3/22","DEPOSIT","50.00"
"2012/3/23","TRANSFER TO SAVINGS","-10.00"
We tell hledger how to intepret this with a file named `checking.csv.rules`, using the [rules syntax](MANUAL.html#csv-files). Eg:
# skip the first CSV line (headings)
skip 1
# use the first three fields in each CSV record as transaction date, description and amount respectively
fields date, description, amount
# prepend $ to CSV amounts
currency $
# always set the first account to assets:bank:checking
account1 assets:bank:checking
# if the CSV record contains ‘SAVINGS’, set the second account to assets:bank:savings
# (if not set, it will be expenses:unknown or income:unknown)
if ~ SAVINGS
account2 assets:bank:savings
Now hledger can read this CSV file as journal data:
$ hledger -f checking.csv print
using conversion rules file checking.csv.rules
2012/03/22 DEPOSIT
income:unknown $-50.00
assets:bank:checking $50.00
2012/03/23 TRANSFER TO SAVINGS
assets:bank:savings $10.00
assets:bank:checking $-10.00
We might save this output as `checking.journal`, and/or merge it (manually) into the main journal file.
We could also run other commands:
$ hledger -f checking.csv balance
using conversion rules file checking.csv.rules
$50.00 assets:bank
$40.00 checking
$10.00 savings
$-50.00 income:unknown
--------------------
0

291
doc/DEVELOP.md
View File

@ -1,291 +0,0 @@
# Developer guide
**Quick links:**
**hledger released version**\
[release notes](NEWS.html)\
[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-lib](http://hackage.haskell.org/package/hledger-lib)
packages\
<!-- [hledger-web demo](http://demo.hledger.org) -->
<!-- <script type="text/javascript" src="http://haskell.org/hoogle/datadir/resources/jquery-1.4.2.js"></script> -->
<script type="text/javascript" src="http://haskell.org/hoogle/datadir/resources/hoogle.js"></script>
<form action="http://haskell.org/hoogle/" method="get" style="display:inline; margin:0; padding:0;">
<input type="hidden" name="prefix" value="+hledger +hledger-lib +hledger-web +hledger-vty +hledger-chart" />
<span style="white-space:nowrap;"
><input type="text" name="hoogle" id="hoogle" accesskey="1" size="30"
/><input type="submit" value="search API with hoogle"
/></span>
</form>
**hledger development version**<br>
[Get it](#how-to-set-up-for-development),
[browse it](http://github.com/simonmichael/hledger),
[changes](http://github.com/simonmichael/hledger/commits),
[CHANGES](http://starlogs.net/#simonmichael/hledger) (turn up your volume!)
<!-- [hledger-web dev demo](http://demo.hledger.org:5001) -->
<br>
[build](http://hydra.cryp.to:8080/project/hledger),
[dependencies](http://packdeps.haskellers.com/feed/?needle=hledger)
<!-- [haddock coverage](http://hledger.org/profs/haddock-coverage), -->
<!-- [unit test coverage](http://hledger.org/profs/coverage/hpc_index_fun.html), -->
<!-- [benchmark](http://hledger.org/profs/latest.bench) -->
<!-- [profile](http://hledger.org/profs/latest.prof), -->
<!-- [heap](http://hledger.org/profs/latest.ps) -->
reports\
<!-- [developer notes](http://github.com/simonmichael/hledger/NOTES.org)\ -->
<!-- [browse dev API docs](http://hledger.org/api/frames.html) -->
\
## How to..
New contributors of all levels are most welcome.
Here are some tips to help you get productive on the hledger project.
### how to suggest enhancements
Suggestions and feature requests are easy to make, less easy to
research, and hard to implement. And, alas! We don't have a team of
sleek, well-fed, idle coders standing by to implement everybody's
wishes. (Please
[help change that](#how-to-set-up-for-hledger-development)).
Wishes *are* welcome feedback, but we don't want them to pile up and
obscure bugs and other developer priorities, so we manage them with discussion
and optionally as cards on a trello board.
The current recommendation is
1. **discuss/research first**\
Is your wish already on the [trello wishlist/planning board](http://hledger.org/trello)
or [bug tracker](http://hledger.org/bugs) ?\
Perhaps discuss it on [irc](irc://irc.freenode.net/#ledger), the [mail list](http://hledger.org/list) or trello ?
2. **report wishes on trello, bugs in the bug tracker**\
Is it a problem with the released and documented functionality ? report in the [bug tracker](http://hledger.org/bugs)\
Is it a wish ? add a card on the [trello board](http://hledger.org/trello), if needed
3. **don't sweat it**\
Or, do what you think best. If a wish does land in the bug tracker, it gets the WISH label.
### how to report problems
- check for related issues in the [bug tracker](http://hledger.org/bugs) or in the [mail list archive](http://hledger.org/list)
- discuss/confirm the issue on irc or list
- report new issues in the bug tracker
<!-- - test and share problem journal snippets at paste . hledger.org -->
### how to help with testing
- review and test our documentation and web presence
- download and test the binaries on your platform
- test installing via cabal
- use the tools and test functionality, usability, browser compatibility, ui layout etc.
- check that `hledger test` reports no failures
- [run the developer tests](#how-to-run-the-tests)
- discuss/report problems via irc/mail list/bug tracker
### how to help with bug tracking
- get to know the [bug tracker](http://hledger.org/bugs) and its contents
- research and update issues
- some convenient url shortcuts:
[`hledger.org/bugs`](http://hledger.org/bugs)
[`hledger.org/bugs/new`](http://hledger.org/bugs/new)
`hledger.org/bugs/N`
### how to set up for development
1. get an up-to-date [ghc](http://haskell.org/ghc), at least 7.0 and preferably 7.6
2. there's probably no need to install the [haskell platform](http://haskell.org/platform) now, but you could
3. it's probably worth getting the latest and best cabal: `cabal update; cabal install cabal-install`
4. ensure you have [git](http://git-scm.com) installed
5. the hledger Makefile assumes GNU Make, so on some platforms you may need to spell "make" as "gmake"
- get the hledger repo:
git clone git@github.com:simonmichael/hledger.git
cd hledger
- install packages required to build hledger and add-ons, or as many of them as possible:
cabal update
make install
This will also try to cabal install development builds of the hledger
executables, so ghc-pkg unregister those afterwards if you don't want
that.
- try building with make:
make bin/hledgerdev
This is usually quicker and simpler than fiddling with multiple cabal packages during development.
Note this executable will not be as optimised as the normal cabal build, and has the "dev" suffix
as a reminder of this.
- try auto-building with sp:
make auto # or autoweb
You'll need to follow the instructions to install `sp`.
This is how I do most hledger development. It will recompile whenever you save changes to source files.
### how to get your changes accepted
Follow the usual github workflow:
- fork the main hledger repo on github,
- git clone it to your local machine,
- git commit, after (?) pulling and merging the latest upstream changes
- git push back to github,
- open a pull request on github,
- follow up on any discussion there.
If you're new to this process, [help.github.com](http://help.github.com) may be useful.
### how to improve the documentation
- get familiar with the website and documentation online, review and test
- get familiar with the site/doc source files (see Makefile)
- set up for hledger development
- send patches with names prefixed with "doc: " (or "site: ")
### how to run the tests
- set up for hledger development
- cabal install shelltestrunner
- make test
### how to add a test
- identify what to test
- choose the test type: unit ? functional ? benchmark ?
- currently expected to pass or fail ?
- figure out where it goes
- write test, verify expected result
- get it committed
### how to fix a bug or add a feature
- research, discuss, validate the issue/feature on irc/list/bug tracker
- look for related tests, run the tests and check they are passing
- add a test ?
- develop a patch
- include any related issue numbers in the patch name, eg: "fix for blah blah (#NNN)"
- get it committed
### how to become a contributor
- after getting one or more patches committed, read and sign the [contributor list & agreement](CONTRIBUTORS.html)
- or, [ask](#how-to-get-help) to be added
### how to do code review
- review and discuss new pull requests and commits on github
- set up for development and test the latest changes in your own repo
- read the existing [code docs and source](#quick-links)
- send feedback or discuss via irc or list
### how to help with packaging
- package hledger for linux distros, macports, etc.
- develop mac/windows installers
- find and assist distro packagers/installer developers
### how to help with project management
- clarify/update goals and principles
- monitor, report on project progress and performance
- research, compare and report on successful projects, related projects
- identify collaboration opportunities
- marketing, communication, outreach
- release management, roadmap planning
## Project overview
A rough overview/blueprint for the hledger project.
### mission, principles, goals
The hledger project aims to produce:
- a practical, accessible, dependable tool for end users
- a useful library and toolbox for finance-minded haskell programmers
- a successful, time-and-money-solvent project within a thriving ecosystem of financial software projects.
### roles and activities
- newcomer/potential user
- user
- library user
- field tester
- bug wrangler
- support
- documentor
- qa
- developer
- packager
- communicator
- project manager
### documentation
- website
- user manual
- developer guide
- code documentation: haddock
- various developer reports
- developer notes outline
- blurbs: in cabal files, module headers, google project, repo message of the day..
### quality assurance
- unit tests (HUnit, make unittest)
- functional tests (shelltestrunner, make functest)
- performance tests (simplebench, make bench)
- documentation tests (make haddocktest + manual)
- ui tests (manual)
- installation tests (manual)
### code
- the hledger repo is hosted on github.com:
[http://github.com/simonmichael/hledger](http://github.com/simonmichael/hledger).
(You can also jump there via [hledger.org/code](http://hledger.org/code) or code.hledger.org).
<!-- ### release process -->
<!-- ### roadmap -->
<!-- ### communication and collaboration -->
<!-- ### web presence and hosting setup -->
<!-- ### finances and other resources -->
<!-- ### licensing and legal issues -->
<!-- ### contributors and credits -->
## Related projects
- I have a few older bits and pieces [here](http://joyful.com/Ledger)
- John Wiegley's [ledger](http://wiki.github.com/jwiegley/ledger) inspired hledger.
- [ledger-autosync](https://bitbucket.org/egh/ledger-autosync) downloads and converts bank OFX data for ledger or hledger
- Tim Docker's [ledger-reports](http://dockerz.net/repos/ledger-reports) builds on hledger to generate
[html reports](http://dockerz.net/software/hledger_report_sample/report.html)
- [beancount](https://furius.ca/beancount/) is another ledger clone, in python
- h/ledger inspired Omari Norman's [penny](https://github.com/massysett/penny)
- and Uwe Hollerbach's [umm](http://hackage.haskell.org/package/UMM)
- [http://darcsden.com/alex/bill](http://darcsden.com/alex/bill), [http://darcsden.com/alex/bill-atomo](http://darcsden.com/alex/bill-atomo), [http://darcsden.com/alex/bill-scheme](http://darcsden.com/alex/bill-scheme) - a time-tracking and billing app
- [http://darcsden.com/ozamosi/debts](http://darcsden.com/ozamosi/debts) - Silly debt tracking webapp
- [http://darcsden.com/housetab-multi](http://darcsden.com/dbp/housetab-multi), [housetab.org](http://housetab.org) - a webapp to manage expenses between a group of friends.
<!-- <a href="https://www.google.com/analytics/reporting/?reset=1&id=15489822" accesskey="a"></a> -->

25
doc/DOCS.md
View File

@ -1,25 +0,0 @@
# More Docs
See also:
Ledger's informative [manual](http://ledger-cli.org/3.0/doc/ledger3.html)
[Non-Profit Accounting With Ledger CLI, A Tutorial](https://gitorious.org/ledger/npo-ledger-cli/source/npo-ledger-cli-tutorial.md)
[Accounting For Dragons](http://podcastle.org/2009/10/09/pc-miniature-38-accounting-for-dragons) - essential tips
Wikipedia:\
&nbsp;[Accountancy](https://en.wikipedia.org/wiki/Accountancy)\
&nbsp;[Bookkeeping](https://en.wikipedia.org/wiki/Bookkeeping)\
&nbsp;[Double-entry bookkeeping system](https://en.wikipedia.org/wiki/Double-entry_bookkeeping_system)\
&nbsp;etc.
WikiWikiWeb:\
&nbsp;[Double Entry Bookkeeping](http://c2.com/cgi/wiki?DoubleEntryBookkeeping) - software developers discuss it
Similar software:\
&nbsp;[ledger](http://ledger-cli.org),
[UMM](http://hackage.haskell.org/package/UMM),
[penny](http://hackage.haskell.org/package/penny),
[beancount](http://furius.ca/beancount/),
and [more](https://github.com/ledger/ledger/wiki/Ports)

211
doc/FAQ.md
View File

@ -1,211 +0,0 @@
# Frequently asked questions
## hledger and ledger
### How does hledger relate to ledger ?
hledger was inspired by and is partly a clone of John Wiegley's [ledger](http://ledger-cli.org).
I was a happy ledger user and contributor for some time; I still use it
occasionally. I wrote hledger because I wanted to develop financial tools
in the Haskell programming language and ecosystem, whose advantages I
believe are compelling. I have also tried to make hledger a little more
simple, usable, installable, documented, appealing to collaborators, and
to provide alternate user interfaces to make it more widely useful.
ledger has more advanced power-user features on the command-line
(periodic and modifier transactions, budgets, capital gains tracking,
value expressions, custom output formats, etc.) and it remains faster
and more memory efficient (for now!)...
hledger builds faster and has an up-to-date manual and an optional web
interface (which often works on ledger files too)...
The two projects collaborate freely. We share the
[#ledger](irc://irc.freenode.net/#ledger) IRC channel but have
separate mail lists
([hledger list](http://groups.google.com/group/hledger/),
[ledger-cli list](http://groups.google.com/group/ledger-cli/)). I try
to give back by providing infrastructure
([ledger-cli.org](http://ledger-cli.org)) and IRC support.
hledger stays compatible with ledger wherever possible, so that you
can often use both tools on the same data file.
Summary: hledger is a friendly, co-evolving, compatible rewrite of ledger
in Haskell, lacking some of ledger's power features and raw performance,
and focussing on robustness, usability, ease of development, and
experimental add-ons such as the [web interface](MANUAL.html#web).
### What are the feature differences ?
hledger mimics a subset of [ledger 3.x](http://ledger-cli.org), and adds some features of its own.
We currently support:
- ledger's journal format, mostly
- csv format
- timelog format
- regular journal transactions
- multiple commodities
- fixed prices and price history
- virtual postings
- print, register & balance commands
- filtering by many criteria, with different query syntax
- display expressions containing just a simple date predicate
- some basic output formatting
We do not support:
- automated transactions
- value expressions
- fluctuating prices
- display formats other than `d>[DATE]` or similar
- budget reports
And we add these commands:
- add
- balancesheet
- cashflow
- chart
- incomestatement
- irr
- interest
- vty
- web
ledger options and commands not supported include:
Basic options:
-o, --output FILE write output to FILE
-i, --init-file FILE initialize ledger using FILE (default: ~/.ledgerrc)
-a, --account NAME use NAME for the default account (useful with QIF)
Report filtering:
-c, --current show only current and past entries (not future)
--period-sort EXPR sort each report period's entries by EXPR
-L, --actual consider only actual (non-automated) transactions
--budget generate budget entries based on periodic entries
--add-budget show all transactions plus the budget
--unbudgeted show only unbudgeted transactions
--forecast EXPR generate forecast entries while EXPR is true
-l, --limit EXPR calculate only transactions matching EXPR
-t, --amount EXPR use EXPR to calculate the displayed amount
-T, --total EXPR use EXPR to calculate the displayed total
Output customization:
-n, --collapse Only show totals in the top-most accounts.
-P, --by-payee show summarized totals by payee
-x, --comm-as-payee set commodity name as the payee, for reporting
--dow show a days-of-the-week report
-S, --sort EXPR sort report according to the value expression EXPR
--head COUNT show only the first COUNT entries (negative inverts)
--tail COUNT show only the last COUNT entries (negative inverts)
--pager PAGER send all output through the given PAGER program
-A, --average report average transaction amount
-D, --deviation report deviation from the average
-%, --percentage report balance totals as a percentile of the parent
--totals in the "xml" report, include running total
-j, --amount-data print only raw amount data (useful for scripting)
-J, --total-data print only raw total data
-y, --date-format STR use STR as the date format (default: %Y/%m/%d)
--balance-format --register-format --print-format
--plot-amount-format --plot-total-format --equity-format
--prices-format --wide-register-format
Commodity reporting:
--price-db FILE sets the price database to FILE (def: ~/.pricedb)
-L, --price-exp MINS download quotes only if newer than MINS (def: 1440)
-Q, --download download price information when needed
-O, --quantity report commodity totals (this is the default)
-V, --market report last known market value
-g, --performance report gain/loss for each displayed transaction
-G, --gain report net gain/loss
Commands:
xml [REGEXP]... print matching entries in XML format
equity [REGEXP]... output equity entries for matching accounts
prices [REGEXP]... display price history for matching commodities
entry DATE PAYEE AMT output a derived entry, based on the arguments
### What are the file format differences ?
hledger's file format is mostly identical with ledger's, by design.
Generally, it's easy to keep a journal file that works with both hledger
and ledger if you avoid ledger's most advanced features.
Some ledger features are parsed but ignored, eg:
- automated transactions ( = ... , ~ ... )
- fixed lot prices ( {...} )
- historical prices ( P ... )
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.
### What other functionality differences are there ?
- hledger recognises description and negative patterns by "desc:"
and "not:" prefixes, unlike ledger 3's free-form parser
- hledger doesn't require a space before command-line option
values, eg `-fFILE` or `-f FILE` works
- hledger's weekly reporting intervals always start on mondays
- hledger shows start and end dates of the intervals requested,
not just the span containing data
- hledger always shows timelog balances in hours
- hledger splits multi-day timelog sessions at midnight
- hledger doesn't track the value of commodities with varying
price; prices are fixed as of the transaction date
- hledger's output follows the decimal point character, digit grouping,
and digit group separator character used in the journal.
- hledger print shows amounts for all postings, and shows unit prices for
amounts which have them. (This means that it does not currently print
multi-commodity transactions in valid journal format.)
- hledger print ignores the --date2 flag, always showing both dates.
ledger print shows only the secondary date with --aux-date, but not
vice versa.
- hledger's default commodity directive (D) sets the commodity to be
used for subsequent commodityless amounts, and also sets that
commodity's display settings if such an amount is the first
seen. ledger uses D only for commodity display settings and for the
entry command.
- hledger generates a description for timelog sessions, instead of
taking it from the clock-out entry
- hledger's [include directive](MANUAL.html#including-other-files) does not support
shell glob patterns (eg `include *.journal` ), which ledger does.
- when checking [balance assertions](MANUAL.html#balance-assertions)
hledger sorts the account's postings first by date and then (for
postings with the same date) by parse order. ledger goes strictly by
parse order.
- ledger allows amounts to have a
[fixed lot price](MANUAL.html#prices) and a regular price in any
order (and uses whichever appears first). hledger requires the fixed
lot price to come last (and ignores it).
### How are the implementations different ?
ledger is written in C++, whereas hledger is written in the
[Haskell](http://haskell.org) programming language.
Haskell is a highly regarded up-and-coming language that enables
a coding style known as pure functional programming, offering the
promise of more bug-free and maintainable software built in fewer
lines of code. Haskell also provides a more abstracted, portable
platform which can make deployment and installation easier in some
cases. Haskell also brings some new challenges such as managing memory
growth and laziness.

211
doc/INSTALL.md
View File

@ -1,211 +0,0 @@
# Installation Guide
hledger works on GNU/linux, mac and windows.
Here are several ways to install it.
## Install with your system package manager
If you have a system package manager that includes hledger,
this will be the quickest and easiest way to install,
if you don't need the very latest version.
Debian, Ubuntu: `apt-get install hledger [hledger-web]`
Red Hat, Fedora: `yum install hledger`
## Install binaries from hledger.org
[Ready-to-run binaries](DOWNLOAD.html) for GNU/Linux, Mac OSX, and Microsoft Windows can be downloaded from this site.
They are out of date, but you can fund new ones with a donation of any size (see the page for more).
This is probably the easiest way to install hledger on windows and mac.
The binaries do not currently include installers, so after downloading
you may need to decompress, make executable, and/or rename the file. Eg:
$ gunzip hledger-web-0.18.2-mac-x86_64.gz
$ chmod +x hledger-web-0.18.2-mac-x86_64
$ mv hledger-web-0.18.2-mac-x86_64 /usr/local/bin/hledger-web
$ /usr/local/bin/hledger-web --version
## Install from hackage with cabal
You can download and build the latest release yourself using cabal, the standard installer for Haskell software.
This is the most common way to install hledger, but not always the easiest;
use the troubleshooting tips below if needed.
Ensure you have [GHC](http://hackage.haskell.org/ghc/) or
the [Haskell Platform](http://hackage.haskell.org/platform/) installed.
hledger requires GHC 7.2 or greater, and hledger-web requires GHC 7.4 or greater.
Also note that some Haskell packages depend on C packages, and cabal
currently isn't able to install or identify those for you. A common
issue is not having all the ncurses C libraries installed. A quick way
to ensure you have all required C libs is to
[install hledger once with your system package manager](#install-with-your-system-package-manager)
before installing the latest version with cabal.
Then install the hledger command-line tool:
$ cabal update
$ cabal install hledger [--dry-run]
$ hledger --version
You should see the proper version reported.
If you get "could not resolve dependencies", "hledger not found",
or any other problem, see [troubleshooting](#troubleshooting).
Also note, to use non-ascii characters like £ in your data, you might need to [configure a suitable locale](MANUAL.html#locale).
To also install the web interface (slightly harder), do:
$ cabal install hledger-web [--dry-run]
$ hledger-web --version
This also installs hledger if not already installed, and the hledger-web command
will also be available as hledger's `web` subcommand.
Other add-on packages are available on Hackage, although some of these are
unmaintained or work only on certain platforms:
- [hledger-chart](http://hackage.haskell.org/package/hledger-chart)
- [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)
## Install the latest development version
To download and build the latest development version of hledger, ensure you have
[git](http://git-scm.com) installed, then:
$ git clone http://github.com/simonmichael/hledger.git
$ cd hledger
$ cabal update
$ cabal install ./hledger-lib ./hledger [./hledger-web]
The same [notes above](#install-from-hackage-with-cabal) about requirements and checking your installation apply.
## Troubleshooting
There are a lot of ways things can go wrong. Here are
some known issues and things to try. Please also seek
[support](DEVELOPMENT.html#support) from the
[IRC channel](irc://irc.freenode.net/#ledger),
[mail list](http://hledger.org/list) or
[bug tracker](http://hledger.org/bugs).
Starting from the top, consider whether each of these might apply to
you. Tip: blindly reinstalling/upgrading everything in sight probably
won't work, it's better to go in small steps and understand the problem,
or get help.
#. **hledger not found ?**
If cabal install succeeded but you get a message like "hledger not found" when you run hledger,
you should add cabal's bin directory to your PATH environment variable.
Eg on unix-like systems, something like:
$ echo 'export PATH=$PATH:~/cabal/bin' >> ~/.bash_profile
$ source ~/.bash_profile
#. **hledger --version shows unexpected version ?**
Perhaps you have multiple versions of hledger in your PATH. Eg you installed with the system package manager
(to get C libs) and then with cabal (to get the latest version), but cabal's bin directory appears too late
in the PATH. Move it closer to the front.
#. **Did you cabal update ?**
If not, `cabal update` and try again.
#. **Do you have a new enough version of GHC ?**
Run `ghc --version`. hledger requires GHC 7.0 or greater
(and on [some platforms](#5551), 7.2.1+ can be helpful).
#. **Do you have a new enough version of cabal ?**
Avoid ancient versions, which are less capable and more confusing.
`cabal --version` should probably report at least 1.16 (and for sandboxed
installs, 1.18+). You may be able to upgrade it with:
$ cabal update
$ cabal install cabal-install
#. **Are your installed GHC/cabal packages in good repair ?**
Run `ghc-pkg check`. If it reports problems, some of your packages have
become inconsistent, and you should fix these first.
[ghc-pkg-clean](https://gist.github.com/1185421) is an easy way.
#. **cabal says "rejecting: system-fileio-0.3.11, 0.3.10 (conflict: blah blah blah.."**
system-fileio does not yet allow text 1.x, making cabal sweat.
If your cabal is modern enough, adding `--max-backjumps=10000` should help.
([more](https://groups.google.com/d/topic/hledger/FdWGTSAVzYU/discussion)).
#. **cabal can't satisfy the new dependencies due to old installed packages**
Cabal dependency failures become more likely as you install more
packages over time. If `cabal install hledger-web --dry` says it can't
satisfy dependencies, you have this problem. You can:
a. try to understand which packages to remove (with `ghc-pkg unregister`)
or which constraints to add (with `--constraint 'PKG == ...'`) to help cabal
find a solution
b. install into a fresh cabal sandbox, created with `cabal sandbox init`.
([virthualenv](http://hackage.haskell.org/package/virthualenv) or
[cabal-dev](http://hackage.haskell.org/package/cabal-dev) also work).
c. or (easiest) erase your installed packages with
[ghc-pkg-reset](https://gist.github.com/1185421) and try again.
For more detail, see [How to cabal install](https://www.fpcomplete.com/user/simonmichael/how-to-cabal-install).
#. **Dependency or compilation error in one of the new packages ?**
If cabal starts downloading and building packages and then terminates
with an error, look at the output carefully and identify the problem
package(s). If necessary, add `-v2` or `-v3` for more verbose
output. You can install the new packages one at a time to troubleshoot,
but remember cabal is smarter when installing all packages at once.
Often the problem is that you need to install a particular C library
using your platform's package management system. Or the dependencies
specified on a package may need updating. Or there may be a compilation
error. If you find an error in a hledger package, check the
[recent commits](http://github.com/simonmichael/hledger/commits) to
see if the [latest development version](#installing) might have a fix.
#. **ExitFailure 11**
See
[http://hackage.haskell.org/trac/hackage/ticket/777](http://hackage.haskell.org/trac/hackage/ticket/777).
This means that a build process has been killed, usually because it grew
too large. This is common on memory-limited VPS's and with GHC 7.4.1.
Look for some memory-hogging processes you can kill, increase your RAM,
or limit GHC's heap size by doing `cabal install ... --ghc-options='+RTS
-M400m'` (400 megabytes works well on my 1G VPS, adjust up or down..)
#. **Can't load .so/.DLL for: ncursesw (/usr/lib/libncursesw.so: file too short)**
(or similar): cf [GHC bug #5551](http://hackage.haskell.org/trac/ghc/ticket/5551).
Upgrade GHC to 7.2.1, or try your luck with [this workaround](http://eclipsefp.github.com/faq.html).
#. **Undefined iconv symbols on OS X**
This kind of error:
Linking dist/build/hledger/hledger ...
Undefined symbols:
"_iconv_close", referenced from:
_hs_iconv_close in libHSbase-4.2.0.2.a(iconv.o)
"_iconv", referenced from:
_hs_iconv in libHSbase-4.2.0.2.a(iconv.o)
"_iconv_open", referenced from:
_hs_iconv_open in libHSbase-4.2.0.2.a(iconv.o)
probably means you are on a mac with macports libraries installed, cf
[http://hackage.haskell.org/trac/ghc/ticket/4068](http://hackage.haskell.org/trac/ghc/ticket/4068).
To work around temporarily, add this --extra-lib-dirs flag:
$ cabal install hledger --extra-lib-dirs=/usr/lib
or permanently, add this to ~/.cabal/config:
extra-lib-dirs: /usr/lib
#. **hledger-vty requires curses-related libraries**
On Ubuntu, eg, you'll need the `libncurses5-dev` package. On Windows,
these are not available (unless perhaps via Cygwin.)
#. **hledger-chart requires GTK-related libraries**
On Ubuntu, eg, install the `libghc6-gtk-dev` package. See also [Gtk2Hs installation notes](http://code.haskell.org/gtk2hs/INSTALL).

46
site/content.yaml
View File

@ -4,10 +4,6 @@
data:
home: true
- title : Installing
url : INSTALL.html
source : INSTALL.md
# - title : Downloads
# url : DOWNLOAD.html
# source : DOWNLOAD.md
@ -16,13 +12,9 @@
url : NEWS.html
source : NEWS.md
- title : FAQ
url : FAQ.html
source : FAQ.md
- User Manual:
- Manual:
- title : Latest
- title : Latest Manual
url : MANUAL.html
source : MANUAL.md
@ -34,27 +26,29 @@
url : 0.21/MANUAL.html
source : 0.21/MANUAL.md
- How-tos:
- Wiki:
- title : Installing
url : wiki/installing
template : null.st
- title : FAQ
url : wiki/faq
template : null.st
# - How-tos:
- title : How to read CSV files
url : CSV.html
source : CSV.md
url : wiki/how_to_read_csv_files
template : null.st
- title : How to use account aliases
url : ALIASES.html
source : ALIASES.md
url : wiki/how_to_use_account_aliases
template : null.st
- title : More docs
url : DOCS.html
source : DOCS.md
- title : Developer guide
url : DEVELOP.html
source : DEVELOP.md
- title : Wiki
url : wiki
template : null.st
- title : Developer Guide
url : wiki/developer_guide
template : null.st
- title : hledger-web demo
url : demo

15
site/files/css/style.css
View File

@ -2,7 +2,7 @@
/* list-style-type:none; */
/* } */
/* div#nav { margin-top: 2em; } */
div#nav { padding-top: 2em; }
/* div#nav ul { margin-top: 0; margin-left: 1em; margin-bottom: 0; } */
/* div#nav ul li { list-style: none; padding-bottom: 0.1em; } */
div#nav ul li.current {
@ -10,11 +10,18 @@ div#nav ul li.current {
font-weight:bold;
}
div#nav a:active {
position:relative;
top:1px;
div#nav ul li.current {
/* list-style: square; */
font-weight:bold;
}
ul.nav ul {
padding-left:30px;
}
/* ul.nav ul li { */
/* list-style:none; */
/* } */
code {
color: #226600;
font-weight:bold;

8
site/files/js/nav.js
View File

@ -1,7 +1,9 @@
$(document).ready(function(){
$("div#nav li > ul").hide();
$("div#nav li > ul.active").show();
/*$("div#nav li > ul").hide();*/
/*$("div#nav li > ul.active").show();*/
$("div#nav ul li a").click(function(event){
$(event.target).parent().children("ul").slideToggle("fast");
// $(event.target).parent().children("ul").slideToggle("fast");
if ($(event.target).html() == "User Manual »") document.location = "/MANUAL.html";
else if ($(event.target).html() == "Wiki »") document.location = "/wiki";
});
});