doc: merge last bits of old manual into new one

hledger-lib/doc/hledger_journal.5.md

@@ -59,7 +59,8 @@ Here's an example:
     assets:bank:checking
 ```
 
-Now let's explore the available journal file syntax in detail.
+# FILE FORMAT
+<!-- Now let's explore the available journal file syntax in detail. -->
 
 ## Transactions
 
@@ -691,3 +692,29 @@ Glob patterns (`*`) are not currently supported.
 
 The `include` directive may only be used in journal files, and currently
 it may only include other journal files (eg, not CSV or timelog files.)
+
+# EDITOR SUPPORT
+
+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.
+
+These were written with Ledger in mind, but also work with hledger files:
+
+|
+|----------------|----------------------------------------------------|
+| Emacs          | <http://www.ledger-cli.org/3.0/doc/ledger-mode.html> |
+| Vim            | <https://github.com/ledger/ledger/wiki/Getting-started> |
+| Sublime Text   | <https://github.com/ledger/ledger/wiki/Using-Sublime-Text> |
+| Textmate       | <https://github.com/ledger/ledger/wiki/Using-TextMate-2> |
+| Text Wrangler &nbsp; | <https://github.com/ledger/ledger/wiki/Editing-Ledger-files-with-TextWrangler> |
+
+<!-- Some related LedgerTips:
+https://twitter.com/LedgerTips/status/504061626233159681
+https://twitter.com/LedgerTips/status/502820400276193280
+https://twitter.com/LedgerTips/status/502503912084361216
+https://twitter.com/LedgerTips/status/501767602067472384
+-->
+
+

hledger/doc/hledger.1.m4.md

@@ -21,9 +21,9 @@ hledger - a command-line accounting tool
 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
+Tested on unix, mac, windows, hledger aims to be a reliable, practical
-page is a quick reference and introduction; for more complete docs, see
+tool for daily use.
-http://hledger.org/manual.
+
 </div>
 
 _include_(description.m4.md)
@@ -31,6 +31,7 @@ _include_(examples.m4.md)
 _include_(options.m4.md)
 _include_(queries.m4.md)
 _include_(commands.m4.md)
+_include_(troubleshooting.m4.md)
 
 <div class="man">
 

hledger/doc/options.m4.md

@@ -194,3 +194,38 @@ Examples:
     -p "every 15th day of month"
     -p "every 4th day of week"
 
+## Regular Expressions
+
+hledger uses [regular expressions](http://www.regular-expressions.info) in a number of places:
+
+- [query terms](#queries), on the command line and in the hledger-web search form: `REGEX`, `desc:REGEX`, `cur:REGEX`, `tag:...=REGEX`
+- [CSV rules](#csv-rules) conditional blocks: `if REGEX ...`
+- [account alias](#account-aliases) directives and options: `alias /REGEX/ = REPLACEMENT`, `--alias /REGEX/=REPLACEMENT`
+
+hledger's regular expressions come from the
+[regex-tdfa](http://hackage.haskell.org/package/regex-tdfa/docs/Text-Regex-TDFA.html)
+library. In general they:
+
+- are case insensitive
+- are infix matching (do not need to match the entire thing being matched)
+- are [POSIX extended regular expressions](http://www.regular-expressions.info/posix.html#ere)
+- also support [GNU word boundaries](http://www.regular-expressions.info/wordboundaries.html) (\\<, \\>, \\b, \\B)
+- and parenthesised [capturing groups](http://www.regular-expressions.info/refcapture.html) and numeric backreferences in replacement strings
+- do not support [mode modifiers](http://www.regular-expressions.info/modifiers.html) like (?s)
+
+Some things to note:
+
+- In the `alias` directive and `--alias` option, regular expressions
+must be enclosed in forward slashes (`/REGEX/`). Elsewhere in hledger,
+these are not required.
+
+- To match a regular expression metacharacter like `$` as a literal
+character, prepend a backslash. Eg to search for amounts with the
+dollar sign in hledger-web, write `cur:\$`.
+
+- On the command line, some metacharacters like `$` 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 `cur:'\$'` or `cur:\\$`.
+
+

hledger/doc/queries.m4.md

@@ -93,6 +93,65 @@ parent transaction.
 **`not:`**
 : before any of the above negates the match.
 
+---
+# as a table:
+#---------------------------------- ------------------------------------------------------------------------------------------------------------------------
+#`REGEX`                            match account names by this regular expression
+#
+#\                                  \
+#`acct:REGEX`                       same as above
+#
+#\                                  \
+#`amt:N`, `amt:<N`, `amt:<=N`,      match postings with a single-commodity
+#`amt:>N`, `amt:>=N`                amount that is equal to, less than, or greater than N.
+#\                                  (Multi-commodity amounts are not tested, and will always match.)
+#\                                  The comparison has two modes: if N is preceded by a `+` or `-` sign
+#                                   (or is 0), the two signed numbers are compared. Otherwise, the
+#                                   absolute magnitudes are compared, ignoring sign.
+#
+#\                                  \
+#`code:REGEX`                       match by transaction code (eg check number)
+#
+#\                                  \
+#`cur:REGEX`                        match postings or transactions including any amounts
+#\                                  whose currency/commodity symbol is fully matched by REGEX. (For a
+#\                                  partial match, use `.*REGEX.*`). Note, to match characters which are
+#\                                  regex-significant, like the dollar sign (`$`), you need to prepend `\`.
+#\                                  And when using the command line you need to add one more level
+#                                   of quoting to hide it from the shell, so eg do: `hledger print cur:'\$'`
+#                                   or `hledger print cur:\\$`.
+#
+#\                                  \
+#`desc:REGEX`                       match transaction descriptions
+#
+#\                                  \
+#`date:PERIODEXPR`                  match dates within the specified [period](#period-expressions)
+#\                                  (which should not include a [reporting interval](#reporting-interval))
+#
+#\                                  \
+#`date2:PERIODEXPR`                 as above, but match [secondary dates](#secondary-dates)
+#
+#\                                  \
+#`depth:N`                          match (or display, depending on command) accounts at or above this [depth](#depth-limiting)
+#
+#\                                  \
+#`real:`, `real:0`                  match real or [virtual](#virtual-postings) postings respectively
+#
+#\                                  \
+#`status:*`, `status:!`, `status:`  match cleared, pending, or uncleared/pending transactions respectively
+#                                   \
+#                                   \
+#
+#\                                  \
+#`tag:REGEX[=REGEX]`                match by [tag](#tags) name, and optionally also by tag value.
+#\                                  Note a `tag:` query is considered to match a transaction if it matches any of the postings.
+#\                                  Also remember that postings inherit the tags of their parent transaction.
+#
+#\                                  \
+#`not:`                             before any of the above negates the match.
+...
+---------------------------------- ------------------------------------------------------------------------------------------------------------------------
 
-Some of the above can also be expressed as command-line options (eg `depth:2` is equivalent to `--depth 2`).
+Some of these can also be expressed as command-line options (eg `depth:2` is equivalent to `--depth 2`).
-Generally you can mix options and query arguments, and the resulting query will be their intersection (aside from the `-p/--period` option).
+Generally you can mix options and query arguments, and the resulting query will be their intersection
+(perhaps excluding the `-p/--period` option).

hledger/doc/troubleshooting.m4.md

@@ -0,0 +1,85 @@
+# TROUBLESHOOTING
+
+## Run-time problems
+
+Here are some issues you might encounter when you run hledger
+(and remember you can also seek help from the
+[IRC channel](http://irc.hledger.org),
+[mail list](http://list.hledger.org) or
+[bug tracker](http://bugs.hledger.org)):
+
+**Successfully installed, but "No command 'hledger' found"**  
+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.
+
+**I set a custom LEDGER_FILE, but hledger is still using the default file**  
+`LEDGER_FILE` should be a real environment variable, not just a shell variable.
+The command `env | grep LEDGER_FILE` should show it.
+You may need to use `export`. Here's an [explanation](http://stackoverflow.com/a/7411509).
+
+**"Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors**  
+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'm not sure yet).
+
+Here's an example of setting the locale temporarily, on ubuntu gnu/linux:
+
+```{.shell}
+$ 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
+```
+
+Here's one way to set it permanently, there are probably better ways:
+
+```{.shell}
+$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
+$ bash --login
+```
+
+If we preferred to use eg `fr_FR.utf8`, we might have to install that first:
+
+```{.shell}
+$ 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
+```
+
+Note some platforms allow variant locale spellings, but not all (ubuntu
+accepts `fr_FR.UTF8`, mac osx requires exactly `fr_FR.UTF-8`).
+
+
+## Known limitations
+
+**Command line interface**
+
+Add-on command options, unless they are also understood by the main
+hledger executable, must be written after `--`, like this:
+`hledger web -- --server`
+
+**Differences from Ledger**
+
+Not all of Ledger's journal file syntax is supported. See [file format differences](faq#file-format-differences).
+
+hledger is slower than Ledger, and uses more memory, on large data files.
+
+**Windows limitations**
+
+In a windows CMD window, non-ascii characters and colours are not supported.
+
+In a windows Cygwin/MSYS/Mintty window, the tab key is not supported in hledger add.