doc: update man pages
This commit is contained in:
Simon Michael
parent
5ef67e0d4d
commit
8ee0c7fa76
@ -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),
|
||||
|
||||
@ -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),
|
||||
|
||||
@ -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),
|
||||
|
||||
@ -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),
|
||||
|
||||
@ -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),
|
||||
|
||||
@ -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),
|
||||
|
||||
@ -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),
|
||||
|
||||
@ -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),
|
||||
|
||||
@ -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),
|
||||
|
||||
Loading…
Reference in New Issue
Block a user