diff --git a/doc/lib.m4 b/doc/lib.m4
index 8898583f1..ef964bb64 100644
--- a/doc/lib.m4
+++ b/doc/lib.m4
@@ -1,35 +1,34 @@
 m4_changequote({{,}})m4_dnl
 m4_dnl
+m4_dnl _MACRO_ will be our convention
 m4_define({{_include_}},     m4_defn({{m4_include}})              )m4_dnl
+m4_dnl
+m4_dnl Macros for conditionally including format-specific content
+m4_dnl $1 is the manual's web slug: hledger, hledger-ui, journal, csv etc.
 m4_define({{_man_}},         m4_ifdef({{MAN}},{{$1}})             )m4_dnl
 m4_define({{_web_}},         m4_ifdef({{WEB}},{{$1}})             )m4_dnl
 m4_define({{_webseparate_}}, m4_ifdef({{WEB && SEPARATE}},{{$1}}) )m4_dnl
 m4_define({{_webcombined_}}, m4_ifdef({{WEB && COMBINED}},{{$1}}) )m4_dnl
 m4_dnl
+m4_dnl Author/date/version macros. These are updated by make setdate, setversion etc.
 m4_define({{_author_}}, {{}})m4_dnl
 m4_define({{_monthyear_}}, {{February 2019}})m4_dnl
 m4_define({{_version_}}, {{1.13}})m4_dnl
 m4_dnl
 m4_dnl Links to dev and recent release versions of a manual.
-m4_dnl $1 is the manual's web slug: hledger, hledger-ui, journal, csv etc.
-m4_dnl The current version is hidden (or whatever) by highlightDocVersion in site.js.
-m4_dnl
+m4_dnl The actual links are inserted dynamically by site.js, static generation was much too painful.
+m4_dnl There should be a " (dev)" suffix here except when generating release docs.
 m4_define({{_docversionlinks_}},m4_dnl
 This doc is for version **_version_** (dev).
 <span class="docversions">m4_dnl
-m4_dnl #(inserted by site.js, too painful for static generation)
-m4_dnl #Available versions:
-m4_dnl #<a href="/$1.html">dev</a>
-m4_dnl #| <a href="/doc/1.12/$1.html">1.12</a>
-m4_dnl #...
-m4_dnl #| <a href="/doc/1.0/$1.html">1.0</a>
-m4_dnl #| <a href="/doc/0.27/manual.html#$1">0.27</a>
 </span>)m4_dnl
 m4_dnl
+m4_dnl Insert a table of contents marker, which doc build scripts will populate.
 m4_define({{_toc_}},{{
 \$toc\$
 }})m4_dnl
 m4_dnl
+m4_dnl Helpers for generating table markup.
 m4_dnl _table_({{
 m4_dnl | cell1 | cell2 ...
 m4_dnl | cell1 | cell2 ...
@@ -39,6 +38,7 @@ m4_define({{_table2_}}, {{
 |
 |-|-$1}})m4_dnl
 m4_dnl
+m4_dnl Two side-by-side columns.
 m4_define({{_col2_}},
 {{<div class="container-fluid">
 <div class="row">
@@ -47,6 +47,7 @@ m4_define({{_col2_}},
 </div>
 </div>}})m4_dnl
 m4_dnl
+m4_dnl Three side-by-side columns.
 m4_define({{_col3_}},
 {{<div class="container-fluid">
 <div class="row">
@@ -56,6 +57,7 @@ m4_define({{_col3_}},
 </div>
 </div>}})m4_dnl
 m4_dnl
+m4_dnl Various kinds of code block.
 m4_define({{_shell_}},     {{```shell$1```}}          )m4_dnl
 m4_define({{_shellbold_}}, {{```{.shell .bold}$1```}} )m4_dnl
 m4_define({{_journal_}},   {{```journal$1```}}        )m4_dnl
@@ -64,6 +66,8 @@ m4_define({{_rules_}},     {{```rules$1```}}          )m4_dnl
 m4_define({{_timeclock_}}, {{```timeclock$1```}}      )m4_dnl
 m4_define({{_timedot_}},   {{```timedot$1```}}        )m4_dnl
 m4_dnl
+m4_dnl Various lists of common command line options.
+m4_dnl Should be kept synced with CliOptions.hs etc.
 m4_define({{_helpoptions_}}, {{
 
 `-h --help`
@@ -182,21 +186,22 @@ _optionnotes_
 
 }} )m4_dnl
 m4_dnl
+m4_dnl A standard description of hledger.
 m4_define({{_hledgerdescription_}}, {{
 hledger is a cross-platform program for tracking money, time, or any other commodity,
 using double-entry accounting and a simple, editable file format.
 hledger is inspired by and largely compatible with ledger(1). }} )m4_dnl
 m4_dnl
+m4_dnl A standard description of where hledger reads data from.
 m4_define({{_files_}},
 {{data from one or more files in hledger journal, timeclock, timedot, or CSV format
 specified with `-f`, or `$LEDGER_FILE`,
 or `$HOME/.hledger.journal` (on windows, perhaps `C:/Users/USER/.hledger.journal`).}})m4_dnl
 m4_dnl
+m4_dnl A standard description of the LEDGER_FILE environment variable.
 m4_define({{_LEDGER_FILE_}}, {{
 **LEDGER_FILE**
 The journal file path when not specified with `-f`.
 Default: `~/.hledger.journal` (on windows, perhaps `C:/Users/USER/.hledger.journal`).
 }} )m4_dnl
 m4_dnl
-m4_define({{_FLAGS_}}, {{}})m4_dnl
-m4_dnl