options, docs, and notes cleanup

NOTES

@@ -10,7 +10,6 @@ clever tricks like the plague." --Edsger Dijkstra
 
 * to do
 ** errors
-*** register report should sort by date
 ** features
 *** more ledger features
 **** rename entry -> transaction, transaction -> posting
@@ -44,7 +43,7 @@ clever tricks like the plague." --Edsger Dijkstra
 **** speed regression tests
 ** tests
 *** test all esoteric ledger file features
-*** wanted: a test for reading a ledger from stdin
+*** test reading from stdin
 *** easy ledger compatibility testing
 **** --compare to compare (xml?) output with ledger with same args
 ** docs
@@ -253,6 +252,7 @@ competitors/fellow niche inhabitants
 *** readme
 **** keep in sync (automate)
 ***** README file
+****** options list in Features should match Options.hs, generate from hledger --help ?
 ***** hledger.hs module description
 ***** hledger.cabal description field (exclude home page link)
 ***** home page description (http://joyful.com/Hledger/editform)
@@ -273,7 +273,7 @@ competitors/fellow niche inhabitants
 ****** we test continuously and thoroughly (code, doc & speed tests on each checkin)
 ****** less is more
 *** user manual
-*** differences not noted in README
+*** other differences not noted in README
 **** ledger shows description comments as part of description
 **** ledger seems to get amounts' x-position wrong more than hledger
 **** ledger can't parse full smart dates in display expressions

Options.hs

@@ -24,35 +24,34 @@ usagehdr = printf (
   "  %s [OPTIONS] COMMAND [PATTERNS]\n" ++
   "  %s [OPTIONS] [PERIOD [COMMAND [PATTERNS]]]\n" ++
   "\n" ++
-  "Commands (can be abbreviated):\n" ++
+  "COMMAND is one of (may be abbreviated):\n" ++
   "  balance  - show account balances\n" ++
   "  print    - show formatted ledger entries\n" ++
   "  register - show register transactions\n" ++
 #ifdef VTY
-  "  ui       - run a simple vty-based text ui\n" ++
+  "  ui       - run a simple curses-based text ui\n" ++
 #endif
 #ifdef ANSI
   "  ansi     - run a simple ansi-based text ui\n" ++
 #endif
 #ifdef HAPPS
-  "  web      - run a simple web interface on port 5000\n" ++
+  "  web      - run a simple web ui\n" ++
 #endif
+  "  test     - run self-tests\n" ++
   "\n" ++
   "PATTERNS are regular expressions which filter by account name.\n" ++
   "Or, prefix with desc: to filter by entry description.\n" ++
   "Or, prefix with not: to negate a pattern. (When using both, not: comes last.)\n" ++
   "\n" ++
+  "Dates can be y/m/d or ledger-style smart dates like \"last month\".\n" ++
+  "\n" ++
   "Options:"
   ) progname timeprogname
   
 
 usageftr = printf (
-  "\n" ++
-  "All dates can be y/m/d or ledger-style smart dates like \"last month\".\n" ++
-  "\n" ++
-  "Also: %s [-v] test [TESTPATTERNS] to run self-tests.\n" ++
   "\n"
-  ) progname
+  )
 
 usage = usageInfo usagehdr options ++ usageftr
 
@@ -65,26 +64,27 @@ options = [
  ,Option ['p'] ["period"]       (ReqArg Period "EXPR") ("report on entries during the specified period\n" ++
                                                        "and/or with the specified reporting interval\n")
  ,Option ['C'] ["cleared"]      (NoArg  Cleared)       "report only on cleared entries"
- ,Option ['B'] ["cost","basis"] (NoArg  CostBasis)     "report cost basis of commodities"
+ ,Option ['B'] ["cost","basis"] (NoArg  CostBasis)     "report cost of commodities"
- ,Option []    ["depth"]        (ReqArg Depth "N")     "balance report: maximum account depth to show"
+ ,Option []    ["depth"]        (ReqArg Depth "N")     "hide accounts/transactions deeper than this"
- ,Option ['d'] ["display"]      (ReqArg Display "EXPR") ("display only transactions matching simple EXPR\n" ++
+ ,Option ['d'] ["display"]      (ReqArg Display "EXPR") ("show only transactions matching simple EXPR\n" ++
                                                         "(where EXPR is 'dOP[DATE]', OP is <, <=, =, >=, >)")
- ,Option ['E'] ["empty"]        (NoArg  Empty)         "balance report: show accounts with zero balance"
+ ,Option ['E'] ["empty"]        (NoArg  Empty)         "show empty/zero things which are normally elided"
  ,Option ['R'] ["real"]         (NoArg  Real)          "report only on real (non-virtual) transactions"
- ,Option ['n'] ["collapse"]     (NoArg  Collapse)      "balance report: no grand total"
+-- ,Option ['s'] ["subtotal"]     (NoArg  SubTotal)      "balance report: show subaccounts"
- ,Option ['s'] ["subtotal"]     (NoArg  SubTotal)      "balance report: show subaccounts"
  ,Option ['W'] ["weekly"]       (NoArg  WeeklyOpt)     "register report: show weekly summary"
  ,Option ['M'] ["monthly"]      (NoArg  MonthlyOpt)    "register report: show monthly summary"
  ,Option ['Y'] ["yearly"]       (NoArg  YearlyOpt)     "register report: show yearly summary"
  ,Option ['h'] ["help"] (NoArg  Help)                  "show this help"
- ,Option ['v'] ["verbose"]      (NoArg  Verbose)       "verbose test output"
+ ,Option ['V'] ["version"]      (NoArg  Version)       "show version information"
- ,Option ['V'] ["version"]      (NoArg  Version)       "show version"
+ ,Option ['v'] ["verbose"]      (NoArg  Verbose)       "show verbose test output"
- ,Option []    ["debug"]        (NoArg  Debug)         "debug output"
+ ,Option []    ["debug"]        (NoArg  Debug)         "show some debug output"
- ,Option []    ["debug-no-ui"]  (NoArg  DebugNoUI)     "run ui commands without no output"
+ ,Option []    ["debug-no-ui"]  (NoArg  DebugNoUI)     "run ui commands with no output"
  ]
     where 
-      filehelp = printf "ledger file; - means use standard input. Defaults\nto the %s environment variable or %s"
+      filehelp = printf (intercalate "\n"
-                 ledgerenvvar ledgerpath
+                         ["ledger file; default is the %s env. variable's"
+                         ,"value, or %s. - means use standard input."
+                         ]) ledgerenvvar ledgerpath
 
 -- | An option value from a command-line flag.
 data Opt = 
@@ -98,7 +98,6 @@ data Opt =
     Display {value::String} | 
     Empty | 
     Real | 
-    Collapse |
     SubTotal |
     WeeklyOpt |
     MonthlyOpt |

README

@@ -4,13 +4,10 @@ hledger - a ledger-compatible text-based accounting tool
 Welcome to hledger! 
 
 hledger is a partial haskell clone of John Wiegley's text-based accounting
-tool, ledger (http://wiki.github.com/jwiegley/ledger).  
+tool, ledger (http://wiki.github.com/jwiegley/ledger). hledger generates
-
+ledger-compatible register & balance reports from a plain text journal,
-hledger generates ledger-compatible register & balance reports from a
+and demonstrates a functional implementation of ledger.  For more
-plain text journal, and demonstrates a functional implementation of
+information, see http://hledger.org .
-ledger.  
-
-For more information, see http://hledger.org .
 
 Copyright (c) 2007-2009 Simon Michael <simon@joyful.com>
 Released under GPL version 3 or later.
@@ -39,7 +36,7 @@ dependencies)::
 
 The available flags are::
 
-  happs - enable the built-in webserver
+  happs - enable the webserver ui
   vty   - enable the curses text ui
   ansi  - enable the ansi text ui (use instead of vty on MS windows)
 
@@ -88,58 +85,61 @@ Examples::
 Features
 --------
 
-This version of hledger mimics a subset of ledger 2.6.1, and adds some
+This version of hledger mimics a subset of ledger 3.x, and adds some
-features of its own. We currently support: the balance, print, and
+features of its own. We currently support regular ledger entries, timelog
-register commands, regular ledger entries, multiple commodities, virtual
+entries, multiple commodities, virtual transactions, account and
-transactions, account and description patterns, the LEDGER environment
+description patterns, the LEDGER environment variable, and these commands
-variable, and these options::
+and options::
-
-   Basic options:
-   -h, --help             display summarized help text
-   -v, --version          show version information
-   -f, --file FILE        read ledger data from FILE
- 
-   Report filtering:
-   -b, --begin DATE       set report begin date
-   -e, --end DATE         set report end date
-   -p, --period EXPR      report using the given period
-   -C, --cleared          consider only cleared transactions
-   -R, --real             consider only real (non-virtual) transactions
- 
-   Output customization:
-   -n, --collapse         balance report: no grand total
-   -d, --display EXPR     display only transactions matching EXPR (limited support)
-   -E, --empty            balance report: show accounts with zero balance
-   -s, --subtotal         balance report: show sub-accounts
- 
-   Commodity reporting:
-   -B, --basis, --cost    report cost basis of commodities
 
    Commands:
    balance  [REGEXP]...   show balance totals for matching accounts
    register [REGEXP]...   show register of matching transactions
    print    [REGEXP]...   print all matching entries
 
-We handle (almost) the full period expression syntax, and simple display
+   Basic options:
-expressions consisting of a date predicate.  Also the following
+   -h, --help             show summarized help
-hledger-specific features are supported::
+   -f, --file FILE        read ledger data from FILE
  
-   ui                     a simple curses-based text ui (unix platforms only)
+   Report filtering:
-   ansi                   an even more rudimentary ansi-based text ui
+   -b, --begin DATE       report on entries on or after this date
-   web                    a simple web interface on port 5000
+   -e, --end DATE         report on entries prior to this date
-   --depth=N              balance report: maximum account depth to show
+   -p, --period EXPR      report on entries during the specified period
+                          and/or with the specified reporting interval
+   -C, --cleared          report only on cleared entries
+   -R, --real             report only on real (non-virtual) transactions
+ 
+   Output customization:
+   -B, --basis, --cost    report cost of commodities
+   -d, --display EXPR     display only transactions matching EXPR (limited support)
+   -E, --empty            show empty/zero things which are normally elided
+   --no-total             balance report: hide the final total
+   -W, --weekly           register report: show weekly summary
+   -M, --monthly          register report: show monthly summary
+   -Y, --yearly           register report: show yearly summary
+
+   Misc:
+   -V, --version          show version information
+   -v, --verbose          show verbose test output
+   --debug                show some debug output 
+   --debug-no-ui          run ui commands with no output
+
+We handle (almost) the full period expression syntax, and very limited
+display expressions consisting of a simple date predicate. Also the
+following new commands are supported::
+
+   ui                     a simple curses-based text ui (on windows, ansi-based)
+   web                    a simple web-based ui
+   test                   run self-tests
 
 ledger features not supported
 .............................
 
-ledger features not yet supported include: modifier and periodic entries,
+ledger features not currently supported include: modifier and periodic
-parsing gnucash files, and the following options::
+entries, and options such as these::
 
    Basic options:
    -o, --output FILE      write output to FILE
    -i, --init-file FILE   initialize ledger using FILE (default: ~/.ledgerrc)
-       --cache FILE       use FILE as a binary cache when --file is not used
-       --no-cache         don't use a cache, even if it would be appropriate
    -a, --account NAME     use NAME for the default account (useful with QIF)
  
    Report filtering:
@@ -157,13 +157,10 @@ parsing gnucash files, and the following options::
    -T, --total EXPR       use EXPR to calculate the displayed total
  
    Output customization:
-   -n, --collapse         register: collapse entries
+   -n, --collapse         Only show totals in the top-most accounts.
    -s, --subtotal         other: show subtotals
    -P, --by-payee         show summarized totals by payee
    -x, --comm-as-payee    set commodity name as the payee, for reporting
-   -W, --weekly           show weekly sub-totals
-   -M, --monthly          show monthly sub-totals
-   -Y, --yearly           show yearly sub-totals
        --dow              show a days-of-the-week report
    -S, --sort EXPR        sort report according to the value expression EXPR
    -w, --wide             for the default register report, use 132 columns
@@ -200,13 +197,14 @@ parsing gnucash files, and the following options::
 Other differences
 .................
 
-* hledger accepts options anywhere on the command line. Instead of - and --
+* hledger calls the "note" field "description"
-  for pattern negation and separation, use ^ and ^^.
+* hledger recognises description and negative patterns by  "desc:" and "not:" prefixes,
-* hledger always keeps differently-priced amounts of the same commodity separate
+  unlike ledger 3's free-form parser
-* hledger calls ledger's "note" field "description"
+* hledger keeps differently-priced amounts of the same commodity separate
 * hledger doesn't require a space before command-line option values, eg: -f-
-* hledger provides "--cost" as a synonym for "--basis"
 * 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 period expressions don't support "biweekly", "bimonthly", or "every N days/weeks/..." 
 * hledger always shows timelog balances in hours
+* hledger splits multi-day timelog sessions at midnight
+* hledger register report always sorts transactions by date

hledger.cabal

@@ -20,15 +20,15 @@ Extra-Tmp-Files:
 Cabal-Version:  >= 1.2
 
 Flag happs
-  description: Build web-based ui (requires happstack)
+  description: enable the webserver ui
   default:     False
 
 Flag vty
-  description: Build vty-based text ui (requires vty)
+  description: enable the curses test ui
   default:     False
 
 Flag ansi
-  description: Build ansi-based text ui (requires ansi-terminal, use instead of vty on windows)
+  description: enable the ansi text ui (use instead of vty on MS windows)
   default:     False
 
 Library