From 938abfbbfa289c6e90be4f2fb89c595e38c0bee2 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 2 Apr 2009 23:02:12 +0000 Subject: [PATCH] docs polish --- NEWS | 15 +++++++-------- README | 47 +++++++++++++++++++++++++++++------------------ 2 files changed, 36 insertions(+), 26 deletions(-) diff --git a/NEWS b/NEWS index 2f8e179dd..eb5f61b90 100644 --- a/NEWS +++ b/NEWS @@ -9,27 +9,26 @@ Changes: * avoid bulky/non-portable dependencies by default, curses ui now requires a build flag (-f vty) * on MS windows, provide a simple ansi-based ui in place of vty (-f ansi) - * new "web" command starts a webserver and shows filterable reports in a browser (-f happs) + * new "web" command starts a webserver and shows reports in a browser (-f happs) * drop the --options-anywhere flag, that is now the default * patterns now use not: and desc: prefixes instead of ^ and ^^ * patterns are now case-insensitive, like ledger * !include directives are now relative to the including file (Tim Docker) * "Y2009" default year directives are now supported, allowing m/d dates in ledger * individual transactions now have a cleared status - * unbalanced entries are now reported properly + * unbalanced entries now cause a proper warning * balance report now passes all ledger compatibility tests * balance report now shows subtotals by default, like ledger 3 - * show the balance report's zero total when -E is used - * --no-total hides balance report's final total + * balance report shows the final zero total when -E is used + * balance report hides the final total when --no-total is used * --depth affects print and register reports (aggregating with a reporting interval, filtering otherwise) - * register command sorts transactions by date - * -E works in register report + * register report sorts transactions by date + * register report shows zero-amount transactions when -E is used * provide more convenient timelog querying when invoked as "hours" * multi-day timelog sessions are split at midnight * unterminated timelog sessions are now counted. Accurate time reports at last! * the test command gives better --verbose output * --version gives more detailed version numbers including patchlevel for dev builds - * haddock & hoogle docs now include optional build components * new make targets include: ghci, haddocktest, doctest, unittest, view-api-docs * a doctest-style framework for functional/shell tests has been added * performance has decreased slightly:: @@ -45,7 +44,7 @@ Contributors: * Simon Michael * Tim Docker - * happstack and testpack developers + * HAppS, happstack and testpack developers Stats: ...... diff --git a/README b/README index 00fe74645..5d73b1f9e 100644 --- a/README +++ b/README @@ -1,11 +1,12 @@ Welcome to hledger! -hledger is a limited haskell clone of John Wiegley's text-based accounting +hledger is a partial haskell clone of John Wiegley's text-based accounting tool, ledger (http://wiki.github.com/jwiegley/ledger). hledger generates ledger-compatible register & balance reports from a plain text journal, -provides simple interactive querying, and demonstrates a functional -implementation of ledger. For more information, see http://hledger.org . +allows precise batch-mode or interactive querying, and demonstrates a pure +functional implementation of ledger. For more information, see +http://hledger.org . Copyright (c) 2007-2009 Simon Michael Released under GPL version 3 or later. @@ -13,13 +14,14 @@ Released under GPL version 3 or later. Installation ------------ + Building hledger requires GHC (http://haskell.org/ghc); it is known to build with GHC 6.8 and up. hledger should work on any platform which GHC -supports. +supports. Also, installing hledger easily requires the "cabal" command-line tool, version 0.6.0 and up (http://www.haskell.org/cabal/download.html). (You -can also manually download and install each dependency mentioned in +can manually download and install each dependency mentioned in hledger.cabal from hackage.org, but installing cabal is much quicker.) Here's how to download and install the latest hledger release:: @@ -38,44 +40,53 @@ The available flags are:: vty - enable the curses text ui ansi - enable the ansi text ui (use instead of vty on MS windows) -And for developers, here's how to get the latest development code:: +For developers, here's how to get the latest code:: darcs get http://joyful.com/repos/hledger Usage ----- + hledger looks for your ledger file at ~/.ledger by default. To use a different file, specify it with the LEDGER environment variable or -f -option (which may be - for standard input). Here are some commands to try:: +option (which may be - for standard input). Basic usage is:: + + hledger [OPTIONS] COMMAND [PATTERNS] + +where COMMAND is one of balance, print, register, ui, web, test; and +PATTERNS are zero or more regular expressions used to narrow the results. +Here are some commands to try:: hledger --help - hledger -f sample.ledger balance export LEDGER=sample.ledger - hledger balance --depth 1 + hledger balance + hledger bal --depth 1 hledger register hledger reg income hledger reg desc:shop - hledger ui + hledger ui # if you installed with -f vty or ansi + hledger web # if you installed with -f happs Time reporting -------------- -If hledger is invoked by the "hours" alias it looks for your timelog -(~/.timelog, or the file specified by $TIMELOG or -f), and parses -arguments slightly differently for convenient timelog querying:: +hledger will also read timeclock.el-format timelog entries. As a +convenience, if you invoke the hledger executable via a link or copy named +"hours", it looks for your timelog file (~/.timelog, or the file specified +by $TIMELOG or -f), and parses arguments slightly differently:: hours [OPTIONS] [PERIOD [COMMAND [PATTERNS]]] -where PERIOD and COMMAND are "today" and "balance" by default. -The timelog file is in timeclock.el's format, where an entry looks like:: +where PERIOD is a ledger-style period expression, defaulting to "today", +and COMMAND is one of the commands above. Timelog entries look like this:: - i 2009/03/31 22:21:45 work:hledger + i 2009/03/31 22:21:45 some:project o 2009/04/01 02:00:34 -Time categories are treated as accounts. Here are some time queries to try:: +The clock-in project is treated as an account. Here are some time queries to try:: - export TIMELOG=/my/timelog # if not ~/.timelog + export TIMELOG=/my/timelog # if it's not ~/.timelog hours # today's balances hours today # the same hours 'this week' # so far this week