doc: add 1.5 manuals snapshot

doc/lib.m4

@@ -20,6 +20,7 @@ This doc is for version **_version_**.
 m4_dnl Too painful for static generation, insert from site.js instead
 m4_dnl Available versions:
 m4_dnl <a href="/$1.html">dev</a>
+m4_dnl | <a href="/doc/1.5/$1.html">1.5</a>
 m4_dnl | <a href="/doc/1.4/$1.html">1.4</a>
 m4_dnl | <a href="/doc/1.3/$1.html">1.3</a>
 m4_dnl | <a href="/doc/1.2/$1.html">1.2</a>

site/doc/1.5/csv.md

@@ -0,0 +1,273 @@
+# csv format
+
+This doc is for version **1.5**. []{.docversions}
+
+-   toc
+
+## NAME
+
+CSV - how hledger reads CSV data, and the CSV rules file format
+
+## DESCRIPTION
+
+hledger can read
+[CSV](http://en.wikipedia.org/wiki/Comma-separated_values)
+(comma-separated value) files as if they were journal files,
+automatically converting each CSV record into a transaction. (To learn
+about *writing* CSV, see [CSV output](hledger.html#csv-output).)
+
+Converting CSV to transactions requires some special conversion rules.
+These do several things:
+
+-   they describe the layout and format of the CSV data
+-   they can customize the generated journal entries using a simple
+    templating language
+-   they can add refinements based on patterns in the CSV data, eg
+    categorizing transactions with more detailed account names.
+
+When reading a CSV file named `FILE.csv`, hledger looks for a conversion
+rules file named `FILE.csv.rules` in the same directory. You can
+override this with the `--rules-file` option. If the rules file does not
+exist, hledger will auto-create one with some example rules, which
+you'll need to adjust.
+
+At minimum, the rules file must identify the `date` and `amount` fields.
+It may also be necessary to specify the date format, and the number of
+header lines to skip. Eg:
+
+    fields date, _, _, amount
+    date-format  %d/%m/%Y
+    skip 1
+
+A more complete example:
+
+    # hledger CSV rules for amazon.com order history
+
+    # sample:
+    # "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"
+    # "Jul 29, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$0.00","17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL"
+
+    # skip one header line
+    skip 1
+
+    # name the csv fields (and assign the transaction's date, amount and code)
+    fields date, _, toorfrom, name, amzstatus, amount, fees, code
+
+    # how to parse the date
+    date-format %b %-d, %Y
+
+    # combine two fields to make the description
+    description %toorfrom %name
+
+    # save these fields as tags
+    comment     status:%amzstatus, fees:%fees
+
+    # set the base account for all transactions
+    account1    assets:amazon
+
+    # flip the sign on the amount
+    amount      -%amount
+
+For more examples, see [Convert CSV files](csv-import.html).
+
+## CSV RULES
+
+The following seven kinds of rule can appear in the rules file, in any
+order. Blank lines and lines beginning with `#` or `;` are ignored.
+
+### skip
+
+`skip`*`N`*
+
+Skip this number of CSV records at the beginning. You'll need this
+whenever your CSV data contains header lines. Eg: <!-- XXX -->
+<!-- hledger tries to skip initial CSV header lines automatically. -->
+<!-- If it guesses wrong, use this directive to skip exactly N lines. -->
+<!-- This can also be used in a conditional block to ignore certain CSV records. -->
+
+``` {.rules}
+# ignore the first CSV line
+skip 1
+```
+
+### date-format
+
+`date-format`*`DATEFMT`*
+
+When your CSV date fields are not formatted like `YYYY/MM/DD` (or
+`YYYY-MM-DD` or `YYYY.MM.DD`), you'll need to specify the format.
+DATEFMT is a [strptime-like date parsing
+pattern](http://hackage.haskell.org/packages/archive/time/latest/doc/html/Data-Time-Format.html#v:formatTime),
+which must parse the date field values completely. Examples:
+
+``` {.rules .display-table}
+# for dates like "6/11/2013":
+date-format %-d/%-m/%Y
+```
+
+``` {.rules .display-table}
+# for dates like "11/06/2013":
+date-format %m/%d/%Y
+```
+
+``` {.rules .display-table}
+# for dates like "2013-Nov-06":
+date-format %Y-%h-%d
+```
+
+``` {.rules .display-table}
+# for dates like "11/6/2013 11:32 PM":
+date-format %-m/%-d/%Y %l:%M %p
+```
+
+### field list
+
+`fields`*`FIELDNAME1`*, *`FIELDNAME2`*...
+
+This (a) names the CSV fields, in order (names may not contain
+whitespace; uninteresting names may be left blank), and (b) assigns them
+to journal entry fields if you use any of these standard field names:
+`date`, `date2`, `status`, `code`, `description`, `comment`, `account1`,
+`account2`, `amount`, `amount-in`, `amount-out`, `currency`, `balance`.
+Eg:
+
+``` {.rules}
+# use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount,
+# and give the 7th and 8th fields meaningful names for later reference:
+#
+# CSV field:
+#      1     2            3 4       5 6 7          8
+# entry field:
+fields date, description, , amount, , , somefield, anotherfield
+```
+
+### field assignment
+
+*`ENTRYFIELDNAME`* *`FIELDVALUE`*
+
+This sets a journal entry field (one of the standard names above) to the
+given text value, which can include CSV field values interpolated by
+name (`%CSVFIELDNAME`) or 1-based position (`%N`).
+<!-- Whitespace before or after the value is ignored. --> Eg:
+
+``` {.rules .display-table}
+# set the amount to the 4th CSV field with "USD " prepended
+amount USD %4
+```
+
+``` {.rules .display-table}
+# combine three fields to make a comment (containing two tags)
+comment note: %somefield - %anotherfield, date: %1
+```
+
+Field assignments can be used instead of or in addition to a field list.
+
+### conditional block
+
+`if` *`PATTERN`*\
+    *`FIELDASSIGNMENTS`*...
+
+`if`\
+*`PATTERN`*\
+*`PATTERN`*...\
+    *`FIELDASSIGNMENTS`*...
+
+This applies one or more field assignments, only to those CSV records
+matched by one of the PATTERNs. The patterns are case-insensitive
+regular expressions which match anywhere within the whole CSV record
+(it's not yet possible to match within a specific field). When there are
+multiple patterns they can be written on separate lines, unindented. The
+field assignments are on separate lines indented by at least one space.
+Examples:
+
+``` {.rules .display-table}
+# if the CSV record contains "groceries", set account2 to "expenses:groceries"
+if groceries
+ account2 expenses:groceries
+```
+
+``` {.rules .display-table}
+# if the CSV record contains any of these patterns, set account2 and comment as shown
+if
+monthly service fee
+atm transaction fee
+banking thru software
+ account2 expenses:business:banking
+ comment  XXX deductible ? check it
+```
+
+### include
+
+`include`*`RULESFILE`*
+
+Include another rules file at this point. `RULESFILE` is either an
+absolute file path or a path relative to the current file's directory.
+Eg:
+
+``` {.rules}
+# rules reused with several CSV files
+include common.rules
+```
+
+### newest-first
+
+`newest-first`
+
+Consider adding this rule if all of the following are true: you might be
+processing just one day of data, your CSV records are in reverse
+chronological order (newest first), and you care about preserving the
+order of same-day transactions. It usually isn't needed, because hledger
+autodetects the CSV order, but when all CSV records have the same date
+it will assume they are oldest first.
+
+## CSV TIPS
+
+### CSV ordering
+
+The generated [journal entries](/journal.html#transactions) will be
+sorted by date. The order of same-day entries will be preserved (except
+in the special case where you might need
+[`newest-first`](#newest-first), see above).
+
+### CSV accounts
+
+Each journal entry will have two [postings](/journal.html#postings), to
+`account1` and `account2` respectively. It's not yet possible to
+generate entries with more than two postings. It's conventional and
+recommended to use `account1` for the account whose CSV we are reading.
+
+### CSV amounts
+
+The `amount` field sets the [amount](/journal.html#amounts) of the
+`account1` posting.
+
+If the CSV has debit/credit amounts in separate fields, assign to the
+`amount-in` and `amount-out` pseudo fields instead. (Whichever one has a
+value will be used, with appropriate sign. If both contain a value, it
+may not work so well.)
+
+If an amount value is parenthesised, it will be de-parenthesised and
+sign-flipped.
+
+If an amount value begins with a double minus sign, those will cancel
+out and be removed.
+
+If the CSV has the currency symbol in a separate field, assign that to
+the `currency` pseudo field to have it prepended to the amount. Or, you
+can use a [field assignment](#field-assignment) to `amount` that
+interpolates both CSV fields (giving more control, eg to put the
+currency symbol on the right).
+
+### CSV balance assertions
+
+If the CSV includes a running balance, you can assign that to the
+`balance` pseudo field; whenever the running balance value is non-empty,
+it will be [asserted](/journal.html#balance-assertions) as the balance
+after the `account1` posting.
+
+### Reading multiple CSV files
+
+You can read multiple CSV files at once using multiple `-f` arguments on
+the command line, and hledger will look for a correspondingly-named
+rules file for each. Note if you use the `--rules-file` option, this one
+rules file will be used for all the CSV files being read.

site/doc/1.5/hledger-api.md

@@ -0,0 +1,86 @@
+# hledger-api
+
+This doc is for version **1.5**. []{.docversions}
+
+-   toc
+
+## NAME
+
+hledger-api - web API server for the hledger accounting tool
+
+## SYNOPSIS
+
+`hledger-api [OPTIONS]`\
+`hledger api -- [OPTIONS]`
+
+## DESCRIPTION
+
+hledger is a cross-platform program for tracking money, time, or any
+other commodity, using double-entry accounting and a simple, editable
+file format. hledger is inspired by and largely compatible with
+ledger(1).
+
+hledger-api is a simple web API server, intended to support client-side
+web apps operating on hledger data. It comes with a series of simple
+client-side app examples, which drive its evolution.
+
+Like hledger, it reads data from one or more files in hledger journal,
+timeclock, timedot, or CSV format specified with `-f`, or
+`$LEDGER_FILE`, or `$HOME/.hledger.journal` (on windows, perhaps
+`C:/Users/USER/.hledger.journal`). For more about this see hledger(1),
+hledger\_journal(5) etc.
+
+The server listens on IP address 127.0.0.1, accessible only to local
+requests, by default. You can change this with `--host`, eg
+`--host 0.0.0.0` to listen on all addresses. Note there is no other
+access control, so you will need to hide hledger-api behind an
+authenticating proxy if you want to restrict access. You can change the
+TCP port (default: 8001) with `-p PORT`.
+
+If invoked as `hledger-api --swagger`, instead of starting a server the
+API docs will be printed in Swagger 2.0 format.
+
+## OPTIONS
+
+Note: if invoking hledger-api as a hledger subcommand, write `--` before
+options as shown above.
+
+`-f --file=FILE`
+:   use a different input file. For stdin, use - (default:
+    `$LEDGER_FILE` or `$HOME/.hledger.journal`)
+
+`-d --static-dir=DIR`
+:   serve files from a different directory (default: `.`)
+
+`--host=IPADDR`
+:   listen on this IP address (default: 127.0.0.1)
+
+`-p --port=PORT`
+:   listen on this TCP port (default: 8001)
+
+`--swagger`
+:   print API docs in Swagger 2.0 format, and exit
+
+`--version`
+:   show version
+
+`-h --help`
+:   show usage
+
+## ENVIRONMENT
+
+**LEDGER\_FILE** The journal file path when not specified with `-f`.
+Default: `~/.hledger.journal` (on windows, perhaps
+`C:/Users/USER/.hledger.journal`).
+
+## FILES
+
+Reads data from one or more files in hledger journal, timeclock,
+timedot, or CSV format specified with `-f`, or `$LEDGER_FILE`, or
+`$HOME/.hledger.journal` (on windows, perhaps
+`C:/Users/USER/.hledger.journal`).
+
+## BUGS
+
+The need to precede options with `--` when invoked from hledger is
+awkward.

site/doc/1.5/hledger-ui.md

@@ -0,0 +1,406 @@
+# hledger-ui
+
+This doc is for version **1.5**. []{.docversions}
+
+-   toc
+
+## NAME
+
+hledger-ui - curses-style interface for the hledger accounting tool
+
+## SYNOPSIS
+
+`hledger-ui [OPTIONS] [QUERYARGS]`\
+`hledger ui -- [OPTIONS] [QUERYARGS]`
+
+## DESCRIPTION
+
+hledger is a cross-platform program for tracking money, time, or any
+other commodity, using double-entry accounting and a simple, editable
+file format. hledger is inspired by and largely compatible with
+ledger(1).
+
+<style>
+.highslide img {max-width:200px; border:0;}
+.highslide-caption {color:white; background-color:black;}
+</style>
+::: {style="float:right; max-width:200px; text-align:right;"}
+<a href="images/hledger-ui/hledger-ui-sample-acc2.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-sample-acc2.png" title="Accounts screen with query and depth limit" /></a>
+<a href="images/hledger-ui/hledger-ui-sample-acc.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-sample-acc.png" title="Accounts screen" /></a>
+<a href="images/hledger-ui/hledger-ui-sample-acc-greenterm.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-sample-acc-greenterm.png" title="Accounts screen with greenterm theme" /></a>
+<a href="images/hledger-ui/hledger-ui-sample-txn.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-sample-txn.png" title="Transaction screen" /></a>
+<a href="images/hledger-ui/hledger-ui-sample-reg.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-sample-reg.png" title="Register screen" /></a>
+<!-- <br clear=all> -->
+<a href="images/hledger-ui/hledger-ui-bcexample-acc.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-bcexample-acc.png" title="beancount example accounts" /></a>
+<a href="images/hledger-ui/hledger-ui-bcexample-acc-etrade-cash.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-bcexample-acc-etrade-cash.png" title="beancount example's etrade cash subaccount" /></a>
+<a href="images/hledger-ui/hledger-ui-bcexample-acc-etrade.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-bcexample-acc-etrade.png" title="beancount example's etrade investments, all commoditiess" /></a>
+:::
+
+hledger-ui is hledger's curses-style interface, providing an efficient
+full-window text UI for viewing accounts and transactions, and some
+limited data entry capability. It is easier than hledger's command-line
+interface, and sometimes quicker and more convenient than the web
+interface.
+
+Like hledger, it reads data from one or more files in hledger journal,
+timeclock, timedot, or CSV format specified with `-f`, or
+`$LEDGER_FILE`, or `$HOME/.hledger.journal` (on windows, perhaps
+`C:/Users/USER/.hledger.journal`). For more about this see hledger(1),
+hledger\_journal(5) etc.
+
+## OPTIONS
+
+Note: if invoking hledger-ui as a hledger subcommand, write `--` before
+options as shown above.
+
+Any QUERYARGS are interpreted as a hledger search query which filters
+the data.
+
+`--watch`
+:   watch for data and date changes and reload automatically
+
+`--theme=default|terminal|greenterm`
+:   use this custom display theme
+
+`--register=ACCTREGEX`
+:   start in the (first) matched account's register screen
+
+`--change`
+:   show period balances (changes) at startup instead of historical
+    balances
+
+`--flat`
+:   show full account names, unindented
+
+hledger input options:
+
+`-f FILE --file=FILE`
+:   use a different input file. For stdin, use - (default:
+    `$LEDGER_FILE` or `$HOME/.hledger.journal`)
+
+`--rules-file=RULESFILE`
+:   Conversion rules file to use when reading CSV (default: FILE.rules)
+
+`--alias=OLD=NEW`
+:   rename accounts named OLD to NEW
+
+`--anon`
+:   anonymize accounts and payees
+
+`--pivot FIELDNAME`
+:   use some other field or tag for the account name
+
+`-I --ignore-assertions`
+:   ignore any failing balance assertions
+
+hledger reporting options:
+
+`-b --begin=DATE`
+:   include postings/txns on or after this date
+
+`-e --end=DATE`
+:   include postings/txns before this date
+
+`-D --daily`
+:   multiperiod/multicolumn report by day
+
+`-W --weekly`
+:   multiperiod/multicolumn report by week
+
+`-M --monthly`
+:   multiperiod/multicolumn report by month
+
+`-Q --quarterly`
+:   multiperiod/multicolumn report by quarter
+
+`-Y --yearly`
+:   multiperiod/multicolumn report by year
+
+`-p --period=PERIODEXP`
+:   set start date, end date, and/or reporting interval all at once
+    using [period expressions](manual.html#period-expressions) syntax
+    (overrides the flags above)
+
+`--date2`
+:   match the secondary date instead (see command help for other
+    effects)
+
+`-U --unmarked`
+:   include only unmarked postings/txns (can combine with -P or -C)
+
+`-P --pending`
+:   include only pending postings/txns
+
+`-C --cleared`
+:   include only cleared postings/txns
+
+`-R --real`
+:   include only non-virtual postings
+
+`-NUM --depth=NUM`
+:   hide/aggregate accounts or postings more than NUM levels deep
+
+`-E --empty`
+:   show items with zero amount, normally hidden
+
+`-B --cost`
+:   convert amounts to their cost at transaction time (using the
+    [transaction price](journal.html#transaction-prices), if any)
+
+`-V --value`
+:   convert amounts to their market value on the report end date (using
+    the most recent applicable [market
+    price](journal.html#market-prices), if any)
+
+`--auto`
+:   apply [automated posting
+    rules](journal.html#automated-posting-rules) to modify transactions.
+
+`--forecast`
+:   apply [periodic transaction](journal.html#periodic-transactions)
+    rules to generate future transactions, to 6 months from now or
+    report end date.
+
+When a reporting option appears more than once in the command line, the
+last one takes precedence.
+
+Some reporting options can also be written as [query
+arguments](#queries).
+
+hledger help options:
+
+`-h --help`
+:   show general usage (or after COMMAND, command usage)
+
+`--version`
+:   show version
+
+`--debug[=N]`
+:   show debug output (levels 1-9, default: 1)
+
+A @FILE argument will be expanded to the contents of FILE, which should
+contain one command line option/argument per line. (To prevent this,
+insert a `--` argument before.)
+
+## KEYS
+
+`?` shows a help dialog listing all keys. (Some of these also appear in
+the quick help at the bottom of each screen.) Press `?` again (or
+`ESCAPE`, or `LEFT`) to close it. The following keys work on most
+screens:
+
+The cursor keys navigate: `right` (or `enter`) goes deeper, `left`
+returns to the previous screen,
+`up`/`down`/`page up`/`page down`/`home`/`end` move up and down through
+lists. Vi-style (`h`/`j`/`k`/`l`) and Emacs-style
+(`CTRL-p`/`CTRL-n`/`CTRL-f`/`CTRL-b`) movement keys are also supported.
+A tip: movement speed is limited by your keyboard repeat rate, to move
+faster you may want to adjust it. (If you're on a mac, the Karabiner app
+is one way to do that.)
+
+With shift pressed, the cursor keys adjust the report period, limiting
+the transactions to be shown (by default, all are shown).
+`shift-down/up` steps downward and upward through these standard report
+period durations: year, quarter, month, week, day. Then,
+`shift-left/right` moves to the previous/next period. `t` sets the
+report period to today. With the `--watch` option, when viewing a
+"current" period (the current day, week, month, quarter, or year), the
+period will move automatically to track the current date. To set a
+non-standard period, you can use `/` and a `date:` query.
+
+`/` lets you set a general filter query limiting the data shown, using
+the same [query terms](/hledger.html#queries) as in hledger and
+hledger-web. While editing the query, you can use [CTRL-a/e/d/k, BS,
+cursor
+keys](http://hackage.haskell.org/package/brick-0.7/docs/Brick-Widgets-Edit.html#t:Editor);
+press `ENTER` to set it, or `ESCAPE`to cancel. There are also keys for
+quickly adjusting some common filters like account depth and transaction
+status (see below). `BACKSPACE` or `DELETE` removes all filters, showing
+all transactions.
+
+`ESCAPE` removes all filters and jumps back to the top screen. Or, it
+cancels a minibuffer edit or help dialog in progress.
+
+`CTRL-l` redraws the screen and centers the selection if possible
+(selections near the top won't be centered, since we don't scroll above
+the top).
+
+`g` reloads from the data file(s) and updates the current screen and any
+previous screens. (With large files, this could cause a noticeable
+pause.)
+
+`I` toggles balance assertion checking. Disabling balance assertions
+temporarily can be useful for troubleshooting.
+
+`a` runs command-line hledger's add command, and reloads the updated
+file. This allows some basic data entry.
+
+`A` is like `a`, but runs the
+[hledger-iadd](http://hackage.haskell.org/package/hledger-iadd) tool,
+which provides a curses-style interface. This key will be available if
+`hledger-iadd` is installed in \$PATH.
+
+`E` runs \$HLEDGER\_UI\_EDITOR, or \$EDITOR, or a default
+(`emacsclient -a "" -nw`) on the journal file. With some editors (emacs,
+vi), the cursor will be positioned at the current transaction when
+invoked from the register and transaction screens, and at the error
+location (if possible) when invoked from the error screen.
+
+`q` quits the application.
+
+Additional screen-specific keys are described below.
+
+## SCREENS
+
+### Accounts screen
+
+This is normally the first screen displayed. It lists accounts and their
+balances, like hledger's balance command. By default, it shows all
+accounts and their latest ending balances (including the balances of
+subaccounts). if you specify a query on the command line, it shows just
+the matched accounts and the balances from matched transactions.
+
+Account names are normally indented to show the hierarchy (tree mode).
+To see less detail, set a depth limit by pressing a number key, `1` to
+`9`. `0` shows even less detail, collapsing all accounts to a single
+total. `-` and `+` (or `=`) decrease and increase the depth limit. To
+remove the depth limit, set it higher than the maximum account depth, or
+press `ESCAPE`.
+
+`F` toggles flat mode, in which accounts are shown as a flat list, with
+their full names. In this mode, account balances exclude subaccounts,
+except for accounts at the depth limit (as with hledger's balance
+command).
+
+`H` toggles between showing historical balances or period balances.
+Historical balances (the default) are ending balances at the end of the
+report period, taking into account all transactions before that date
+(filtered by the filter query if any), including transactions before the
+start of the report period. In other words, historical balances are what
+you would see on a bank statement for that account (unless disturbed by
+a filter query). Period balances ignore transactions before the report
+start date, so they show the change in balance during the report period.
+They are more useful eg when viewing a time log.
+
+`U` toggles filtering by [unmarked status](/journal.html#status),
+including or excluding unmarked postings in the balances. Similarly, `P`
+toggles pending postings, and `C` toggles cleared postings. (By default,
+balances include all postings; if you activate one or two status
+filters, only those postings are included; and if you activate all
+three, the filter is removed.)
+
+`R` toggles real mode, in which [virtual
+postings](/journal.html#virtual-postings) are ignored.
+
+`Z` toggles nonzero mode, in which only accounts with nonzero balances
+are shown (hledger-ui shows zero items by default, unlike command-line
+hledger).
+
+Press `right` or `enter` to view an account's transactions register.
+
+### Register screen
+
+This screen shows the transactions affecting a particular account, like
+a check register. Each line represents one transaction and shows:
+
+-   the other account(s) involved, in abbreviated form. (If there are
+    both real and virtual postings, it shows only the accounts affected
+    by real postings.)
+
+-   the overall change to the current account's balance; positive for an
+    inflow to this account, negative for an outflow.
+
+-   the running historical total or period total for the current
+    account, after the transaction. This can be toggled with `H`.
+    Similar to the accounts screen, the historical total is affected by
+    transactions (filtered by the filter query) before the report start
+    date, while the period total is not. If the historical total is not
+    disturbed by a filter query, it will be the running historical
+    balance you would see on a bank register for the current account.
+
+If the accounts screen was in tree mode, the register screen will
+include transactions from both the current account and its subaccounts.
+If the accounts screen was in flat mode, and a non-depth-clipped account
+was selected, the register screen will exclude transactions from
+subaccounts. In other words, the register always shows the transactions
+responsible for the period balance shown on the accounts screen. As on
+the accounts screen, this can be toggled with `F`.
+
+`U` toggles filtering by [unmarked status](/journal.html#status),
+showing or hiding unmarked transactions. Similarly, `P` toggles pending
+transactions, and `C` toggles cleared transactions. (By default,
+transactions with all statuses are shown; if you activate one or two
+status filters, only those transactions are shown; and if you activate
+all three, the filter is removed.)q
+
+`R` toggles real mode, in which [virtual
+postings](/journal.html#virtual-postings) are ignored.
+
+`Z` toggles nonzero mode, in which only transactions posting a nonzero
+change are shown (hledger-ui shows zero items by default, unlike
+command-line hledger).
+
+Press `right` (or `enter`) to view the selected transaction in detail.
+
+### Transaction screen
+
+This screen shows a single transaction, as a general journal entry,
+similar to hledger's print command and journal format
+(hledger\_journal(5)).
+
+The transaction's date(s) and any cleared flag, transaction code,
+description, comments, along with all of its account postings are shown.
+Simple transactions have two postings, but there can be more (or in
+certain cases, fewer).
+
+`up` and `down` will step through all transactions listed in the
+previous account register screen. In the title bar, the numbers in
+parentheses show your position within that account register. They will
+vary depending on which account register you came from (remember most
+transactions appear in multiple account registers). The \#N number
+preceding them is the transaction's position within the complete
+unfiltered journal, which is a more stable id (at least until the next
+reload).
+
+### Error screen
+
+This screen will appear if there is a problem, such as a parse error,
+when you press g to reload. Once you have fixed the problem, press g
+again to reload and resume normal operation. (Or, you can press escape
+to cancel the reload attempt.)
+
+## ENVIRONMENT
+
+**COLUMNS** The screen width to use. Default: the full terminal width.
+
+**LEDGER\_FILE** The journal file path when not specified with `-f`.
+Default: `~/.hledger.journal` (on windows, perhaps
+`C:/Users/USER/.hledger.journal`).
+
+## FILES
+
+Reads data from one or more files in hledger journal, timeclock,
+timedot, or CSV format specified with `-f`, or `$LEDGER_FILE`, or
+`$HOME/.hledger.journal` (on windows, perhaps
+`C:/Users/USER/.hledger.journal`).
+
+## BUGS
+
+The need to precede options with `--` when invoked from hledger is
+awkward.
+
+`-f-` doesn't work (hledger-ui can't read from stdin).
+
+`-V` affects only the accounts screen.
+
+When you press `g`, the current and all previous screens are
+regenerated, which may cause a noticeable pause with large files. Also
+there is no visual indication that this is in progress.
+
+`--watch` is not yet fully robust. It works well for normal usage, but
+many file changes in a short time (eg saving the file thousands of times
+with an editor macro) can cause problems at least on OSX. Symptoms
+include: unresponsive UI, periodic resetting of the cursor position,
+momentary display of parse errors, high CPU usage eventually subsiding,
+and possibly a small but persistent build-up of CPU usage until the
+program is restarted.

site/doc/1.5/hledger-web.md

@@ -0,0 +1,247 @@
+# hledger-web
+
+This doc is for version **1.5**. []{.docversions}
+
+-   toc
+
+## NAME
+
+hledger-web - web interface for the hledger accounting tool
+
+## SYNOPSIS
+
+`hledger-web [OPTIONS]`\
+`hledger web -- [OPTIONS]`
+
+## DESCRIPTION
+
+hledger is a cross-platform program for tracking money, time, or any
+other commodity, using double-entry accounting and a simple, editable
+file format. hledger is inspired by and largely compatible with
+ledger(1).
+
+<style>
+.highslide img {max-width:200px; border:thin grey solid; margin:0 0 1em 1em; }
+.highslide-caption {color:white; background-color:black;}
+</style>
+::: {style="float:right; max-width:200px; text-align:right;"}
+<a href="images/hledger-web/normal/register.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/register.png" title="Account register view with accounts sidebar" /></a>
+<a href="images/hledger-web/normal/journal.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/journal.png" title="Journal view" /></a>
+<a href="images/hledger-web/normal/help.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/help.png" title="Help dialog" /></a>
+<a href="images/hledger-web/normal/add.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/add.png" title="Add form" /></a>
+:::
+
+hledger-web is hledger's web interface. It starts a simple web
+application for browsing and adding transactions, and optionally opens
+it in a web browser window if possible. It provides a more user-friendly
+UI than the hledger CLI or hledger-ui interface, showing more at once
+(accounts, the current account register, balance charts) and allowing
+history-aware data entry, interactive searching, and bookmarking.
+
+hledger-web also lets you share a ledger with multiple users, or even
+the public web. There is no access control, so if you need that you
+should put it behind a suitable web proxy. As a small protection against
+data loss when running an unprotected instance, it writes a numbered
+backup of the main journal file (only ?) on every edit.
+
+Like hledger, it reads data from one or more files in hledger journal,
+timeclock, timedot, or CSV format specified with `-f`, or
+`$LEDGER_FILE`, or `$HOME/.hledger.journal` (on windows, perhaps
+`C:/Users/USER/.hledger.journal`). For more about this see hledger(1),
+hledger\_journal(5) etc.
+
+By default, hledger-web starts the web app in "transient mode" and also
+opens it in your default web browser if possible. In this mode the web
+app will keep running for as long as you have it open in a browser
+window, and will exit after two minutes of inactivity (no requests and
+no browser windows viewing it). With `--serve`, it just runs the web app
+without exiting, and logs requests to the console.
+
+By default the server listens on IP address 127.0.0.1, accessible only
+to local requests. You can use `--host` to change this, eg
+`--host 0.0.0.0` to listen on all configured addresses.
+
+Similarly, use `--port` to set a TCP port other than 5000, eg if you are
+running multiple hledger-web instances.
+
+You can use `--base-url` to change the protocol, hostname, port and path
+that appear in hyperlinks, useful eg for integrating hledger-web within
+a larger website. The default is `http://HOST:PORT/` using the server's
+configured host address and TCP port (or `http://HOST` if PORT is 80).
+
+With `--file-url` you can set a different base url for static files, eg
+for better caching or cookie-less serving on high performance websites.
+
+Note there is no built-in access control (aside from listening on
+127.0.0.1 by default). So you will need to hide hledger-web behind an
+authenticating proxy (such as apache or nginx) if you want to restrict
+who can see and add entries to your journal.
+
+Command-line options and arguments may be used to set an initial filter
+on the data. This is not shown in the web UI, but it will be applied in
+addition to any search query entered there.
+
+With journal and timeclock files (but not CSV files, currently) the web
+app detects changes made by other means and will show the new data on
+the next request. If a change makes the file unparseable, hledger-web
+will show an error until the file has been fixed.
+
+## OPTIONS
+
+Note: if invoking hledger-web as a hledger subcommand, write `--` before
+options as shown above.
+
+`--serve`
+:   serve and log requests, don't browse or auto-exit
+
+`--host=IPADDR`
+:   listen on this IP address (default: 127.0.0.1)
+
+`--port=PORT`
+:   listen on this TCP port (default: 5000)
+
+`--base-url=URL`
+:   set the base url (default: http://IPADDR:PORT). You would change
+    this when sharing over the network, or integrating within a larger
+    website.
+
+`--file-url=URL`
+:   set the static files url (default: BASEURL/static). hledger-web
+    normally serves static files itself, but if you wanted to serve them
+    from another server for efficiency, you would set the url with this.
+
+hledger input options:
+
+`-f FILE --file=FILE`
+:   use a different input file. For stdin, use - (default:
+    `$LEDGER_FILE` or `$HOME/.hledger.journal`)
+
+`--rules-file=RULESFILE`
+:   Conversion rules file to use when reading CSV (default: FILE.rules)
+
+`--alias=OLD=NEW`
+:   rename accounts named OLD to NEW
+
+`--anon`
+:   anonymize accounts and payees
+
+`--pivot FIELDNAME`
+:   use some other field or tag for the account name
+
+`-I --ignore-assertions`
+:   ignore any failing balance assertions
+
+hledger reporting options:
+
+`-b --begin=DATE`
+:   include postings/txns on or after this date
+
+`-e --end=DATE`
+:   include postings/txns before this date
+
+`-D --daily`
+:   multiperiod/multicolumn report by day
+
+`-W --weekly`
+:   multiperiod/multicolumn report by week
+
+`-M --monthly`
+:   multiperiod/multicolumn report by month
+
+`-Q --quarterly`
+:   multiperiod/multicolumn report by quarter
+
+`-Y --yearly`
+:   multiperiod/multicolumn report by year
+
+`-p --period=PERIODEXP`
+:   set start date, end date, and/or reporting interval all at once
+    using [period expressions](manual.html#period-expressions) syntax
+    (overrides the flags above)
+
+`--date2`
+:   match the secondary date instead (see command help for other
+    effects)
+
+`-U --unmarked`
+:   include only unmarked postings/txns (can combine with -P or -C)
+
+`-P --pending`
+:   include only pending postings/txns
+
+`-C --cleared`
+:   include only cleared postings/txns
+
+`-R --real`
+:   include only non-virtual postings
+
+`-NUM --depth=NUM`
+:   hide/aggregate accounts or postings more than NUM levels deep
+
+`-E --empty`
+:   show items with zero amount, normally hidden
+
+`-B --cost`
+:   convert amounts to their cost at transaction time (using the
+    [transaction price](journal.html#transaction-prices), if any)
+
+`-V --value`
+:   convert amounts to their market value on the report end date (using
+    the most recent applicable [market
+    price](journal.html#market-prices), if any)
+
+`--auto`
+:   apply [automated posting
+    rules](journal.html#automated-posting-rules) to modify transactions.
+
+`--forecast`
+:   apply [periodic transaction](journal.html#periodic-transactions)
+    rules to generate future transactions, to 6 months from now or
+    report end date.
+
+When a reporting option appears more than once in the command line, the
+last one takes precedence.
+
+Some reporting options can also be written as [query
+arguments](#queries).
+
+hledger help options:
+
+`-h --help`
+:   show general usage (or after COMMAND, command usage)
+
+`--version`
+:   show version
+
+`--debug[=N]`
+:   show debug output (levels 1-9, default: 1)
+
+A @FILE argument will be expanded to the contents of FILE, which should
+contain one command line option/argument per line. (To prevent this,
+insert a `--` argument before.)
+
+## ENVIRONMENT
+
+**LEDGER\_FILE** The journal file path when not specified with `-f`.
+Default: `~/.hledger.journal` (on windows, perhaps
+`C:/Users/USER/.hledger.journal`).
+
+## FILES
+
+Reads data from one or more files in hledger journal, timeclock,
+timedot, or CSV format specified with `-f`, or `$LEDGER_FILE`, or
+`$HOME/.hledger.journal` (on windows, perhaps
+`C:/Users/USER/.hledger.journal`).
+
+## BUGS
+
+The need to precede options with `--` when invoked from hledger is
+awkward.
+
+`-f-` doesn't work (hledger-web can't read from stdin).
+
+Query arguments and some hledger options are ignored.
+
+Does not work in text-mode browsers.
+
+Does not work well on small screens.

site/doc/1.5/timeclock.md

@@ -0,0 +1,69 @@
+# timeclock format
+
+This doc is for version **1.5**. []{.docversions}
+
+-   toc
+
+## NAME
+
+Timeclock - the time logging format of timeclock.el, as read by hledger
+
+## DESCRIPTION
+
+hledger can read timeclock files. [As with
+Ledger](http://ledger-cli.org/3.0/doc/ledger3.html#Time-Keeping), these
+are (a subset of)
+[timeclock.el](http://www.emacswiki.org/emacs/TimeClock)'s format,
+containing clock-in and clock-out entries as in the example below. The
+date is a [simple date](#simple-dates). The time format is
+HH:MM\[:SS\]\[+-ZZZZ\]. Seconds and timezone are optional. The timezone,
+if present, must be four digits and is ignored (currently the time is
+always interpreted as a local time).
+
+``` {.timeclock}
+i 2015/03/30 09:00:00 some:account name  optional description after two spaces
+o 2015/03/30 09:20:00
+i 2015/03/31 22:21:45 another account
+o 2015/04/01 02:00:34
+```
+
+hledger treats each clock-in/clock-out pair as a transaction posting
+some number of hours to an account. Or if the session spans more than
+one day, it is split into several transactions, one for each day. For
+the above time log, `hledger print` generates these journal entries:
+
+``` {.shell}
+$ hledger -f t.timeclock print
+2015/03/30 * optional description after two spaces
+    (some:account name)         0.33h
+
+2015/03/31 * 22:21-23:59
+    (another account)         1.64h
+
+2015/04/01 * 00:00-02:00
+    (another account)         2.01h
+```
+
+Here is a
+[sample.timeclock](https://raw.github.com/simonmichael/hledger/master/examples/sample.timeclock)
+to download and some queries to try:
+
+``` {.shell}
+$ hledger -f sample.timeclock balance                               # current time balances
+$ hledger -f sample.timeclock register -p 2009/3                    # sessions in march 2009
+$ hledger -f sample.timeclock register -p weekly --depth 1 --empty  # time summary by week
+```
+
+To generate time logs, ie to clock in and clock out, you could:
+
+-   use emacs and the built-in timeclock.el, or the extended
+    [timeclock-x.el](http://www.emacswiki.org/emacs/timeclock-x.el) and
+    perhaps the extras in
+    [ledgerutils.el](http://hub.darcs.net/simon/ledgertools/ledgerutils.el)
+
+-   at the command line, use these bash aliases:
+    `` shell   alias ti="echo i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG"   alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" ``
+-   or use the old `ti` and `to` scripts in the [ledger 2.x
+    repository](https://github.com/ledger/ledger/tree/maint/scripts).
+    These rely on a "timeclock" executable which I think is just the
+    ledger 2 executable renamed.

site/doc/1.5/timedot.md

@@ -0,0 +1,124 @@
+# timedot format
+
+This doc is for version **1.5**. []{.docversions}
+
+-   toc
+
+## NAME
+
+Timedot - hledger's human-friendly time logging format
+
+## DESCRIPTION
+
+Timedot is a plain text format for logging dated, categorised quantities
+(of time, usually), supported by hledger. It is convenient for
+approximate and retroactive time logging, eg when the real-time
+clock-in/out required with a timeclock file is too precise or too
+interruptive. It can be formatted like a bar chart, making clear at a
+glance where time was spent.
+
+Though called "timedot", this format is read by hledger as commodityless
+quantities, so it could be used to represent dated quantities other than
+time. In the docs below we'll assume it's time.
+
+## FILE FORMAT
+
+A timedot file contains a series of day entries. A day entry begins with
+a date, and is followed by category/quantity pairs, one per line. Dates
+are hledger-style [simple dates](/journal.html#simple-dates) (see
+hledger\_journal(5)). Categories are hledger-style account names,
+optionally indented. As in a hledger journal, there must be at least two
+spaces between the category (account name) and the quantity.
+
+Quantities can be written as:
+
+-   a sequence of dots (.) representing quarter hours. Spaces may
+    optionally be used for grouping and readability. Eg: .... ..
+
+-   an integral or decimal number, representing hours. Eg: 1.5
+
+-   an integral or decimal number immediately followed by a unit symbol
+    `s`, `m`, `h`, `d`, `w`, `mo`, or `y`, representing seconds,
+    minutes, hours, days weeks, months or years respectively. Eg: 90m.
+    The following equivalencies are assumed, currently: 1m = 60s, 1h =
+    60m, 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d.
+
+Blank lines and lines beginning with \#, ; or \* are ignored. An
+example:
+
+``` {.timedot}
+# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
+2016/2/1
+inc:client1   .... .... .... .... .... ....
+fos:haskell   .... .. 
+biz:research  .
+
+2016/2/2
+inc:client1   .... ....
+biz:research  .
+```
+
+Or with numbers:
+
+``` {.timedot}
+2016/2/3
+inc:client1   4
+fos:hledger   3
+biz:research  1
+```
+
+Reporting:
+
+``` {.shell}
+$ hledger -f t.timedot print date:2016/2/2
+2016/02/02 *
+    (inc:client1)          2.00
+
+2016/02/02 *
+    (biz:research)          0.25
+```
+
+``` {.shell}
+$ hledger -f t.timedot bal --daily --tree
+Balance changes in 2016/02/01-2016/02/03:
+
+            ||  2016/02/01d  2016/02/02d  2016/02/03d 
+============++========================================
+ biz        ||         0.25         0.25         1.00 
+   research ||         0.25         0.25         1.00 
+ fos        ||         1.50            0         3.00 
+   haskell  ||         1.50            0            0 
+   hledger  ||            0            0         3.00 
+ inc        ||         6.00         2.00         4.00 
+   client1  ||         6.00         2.00         4.00 
+------------++----------------------------------------
+            ||         7.75         2.25         8.00 
+```
+
+I prefer to use period for separating account components. We can make
+this work with an [account alias](/journal.html#account-aliases):
+
+``` {.timedot}
+2016/2/4
+fos.hledger.timedot  4
+fos.ledger           ..
+```
+
+``` {.shell}
+$ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4
+                4.50  fos
+                4.00    hledger:timedot
+                0.50    ledger
+--------------------
+                4.50
+```
+
+Here is a
+[sample.timedot](https://raw.github.com/simonmichael/hledger/master/examples/sample.timedot).
+<!-- to download and some queries to try: -->
+
+<!-- ```shell -->
+<!-- $ hledger -f sample.timedot balance                               # current time balances -->
+<!-- $ hledger -f sample.timedot register -p 2009/3                    # sessions in march 2009 -->
+<!-- $ hledger -f sample.timedot register -p weekly --depth 1 --empty  # time summary by week -->
+<!-- ``` -->