doc: updates, merge some more from old manual

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
+CSV \- how hledger reads CSV data, and the CSV rules file format
-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@joyful.com>
+Simon Michael <simon@joyful.com> 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)
+hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
-.br
+hledger_csv(5), hledger_journal(5), hledger_timelog(5), hledger_timedot(5),
-hledger_csv(5), hledger_journal(5), hledger_timelog(5)
+ledger(1)
 
-For more information, see http://hledger.org.
+http://hledger.org

hledger-lib/doc/hledger_csv.5.md

@@ -1,6 +1,6 @@
 % hledger_csv(5)
 %
-% October 2015
+% April 2016
 
 <div class="web">
 * 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
 

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@joyful.com>
+Simon Michael <simon@joyful.com> 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)
+hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
-.br
+hledger_csv(5), hledger_journal(5), hledger_timelog(5), hledger_timedot(5),
-hledger_csv(5), hledger_journal(5), hledger_timelog(5)
+ledger(1)
 
-For more information, see http://hledger.org.
+http://hledger.org

hledger-lib/doc/hledger_journal.5.md

@@ -1,6 +1,6 @@
 % hledger_journal(5)
 %
-% October 2015
+% April 2016
 
 <div class="web">
 * 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
 

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@joyful.com>
+Simon Michael <simon@joyful.com> 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)
+hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
-.br
+hledger_csv(5), hledger_journal(5), hledger_timelog(5), hledger_timedot(5),
-hledger_csv(5), hledger_journal(5), hledger_timelog(5)
+ledger(1)
 
-For more information, see http://hledger.org.
+http://hledger.org

hledger-lib/doc/hledger_timedot.5.md

@@ -1,6 +1,6 @@
 % hledger_timedot(5)
 %
-% February 2016
+% April 2016
 
 <div class="web">
 * toc
@@ -9,7 +9,7 @@
 
 # NAME
 
-hledger_timedot - time logging format
+Timedot - hledger's human-friendly time logging format
 
 # DESCRIPTION
 

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@joyful.com>
+Simon Michael <simon@joyful.com> 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)
+hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
-.br
+hledger_csv(5), hledger_journal(5), hledger_timelog(5), hledger_timedot(5),
-hledger_csv(5), hledger_journal(5), hledger_timelog(5)
+ledger(1)
 
-For more information, see http://hledger.org.
+http://hledger.org

hledger-lib/doc/hledger_timelog.5.md

@@ -1,6 +1,6 @@
 % hledger_timelog(5)
 % 
-% October 2015
+% April 2016
 
 <div class="web">
 * toc
@@ -9,7 +9,7 @@
 
 # NAME
 
-hledger_timelog - hledger's timelog file format
+Timelog - the timeclock time logging format, as read by hledger
 
 # DESCRIPTION
 

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@joyful.com>
+Simon Michael <simon@joyful.com> 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)
+hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
-.br
+hledger_csv(5), hledger_journal(5), hledger_timelog(5), hledger_timedot(5),
-hledger_csv(5), hledger_journal(5), hledger_timelog(5)
+ledger(1)
 
-For more information, see http://hledger.org.
+http://hledger.org

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@joyful.com>
+Simon Michael <simon@joyful.com> 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)
+hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
-.br
+hledger_csv(5), hledger_journal(5), hledger_timelog(5), hledger_timedot(5),
-hledger_csv(5), hledger_journal(5), hledger_timelog(5)
+ledger(1)
 
-For more information, see http://hledger.org.
+http://hledger.org

hledger/doc/commands.m4.md

@@ -1,11 +1,15 @@
 # COMMANDS
 
-COMMAND selects one of hledger's subcommands; omit it to list available commands.
+hledger provides a number of subcommands; `hledger` with no arguments shows a list.
-To save typing, some commands have a short form; any unique prefix also works.
+
+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

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
+hledger provides a number of subcommands; \f[C]hledger\f[] with no
-available commands.
+arguments shows a list.
-To save typing, some commands have a short form; any unique prefix also
+.PP
-works.
+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@joyful.com>
+Simon Michael <simon@joyful.com> 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)
+hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
-.br
+hledger_csv(5), hledger_journal(5), hledger_timelog(5), hledger_timedot(5),
-hledger_csv(5), hledger_journal(5), hledger_timelog(5)
+ledger(1)
 
-For more information, see http://hledger.org.
+http://hledger.org

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
 
 <div class="web">
 * 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.
-
-}})
 </div>

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:
+There are three kinds of options.
-
+General options are always available and can appear anywhere in the command line:
-These 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:
+Common reporting options are supported by most commands where applicable,
-
+and individual commands may provide additional command-specific options.
-These are supported by most commands, where applicable.
+Both of these must be written after the command name.
-They must be written after the command name.
-Additional command-specific flags are described in COMMANDS below.
 
 `-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"
+

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

site/docs.md

@@ -87,7 +87,7 @@ File formats:
 
 </div>
 
-#### 3. [New man pages, one page](manual2.html)
+#### 3. [New man pages, combined](manual2.html)
 
 </div>
 <div class="col-sm-3">