diff --git a/hledger-lib/doc/hledger_journal.5.md b/hledger-lib/doc/hledger_journal.5.md index 0f916e198..89ad999d1 100644 --- a/hledger-lib/doc/hledger_journal.5.md +++ b/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 + ## 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 | | +| Vim | | +| Sublime Text | | +| Textmate | | +| Text Wrangler   | | + + + + diff --git a/hledger/doc/hledger.1.m4.md b/hledger/doc/hledger.1.m4.md index e2dcdccd1..3d257446b 100644 --- a/hledger/doc/hledger.1.m4.md +++ b/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 -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. + _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)
diff --git a/hledger/doc/options.m4.md b/hledger/doc/options.m4.md index 2b429f9d0..87bcbdce4 100644 --- a/hledger/doc/options.m4.md +++ b/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:\\$`. + + diff --git a/hledger/doc/queries.m4.md b/hledger/doc/queries.m4.md index 5e8484feb..342c1dd79 100644 --- a/hledger/doc/queries.m4.md +++ b/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` 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`). -Generally you can mix options and query arguments, and the resulting query will be their intersection (aside from the `-p/--period` option). +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 +(perhaps excluding the `-p/--period` option). diff --git a/hledger/doc/troubleshooting.m4.md b/hledger/doc/troubleshooting.m4.md new file mode 100644 index 000000000..cd301df14 --- /dev/null +++ b/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.