;doc: consolidate hledger manual a bit

hledger/hledger.m4.md

@@ -7,7 +7,6 @@ m4_dnl
 m4_dnl hledger.1.m4.md
 m4_dnl  hledger_examples.m4.md
 m4_dnl  hledger_options.m4.md
-m4_dnl  hledger_queries.m4.md
 m4_dnl  hledger_commands.m4.md
 m4_dnl  hledger_troubleshooting.m4.md
 
@@ -66,8 +65,9 @@ try some commands like `hledger print` or `hledger balance`.
 Run `hledger` with no arguments for a list of commands.
  
 _include_(hledger_examples.m4.md)
+
 _include_(hledger_options.m4.md)
-_include_(hledger_queries.m4.md)
+
 _include_(hledger_commands.m4.md)
 
 # ENVIRONMENT

hledger/hledger_addons.m4.md

@@ -1,68 +0,0 @@
-# ADD-ON COMMANDS
-
-hledger also searches for external add-on commands, and will include these in the commands list.
-These are programs or scripts in your PATH whose name starts with `hledger-`
-and ends with a recognised file extension 
-(currently: no extension, `bat`,`com`,`exe`, `hs`,`lhs`,`pl`,`py`,`rb`,`rkt`,`sh`).
-
-Add-ons can be invoked like any hledger command, but there are a few things to be aware of.
-Eg if the `hledger-web` add-on is installed,
-
-- `hledger -h web` shows hledger's help, while `hledger web -h` shows hledger-web's help.
-  
-- Flags specific to the add-on must have a preceding `--` to hide them from hledger.
-  So `hledger web --serve --port 9000` will be rejected; you must use `hledger web -- --serve --port 9000`.
-
-- You can always run add-ons directly if preferred: `hledger-web --serve --port 9000`.
-
-Add-ons are a relatively easy way to add local features or experiment with new ideas.
-They can be written in any language, but haskell scripts have a big advantage:
-they can use the same hledger (and haskell) library functions that built-in commands do,
-for command-line options, journal parsing, reporting, etc.
-
-Here are some hledger add-ons available:
-
-## Official add-ons
-
-These are maintained and released along with hledger.   
-
-### ui
-[hledger-ui](hledger-ui.html) provides an efficient terminal interface. 
-
-### web
-[hledger-web](hledger-web.html) provides a simple web interface.
-
-## Third party add-ons
-
-These are maintained separately, and usually updated shortly after a hledger release.
-
-### iadd
-
-[hledger-iadd](http://hackage.haskell.org/package/hledger-iadd)
-is a more interactive, terminal UI replacement for the [add command](hledger.html#add). 
-
-### interest
-
-[hledger-interest](http://hackage.haskell.org/package/hledger-interest)
-generates interest transactions for an account according to various schemes. 
-
-## Experimental add-ons
-  
-These are available in source form in the hledger repo's bin/ directory.
-They may be less mature and documented than built-in commands.
-Reading and tweaking these is a good way to start making your own!
-
-### autosync
-
-[hledger-autosync](https://github.com/simonmichael/hledger/blob/master/bin/hledger-autosync) 
-is a symbolic link for easily running 
-[ledger-autosync](https://pypi.python.org/pypi/ledger-autosync), if installed. 
-ledger-autosync does deduplicating conversion of OFX data and some CSV formats,
-and can also download the data 
-[if your bank offers OFX Direct Connect](http://wiki.gnucash.org/wiki/OFX_Direct_Connect_Bank_Settings). 
-
-### chart
-
-[hledger-chart.hs](https://github.com/simonmichael/hledger/blob/master/bin/_hledger-chart.hs#L47)
-is an old very basic pie chart generator.
-

hledger/hledger_commands.m4.md

@@ -132,4 +132,59 @@ _include_({{Hledger/Cli/Commands/Tags.md}})
 
 _include_({{Hledger/Cli/Commands/Test.md}})
 
-_include_(hledger_addons.m4.md)
+
+## Add-on Commands
+
+hledger also searches for external add-on commands, and will include these in the commands list.
+These are programs or scripts in your PATH whose name starts with `hledger-`
+and ends with a recognised file extension 
+(currently: no extension, `bat`,`com`,`exe`, `hs`,`lhs`,`pl`,`py`,`rb`,`rkt`,`sh`).
+
+Add-ons can be invoked like any hledger command, but there are a few things to be aware of.
+Eg if the `hledger-web` add-on is installed,
+
+- `hledger -h web` shows hledger's help, while `hledger web -h` shows hledger-web's help.
+  
+- Flags specific to the add-on must have a preceding `--` to hide them from hledger.
+  So `hledger web --serve --port 9000` will be rejected; you must use `hledger web -- --serve --port 9000`.
+
+- You can always run add-ons directly if preferred: `hledger-web --serve --port 9000`.
+
+Add-ons are a relatively easy way to add local features or experiment with new ideas.
+They can be written in any language, but haskell scripts have a big advantage:
+they can use the same hledger (and haskell) library functions that built-in commands do,
+for command-line options, journal parsing, reporting, etc.
+
+Two important add-ons are the hledger-ui and hledger-web user interfaces.
+These are maintained and released along with hledger:
+
+### ui
+[hledger-ui](hledger-ui.html) provides an efficient terminal interface. 
+
+### web
+[hledger-web](hledger-web.html) provides a simple web interface.
+
+Third party add-ons, maintained separately from hledger, include:
+
+### iadd
+
+[hledger-iadd](http://hackage.haskell.org/package/hledger-iadd)
+is a more interactive, terminal UI replacement for the [add command](hledger.html#add). 
+
+### interest
+
+[hledger-interest](http://hackage.haskell.org/package/hledger-interest)
+generates interest transactions for an account according to various schemes. 
+
+<!-- ### autosync -->
+
+<!-- [hledger-autosync](https://github.com/simonmichael/hledger/blob/master/bin/hledger-autosync)  -->
+<!-- is a symbolic link for easily running  -->
+<!-- [ledger-autosync](https://pypi.python.org/pypi/ledger-autosync) if you make a symbolic -->
+<!-- ledger-autosync does deduplicating conversion of OFX data and some CSV formats, -->
+<!-- and can also download the data  -->
+<!-- [if your bank offers OFX Direct Connect](http://wiki.gnucash.org/wiki/OFX_Direct_Connect_Bank_Settings).  -->
+
+A few more experimental or old add-ons can be found in hledger's bin/
+directory. These are typically prototypes and not guaranteed to work.
+

hledger/hledger_examples.m4.md

@@ -2,7 +2,17 @@ m4_dnl Quick examples included early in the manual
 m4_dnl TODO make these and all the command examples pasteable/doctestable ?
 m4_dnl   eg include -f FILE or $LEDGER_FILE details
 
-# EXAMPLES
+# COMMON TASKS
+
+Here are some quick examples of how to do some basic tasks with hledger.
+For more background, see the reference section below, and the journal format manual.
+For a more gentle introduction and additional how-tos, see the hledger.org website.
+
+## Starting a Journal
+
+## Setting Opening Balances
+
+## Recording Transactions
 
 Two simple transactions in hledger journal format:
 
@@ -16,7 +26,9 @@ Two simple transactions in hledger journal format:
   assets:cash
 ```
 
-Some basic reports:
+## Reconciling
+
+## Some basic reports
 
 ```shell
 $ hledger print
@@ -54,7 +66,7 @@ $ hledger register cash
 2015-10-16 farmers market  assets:cash              $-10           $10
 ```
 
-More commands:
+## More commands
 
 ```shell
 $ hledger                                 # show available commands

hledger/hledger_options.m4.md

@@ -32,8 +32,6 @@ Or, you can run the addon executable directly: `hledger-ui --watch`.
 Most hledger commands accept arguments after the command name, 
 which are often a [query](#queries), filtering the data in some way. 
 
-## Argument files
-
 You can save a set of command line options/arguments in a file,
 and then reuse them by writing `@FILENAME` as a command line argument.
 Eg: `hledger bal @foo.args`.
@@ -66,6 +64,105 @@ Good:
 
 See also: [Save frequently used options](save-frequently-used-options.html).
 
+## 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:
+one or more space-separated search terms,
+quotes to enclose whitespace,
+prefixes to match specific fields,
+a not: prefix to negate the match.
+
+We do not yet support arbitrary boolean combinations of search terms;
+instead most commands show transactions/postings/accounts which match (or negatively match):
+
+- any of the description terms AND
+- any of the account terms AND
+- any of the status terms AND
+- all the other terms.
+
+The [print](hledger.html#print) command instead shows transactions which:
+
+- match any of the description terms AND
+- have any postings matching any of the positive account terms AND
+- have no postings matching any of the negative account terms AND
+- match all the other terms.
+
+The following kinds of search terms can be used. 
+Remember these can also be prefixed with **`not:`**, eg to exclude a particular subaccount.
+
+**`REGEX`, `acct:REGEX`**
+: match account names by this regular expression. (With no prefix, `acct:` is assumed.)
+
+: same as above
+
+**`amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N`**
+: match postings with a single-commodity amount that is equal to, less
+than, or greater than N.  (Multi-commodity amounts are not tested, and
+will always match.)  The comparison has two modes: if N is preceded by
+a + or - sign (or is 0), the two signed numbers are
+compared. Otherwise, the absolute magnitudes are compared, ignoring
+sign.
+
+**`code:REGEX`**
+: match by transaction code (eg check number)
+
+**`cur:REGEX`**
+: match postings or transactions including any amounts whose
+currency/commodity symbol is fully matched by REGEX. (For a partial
+match, use `.*REGEX.*`). Note, to match characters which are
+regex-significant, like the dollar sign (`$`), you need to prepend `\`.
+And when using the command line you need to add one more level of
+quoting to hide it from the shell, so eg do: `hledger print cur:'\$'`
+or `hledger print cur:\\$`.
+
+**`desc:REGEX`**
+: match transaction descriptions.
+
+**`date:PERIODEXPR`**
+: match dates within the specified period.
+PERIODEXPR is a [period expression](hledger.html#period-expressions) (with no report interval).
+Examples: `date:2016`, `date:thismonth`, `date:2000/2/1-2/15`, `date:lastweek-`.
+If the `--date2` command line flag is present, this matches [secondary dates](journal.html#secondary-dates) instead.
+
+**`date2:PERIODEXPR`**
+: match secondary dates within the specified period.
+
+**`depth:N`**
+: match (or display, depending on command) accounts at or above this depth
+
+**`note:REGEX`**
+: match transaction [notes](journal.html#payee-and-note)
+(part of description right of `|`, or whole description when there's no `|`)
+
+**`payee:REGEX`**
+: match transaction [payee/payer names](journal.html#payee-and-note)
+(part of description left of `|`, or whole description when there's no `|`)
+
+**`real:, real:0`**
+: match real or virtual postings respectively
+
+**`status:, status:!, status:*`**
+: match unmarked, pending, or cleared transactions respectively
+
+**`tag:REGEX[=REGEX]`**
+: match by tag name, and optionally also by tag value.  Note a
+tag: query is considered to match a transaction if it matches any of
+the postings.  Also remember that postings inherit the tags of their
+parent transaction.
+
+The following special search term is used automatically in hledger-web, only:
+
+**`inacct:ACCTNAME`**
+: tells hledger-web to show the transaction register for this account.
+Can be filtered further with `acct` etc.
+
+Some of these can also be expressed as command-line options (eg `depth:2` is equivalent to `--depth 2`).
+Generally you can mix options and query arguments, and the resulting query will be their intersection
+(perhaps excluding the `-p/--period` option).
+
 ## Special characters in arguments and queries
 
 In shell command lines, option and argument values which contain "problematic" characters,
@@ -823,3 +920,4 @@ meaning to the shell and so must be escaped at least once more.
 See [Special characters](#special-characters). 
 
 
+

hledger/hledger_queries.m4.md

@@ -1,98 +0,0 @@
-# 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:
-one or more space-separated search terms,
-quotes to enclose whitespace,
-prefixes to match specific fields,
-a not: prefix to negate the match.
-
-We do not yet support arbitrary boolean combinations of search terms;
-instead most commands show transactions/postings/accounts which match (or negatively match):
-
-- any of the description terms AND
-- any of the account terms AND
-- any of the status terms AND
-- all the other terms.
-
-The [print](hledger.html#print) command instead shows transactions which:
-
-- match any of the description terms AND
-- have any postings matching any of the positive account terms AND
-- have no postings matching any of the negative account terms AND
-- match all the other terms.
-
-The following kinds of search terms can be used. 
-Remember these can also be prefixed with **`not:`**, eg to exclude a particular subaccount.
-
-**`REGEX`, `acct:REGEX`**
-: match account names by this regular expression. (With no prefix, `acct:` is assumed.)
-
-: same as above
-
-**`amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N`**
-: match postings with a single-commodity amount that is equal to, less
-than, or greater than N.  (Multi-commodity amounts are not tested, and
-will always match.)  The comparison has two modes: if N is preceded by
-a + or - sign (or is 0), the two signed numbers are
-compared. Otherwise, the absolute magnitudes are compared, ignoring
-sign.
-
-**`code:REGEX`**
-: match by transaction code (eg check number)
-
-**`cur:REGEX`**
-: match postings or transactions including any amounts whose
-currency/commodity symbol is fully matched by REGEX. (For a partial
-match, use `.*REGEX.*`). Note, to match characters which are
-regex-significant, like the dollar sign (`$`), you need to prepend `\`.
-And when using the command line you need to add one more level of
-quoting to hide it from the shell, so eg do: `hledger print cur:'\$'`
-or `hledger print cur:\\$`.
-
-**`desc:REGEX`**
-: match transaction descriptions.
-
-**`date:PERIODEXPR`**
-: match dates within the specified period.
-PERIODEXPR is a [period expression](hledger.html#period-expressions) (with no report interval).
-Examples: `date:2016`, `date:thismonth`, `date:2000/2/1-2/15`, `date:lastweek-`.
-If the `--date2` command line flag is present, this matches [secondary dates](journal.html#secondary-dates) instead.
-
-**`date2:PERIODEXPR`**
-: match secondary dates within the specified period.
-
-**`depth:N`**
-: match (or display, depending on command) accounts at or above this depth
-
-**`note:REGEX`**
-: match transaction [notes](journal.html#payee-and-note)
-(part of description right of `|`, or whole description when there's no `|`)
-
-**`payee:REGEX`**
-: match transaction [payee/payer names](journal.html#payee-and-note)
-(part of description left of `|`, or whole description when there's no `|`)
-
-**`real:, real:0`**
-: match real or virtual postings respectively
-
-**`status:, status:!, status:*`**
-: match unmarked, pending, or cleared transactions respectively
-
-**`tag:REGEX[=REGEX]`**
-: match by tag name, and optionally also by tag value.  Note a
-tag: query is considered to match a transaction if it matches any of
-the postings.  Also remember that postings inherit the tags of their
-parent transaction.
-
-The following special search term is used automatically in hledger-web, only:
-
-**`inacct:ACCTNAME`**
-: tells hledger-web to show the transaction register for this account.
-Can be filtered further with `acct` etc.
-
-Some of these can also be expressed as command-line options (eg `depth:2` is equivalent to `--depth 2`).
-Generally you can mix options and query arguments, and the resulting query will be their intersection
-(perhaps excluding the `-p/--period` option).