slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: merge last bits of old manual into new one

Browse Source
This commit is contained in:
Simon Michael 2016-04-12 20:22:40 -07:00
parent b4d491791c
commit aecbcf9461
5 changed files with 213 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
hledger-lib/doc/hledger_journal.5.md
View File

@ -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
-->

7
hledger/doc/hledger.1.m4.md
View File

@ -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.
</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">

35
hledger/doc/options.m4.md
View File

@ -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:\\$`.

63
hledger/doc/queries.m4.md
View File

@ -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`).
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).

85
hledger/doc/troubleshooting.m4.md Normal file
View File

@ -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.