diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md
index 7490660d3..d2607f96c 100644
--- a/hledger/hledger.m4.md
+++ b/hledger/hledger.m4.md
@@ -1684,47 +1684,49 @@ Here are some more definitions:
symbol side and spacing, digit groups, decimal mark, and number of
decimal places.
-Directives are not required when starting out with hledger, but you
-will probably add some as your needs grow.
-Here is an overview of directives by purpose:
+Directives are not required when starting out with hledger,
+but you will probably want to add some as your needs grow.
+Here are the directives organised by use case:
-| purpose | directives | command line options with similar effect |
-|-------------------------------------------------------------------------------|---------------------------------------------------------|---------------------------------------------|
-| **READING/GENERATING DATA:** | | |
-| Declare a commodity's or file's decimal mark to help parse amounts accurately | [`commodity`], [`D`], [`decimal-mark`] | |
-| Apply changes to the data while parsing | [`alias`], [`apply account`], [`comment`], [`D`], [`Y`] | [`--alias`] |
-| Inline extra data files | [`include`] | [multiple `-f/--file`'s](#multiple-files) |
-| Generate extra transactions or budget goals | [`~`] | |
-| Generate extra postings | [`=`] | |
-| **CHECKING FOR ERRORS:** | | |
-| Define valid entities to allow stricter error checking | [`account`], [`commodity`], [`payee`] | |
-| **DISPLAYING REPORTS:** | | |
-| Declare accounts' display order and accounting type | [`account`] | |
-| Declare commodity display styles | [`commodity`], [`D`] | [`-c/--commodity-style`](#commodity-styles) |
-| Declare market prices | [`P`] | |
+| purpose | directives |
+|-------------------------------------------------------------------------------|---------------------------------------------------------|
+| **READING/GENERATING DATA:** | |
+| Declare a commodity's or file's decimal mark to help parse amounts accurately | [`commodity`], [`D`], [`decimal-mark`] |
+| Apply changes to the data while parsing | [`alias`], [`apply account`], [`comment`], [`D`], [`Y`] |
+| Inline extra data files | [`include`] |
+| Generate extra transactions or budget goals | [`~`] |
+| Generate extra postings | [`=`] |
+| **CHECKING FOR ERRORS:** | |
+| Define valid entities to allow stricter error checking | [`account`], [`commodity`], [`payee`] |
+| **DISPLAYING REPORTS:** | |
+| Declare accounts' display order and accounting type | [`account`] |
+| Declare commodity display styles | [`commodity`], [`D`] |
+| Declare market prices | [`P`] |
-And here are all the directives and their precise effects:
+### Directive effects
+
+And here is what each directive does, and which files and journal entries (transactions) it affects:
-| directive | effects | ends at file end? |
-|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|
-| **[`account`]** | Declares an account, for [checking](#check) all entries in all files;
and its [display order](#account-display-order) and [type](#declaring-account-types), for reports.
Subdirectives: any text, ignored. | |
-| **[`alias`]** | Rewrites account names, in following entries until end of current file or [`end aliases`]. | Y |
-| **[`apply account`]** | Prepends a common parent account to all account names, in following entries until end of current file or `end apply account`. | Y |
-| **[`comment`]** | Ignores part of the journal file, until end of current file or `end comment`. | Y |
-| **[`commodity`]** | Declares a commodity, for checking all entries in all files;
the decimal mark for parsing amounts of this commodity, for following entries until end of current file;
and its display style, for reports. Takes precedence over `D`.
Subdirectives: `format` (alternate syntax). | N,
Y
|
-| **[`D`]** | Sets a default commodity to use for no-symbol amounts,
and its decimal mark for parsing amounts of this commodity in following entries until end of current file;
and its display style, for reports. | Y |
-| **[`decimal-mark`]** | Declares the decimal mark, for parsing amounts of all commodities in following entries until next `decimal-mark` or end of current file. Included files can override. Takes precedence over `commodity` and `D`. | Y |
-| **[`include`]** | Includes entries and directives from another file, as if they were written inline. | |
-| **[`payee`]** | Declares a payee name, for checking all entries in all files. | |
-| **[`P`]** | Declares a market price for a commodity on some date, for [valuation](#valuation) reports. | |
-| **[`Y`]** | Declares a year for yearless dates, for following entries until end of current file. | Y |
-| **[`~`]** (tilde) | Declares a periodic transaction rule that generates future transactions with `--forecast` and budget goals with `balance --budget`. | |
-| **[`=`]** (equals) | Declares an auto posting rule that generates extra postings on matched transactions with `--auto`, in current, parent, and child files (but not sibling files, see [#1212](https://github.com/simonmichael/hledger/issues/1212)). | partly |
+| directive | what it does | ends at file end? |
+|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|
+| **[`account`]** | Declares an account, for [checking](#check) all entries in all files;
and its [display order](#account-display-order) and [type](#declaring-account-types).
Subdirectives: any text, ignored. | N |
+| **[`alias`]** | Rewrites account names, in following entries until end of current file or [`end aliases`].
Command line equivalent: [`--alias`] | Y |
+| **[`apply account`]** | Prepends a common parent account to all account names, in following entries until end of current file or `end apply account`. | Y |
+| **[`comment`]** | Ignores part of the journal file, until end of current file or `end comment`. | Y |
+| **[`commodity`]** | Declares up to four things:
1. a commodity symbol, for checking all amounts in all files
2. the decimal mark for parsing amounts of this commodity, in the following entries until end of current file (if there is no `decimal-mark` directive)
3. and the display style for amounts of this commodity
4. which is also the precision to use for balanced-transaction checking in this commodity.
Takes precedence over `D`.
Subdirectives: `format` (Ledger-compatible syntax).
Command line equivalent: [`-c/--commodity-style`](#commodity-styles) | N,
Y,
N,
N |
+| **[`D`]** | Sets a default commodity to use for no-symbol amounts;
and, if there is no `commodity` directive for this commodity: its decimal mark, balancing precision, and display style, as above. | Y,
Y,
N,
N |
+| **[`decimal-mark`]** | Declares the decimal mark, for parsing amounts of all commodities in following entries until next `decimal-mark` or end of current file. Included files can override. Takes precedence over `commodity` and `D`. | Y |
+| **[`include`]** | Includes entries and directives from another file, as if they were written inline.
Command line alternative: multiple [`-f/--file`](#multiple-files) | N |
+| **[`payee`]** | Declares a payee name, for checking all entries in all files. | N |
+| **[`P`]** | Declares the market price of a commodity on some date, for [value reports](#valuation). | N |
+| **[`Y`]** | Sets a default year to use for any yearless dates, in following entries until end of current file. | Y |
+| **[`~`]** (tilde) | Declares a periodic transaction rule that generates future transactions with `--forecast` and budget goals with `balance --budget`. | N |
+| **[`=`]** (equals) | Declares an auto posting rule that generates extra postings on matched transactions with `--auto`, in current, parent, and child files (but not sibling files, see [#1212](https://github.com/simonmichael/hledger/issues/1212)). | partly |
[`=`]: #auto-postings
[`D`]: #default-commodity