diff --git a/doc/manpage.nroff b/doc/manpage.nroff
index 6220749f4..677a3ea06 100644
--- a/doc/manpage.nroff
+++ b/doc/manpage.nroff
@@ -33,7 +33,7 @@ $endif$
 
 Copyright (C) 2007-2016 Simon Michael.
 .br
-Released under GNU GPLv3+.
+Released under GNU GPL v3 or later.
 
 .SH SEE ALSO
 hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
diff --git a/hledger-api/doc/hledger-api.1 b/hledger-api/doc/hledger-api.1
index 02abbf3c2..bd02c89d0 100644
--- a/hledger-api/doc/hledger-api.1
+++ b/hledger-api/doc/hledger-api.1
@@ -61,7 +61,7 @@ Simon Michael <simon@joyful.com> and contributors
 
 Copyright (C) 2007-2016 Simon Michael.
 .br
-Released under GNU GPLv3+.
+Released under GNU GPL v3 or later.
 
 .SH SEE ALSO
 hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
diff --git a/hledger-lib/doc/hledger_csv.5 b/hledger-lib/doc/hledger_csv.5
index 848844b24..69854c9c1 100644
--- a/hledger-lib/doc/hledger_csv.5
+++ b/hledger-lib/doc/hledger_csv.5
@@ -20,20 +20,19 @@ At minimum, the rules file must specify the \f[C]date\f[] and
 \f[C]amount\f[] fields.
 For an example, see How to read CSV files.
 .PP
-(For CSV output, see CSV output.)
-.SS CSV rules
+To learn about \f[I]exporting\f[] CSV, see CSV output.
+.SH CSV RULES
 .PP
 The following six kinds of rule can appear in the rules file, in any
 order.
 Blank lines and lines beginning with \f[C]#\f[] or \f[C];\f[] are
 ignored.
+.SS skip
+.PP
+\f[C]skip\f[]\f[I]\f[C]N\f[]\f[]
 .PP
-\f[B]\f[C]skip\f[] \f[I]N\f[]\f[]
-.PD 0
-.P
-.PD
 Skip this number of CSV records at the beginning.
-You\[aq]ll need this when your CSV contains header lines.
+You\[aq]ll need this whenever your CSV data contains header lines.
 Eg:
 .IP
 .nf
@@ -42,11 +41,10 @@ Eg:
 skip\ 1
 \f[]
 .fi
+.SS date\-format
+.PP
+\f[C]date\-format\f[]\f[I]\f[C]DATEFMT\f[]\f[]
 .PP
-\f[B]\f[C]date\-format\f[] \f[I]DATEFMT\f[]\f[]
-.PD 0
-.P
-.PD
 When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[] (or
 \f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you\[aq]ll need to
 specify the format.
@@ -56,71 +54,63 @@ Examples:
 .IP
 .nf
 \f[C]
-#\ parses\ "6/11/2013":
+#\ for\ dates\ like\ "6/11/2013":
 date\-format\ %\-d/%\-m/%Y
 \f[]
 .fi
 .IP
 .nf
 \f[C]
-#\ parses\ "11/06/2013":
+#\ for\ dates\ like\ "11/06/2013":
 date\-format\ %m/%d/%Y
 \f[]
 .fi
 .IP
 .nf
 \f[C]
-#\ parses\ "2013\-Nov\-06":
+#\ for\ dates\ like\ "2013\-Nov\-06":
 date\-format\ %Y\-%h\-%d
 \f[]
 .fi
 .IP
 .nf
 \f[C]
-#\ parses\ "11/6/2013\ 11:32\ PM":
+#\ for\ dates\ like\ "11/6/2013\ 11:32\ PM":
 date\-format\ %\-m/%\-d/%Y\ %l:%M\ %p
 \f[]
 .fi
+.SS field list
 .PP
-\f[B]\f[C]fields\f[] \f[I]CSVFIELDNAME1\f[],
-\f[I]CSVFIELDNAME2\f[]...\f[]
-.PD 0
-.P
-.PD
-(Field list)
-.PD 0
-.P
-.PD
-This (a) names the CSV fields (names may not contain whitespace), and
-(b) assigns them to journal entry fields if you use any of these
-standard field names: \f[C]date\f[], \f[C]date2\f[], \f[C]status\f[],
-\f[C]code\f[], \f[C]description\f[], \f[C]comment\f[],
-\f[C]account1\f[], \f[C]account2\f[], \f[C]amount\f[],
+\f[C]fields\f[]\f[I]\f[C]FIELDNAME1\f[]\f[],
+\f[I]\f[C]FIELDNAME2\f[]\f[]...
+.PP
+This (a) names the CSV fields, in order (names may not contain
+whitespace, but may be omitted), and (b) assigns them to journal entry
+fields if you use any of these standard field names: \f[C]date\f[],
+\f[C]date2\f[], \f[C]status\f[], \f[C]code\f[], \f[C]description\f[],
+\f[C]comment\f[], \f[C]account1\f[], \f[C]account2\f[], \f[C]amount\f[],
 \f[C]amount\-in\f[], \f[C]amount\-out\f[], \f[C]currency\f[].
 Eg:
 .IP
 .nf
 \f[C]
-#\ use\ the\ 1st,\ 2nd\ and\ 4th\ CSV\ fields\ as\ the\ entry\ date,\ description\ and\ amount
-#\ give\ the\ 7th\ and\ 8th\ fields\ custom\ names\ for\ later\ reference
+#\ use\ the\ 1st,\ 2nd\ and\ 4th\ CSV\ fields\ as\ the\ entry\[aq]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
 \f[]
 .fi
+.SS field assignment
+.PP
+\f[I]\f[C]ENTRYFIELDNAME\f[]\f[] \f[I]\f[C]FIELDVALUE\f[]\f[]
 .PP
-\f[B]\f[I]ENTRYFIELDNAME\f[] \f[I]FIELDVALUE\f[]\f[]
-.PD 0
-.P
-.PD
-(Field assignment)
-.PD 0
-.P
-.PD
 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 (\f[C]%CSVFIELDNAME\f[]) or 1\-based position (\f[C]%N\f[]).
- Field assignments can be used instead of or in addition to a field
-list.
-Eg:
+ Eg:
 .IP
 .nf
 \f[C]
@@ -136,38 +126,29 @@ comment\ note:\ %somefield\ \-\ %anotherfield,\ date:\ %1
 \f[]
 .fi
 .PP
-\f[B]\f[C]if\f[] \f[I]PATTERN\f[]
+Field assignments can be used instead of or in addition to a field list.
+.SS conditional block
+.PP
+\f[C]if\f[] \f[I]\f[C]PATTERN\f[]\f[]
 .PD 0
 .P
 .PD
-\ \ \ \ \f[I]FIELDASSIGNMENTS\f[]...\f[]
+\ \ \ \ \f[I]\f[C]FIELDASSIGNMENTS\f[]\f[]...
+.PP
+\f[C]if\f[]
 .PD 0
 .P
 .PD
-or
+\f[I]\f[C]PATTERN\f[]\f[]
 .PD 0
 .P
 .PD
-\f[B]\f[C]if\f[]
-.PD 0
-.P
-.PD
-\f[I]PATTERN\f[]
-.PD 0
-.P
-.PD
-\f[I]PATTERN\f[]...
-.PD 0
-.P
-.PD
-\ \ \ \ \f[I]FIELDASSIGNMENTS\f[]...\f[]
-.PD 0
-.P
-.PD
-(Conditional block)
+\f[I]\f[C]PATTERN\f[]\f[]...
 .PD 0
 .P
 .PD
+\ \ \ \ \f[I]\f[C]FIELDASSIGNMENTS\f[]\f[]...
+.PP
 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
@@ -195,14 +176,13 @@ monthly\ service\ fee
 atm\ transaction\ fee
 banking\ thru\ software
 \ account2\ expenses:business:banking
-\ comment\ \ XXX\ deductible\ ?\ check
+\ comment\ \ XXX\ deductible\ ?\ check\ it
 \f[]
 .fi
+.SS include
+.PP
+\f[C]include\f[]\f[I]\f[C]RULESFILE\f[]\f[]
 .PP
-\f[B]\f[C]include\f[] \f[I]RULESFILE\f[]\f[]
-.PD 0
-.P
-.PD
 Include another rules file at this point.
 \f[C]RULESFILE\f[] is either an absolute file path or a path relative to
 the current file\[aq]s directory.
@@ -214,7 +194,7 @@ Eg:
 include\ common.rules
 \f[]
 .fi
-.SS CSV tips
+.SH TIPS
 .PP
 Each generated journal entry will have two postings, to
 \f[C]account1\f[] and \f[C]account2\f[] respectively.
@@ -248,7 +228,7 @@ Simon Michael <simon@joyful.com> and contributors
 
 Copyright (C) 2007-2016 Simon Michael.
 .br
-Released under GNU GPLv3+.
+Released under GNU GPL v3 or later.
 
 .SH SEE ALSO
 hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
diff --git a/hledger-lib/doc/hledger_journal.5 b/hledger-lib/doc/hledger_journal.5
index 25bb68405..0c905e4d7 100644
--- a/hledger-lib/doc/hledger_journal.5
+++ b/hledger-lib/doc/hledger_journal.5
@@ -1,3 +1,4 @@
+.\"t
 
 .TH "hledger_journal" "5" "April 2016" "" "hledger User Manuals"
 
@@ -57,8 +58,7 @@ Here\[aq]s an example:
 \ \ \ \ assets:bank:checking
 \f[]
 .fi
-.PP
-Now let\[aq]s explore the available journal file syntax in detail.
+.SH FILE FORMAT
 .SS Transactions
 .PP
 Transactions are represented by journal entries.
@@ -806,6 +806,46 @@ Glob patterns (\f[C]*\f[]) are not currently supported.
 The \f[C]include\f[] directive may only be used in journal files, and
 currently it may only include other journal files (eg, not CSV or
 timelog files.)
+.SH EDITOR SUPPORT
+.PP
+Add\-on modes exist for various text editors, to make working with
+journal files easier.
+They add colour, navigation aids and helpful commands.
+For hledger users who edit the journal file directly (the majority),
+using one of these modes is quite recommended.
+.PP
+These were written with Ledger in mind, but also work with hledger
+files:
+.PP
+.TS
+tab(@);
+lw(16.5n) lw(51.5n).
+T{
+Emacs
+T}@T{
+http://www.ledger\-cli.org/3.0/doc/ledger\-mode.html
+T}
+T{
+Vim
+T}@T{
+https://github.com/ledger/ledger/wiki/Getting\-started
+T}
+T{
+Sublime Text
+T}@T{
+https://github.com/ledger/ledger/wiki/Using\-Sublime\-Text
+T}
+T{
+Textmate
+T}@T{
+https://github.com/ledger/ledger/wiki/Using\-TextMate\-2
+T}
+T{
+Text Wrangler \ 
+T}@T{
+https://github.com/ledger/ledger/wiki/Editing\-Ledger\-files\-with\-TextWrangler
+T}
+.TE
 
 
 .SH "REPORTING BUGS"
@@ -819,7 +859,7 @@ Simon Michael <simon@joyful.com> and contributors
 
 Copyright (C) 2007-2016 Simon Michael.
 .br
-Released under GNU GPLv3+.
+Released under GNU GPL v3 or later.
 
 .SH SEE ALSO
 hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
diff --git a/hledger-lib/doc/hledger_timedot.5 b/hledger-lib/doc/hledger_timedot.5
index 19597697f..976cac85c 100644
--- a/hledger-lib/doc/hledger_timedot.5
+++ b/hledger-lib/doc/hledger_timedot.5
@@ -136,7 +136,7 @@ Simon Michael <simon@joyful.com> and contributors
 
 Copyright (C) 2007-2016 Simon Michael.
 .br
-Released under GNU GPLv3+.
+Released under GNU GPL v3 or later.
 
 .SH SEE ALSO
 hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
diff --git a/hledger-lib/doc/hledger_timelog.5 b/hledger-lib/doc/hledger_timelog.5
index bcad6da78..421146b28 100644
--- a/hledger-lib/doc/hledger_timelog.5
+++ b/hledger-lib/doc/hledger_timelog.5
@@ -90,7 +90,7 @@ Simon Michael <simon@joyful.com> and contributors
 
 Copyright (C) 2007-2016 Simon Michael.
 .br
-Released under GNU GPLv3+.
+Released under GNU GPL v3 or later.
 
 .SH SEE ALSO
 hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
diff --git a/hledger-ui/doc/hledger-ui.1 b/hledger-ui/doc/hledger-ui.1
index 7ac24b314..f10034115 100644
--- a/hledger-ui/doc/hledger-ui.1
+++ b/hledger-ui/doc/hledger-ui.1
@@ -320,7 +320,7 @@ Simon Michael <simon@joyful.com> and contributors
 
 Copyright (C) 2007-2016 Simon Michael.
 .br
-Released under GNU GPLv3+.
+Released under GNU GPL v3 or later.
 
 .SH SEE ALSO
 hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
diff --git a/hledger-web/doc/hledger-web.1 b/hledger-web/doc/hledger-web.1
index e02a3f39d..fe41330b1 100644
--- a/hledger-web/doc/hledger-web.1
+++ b/hledger-web/doc/hledger-web.1
@@ -245,7 +245,7 @@ Simon Michael <simon@joyful.com> and contributors
 
 Copyright (C) 2007-2016 Simon Michael.
 .br
-Released under GNU GPLv3+.
+Released under GNU GPL v3 or later.
 
 .SH SEE ALSO
 hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
diff --git a/hledger/doc/hledger.1 b/hledger/doc/hledger.1
index ac0eb4dbe..fe1a1d3c4 100644
--- a/hledger/doc/hledger.1
+++ b/hledger/doc/hledger.1
@@ -20,9 +20,8 @@ hledger is a cross\-platform program for tracking money, time, or any
 other commodity, using double\-entry accounting and a simple, editable
 file format.
 It is inspired by and largely compatible with ledger(1).
-hledger aims to be a reliable, practical tool for daily use.
-This man page is a quick reference and introduction; for more complete
-docs, see http://hledger.org/manual.
+Tested on unix, mac, windows, hledger aims to be a reliable, practical
+tool for daily use.
 .PP
 This is hledger's command\-line interface (there are also curses and web
 interfaces).
@@ -463,6 +462,52 @@ Examples:
 \-p\ "every\ 4th\ day\ of\ week"
 \f[]
 .fi
+.SS Regular Expressions
+.PP
+hledger uses regular expressions in a number of places:
+.IP \[bu] 2
+query terms, on the command line and in the hledger\-web search form:
+\f[C]REGEX\f[], \f[C]desc:REGEX\f[], \f[C]cur:REGEX\f[],
+\f[C]tag:...=REGEX\f[]
+.IP \[bu] 2
+CSV rules conditional blocks: \f[C]if\ REGEX\ ...\f[]
+.IP \[bu] 2
+account alias directives and options:
+\f[C]alias\ /REGEX/\ =\ REPLACEMENT\f[],
+\f[C]\-\-alias\ /REGEX/=REPLACEMENT\f[]
+.PP
+hledger\[aq]s regular expressions come from the regex\-tdfa library.
+In general they:
+.IP \[bu] 2
+are case insensitive
+.IP \[bu] 2
+are infix matching (do not need to match the entire thing being matched)
+.IP \[bu] 2
+are POSIX extended regular expressions
+.IP \[bu] 2
+also support GNU word boundaries (\\<, \\>, \\b, \\B)
+.IP \[bu] 2
+and parenthesised capturing groups and numeric backreferences in
+replacement strings
+.IP \[bu] 2
+do not support mode modifiers like (?s)
+.PP
+Some things to note:
+.IP \[bu] 2
+In the \f[C]alias\f[] directive and \f[C]\-\-alias\f[] option, regular
+expressions must be enclosed in forward slashes (\f[C]/REGEX/\f[]).
+Elsewhere in hledger, these are not required.
+.IP \[bu] 2
+To match a regular expression metacharacter like \f[C]$\f[] as a literal
+character, prepend a backslash.
+Eg to search for amounts with the dollar sign in hledger\-web, write
+\f[C]cur:\\$\f[].
+.IP \[bu] 2
+On the command line, some metacharacters like \f[C]$\f[] have a special
+meaning to the shell and so must be escaped a second time, with single
+or double quotes or another backslash.
+Eg, to match amounts with the dollar sign from the command line, write
+\f[C]cur:\[aq]\\$\[aq]\f[] or \f[C]cur:\\\\$\f[].
 .SH QUERIES
 .PP
 One of hledger\[aq]s strengths is being able to quickly report on
@@ -579,11 +624,13 @@ before any of the above negates the match.
 .RS
 .RE
 .PP
-Some of the above can also be expressed as command\-line options (eg
+   *   *   *   *   *
+.PP
+Some of these can also be expressed as command\-line options (eg
 \f[C]depth:2\f[] is equivalent to \f[C]\-\-depth\ 2\f[]).
 Generally you can mix options and query arguments, and the resulting
-query will be their intersection (aside from the \f[C]\-p/\-\-period\f[]
-option).
+query will be their intersection (perhaps excluding the
+\f[C]\-p/\-\-period\f[] option).
 .SH COMMANDS
 .PP
 hledger provides a number of subcommands; \f[C]hledger\f[] with no
@@ -694,6 +741,85 @@ $\ hledger\ activity\ \-\-quarterly
 2008\-10\-01\ **
 \f[]
 .fi
+.SS add
+.PP
+Prompt for transactions and add them to the journal.
+.TP
+.B \f[C]\-\-no\-new\-accounts\f[]
+don\[aq]t allow creating new accounts; helps prevent typos when entering
+account names
+.RS
+.RE
+.PP
+Many hledger users edit their journals directly with a text editor, or
+generate them from CSV.
+For more interactive data entry, there is the \f[C]add\f[] command,
+which prompts interactively on the console for new transactions, and
+appends them to the journal file (existing transactions are not
+changed).
+This is the only hledger command that writes to the journal file.
+.PP
+To use it, just run \f[C]hledger\ add\f[] and follow the prompts.
+You can add as many transactions as you like; when you are finished,
+enter \f[C]\&.\f[] or press control\-d or control\-c to exit.
+.PP
+Features:
+.IP \[bu] 2
+add tries to provide useful defaults, using the most similar recent
+transaction (by description) as a template.
+.IP \[bu] 2
+You can also set the initial defaults with command line arguments.
+.IP \[bu] 2
+Readline\-style edit keys can be used during data entry.
+.IP \[bu] 2
+The tab key will auto\-complete whenever possible \- accounts,
+descriptions, dates (\f[C]yesterday\f[], \f[C]today\f[],
+\f[C]tomorrow\f[]).
+If the input area is empty, it will insert the default value.
+.IP \[bu] 2
+If the journal defines a default commodity, it will be added to any bare
+numbers entered.
+.IP \[bu] 2
+A parenthesised transaction code may be entered following a date.
+.IP \[bu] 2
+Comments and tags may be entered following a description or amount.
+.IP \[bu] 2
+If you make a mistake, enter \f[C]<\f[] at any prompt to restart the
+transaction.
+.IP \[bu] 2
+Input prompts are displayed in a different colour when the terminal
+supports it.
+.PP
+Example (see the tutorial for a detailed explanation):
+.IP
+.nf
+\f[C]
+$\ hledger\ add
+Adding\ transactions\ to\ journal\ file\ /src/hledger/data/sample.journal
+Any\ command\ line\ arguments\ will\ be\ used\ as\ defaults.
+Use\ tab\ key\ to\ complete,\ readline\ keys\ to\ edit,\ enter\ to\ accept\ defaults.
+An\ optional\ (CODE)\ may\ follow\ transaction\ dates.
+An\ optional\ ;\ COMMENT\ may\ follow\ descriptions\ or\ amounts.
+If\ you\ make\ a\ mistake,\ enter\ <\ at\ any\ prompt\ to\ restart\ the\ transaction.
+To\ end\ a\ transaction,\ enter\ .\ when\ prompted.
+To\ quit,\ enter\ .\ at\ a\ date\ prompt\ or\ press\ control\-d\ or\ control\-c.
+Date\ [2015/05/22]:\ 
+Description:\ supermarket
+Account\ 1:\ expenses:food
+Amount\ \ 1:\ $10
+Account\ 2:\ assets:checking
+Amount\ \ 2\ [$\-10.0]:\ 
+Account\ 3\ (or\ .\ or\ enter\ to\ finish\ this\ transaction):\ .
+2015/05/22\ supermarket
+\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ $10
+\ \ \ \ assets:checking\ \ \ \ \ \ \ \ $\-10.0
+
+Save\ this\ transaction\ to\ the\ journal\ ?\ [y]:\ 
+Saved.
+Starting\ the\ next\ transaction\ (.\ or\ ctrl\-D/ctrl\-C\ to\ quit)
+Date\ [2015/05/22]:\ <CTRL\-D>\ $
+\f[]
+.fi
 .SS balance
 .PP
 Show accounts and their balances.
@@ -1088,85 +1214,6 @@ charts in a spreadsheet.
 This is controlled by the \f[C]\-O/\-\-output\-format\f[] option, or by
 specifying a \f[C]\&.csv\f[] file extension with
 \f[C]\-o/\-\-output\-file\f[].
-.SS add
-.PP
-Prompt for transactions and add them to the journal.
-.TP
-.B \f[C]\-\-no\-new\-accounts\f[]
-don\[aq]t allow creating new accounts; helps prevent typos when entering
-account names
-.RS
-.RE
-.PP
-Many hledger users edit their journals directly with a text editor, or
-generate them from CSV.
-For more interactive data entry, there is the \f[C]add\f[] command,
-which prompts interactively on the console for new transactions, and
-appends them to the journal file (existing transactions are not
-changed).
-This is the only hledger command that writes to the journal file.
-.PP
-To use it, just run \f[C]hledger\ add\f[] and follow the prompts.
-You can add as many transactions as you like; when you are finished,
-enter \f[C]\&.\f[] or press control\-d or control\-c to exit.
-.PP
-Features:
-.IP \[bu] 2
-add tries to provide useful defaults, using the most similar recent
-transaction (by description) as a template.
-.IP \[bu] 2
-You can also set the initial defaults with command line arguments.
-.IP \[bu] 2
-Readline\-style edit keys can be used during data entry.
-.IP \[bu] 2
-The tab key will auto\-complete whenever possible \- accounts,
-descriptions, dates (\f[C]yesterday\f[], \f[C]today\f[],
-\f[C]tomorrow\f[]).
-If the input area is empty, it will insert the default value.
-.IP \[bu] 2
-If the journal defines a default commodity, it will be added to any bare
-numbers entered.
-.IP \[bu] 2
-A parenthesised transaction code may be entered following a date.
-.IP \[bu] 2
-Comments and tags may be entered following a description or amount.
-.IP \[bu] 2
-If you make a mistake, enter \f[C]<\f[] at any prompt to restart the
-transaction.
-.IP \[bu] 2
-Input prompts are displayed in a different colour when the terminal
-supports it.
-.PP
-Example (see the tutorial for a detailed explanation):
-.IP
-.nf
-\f[C]
-$\ hledger\ add
-Adding\ transactions\ to\ journal\ file\ /src/hledger/data/sample.journal
-Any\ command\ line\ arguments\ will\ be\ used\ as\ defaults.
-Use\ tab\ key\ to\ complete,\ readline\ keys\ to\ edit,\ enter\ to\ accept\ defaults.
-An\ optional\ (CODE)\ may\ follow\ transaction\ dates.
-An\ optional\ ;\ COMMENT\ may\ follow\ descriptions\ or\ amounts.
-If\ you\ make\ a\ mistake,\ enter\ <\ at\ any\ prompt\ to\ restart\ the\ transaction.
-To\ end\ a\ transaction,\ enter\ .\ when\ prompted.
-To\ quit,\ enter\ .\ at\ a\ date\ prompt\ or\ press\ control\-d\ or\ control\-c.
-Date\ [2015/05/22]:\ 
-Description:\ supermarket
-Account\ 1:\ expenses:food
-Amount\ \ 1:\ $10
-Account\ 2:\ assets:checking
-Amount\ \ 2\ [$\-10.0]:\ 
-Account\ 3\ (or\ .\ or\ enter\ to\ finish\ this\ transaction):\ .
-2015/05/22\ supermarket
-\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ $10
-\ \ \ \ assets:checking\ \ \ \ \ \ \ \ $\-10.0
-
-Save\ this\ transaction\ to\ the\ journal\ ?\ [y]:\ 
-Saved.
-Starting\ the\ next\ transaction\ (.\ or\ ctrl\-D/ctrl\-C\ to\ quit)
-Date\ [2015/05/22]:\ <CTRL\-D>\ $
-\f[]
-.fi
 .SS balancesheet
 .PP
 Show a balance sheet.
@@ -1941,6 +1988,116 @@ Curses\-style interface, see hledger\-ui.
 .SS web
 .PP
 Web interface, see hledger\-web.
+.SH TROUBLESHOOTING
+.SS Run\-time problems
+.PP
+Here are some issues you might encounter when you run hledger (and
+remember you can also seek help from the IRC channel, mail list or bug
+tracker):
+.PP
+\f[B]Successfully installed, but "No command \[aq]hledger\[aq]
+found"\f[]
+.PD 0
+.P
+.PD
+stack and cabal install binaries into a special directory, which should
+be added to your PATH environment variable.
+Eg on unix\-like systems, that is ~/.local/bin and ~/.cabal/bin
+respectively.
+.PP
+\f[B]I set a custom LEDGER_FILE, but hledger is still using the default
+file\f[]
+.PD 0
+.P
+.PD
+\f[C]LEDGER_FILE\f[] should be a real environment variable, not just a
+shell variable.
+The command \f[C]env\ |\ grep\ LEDGER_FILE\f[] should show it.
+You may need to use \f[C]export\f[].
+Here\[aq]s an explanation.
+.PP
+\f[B]"Illegal byte sequence" or "Invalid or incomplete multibyte or wide
+character" errors\f[]
+.PD 0
+.P
+.PD
+In order to handle non\-ascii letters and symbols (like £), hledger
+needs an appropriate locale.
+This is usually configured system\-wide; you can also configure it
+temporarily.
+The locale may need to be one that supports UTF\-8, if you built hledger
+with GHC < 7.2 (or possibly always, I\[aq]m not sure yet).
+.PP
+Here\[aq]s an example of setting the locale temporarily, on ubuntu
+gnu/linux:
+.IP
+.nf
+\f[C]
+$\ file\ my.journal
+my.journal:\ UTF\-8\ Unicode\ text\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ <\-\ the\ file\ is\ UTF8\-encoded
+$\ locale\ \-a
+C
+en_US.utf8\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ <\-\ a\ UTF8\-aware\ locale\ is\ available
+POSIX
+$\ LANG=en_US.utf8\ hledger\ \-f\ my.journal\ print\ \ \ #\ <\-\ use\ it\ for\ this\ command
+\f[]
+.fi
+.PP
+Here\[aq]s one way to set it permanently, there are probably better
+ways:
+.IP
+.nf
+\f[C]
+$\ echo\ "export\ LANG=en_US.UTF\-8"\ >>~/.bash_profile
+$\ bash\ \-\-login
+\f[]
+.fi
+.PP
+If we preferred to use eg \f[C]fr_FR.utf8\f[], we might have to install
+that first:
+.IP
+.nf
+\f[C]
+$\ apt\-get\ install\ language\-pack\-fr
+$\ locale\ \-a
+C
+en_US.utf8
+fr_BE.utf8
+fr_CA.utf8
+fr_CH.utf8
+fr_FR.utf8
+fr_LU.utf8
+POSIX
+$\ LANG=fr_FR.utf8\ hledger\ \-f\ my.journal\ print
+\f[]
+.fi
+.PP
+Note some platforms allow variant locale spellings, but not all (ubuntu
+accepts \f[C]fr_FR.UTF8\f[], mac osx requires exactly
+\f[C]fr_FR.UTF\-8\f[]).
+.SS Known limitations
+.PP
+\f[B]Command line interface\f[]
+.PP
+Add\-on command options, unless they are also understood by the main
+hledger executable, must be written after \f[C]\-\-\f[], like this:
+\f[C]hledger\ web\ \-\-\ \-\-server\f[]
+.PP
+\f[B]Differences from Ledger\f[]
+.PP
+Not all of Ledger\[aq]s journal file syntax is supported.
+See file format differences.
+.PP
+hledger is slower than Ledger, and uses more memory, on large data
+files.
+.PP
+\f[B]Windows limitations\f[]
+.PP
+In a windows CMD window, non\-ascii characters and colours are not
+supported.
+.PP
+In a windows Cygwin/MSYS/Mintty window, the tab key is not supported in
+hledger add.
 .SH ENVIRONMENT
 .PP
 \f[B]LEDGER_FILE\f[] sets the default journal file path.
@@ -1977,7 +2134,7 @@ Simon Michael <simon@joyful.com> and contributors
 
 Copyright (C) 2007-2016 Simon Michael.
 .br
-Released under GNU GPLv3+.
+Released under GNU GPL v3 or later.
 
 .SH SEE ALSO
 hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),