diff --git a/hledger-lib/doc/hledger_csv.5 b/hledger-lib/doc/hledger_csv.5
index 6ab08e634..34e007e76 100644
--- a/hledger-lib/doc/hledger_csv.5
+++ b/hledger-lib/doc/hledger_csv.5
@@ -22,7 +22,7 @@ At minimum, the rules file must specify the \f[C]date\f[] and
 For an example, see How to read CSV files.
 .PP
 (For CSV output, see CSV output.)
-.SH CSV RULES
+.SS CSV rules
 .PP
 The following six kinds of rule can appear in the rules file, in any
 order.
@@ -215,7 +215,7 @@ Eg:
 include\ common.rules
 \f[]
 .fi
-.SS Other CSV tips
+.SS CSV tips
 .PP
 Each generated journal entry will have two postings, to
 \f[C]account1\f[] and \f[C]account2\f[] respectively.
diff --git a/hledger-lib/doc/hledger_csv.5.md b/hledger-lib/doc/hledger_csv.5.md
index 0709b3180..e1a02d3bc 100644
--- a/hledger-lib/doc/hledger_csv.5.md
+++ b/hledger-lib/doc/hledger_csv.5.md
@@ -28,7 +28,7 @@ For an example, see [How to read CSV files](how-to-read-csv-files.html).
 (For CSV output, see [CSV output](#csv-output).)
 
 
-# CSV rules
+## CSV rules
 
 The following six kinds of rule can appear in the rules file, in any order.
 Blank lines and lines beginning with `#` or `;` are ignored.
@@ -137,7 +137,7 @@ a path relative to the current file's directory. Eg:
 include common.rules
 ```
 
-## Other CSV tips
+## CSV tips
 
 Each generated journal entry will have two postings, to `account1` and `account2` respectively.
 Currently it's not possible to generate entries with more than two postings.
diff --git a/hledger-lib/doc/hledger_journal.5 b/hledger-lib/doc/hledger_journal.5
index 5bd0901f2..5cb63ed02 100644
--- a/hledger-lib/doc/hledger_journal.5
+++ b/hledger-lib/doc/hledger_journal.5
@@ -58,7 +58,7 @@ Here\[aq]s an example:
 .fi
 .PP
 Now let\[aq]s explore the available journal file syntax in detail.
-.SH TRANSACTIONS
+.SS Transactions
 .PP
 Transactions are represented by journal entries.
 Each begins with a simple date in column 0, followed by three optional
@@ -80,7 +80,7 @@ The (real) posting amounts within a transaction must always balance, ie
 add up to 0.
 Optionally one amount can be left blank, in which case it will be
 inferred.
-.SH DATES
+.SS Dates
 .SS Simple dates
 .PP
 Within a journal file, transaction dates use Y/M/D (or Y\-M\-D or Y.M.D)
@@ -178,7 +178,7 @@ in a posting comment.
 When using any of these forms, be sure to provide a valid simple date or
 you\[aq]ll get a parse error.
 Eg a \f[C]date:\f[] tag with no value is not allowed.
-.SH ACCOUNT NAMES
+.SS Account names
 .PP
 Account names typically have several parts separated by a full colon,
 from which hledger derives a hierarchical chart of accounts.
@@ -192,7 +192,7 @@ Because of this, they must always be followed by at least two spaces (or
 newline).
 .PP
 Account names can be aliased.
-.SH AMOUNTS
+.SS Amounts
 .PP
 After the account name, there is usually an amount.
 Important: between account name and amount, there must be \f[B]two or
@@ -245,7 +245,7 @@ indirectly, eg when D\[aq]s default commodity is applied to a
 commodity\-less amount or when an amountless posting is balanced using a
 price\[aq]s commodity (actually this last case does not influence the
 canonical display precision but probably should).
-.SH VIRTUAL POSTINGS
+.SS Virtual Postings
 .PP
 When you parenthesise the account name in a posting, that posting is
 considered \f[I]virtual\f[], which means:
@@ -278,7 +278,7 @@ occasionally be useful, but they can be a crutch and you should think
 twice or three times before using them.
 You can almost always find an equivalent journal entry using two or more
 real postings that will be more correct and more error\-proof.
-.SH BALANCE ASSERTIONS
+.SS Balance Assertions
 .PP
 hledger supports ledger\-style balance assertions in journal files.
 These look like \f[C]=EXPECTEDBALANCE\f[] following a posting\[aq]s
@@ -376,7 +376,7 @@ Balance assertions are checked against all postings, both real and
 virtual.
 They are not affected by the \f[C]\-\-real/\-R\f[] flag or
 \f[C]real:\f[] query.
-.SH PRICES
+.SS Prices
 .SS Transaction prices
 .PP
 When recording a transaction, you can also record an amount\[aq]s price
@@ -477,7 +477,7 @@ P\ 2010/1/1\ €\ $1.40
 .fi
 .PP
 Example use for market prices: tracking the value of stocks.
-.SH COMMENTS
+.SS Comments
 .PP
 Lines in the journal beginning with a semicolon (\f[C];\f[]) or hash
 (\f[C]#\f[]) or asterisk (\f[C]*\f[]) are comments, and will be ignored.
@@ -519,7 +519,7 @@ end\ comment
 ;\ a\ journal\ comment\ (because\ not\ indented)
 \f[]
 .fi
-.SH TAGS
+.SS Tags
 .PP
 A \f[I]tag\f[] is a word followed by a full colon inside a transaction
 or posting comment.
@@ -547,7 +547,7 @@ posting\-tag):
 .PP
 Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag
 values are always simple strings.
-.SH DIRECTIVES
+.SS Directives
 .SS Account aliases
 .PP
 You can define aliases which rewrite your account names (after reading
diff --git a/hledger-lib/doc/hledger_journal.5.md b/hledger-lib/doc/hledger_journal.5.md
index 7ecdc5e42..2ec4040f9 100644
--- a/hledger-lib/doc/hledger_journal.5.md
+++ b/hledger-lib/doc/hledger_journal.5.md
@@ -61,7 +61,7 @@ Here's an example:
 
 Now let's explore the available journal file syntax in detail.
 
-# Transactions
+## Transactions
 
 Transactions are represented by journal entries. Each begins with a
 [simple date](#simple-dates) in column 0, followed by three optional
@@ -79,9 +79,9 @@ The ([real](#virtual-postings)) posting amounts within a transaction
 must always balance, ie add up to 0.  Optionally one amount can be
 left blank, in which case it will be inferred.
 
-# Dates
+## Dates
 
-## Simple dates
+### Simple dates
 
 Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D)
 Leading zeroes are optional.
@@ -91,7 +91,7 @@ year, or you can set the default year with a
 
 Some examples: `2010/01/31`, `1/31`, `2010-01-31`, `2010.1.31`.
 
-## Secondary dates
+### Secondary dates
 
 Real-life transactions sometimes involve more than one date - eg the date
 you write a cheque, and the date it clears in your bank.  When you want to
@@ -130,7 +130,7 @@ your journal entries and remember whether to use or not use the
 `--date2` flag for your reports. Arguably they are now obsolete,
 superseded by...
 
-## Posting dates
+### Posting dates
 
 You can give individual postings a different date from their parent
 transaction, by adding a [posting tag](#tags) (see below) like
@@ -168,7 +168,7 @@ When using any of these forms, be sure to provide a valid simple date
 or you'll get a parse error. Eg a `date:` tag with no value is not
 allowed.
 
-# Account names
+## Account names
 
 Account names typically have several parts separated by a full colon, from
 which hledger derives a hierarchical chart of accounts. They can be
@@ -180,7 +180,7 @@ Because of this, they must always be followed by at least two spaces (or newline
 
 Account names can be [aliased](#account-aliases).
 
-# Amounts
+## Amounts
 
 After the account name, there is usually an amount.
 Important: between account name and amount, there must be **two or more** spaces.
@@ -189,7 +189,7 @@ The amount is a number, optionally with a currency symbol or commodity name on e
 Negative amounts may have the minus sign either before or after the currency symbol (`-$1` or `$-1`).
 Commodity names which contain more than just letters should be enclosed in double quotes (`1 "person hours"`).
 
-## Decimal points and digit groups
+### Decimal points and digit groups
 
 hledger supports flexible decimal point and digit group separator styles,
 to support international variations. Numbers can use either a period (`.`)
@@ -200,7 +200,7 @@ digit group separators, you must also include a decimal point in at least
 one number in the same commodity, so that hledger knows which character is
 which. Eg, write `$1,000.00` or `$1.000,00`.
 
-## Amount display styles
+### Amount display styles
 
 Based on how you format amounts, hledger will infer canonical display
 styles for each commodity, and use these when displaying amounts in that
@@ -217,7 +217,7 @@ However the display precision will be the highest precision seen in all posting
 The precisions used in a price amount, or a D directive, don't affect the canonical display precision directly, but they can affect it indirectly, eg when D's default commodity is applied to a commodity-less amount or when an amountless posting is balanced using a price's commodity (actually this last case does not influence the canonical display precision but probably should).
 
 
-# Virtual Postings
+## Virtual Postings
 
 When you parenthesise the account name in a posting, that posting is considered *virtual*, which
 means:
@@ -232,13 +232,13 @@ You could use this, eg, to set an account's opening balance without needing to u
 1/1 special unbalanced posting to set initial balance
   (assets:checking)   $1000
 ```
-## Balanced Virtual Postings
+### Balanced Virtual Postings
 
 When the account name is bracketed, the posting is *balanced virtual*, which is just like a virtual posting except the balanced virtual postings in a transaction must balance to 0, like the real postings (but separately from them). Balanced virtual postings are also excluded by `--real/-R` or `real:1`.
 
 Virtual postings are a feature inherited from Ledger can can occasionally be useful, but they can be a crutch and you should think twice or three times before using them. You can almost always find an equivalent journal entry using two or more real postings that will be more correct and more error-proof.
 
-# Balance Assertions
+## Balance Assertions
 
 hledger supports ledger-style
 [balance assertions](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assertions)
@@ -264,7 +264,7 @@ while cleaning up old entries. You can disable them temporarily with
 the `--ignore-assertions` flag, which can be useful for
 troubleshooting or for reading Ledger files.
 
-## Assertions and ordering
+### Assertions and ordering
 
 hledger sorts an account's postings and assertions first by date and
 then (for postings on the same day) by parse order. Note this is
@@ -287,7 +287,7 @@ account's balance on the same day, you'll have to put the assertion
 in the right file.
 
 
-## Assertions and commodities
+### Assertions and commodities
 
 The asserted balance must be a simple single-commodity amount, and in
 fact the assertion checks only this commodity's balance within the
@@ -302,7 +302,7 @@ that no matter how many assertions you add, you can't be sure the
 account does not contain some unexpected commodity. (We'll add support
 for this kind of total balance assertion if there's demand.)
 
-## Assertions and subaccounts
+### Assertions and subaccounts
 
 Balance assertions do not count the balance from subaccounts; they check
 the posted account's exclusive balance. For example:
@@ -328,9 +328,9 @@ Balance assertions are checked against all postings, both real and
 flag or `real:` query.
 
 
-# Prices
+## Prices
 
-## Transaction prices
+### Transaction prices
 
 When recording a transaction, you can also record an amount's price in another commodity.
 This documents the exchange rate, cost (of a purchase), or selling price (of a sale) that was in effect within this particular transaction (or more precisely, within the particular posting).
@@ -380,7 +380,7 @@ $ hledger print -B
 Example use for transaction prices: recording the effective conversion
 rate of purchases made in a foreign currency.
 
-## Market prices
+### Market prices
 
 Market prices are not tied to a particular transaction; they represent
 historical exchange rates between two commodities, usually from some
@@ -416,7 +416,7 @@ default.  Ledger has a different syntax for specifying
 -->
 <!-- hledger treats this as an alternate spelling of `@ PRICE`, for greater compatibility with Ledger files. -->
 
-# Comments
+## Comments
 
 Lines in the journal beginning with a semicolon (`;`) or hash (`#`) or
 asterisk (`*`) are comments, and will be ignored. (Asterisk comments
@@ -454,7 +454,7 @@ end comment
 ; a journal comment (because not indented)
 ```
 
-# Tags
+## Tags
 
 A *tag* is a word followed by a full colon inside a transaction or
 posting [comment](#comments).  You can write multiple tags, comma
@@ -480,9 +480,9 @@ Tags are like Ledger's
 [metadata](http://ledger-cli.org/3.0/doc/ledger3.html#Metadata)
 feature, except hledger's tag values are always simple strings.
 
-# Directives
+## Directives
 
-## Account aliases
+### Account aliases
 
 You can define aliases which rewrite your account names (after reading the journal,
 before generating reports). hledger's account aliases can be useful for:
@@ -494,7 +494,7 @@ before generating reports). hledger's account aliases can be useful for:
 
 See also [How to use account aliases](how-to-use-account-aliases.html).
 
-### Basic aliases
+#### Basic aliases
 
 To set an account alias, use the `alias` directive in your journal file.
 This affects all subsequent journal entries in the current file or its
@@ -517,7 +517,7 @@ alias checking = assets:bank:wells fargo:checking
 # rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
 ```
 
-### Regex aliases
+#### Regex aliases
 
 There is also a more powerful variant that uses a regular expression,
 indicated by the forward slashes. (This was the default behaviour in hledger 0.24-0.25):
@@ -543,7 +543,7 @@ alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
 # rewrites "assets:bank:wells fargo:checking" to  "assets:wells fargo checking"
 ```
 
-### Multiple aliases
+#### Multiple aliases
 
 You can define as many aliases as you like using directives or command-line options.
 Aliases are recursive - each alias sees the result of applying previous ones.
@@ -553,7 +553,7 @@ Aliases are applied in the following order:
 1. alias directives, most recently seen first (recent directives take precedence over earlier ones; directives not yet seen are ignored)
 2. alias options, in the order they appear on the command line
 
-### end aliases
+#### end aliases
 
 You can clear (forget) all currently defined aliases with the `end aliases` directive:
 
@@ -561,7 +561,7 @@ You can clear (forget) all currently defined aliases with the `end aliases` dire
 end aliases
 ```
 
-## account directive
+### account directive
 
 The `account` directive predefines account names, as in Ledger and Beancount.
 This may be useful for your own documentation; hledger doesn't make use of it yet.
@@ -579,7 +579,7 @@ account expenses:food
 ; etc.
 ```
 
-## apply account directive
+### apply account directive
 
 You can specify a parent account which will be prepended to all accounts
 within a section of the journal. Use the `apply account` and `end apply account`
@@ -614,12 +614,12 @@ include personal.journal
 
 Prior to hledger 0.28, legacy `account` and `end` spellings were also supported.
 
-## Multi-line comments
+### Multi-line comments
 
 A line containing just `comment` starts a multi-line comment, and a
 line containing just `end comment` ends it. See [comments](#comments).
 
-## Default commodity
+### Default commodity
 
 You can set a default commodity, to be used for amounts without one.
 Use the D directive with a sample amount.
@@ -653,7 +653,7 @@ $ hledger print
     d    £-1,000.00
 ```
 
-## Default year
+### Default year
 
 You can set a default year to be used for subsequent dates which don't
 specify a year. This is a line beginning with `Y` followed by the year. Eg:
@@ -676,7 +676,7 @@ Y2010      ; change default year to 2010
   assets
 ```
 
-## Including other files
+### Including other files
 
 You can pull in the content of additional journal files by writing an
 include directive, like this:
diff --git a/hledger-ui/doc/hledger-ui.1 b/hledger-ui/doc/hledger-ui.1
index 4a85b3aec..9856be827 100644
--- a/hledger-ui/doc/hledger-ui.1
+++ b/hledger-ui/doc/hledger-ui.1
@@ -77,7 +77,7 @@ show help
 show version information
 .RS
 .RE
-.SS hledger options:
+.SS hledger options
 .PP
 The following common hledger options should also work:
 .TP
diff --git a/hledger-web/doc/hledger-web.1 b/hledger-web/doc/hledger-web.1
index 666235fc6..141e4e15e 100644
--- a/hledger-web/doc/hledger-web.1
+++ b/hledger-web/doc/hledger-web.1
@@ -106,7 +106,7 @@ show help
 show version information
 .RS
 .RE
-.SS hledger options:
+.SS hledger options
 .PP
 The following common hledger options should also work:
 .TP
diff --git a/hledger/doc/hledger.1 b/hledger/doc/hledger.1
index a25766f37..9cd61864f 100644
--- a/hledger/doc/hledger.1
+++ b/hledger/doc/hledger.1
@@ -89,9 +89,10 @@ $\ 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.
-.SS General flags
 .PP
-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:
 .TP
 .B \f[C]\-h\ \-\-help\f[]
 show general help or (after command) command help
@@ -128,11 +129,11 @@ ignore any failing balance assertions in the journal
 : show debug output if N is 1\-9 (default: 0)
 .RS
 .RE
-.SS Common reporting flags
 .PP
-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.
 .TP
 .B \f[C]\-b\ \-\-begin=DATE\f[]
 include postings/txns on or after this date
diff --git a/hledger/doc/hledger.1.md b/hledger/doc/hledger.1.md
index 564da8929..ed196aab1 100644
--- a/hledger/doc/hledger.1.md
+++ b/hledger/doc/hledger.1.md
@@ -81,9 +81,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
@@ -106,11 +105,10 @@ 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