diff --git a/Makefile b/Makefile
index 65979a1e0..217b9829d 100644
--- a/Makefile
+++ b/Makefile
@@ -138,7 +138,7 @@ CABALFILES:= \
 	hledger-*/*.cabal \
 
 MANUALSOURCEFILES:= \
-	doc/lib.m4 \
+	doc/common.m4 \
 	*/*.m4.md \
 
 MANUALGENFILES:= \
@@ -165,7 +165,7 @@ DOCSOURCEFILES:= \
 # files which should be updated when the version changes
 VERSIONSENSITIVEFILES=\
 	$(HPACKFILES) \
-	doc/lib.m4 \
+	doc/common.m4 \
 
 # # file(s) which require recompilation for a build to have an up-to-date version string
 # VERSIONSOURCEFILE=hledger/Hledger/Cli/Version.hs
@@ -715,12 +715,11 @@ iscleanwd:
 isclean-%:
 	@$(ISCLEAN) $* || (echo "please clean these files first: $*"; false)
 
-#	@$(ISCLEAN) doc/lib.m4 || (echo "please clean doc/lib.m4 first"; false)
 setdate: $(call def-help,setdate, set date in manuals to current month and year )
-	perl -pe "s/^(m4_define\({{_monthyear_}}, *{{)[^}]*(}}\)m4_dnl *)$$/\$${1}$(MONTHYEAR)\$${2}/" -i doc/lib.m4
+	perl -pe "s/^(m4_define\({{_monthyear_}}, *{{)[^}]*(}}\)m4_dnl *)$$/\$${1}$(MONTHYEAR)\$${2}/" -i doc/common.m4
 
 updatedate: setdate $(call def-help,updatedate, set date in manuals to current month and year and commit )
-	git commit -m "bump manual date to $(MONTHYEAR)" doc/lib.m4
+	git commit -m "bump manual date to $(MONTHYEAR)" doc/common.m4
 
 # Updating version numbers.  See VERSIONSENSITIVEFILES etc. defined
 # above, and CONTRIBUTING.md > Version numbers.
@@ -744,9 +743,9 @@ setversion: $(VERSIONSENSITIVEFILES) #$(call def-help,setversion, update version
 	perl -pe "s/(hledger(-\w+)?) *>=? *((\d+\.)*\d+) *&& *< *((\d+\.)*\d+) *$$/\$$1 >=$(VERSION) && <\$$5/" -i $@  # hledgerX >= A && < B
 
 # update version string used in generated docs
-doc/lib.m4: $(VERSIONFILE)
+doc/common.m4: $(VERSIONFILE)
 	perl -pe "s/^(m4_define\({{_version_}}, *{{)((\d+\.)*\d+)(}}\)m4_dnl *)$$/\$${1}$(VERSION)\$${4}/" -i $@
-	@echo "please manually check/update _docversionlinks_ in doc/lib.m4"
+	@echo "please manually check/update _docversionlinks_ in doc/common.m4"
 
 # (re)generate a cabal file from its package.yaml definition 
 # XXX to avoid warnings, this hpack should be the same version as stack's built-in hpack
diff --git a/Shake.hs b/Shake.hs
index e002c7adc..aa2188a58 100755
--- a/Shake.hs
+++ b/Shake.hs
@@ -242,7 +242,7 @@ main = do
     phony "manmanuals" $ need nroffmanuals
     nroffmanuals |%> \out -> do -- hledger/hledger.1
       let src = manpageNameToManualName out <.> "m4.md"
-          lib = "doc/lib.m4"
+          lib = "doc/common.m4"
           dir = takeDirectory out
           tmpl = "doc/manpage.nroff"
       -- assume all other m4 files in dir are included by this one XXX not true in hledger-lib
@@ -269,7 +269,7 @@ main = do
     phony "infomanuals" $ need infomanuals
     infomanuals |%> \out -> do -- hledger/hledger.info
       let src = out -<.> "m4.md"
-          lib = "doc/lib.m4"
+          lib = "doc/common.m4"
           dir = takeDirectory out
       -- assume all other m4 files in dir are included by this one XXX not true in hledger-lib
       deps <- liftIO $ filter (/= src) . filter (".m4.md" `isSuffixOf`) . map (dir </>) <$> S.getDirectoryContents dir
@@ -295,7 +295,7 @@ main = do
           manual  = manpageNameToManualName manpage
           dir     = manpageDir manpage
           src     = dir </> manual <.> "m4.md"
-          lib     = "doc/lib.m4"
+          lib     = "doc/common.m4"
           heading = let h = manual
                     in if "hledger_" `isPrefixOf` h
                        then drop 8 h ++ " format"
@@ -380,7 +380,7 @@ main = do
     
     commandtxts |%> \out -> do
       let src = out -<.> "md"
-          -- lib = "doc/lib.m4"
+          -- lib = "doc/common.m4"
       need [src]
       cmd Shell
         -- "m4 -P -DHELP -I" commandsdir lib src "|"
diff --git a/doc/lib.m4 b/doc/common.m4
similarity index 94%
rename from doc/lib.m4
rename to doc/common.m4
index ef964bb64..12d257dcd 100644
--- a/doc/lib.m4
+++ b/doc/common.m4
@@ -1,6 +1,11 @@
+m4_dnl Common m4 macro definitions used in hledger docs (all packages).
+m4_dnl
+m4_dnl "m4_dnl" causes the rest of the line to be ignored.
+m4_dnl
+m4_dnl {{ }} will be our quoting delimiters
 m4_changequote({{,}})m4_dnl
 m4_dnl
-m4_dnl _MACRO_ will be our convention
+m4_dnl _MACRO_ will be the naming convention for our macros
 m4_define({{_include_}},     m4_defn({{m4_include}})              )m4_dnl
 m4_dnl
 m4_dnl Macros for conditionally including format-specific content
@@ -205,3 +210,6 @@ 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_dnl Dummy macro to strip _FLAGS_ marker in command docs.
+m4_define({{_FLAGS_}}, {{}})m4_dnl
+m4_dnl