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

site: adjust some manual section names

Browse Source
This commit is contained in:
Simon Michael 2014-11-11 16:58:18 -08:00
parent 2a2a42c417
commit 9bf2d352a1
4 changed files with 54 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
doc/manual.md
View File

@ -41,7 +41,7 @@ Basic usage is:
$ hledger COMMAND [OPTIONS] [ARGS] $ hledger COMMAND [OPTIONS] [ARGS]
Most [commands](#commands) query or operate on a Most [commands](#commands) query or operate on a
[journal file](#journal-files), which by default is `.hledger.journal` [journal file](#journal), which by default is `.hledger.journal`
in your home directory. You can specify a different file with the `-f` in your home directory. You can specify a different file with the `-f`
option or `LEDGER_FILE` environment variable, or standard input with `-f-`. option or `LEDGER_FILE` environment variable, or standard input with `-f-`.
@ -71,9 +71,9 @@ enter some transactions. Or, save this
$ hledger reg desc:shop # show postings with shop in the description $ hledger reg desc:shop # show postings with shop in the description
$ hledger activity # show transactions per day as a bar chart $ hledger activity # show transactions per day as a bar chart
## Data format ## Data formats
### Journal files ### Journal
hledger's usual data source is a plain text file containing journal entries in hledger journal format. hledger's usual data source is a plain text file containing journal entries in hledger journal format.
This file represents a standard accounting [general journal](http://en.wikipedia.org/wiki/General_journal). This file represents a standard accounting [general journal](http://en.wikipedia.org/wiki/General_journal).
@ -514,7 +514,7 @@ 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.) it may only include other journal files (eg, not CSV or timelog files.)
### CSV files ### CSV
hledger can also read hledger can also read
[CSV](http://en.wikipedia.org/wiki/Comma-separated_values) files, [CSV](http://en.wikipedia.org/wiki/Comma-separated_values) files,
@ -637,7 +637,7 @@ If the CSV has debit/credit amounts in separate fields, assign the `amount-in` a
Generating entries with three or more postings is not supported at present. Generating entries with three or more postings is not supported at present.
### Timelog files ### Timelog
hledger can also read time log files. These are (a subset of) timeclock.el's hledger can also read time log files. These are (a subset of) timeclock.el's
format, containing clock-in and clock-out entries like so: format, containing clock-in and clock-out entries like so:
@ -945,7 +945,7 @@ Here's [an example](step-by-step#record-a-transaction-with-hledger-add).
$ $
--> -->
### Reporting ### Reports
These are the commands for actually querying your ledger. These are the commands for actually querying your ledger.
@ -1213,8 +1213,6 @@ Examples:
$ hledger stats $ hledger stats
$ hledger stats -p 'monthly in 2009' $ hledger stats -p 'monthly in 2009'
### Misc.
#### test #### test
This command runs hledger's built-in unit tests and displays a quick This command runs hledger's built-in unit tests and displays a quick
@ -1227,7 +1225,7 @@ Examples:
$ hledger test $ hledger test
$ hledger test -v balance $ hledger test -v balance
### Add-on ### Add-ons
Add-on commands are executables in your PATH whose name starts with Add-on commands are executables in your PATH whose name starts with
`hledger-` and ends with no file extension or one of these common `hledger-` and ends with no file extension or one of these common
@ -1319,7 +1317,7 @@ authenticating proxy, any visitor to your server will be able to see and
overwrite the journal file (and included files.) overwrite the journal file (and included files.)
hledger-web disallows edits which would leave the journal file not in hledger-web disallows edits which would leave the journal file not in
valid [journal format](#the-journal-file). If the file becomes unparseable valid [journal format](#journal). If the file becomes unparseable
by other means, hledger-web will show an error until the file has been by other means, hledger-web will show an error until the file has been
fixed. fixed.
@ -1329,9 +1327,8 @@ Examples:
$ hledger-web -E -B --depth 2 -f some.journal $ hledger-web -E -B --depth 2 -f some.journal
$ hledger-web --server --port 5010 --base-url http://some.vhost.com --debug=1 $ hledger-web --server --port 5010 --base-url http://some.vhost.com --debug=1
\\ ### Experimental
\\
\\
The following add-ons are examples and experiments provided in the The following add-ons are examples and experiments provided in the
[extra](https://github.com/simonmichael/hledger/tree/master/extra) [extra](https://github.com/simonmichael/hledger/tree/master/extra)
directory in the hledger source. Add this directory to your PATH to directory in the hledger source. Add this directory to your PATH to
@ -1339,10 +1336,6 @@ make them available. The scripts are designed to run interpreted on
unix systems (for tweaking), or you can compile them (for speed and unix systems (for tweaking), or you can compile them (for speed and
robustness). robustness).
#### balance-csv
Like the balance command, but with CSV output.
#### equity #### equity
Like ledger's equity command, this prints a single journal entry with Like ledger's equity command, this prints a single journal entry with
@ -1360,10 +1353,6 @@ of files as input to hledger.
Prints only journal entries which are unique (by description). Prints only journal entries which are unique (by description).
#### register-csv
Like the register command, but with CSV output.
#### rewrite #### rewrite
Prints all journal entries, adding specified custom postings to matched entries. Prints all journal entries, adding specified custom postings to matched entries.
@ -1450,55 +1439,22 @@ https://twitter.com/LedgerTips/status/501767602067472384
## Known limitations
Here are some things to be aware of.
### Add-on-specific options must follow --
When invoking an add-on via hledger, add-on flags which are not also
understood by the main hledger executable must have a `--` argument
preceding them. Eg hledger-web's `--server` flag must be used like so:
`hledger web -- --server`.
### -w/--width and --debug options must be written without whitespace
Up to hledger 0.23, these optional-value flags [did not work](https://github.com/simonmichael/hledger/issues/149) with whitespace between the flag and value.
IE these worked: `--debug`, `-w`, `--debug=2`, `-w100`, but these did not: `--debug 2`, `-w 100`.
From 0.24, a value is required and the whitespace does not matter.
### Not all of Ledger's journal file syntax is supported
See [file format differences](faq#file-format-differences).
### balance is less speedy than Ledger's on large data files
hledger's balance command (in particular) takes more time, and uses more memory, than Ledger's.
This becomes more noticeable with large data files.
### Windows CMD.EXE
Non-ascii characters and colours are not supported.
### Windows cygwin/msys/mintty
The tab key is not supported in hledger add.
## Troubleshooting ## Troubleshooting
### Run-time problems
Here are some issues you might encounter when you run hledger Here are some issues you might encounter when you run hledger
(and remember you can also seek help from the (and remember you can also seek help from the
[IRC channel](https://github.com/ledger/ledger/wiki/%23ledger-IRC-channel), [IRC channel](http://irc.hledger.org),
[mail list](http://hledger.org/list) or [mail list](http://list.hledger.org) or
[bug tracker](http://hledger.org/bugs)): [bug tracker](http://bugs.hledger.org)):
### Successfully installed, but "No command 'hledger' found" #### Successfully installed, but "No command 'hledger' found"
cabal installs binaries into a special directory, which should be added cabal installs binaries into a special directory, which should be added
to your PATH environment variable. On unix-like systems, it is to your PATH environment variable. On unix-like systems, it is
~/.cabal/bin. ~/.cabal/bin.
### "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors #### "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors
In order to handle non-ascii letters and symbols (like £), hledger needs In order to handle non-ascii letters and symbols (like £), hledger needs
an appropriate locale. This is usually configured system-wide; you can an appropriate locale. This is usually configured system-wide; you can
also configure it temporarily. The locale may need to be one that also configure it temporarily. The locale may need to be one that
@ -1538,4 +1494,37 @@ Note some platforms allow variant locale spellings, but not all (ubuntu
accepts `fr_FR.UTF8`, mac osx requires exactly `fr_FR.UTF-8`). accepts `fr_FR.UTF8`, mac osx requires exactly `fr_FR.UTF-8`).
### Known limitations
Here are some things to be aware of.
#### Add-on-specific options must follow --
When invoking an add-on via hledger, add-on flags which are not also
understood by the main hledger executable must have a `--` argument
preceding them. Eg hledger-web's `--server` flag must be used like so:
`hledger web -- --server`.
#### -w/--width and --debug options must be written without whitespace
Up to hledger 0.23, these optional-value flags [did not work](https://github.com/simonmichael/hledger/issues/149) with whitespace between the flag and value.
IE these worked: `--debug`, `-w`, `--debug=2`, `-w100`, but these did not: `--debug 2`, `-w 100`.
From 0.24, a value is required and the whitespace does not matter.
#### Not all of Ledger's journal file syntax is supported
See [file format differences](faq#file-format-differences).
#### balance is less speedy than Ledger's on large data files
hledger's balance command (in particular) takes more time, and uses more memory, than Ledger's.
This becomes more noticeable with large data files.
#### Windows CMD.EXE
Non-ascii characters and colours are not supported.
#### Windows cygwin/msys/mintty
The tab key is not supported in hledger add.

4
doc/site/how-to-read-csv-files.md
View File

@ -1,6 +1,6 @@
# How to read CSV files # How to read CSV files
Here's a quick example of [converting a CSV file](manual.html#csv-files). Here's a quick example of [converting a CSV file](manual.html#csv).
Say we have downloaded `checking.csv` from a bank for the first time: Say we have downloaded `checking.csv` from a bank for the first time:
@ -8,7 +8,7 @@ Say we have downloaded `checking.csv` from a bank for the first time:
"2012/3/22","DEPOSIT","50.00" "2012/3/22","DEPOSIT","50.00"
"2012/3/23","TRANSFER TO SAVINGS","-10.00" "2012/3/23","TRANSFER TO SAVINGS","-10.00"
We tell hledger how to intepret this with a file named `checking.csv.rules`, using the [CSV rules syntax](manual.html#csv-files). Eg: We tell hledger how to intepret this with a file named `checking.csv.rules`, using the [CSV rules syntax](manual.html#csv). Eg:
# skip the first CSV line (headings) # skip the first CSV line (headings)
skip 1 skip 1

2
doc/site/index.md
View File

@ -61,7 +61,7 @@ performance and long-term maintainability. Most functionality is
exposed as reusable Haskell exposed as reusable Haskell
[libraries](http://hackage.haskell.org/package/hledger-lib), making it [libraries](http://hackage.haskell.org/package/hledger-lib), making it
easy to write your own hledger-compatible easy to write your own hledger-compatible
[scripts](more-docs.html#scripting-examples), [add-ons](manual.html#add-on) and [scripts](more-docs.html#scripting-examples), [add-ons](manual.html#add-ons) and
applications. applications.
</div> </div>

2
doc/site/release-notes.md
View File

@ -317,7 +317,7 @@ Marko Kocić, Max Bolingbroke, and a big welcome to first-time committer John Wi
**CSV reading:** **CSV reading:**
- CSV conversion rules have a simpler, more flexible [syntax](manual.html#csv-files). - CSV conversion rules have a simpler, more flexible [syntax](manual.html#csv).
Existing rules files will need to be updated manually: Existing rules files will need to be updated manually:
- the filename is now `FILE.csv.rules` instead of `FILE.rules` - the filename is now `FILE.csv.rules` instead of `FILE.rules`
- `FIELD-field N` is now `FIELD %N+1` (or set them all at once with a `fields` rule) - `FIELD-field N` is now `FIELD %N+1` (or set them all at once with a `fields` rule)