diff --git a/hledger-lib/doc/hledger_csv.5 b/hledger-lib/doc/hledger_csv.5 index 34e007e76..848844b24 100644 --- a/hledger-lib/doc/hledger_csv.5 +++ b/hledger-lib/doc/hledger_csv.5 @@ -1,12 +1,11 @@ -.TH "hledger_csv" "5" "October 2015" "" "hledger User Manuals" +.TH "hledger_csv" "5" "April 2016" "" "hledger User Manuals" .SH NAME .PP -hledger_csv \- reading CSV files with hledger, and the CSV rules file -format +CSV \- how hledger reads CSV data, and the CSV rules file format .SH DESCRIPTION .PP hledger can read CSV files, converting each CSV record into a journal @@ -239,20 +238,21 @@ The original order of same\-day entries will be preserved, usually. .SH "REPORTING BUGS" -Report bugs at http://bugs.hledger.org. +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) .SH AUTHORS -Simon Michael +Simon Michael and contributors .SH COPYRIGHT -Copyright (C) 2007-2015 Simon Michael. +Copyright (C) 2007-2016 Simon Michael. .br Released under GNU GPLv3+. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) -.br -hledger_csv(5), hledger_journal(5), hledger_timelog(5) +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timelog(5), hledger_timedot(5), +ledger(1) -For more information, see http://hledger.org. +http://hledger.org diff --git a/hledger-lib/doc/hledger_csv.5.md b/hledger-lib/doc/hledger_csv.5.md index e1a02d3bc..85e9e2d81 100644 --- a/hledger-lib/doc/hledger_csv.5.md +++ b/hledger-lib/doc/hledger_csv.5.md @@ -1,6 +1,6 @@ % hledger_csv(5) % -% October 2015 +% April 2016
* toc @@ -9,7 +9,7 @@ # NAME -hledger_csv - reading CSV files with hledger, and the CSV rules file format +CSV - how hledger reads CSV data, and the CSV rules file format # DESCRIPTION diff --git a/hledger-lib/doc/hledger_journal.5 b/hledger-lib/doc/hledger_journal.5 index 5cb63ed02..25bb68405 100644 --- a/hledger-lib/doc/hledger_journal.5 +++ b/hledger-lib/doc/hledger_journal.5 @@ -1,11 +1,12 @@ -.TH "hledger_journal" "5" "October 2015" "" "hledger User Manuals" +.TH "hledger_journal" "5" "April 2016" "" "hledger User Manuals" .SH NAME .PP -hledger_journal \- reference for hledger\[aq]s journal file format +Journal \- hledger\[aq]s default file format, representing a General +Journal .SH DESCRIPTION .PP hledger\[aq]s usual data source is a plain text file containing journal @@ -808,20 +809,21 @@ timelog files.) .SH "REPORTING BUGS" -Report bugs at http://bugs.hledger.org. +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) .SH AUTHORS -Simon Michael +Simon Michael and contributors .SH COPYRIGHT -Copyright (C) 2007-2015 Simon Michael. +Copyright (C) 2007-2016 Simon Michael. .br Released under GNU GPLv3+. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) -.br -hledger_csv(5), hledger_journal(5), hledger_timelog(5) +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timelog(5), hledger_timedot(5), +ledger(1) -For more information, see http://hledger.org. +http://hledger.org diff --git a/hledger-lib/doc/hledger_journal.5.md b/hledger-lib/doc/hledger_journal.5.md index 2ec4040f9..0f916e198 100644 --- a/hledger-lib/doc/hledger_journal.5.md +++ b/hledger-lib/doc/hledger_journal.5.md @@ -1,6 +1,6 @@ % hledger_journal(5) % -% October 2015 +% April 2016
* toc @@ -9,7 +9,7 @@ # NAME -hledger_journal - reference for hledger's journal file format +Journal - hledger's default file format, representing a General Journal # DESCRIPTION diff --git a/hledger-lib/doc/hledger_timedot.5 b/hledger-lib/doc/hledger_timedot.5 index 2f36fe324..19597697f 100644 --- a/hledger-lib/doc/hledger_timedot.5 +++ b/hledger-lib/doc/hledger_timedot.5 @@ -1,11 +1,11 @@ -.TH "hledger_timedot" "5" "February 2016" "" "hledger User Manuals" +.TH "hledger_timedot" "5" "April 2016" "" "hledger User Manuals" .SH NAME .PP -hledger_timedot \- time logging format +Timedot \- hledger\[aq]s human\-friendly time logging format .SH DESCRIPTION .PP Timedot is a plain text format for logging dated, categorised quantities @@ -126,20 +126,21 @@ Here is a sample.timedot. .SH "REPORTING BUGS" -Report bugs at http://bugs.hledger.org. +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) .SH AUTHORS -Simon Michael +Simon Michael and contributors .SH COPYRIGHT -Copyright (C) 2007-2015 Simon Michael. +Copyright (C) 2007-2016 Simon Michael. .br Released under GNU GPLv3+. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) -.br -hledger_csv(5), hledger_journal(5), hledger_timelog(5) +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timelog(5), hledger_timedot(5), +ledger(1) -For more information, see http://hledger.org. +http://hledger.org diff --git a/hledger-lib/doc/hledger_timedot.5.md b/hledger-lib/doc/hledger_timedot.5.md index 765e6a8d1..2805d95de 100644 --- a/hledger-lib/doc/hledger_timedot.5.md +++ b/hledger-lib/doc/hledger_timedot.5.md @@ -1,6 +1,6 @@ % hledger_timedot(5) % -% February 2016 +% April 2016
* toc @@ -9,7 +9,7 @@ # NAME -hledger_timedot - time logging format +Timedot - hledger's human-friendly time logging format # DESCRIPTION diff --git a/hledger-lib/doc/hledger_timelog.5 b/hledger-lib/doc/hledger_timelog.5 index 29cd18a95..bcad6da78 100644 --- a/hledger-lib/doc/hledger_timelog.5 +++ b/hledger-lib/doc/hledger_timelog.5 @@ -1,11 +1,11 @@ -.TH "hledger_timelog" "5" "October 2015" "" "hledger User Manuals" +.TH "hledger_timelog" "5" "April 2016" "" "hledger User Manuals" .SH NAME .PP -hledger_timelog \- hledger\[aq]s timelog file format +Timelog \- the timeclock time logging format, as read by hledger .SH DESCRIPTION .PP hledger can read timelog files. @@ -80,20 +80,21 @@ These rely on a "timeclock" executable which I think is just the ledger .SH "REPORTING BUGS" -Report bugs at http://bugs.hledger.org. +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) .SH AUTHORS -Simon Michael +Simon Michael and contributors .SH COPYRIGHT -Copyright (C) 2007-2015 Simon Michael. +Copyright (C) 2007-2016 Simon Michael. .br Released under GNU GPLv3+. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) -.br -hledger_csv(5), hledger_journal(5), hledger_timelog(5) +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timelog(5), hledger_timedot(5), +ledger(1) -For more information, see http://hledger.org. +http://hledger.org diff --git a/hledger-lib/doc/hledger_timelog.5.md b/hledger-lib/doc/hledger_timelog.5.md index 41d53d545..e3d02560c 100644 --- a/hledger-lib/doc/hledger_timelog.5.md +++ b/hledger-lib/doc/hledger_timelog.5.md @@ -1,6 +1,6 @@ % hledger_timelog(5) % -% October 2015 +% April 2016
* toc @@ -9,7 +9,7 @@ # NAME -hledger_timelog - hledger's timelog file format +Timelog - the timeclock time logging format, as read by hledger # DESCRIPTION diff --git a/hledger-ui/doc/hledger-ui.1 b/hledger-ui/doc/hledger-ui.1 index 9856be827..7ac24b314 100644 --- a/hledger-ui/doc/hledger-ui.1 +++ b/hledger-ui/doc/hledger-ui.1 @@ -310,20 +310,21 @@ heading to indicate which is being displayed. .SH "REPORTING BUGS" -Report bugs at http://bugs.hledger.org. +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) .SH AUTHORS -Simon Michael +Simon Michael and contributors .SH COPYRIGHT -Copyright (C) 2007-2015 Simon Michael. +Copyright (C) 2007-2016 Simon Michael. .br Released under GNU GPLv3+. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) -.br -hledger_csv(5), hledger_journal(5), hledger_timelog(5) +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timelog(5), hledger_timedot(5), +ledger(1) -For more information, see http://hledger.org. +http://hledger.org diff --git a/hledger-web/doc/hledger-web.1 b/hledger-web/doc/hledger-web.1 index 141e4e15e..f732160ba 100644 --- a/hledger-web/doc/hledger-web.1 +++ b/hledger-web/doc/hledger-web.1 @@ -224,20 +224,21 @@ to run normally, but you will be seeing pages served from the first one. .SH "REPORTING BUGS" -Report bugs at http://bugs.hledger.org. +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) .SH AUTHORS -Simon Michael +Simon Michael and contributors .SH COPYRIGHT -Copyright (C) 2007-2015 Simon Michael. +Copyright (C) 2007-2016 Simon Michael. .br Released under GNU GPLv3+. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) -.br -hledger_csv(5), hledger_journal(5), hledger_timelog(5) +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timelog(5), hledger_timedot(5), +ledger(1) -For more information, see http://hledger.org. +http://hledger.org diff --git a/hledger/doc/commands.m4.md b/hledger/doc/commands.m4.md index c8f9da5c0..4ba2edc4b 100644 --- a/hledger/doc/commands.m4.md +++ b/hledger/doc/commands.m4.md @@ -1,11 +1,15 @@ # COMMANDS -COMMAND selects one of hledger's subcommands; omit it to list available commands. -To save typing, some commands have a short form; any unique prefix also works. +hledger provides a number of subcommands; `hledger` with no arguments shows a list. + +Select a subcommand by writing its name as first argument (eg `hledger incomestatement`). You can also write any unambiguous prefix of a command name (`hledger inc`), or one of the standard short aliases displayed in the command list (`hledger is`). + +If you install additional `hledger-*` packages, +or if you put programs or scripts named `hledger-NAME` in your PATH, these will also be listed as hledger subcommands. Here is a summary (see http://hledger.org/manual#commands for the full command help): -## Data entry: +## Data entry ### add prompt for transactions and add them to the journal. @@ -16,9 +20,51 @@ It appends only, existing transactions are not changed. `--no-new-accounts` : don't allow creating new accounts; helps prevent typos when entering account names -## Reporting: +## Reporting ### accounts + +``` {.shell .right} +$ hledger accounts --tree +assets + bank + checking + saving + cash +expenses + food + supplies +income + gifts + salary +liabilities + debts +``` + +``` {.shell .right} +$ hledger accounts --drop 1 +bank:checking +bank:saving +cash +food +supplies +gifts +salary +debts +``` + +``` {.shell .right} +$ hledger accounts +assets:bank:checking +assets:bank:saving +assets:cash +expenses:food +expenses:supplies +income:gifts +income:salary +liabilities:debts +``` + show account names `--tree` @@ -30,6 +76,15 @@ show account names `--drop=N` : in flat mode: omit N leading account name parts +This command lists all account names that are in use (ie, all the +accounts which have at least one transaction posting to them). With +query arguments, only matched account names are shown. + +It shows a flat list by default. In this mode you can add `--drop N` +to omit the first few account name components. + +With `--tree`, it shows the account hierarchy. + ### activity show an ascii barchart of posting counts per interval (default: daily) @@ -145,7 +200,7 @@ show some journal statistics `-o FILE[.FMT] --output-file=FILE[.FMT]` : write output to FILE instead of stdout. A recognised FMT suffix influences the format. -## Add-on commands: +## Add-on commands Additional commands will be available when executables or scripts named "`hledger-`CMD" are installed in the PATH. These are often diff --git a/hledger/doc/hledger.1 b/hledger/doc/hledger.1 index 9cd61864f..407efa216 100644 --- a/hledger/doc/hledger.1 +++ b/hledger/doc/hledger.1 @@ -1,5 +1,6 @@ +.\"t -.TH "hledger" "1" "October 2015" "hledger 0.26.98" "hledger User Manuals" +.TH "hledger" "1" "April 2016" "hledger 0.27.98" "hledger User Manuals" @@ -215,15 +216,191 @@ show empty/zero things which are normally omitted show amounts in their cost price\[aq]s commodity .RS .RE +.SS Multiple files .PP -If a reporting option is repeated, the last one takes precedence. +One may specify the \f[C]\-\-file\ FILE\f[] option multiple times. +This is equivalent to concatenating the files to standard input and +passing \f[C]\-\-file\ \-\f[], except that the add command functions +normally and adds entries to the first specified file. +.SS Repeated options +.PP +Otherwise, if a reporting option is repeated, the last one takes +precedence. Eg \-p jan \-p feb is equivalent to \-p feb. +.SS Depth limiting +.PP +With the \f[C]\-\-depth\ N\f[] option, commands like account, balance +and register will show only the uppermost accounts in the account tree, +down to level N. +Use this when you want a summary with less detail. +.SS Smart dates +.PP +hledger\[aq]s user interfaces accept a flexible "smart date" syntax +(unlike dates in the journal file). +Smart dates allow some english words, can be relative to today\[aq]s +date, and can have less\-significant date parts omitted (defaulting to +1). +.PP +Examples: +.PP +.TS +tab(@); +lw(33.7n) lw(36.3n). +T{ +\f[C]2009/1/1\f[], \f[C]2009/01/01\f[], \f[C]2009\-1\-1\f[], +\f[C]2009.1.1\f[] \ +T}@T{ +simple dates, several separators allowed +T} +T{ +\f[C]2009/1\f[], \f[C]2009\f[] +T}@T{ +same as above \- a missing day or month defaults to 1 +T} +T{ +\f[C]1/1\f[], \f[C]january\f[], \f[C]jan\f[], \f[C]this\ year\f[] +T}@T{ +relative dates, meaning january 1 of the current year +T} +T{ +\f[C]next\ year\f[] +T}@T{ +january 1 of next year +T} +T{ +\f[C]this\ month\f[] +T}@T{ +the 1st of the current month +T} +T{ +\f[C]this\ week\f[] +T}@T{ +the most recent monday +T} +T{ +\f[C]last\ week\f[] +T}@T{ +the monday of the week before this one +T} +T{ +\f[C]lastweek\f[] +T}@T{ +spaces are optional +T} +T{ +\f[C]today\f[], \f[C]yesterday\f[], \f[C]tomorrow\f[] +T}@T{ +T} +.TE +.SS Reporting interval +.PP +A reporting interval can be specified so that commands like register, +balance and activity will divide their reports into multiple report +periods. +The basic intervals can be selected with one of \f[C]\-D/\-\-daily\f[], +\f[C]\-W/\-\-weekly\f[], \f[C]\-M/\-\-monthly\f[], +\f[C]\-Q/\-\-quarterly\f[], or \f[C]\-Y/\-\-yearly\f[]. +More complex intervals may be specified with a period expression. +.SS Period expressions +.PP +The \f[C]\-p/\-\-period\f[] option accepts period expressions, a +shorthand way of expressing a start date, end date, and or reporting +interval all at once. +Note a period expression on the command line will cause any other date +flags +(\f[C]\-b\f[]/\f[C]\-e\f[]/\f[C]\-D\f[]/\f[C]\-W\f[]/\f[C]\-M\f[]/\f[C]\-Q\f[]/\f[C]\-Y\f[]) +to be ignored. +.PP +hledger\[aq]s period expressions are similar to Ledger\[aq]s, though not +identical. +Here\[aq]s a basic period expression specifying the first quarter of +2009. +Note hledger always treats start dates as inclusive and end dates as +exclusive: +.IP +.nf +\f[C] +\-p\ "from\ 2009/1/1\ to\ 2009/4/1" +\f[] +.fi +.PP +Keywords like "from" and "to" are optional, and so are the spaces. +Just don\[aq]t run two dates together: +.IP +.nf +\f[C] +\-p2009/1/1to2009/4/1 +\-p"2009/1/1\ 2009/4/1" +\f[] +.fi +.PP +Dates are smart dates, so if the current year is 2009, the above can +also be written as: +.IP +.nf +\f[C] +\-p\ "1/1\ to\ 4/1" +\-p\ "january\ to\ apr" +\-p\ "this\ year\ to\ 4/1" +\f[] +.fi +.PP +If you specify only one date, the missing start or end date will be the +earliest or latest transaction in your journal: +.IP +.nf +\f[C] +\-p\ "from\ 2009/1/1"\ \ (everything\ after\ january\ 1,\ 2009) +\-p\ "from\ 2009/1"\ \ \ \ (the\ same) +\-p\ "from\ 2009"\ \ \ \ \ \ (the\ same) +\-p\ "to\ 2009"\ \ \ \ \ \ \ \ (everything\ before\ january\ 1,\ 2009) +\f[] +.fi +.PP +A single date with no "from" or "to" defines both the start and end date +like so: +.IP +.nf +\f[C] +\-p\ "2009"\ \ \ \ \ \ \ \ \ \ \ (the\ year\ 2009;\ \ \ \ equivalent\ to\ "2009/1/1\ to\ 2010/1/1") +\-p\ "2009/1"\ \ \ \ \ \ \ \ \ (the\ month\ of\ jan;\ equivalent\ to\ "2009/1/1\ to\ 2009/2/1") +\-p\ "2009/1/1"\ \ \ \ \ \ \ (just\ that\ day;\ \ \ \ equivalent\ to\ "2009/1/1\ to\ 2009/1/2") +\f[] +.fi +.PP +Period expressions can also start with (or be) a reporting interval: +\f[C]daily\f[], \f[C]weekly\f[], \f[C]monthly\f[], \f[C]quarterly\f[], +\f[C]yearly\f[], or one of the \f[C]every\ ...\f[] expressions below. +Optionally the word \f[C]in\f[] may appear between the reporting +interval and the start/end dates. +Examples: +.IP +.nf +\f[C] +\-p\ "weekly\ from\ 2009/1/1\ to\ 2009/4/1" +\-p\ "monthly\ in\ 2008" +\-p\ "bimonthly\ from\ 2008" +\-p\ "quarterly" +\-p\ "every\ 2\ weeks" +\-p\ "every\ 5\ days\ from\ 1/3" +\-p\ "every\ 15th\ day\ of\ month" +\-p\ "every\ 4th\ day\ of\ week" +\f[] +.fi .SH COMMANDS .PP -COMMAND selects one of hledger\[aq]s subcommands; omit it to list -available commands. -To save typing, some commands have a short form; any unique prefix also -works. +hledger provides a number of subcommands; \f[C]hledger\f[] with no +arguments shows a list. +.PP +Select a subcommand by writing its name as first argument (eg +\f[C]hledger\ incomestatement\f[]). +You can also write any unambiguous prefix of a command name +(\f[C]hledger\ inc\f[]), or one of the standard short aliases displayed +in the command list (\f[C]hledger\ is\f[]). +.PP +If you install additional \f[C]hledger\-*\f[] packages, or if you put +programs or scripts named \f[C]hledger\-NAME\f[] in your PATH, these +will also be listed as hledger subcommands. .PP Here is a summary (see http://hledger.org/manual#commands for the full command help): @@ -242,6 +419,53 @@ account names .RE .SS Reporting .SS accounts +.IP +.nf +\f[C] +$\ hledger\ accounts\ \-\-tree +assets +\ \ bank +\ \ \ \ checking +\ \ \ \ saving +\ \ cash +expenses +\ \ food +\ \ supplies +income +\ \ gifts +\ \ salary +liabilities +\ \ debts +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ accounts\ \-\-drop\ 1 +bank:checking +bank:saving +cash +food +supplies +gifts +salary +debts +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ accounts +assets:bank:checking +assets:bank:saving +assets:cash +expenses:food +expenses:supplies +income:gifts +income:salary +liabilities:debts +\f[] +.fi .PP show account names .TP @@ -259,6 +483,16 @@ show full account names, as a list (default) in flat mode: omit N leading account name parts .RS .RE +.PP +This command lists all account names that are in use (ie, all the +accounts which have at least one transaction posting to them). +With query arguments, only matched account names are shown. +.PP +It shows a flat list by default. +In this mode you can add \f[C]\-\-drop\ N\f[] to omit the first few +account name components. +.PP +With \f[C]\-\-tree\f[], it shows the account hierarchy. .SS activity .PP show an ascii barchart of posting counts per interval (default: daily) @@ -466,6 +700,8 @@ curses\-style interface, see hledger\-ui(1) web interface, see hledger\-web(1) .SH QUERIES .PP +One of hledger\[aq]s strengths is being able to quickly report on +precise subsets of your data. Most commands accept an optional query expression, written as arguments after the command name, to filter the data by date, account name or other criteria. @@ -577,6 +813,12 @@ transaction. before any of the above negates the match. .RS .RE +.PP +Some of the above 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). .SH EXAMPLES .PP Two simple transactions in hledger journal format: @@ -676,26 +918,24 @@ command prompt (up to Windows 7 at least). When input data contains non\-ascii characters, a suitable system locale must be configured (or there will be an unhelpful error). Eg on POSIX, set LANG to something other than C. -.SH REPORTING BUGS -.PP -Report bugs at http://bugs.hledger.org. .SH "REPORTING BUGS" -Report bugs at http://bugs.hledger.org. +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) .SH AUTHORS -Simon Michael +Simon Michael and contributors .SH COPYRIGHT -Copyright (C) 2007-2015 Simon Michael. +Copyright (C) 2007-2016 Simon Michael. .br Released under GNU GPLv3+. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) -.br -hledger_csv(5), hledger_journal(5), hledger_timelog(5) +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timelog(5), hledger_timedot(5), +ledger(1) -For more information, see http://hledger.org. +http://hledger.org diff --git a/hledger/doc/hledger.1.m4.md b/hledger/doc/hledger.1.m4.md index 62f9d494c..67d83b27a 100644 --- a/hledger/doc/hledger.1.m4.md +++ b/hledger/doc/hledger.1.m4.md @@ -1,6 +1,6 @@ -% hledger(1) hledger 0.26.98 +% hledger(1) hledger 0.27.98 % -% October 2015 +% April 2016
* toc @@ -57,9 +57,4 @@ hledger can't render non-ascii characters when run from a Windows command prompt When input data contains non-ascii characters, a suitable system locale must be configured (or there will be an unhelpful error). Eg on POSIX, set LANG to something other than C. -# REPORTING BUGS - -Report bugs at http://bugs.hledger.org. - -}})
diff --git a/hledger/doc/options.m4.md b/hledger/doc/options.m4.md index e5964bc51..1300fbc51 100644 --- a/hledger/doc/options.m4.md +++ b/hledger/doc/options.m4.md @@ -18,9 +18,8 @@ $ hledger-ui --register cash Options and command arguments can be intermixed. Arguments are usually interpreted as a search query which filters the data, see QUERIES. -## General flags: - -These can appear anywhere in the command line. +There are three kinds of options. +General options are always available and can appear anywhere in the command line: `-h --help` : show general help or (after command) command help @@ -43,11 +42,9 @@ These can appear anywhere in the command line. `--debug=N` : : show debug output if N is 1-9 (default: 0) -## Common reporting flags: - -These are supported by most commands, where applicable. -They must be written after the command name. -Additional command-specific flags are described in COMMANDS below. +Common reporting options are supported by most commands where applicable, +and individual commands may provide additional command-specific options. +Both of these must be written after the command name. `-b --begin=DATE ` : include postings/txns on or after this date @@ -97,6 +94,103 @@ Additional command-specific flags are described in COMMANDS below. `-B --cost ` : show amounts in their cost price's commodity -If a reporting option is repeated, the last one takes precedence. Eg -p jan -p +## Multiple files + +One may specify the `--file FILE` option multiple times. This is equivalent to +concatenating the files to standard input and passing `--file -`, except that +the add command functions normally and adds entries to the first specified file. + +## Repeated options + +Otherwise, if a reporting option is repeated, the last one takes precedence. Eg -p jan -p feb is equivalent to -p feb. +## Depth limiting + +With the `--depth N` option, commands like [account](#account), [balance](#balance) +and [register](#register) will show only the uppermost accounts in the account +tree, down to level N. Use this when you want a summary with less detail. + +## Smart dates + +hledger's user interfaces accept a flexible "smart date" syntax (unlike dates in the journal file). Smart dates allow some english words, can be relative to today's date, and can have less-significant date parts omitted (defaulting to 1). + +Examples: + +| +|--------------------------------------------------|------------------------------------------------------| +| `2009/1/1`, `2009/01/01`, `2009-1-1`, `2009.1.1`   | simple dates, several separators allowed | +| `2009/1`, `2009` | same as above - a missing day or month defaults to 1 | +| `1/1`, `january`, `jan`, `this year` | relative dates, meaning january 1 of the current year| +| `next year` | january 1 of next year | +| `this month` | the 1st of the current month | +| `this week` | the most recent monday | +| `last week` | the monday of the week before this one | +| `lastweek` | spaces are optional | +| `today`, `yesterday`, `tomorrow` | | + +## Reporting interval + +A reporting interval can be specified so that commands like +[register](#register), [balance](#balance) and [activity](#activity) will divide their +reports into multiple report periods. The basic intervals can be +selected with one of `-D/--daily`, `-W/--weekly`, `-M/--monthly`, +`-Q/--quarterly`, or `-Y/--yearly`. More complex intervals may be +specified with a period expression. + +## Period expressions + +The `-p/--period` option accepts period expressions, a shorthand way +of expressing a start date, end date, and or reporting interval all at +once. Note a period expression on the command line will cause any other date +flags (`-b`/`-e`/`-D`/`-W`/`-M`/`-Q`/`-Y`) to be ignored. + +hledger's period expressions are similar to Ledger's, though not identical. +Here's a basic period expression specifying the first quarter of 2009. Note +hledger always treats start dates as inclusive and end dates as exclusive: + + -p "from 2009/1/1 to 2009/4/1" + +Keywords like "from" and "to" are optional, and so are the spaces. Just +don't run two dates together: + + -p2009/1/1to2009/4/1 + -p"2009/1/1 2009/4/1" + +Dates are [smart dates](#smart-dates), so if the current year is 2009, the +above can also be written as: + + -p "1/1 to 4/1" + -p "january to apr" + -p "this year to 4/1" + +If you specify only one date, the missing start or end date will be the +earliest or latest transaction in your journal: + + -p "from 2009/1/1" (everything after january 1, 2009) + -p "from 2009/1" (the same) + -p "from 2009" (the same) + -p "to 2009" (everything before january 1, 2009) + +A single date with no "from" or "to" defines both the start and end date +like so: + + -p "2009" (the year 2009; equivalent to "2009/1/1 to 2010/1/1") + -p "2009/1" (the month of jan; equivalent to "2009/1/1 to 2009/2/1") + -p "2009/1/1" (just that day; equivalent to "2009/1/1 to 2009/1/2") + +Period expressions can also start with (or be) a reporting interval: +`daily`, `weekly`, `monthly`, `quarterly`, `yearly`, or one of the +`every ...` expressions below. Optionally the word `in` may appear +between the reporting interval and the start/end dates. +Examples: + + -p "weekly from 2009/1/1 to 2009/4/1" + -p "monthly in 2008" + -p "bimonthly from 2008" + -p "quarterly" + -p "every 2 weeks" + -p "every 5 days from 1/3" + -p "every 15th day of month" + -p "every 4th day of week" + diff --git a/hledger/doc/queries.m4.md b/hledger/doc/queries.m4.md index 8a3e9af3a..5e8484feb 100644 --- a/hledger/doc/queries.m4.md +++ b/hledger/doc/queries.m4.md @@ -1,5 +1,6 @@ # QUERIES +One of hledger's strengths is being able to quickly report on precise subsets of your data. Most commands accept an optional query expression, written as arguments after the command name, to filter the data by date, account name or other criteria. The syntax is similar to a web search: @@ -8,13 +9,15 @@ quotes to enclose whitespace, optional prefixes to match specific fields. Multiple search terms are combined as follows: -All commands except print: show transactions/postings/accounts which match (or negatively match) +All commands except print: +show transactions/postings/accounts which match (or negatively match) - any of the description terms AND - any of the account terms AND - all the other terms. -The print command: show transactions which +The print command: +show transactions which - match any of the description terms AND - have any postings matching any of the positive account terms AND @@ -90,3 +93,6 @@ 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). diff --git a/site/docs.md b/site/docs.md index c3ccd3cb2..f5d38ff46 100644 --- a/site/docs.md +++ b/site/docs.md @@ -87,7 +87,7 @@ File formats:
-#### 3. [New man pages, one page](manual2.html) +#### 3. [New man pages, combined](manual2.html)