;doc: refactor, keep commands.m4 in Commands dir

Shake.hs

@@ -97,6 +97,7 @@ usage =
 --  ,"./Shake relnotes           create draft release notes"
 
 -- groff    = "groff -c" ++ " -Wall"  -- see "groff" below
+m4 = "m4 -P"
 makeinfo = "makeinfo --no-split --force --no-warn --no-validate"  -- silence makeinfo warnings, comment these to see them
 pandoc   = "pandoc --strip-comments"
 gitcommit = "git commit --allow-empty"
@@ -399,6 +400,7 @@ main = do
       nroffmanuals |%> \out -> do -- hledger/hledger.1
         let src       = manpageNameToManualName out <.> "m4.md"
             commonm4  = "doc/common.m4"
+            commandsm4 = "hledger/Hledger/Cli/Commands/commands.m4"
             dir       = takeDirectory out
             pkg       = dir
             packagemanversionm4 = dir </> ".version.m4"
@@ -406,12 +408,12 @@ main = do
             tmpl      = "doc/manpage.nroff"
         pkgversion <- liftIO $ readFile $ dir </> ".version"
         -- mandate <- formatTime defaultTimeLocale "%B %Y" <$> liftIO getCurrentDay  -- XXX not using this.. compare with .date.m4
-        -- assume all other m4 files in dir are included by this one XXX not true in hledger-lib
+        -- assume any other .m4.md 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
+        subfiles <- liftIO $ filter (/= src) . filter (".m4.md" `isSuffixOf`) . map (dir </>) <$> S.getDirectoryContents dir
-        need $ [src, commonm4, packagemanversionm4, packagemandatem4, tmpl] ++ deps
+        need $ [src, commonm4, commandsm4, packagemanversionm4, packagemandatem4, tmpl] ++ subfiles
         when (dir=="hledger") $ need commandmds
         cmd Shell
-          "m4 -P -DMAN -I" dir commonm4 packagemanversionm4 packagemandatem4 src "|"
+          m4 "-DMAN -I" dir commonm4 commandsm4 packagemanversionm4 packagemandatem4 src "|"
           pandoc fromsrcmd "-s" "--template" tmpl
           ("-V footer='"++pkg++"-"++pkgversion++"'")
           "--lua-filter tools/pandoc-drop-html-blocks.lua"
@@ -439,14 +441,15 @@ main = do
       infomanuals |%> \out -> do -- hledger/hledger.info
         let src       = out -<.> "m4.md"
             commonm4  = "doc/common.m4"
+            commandsm4 = "hledger/Hledger/Cli/Commands/commands.m4"
             dir       = takeDirectory out
             packagemanversionm4 = dir </> ".version.m4"
-        -- assume all other m4 files in dir are included by this one XXX not true in hledger-lib
+        -- assume any other .m4.md 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
+        subfiles <- liftIO $ filter (/= src) . filter (".m4.md" `isSuffixOf`) . map (dir </>) <$> S.getDirectoryContents dir
-        need $ [src, commonm4, packagemanversionm4] ++ deps
+        need $ [src, commonm4, commandsm4, packagemanversionm4] ++ subfiles
         when (dir=="hledger") $ need commandmds
         cmd Shell
-          "m4 -P -DINFO -I" dir commonm4 packagemanversionm4 src "|"
+          m4 "-DINFO -I" dir commonm4 commandsm4 packagemanversionm4 src "|"
           -- sed "-e 's/^#(#+)/\\1/'" "|"
           pandoc fromsrcmd
           "--lua-filter tools/pandoc-drop-html-blocks.lua"
@@ -471,14 +474,15 @@ main = do
             manual    = manpageNameToManualName manpage -- hledger, hledger_journal
             src       = dir </> manual <.> "m4.md"
             commonm4  = "doc/common.m4"
+            commandsm4 = "hledger/Hledger/Cli/Commands/commands.m4"
             packageversionm4 = dir </> ".version.m4"
             heading   = let h = manual
                         in if "hledger_" `isPrefixOf` h
                            then drop 8 h ++ " format"
                            else h
-        -- assume any other m4 files in dir are included by this one XXX not true in hledger-lib
+        -- assume any other .m4.md files in dir are included by this one XXX not true in hledger-lib
         subfiles <- liftIO $ filter (/= src) . filter (".m4.md" `isSuffixOf`) . map (dir </>) <$> S.getDirectoryContents dir
-        let deps = [src, commonm4, packageversionm4] ++ subfiles
+        let deps = [src, commonm4, commandsm4, packageversionm4] ++ subfiles
         need deps
         when (manual=="hledger") $ need commandmds
         -- add the web page's heading.
@@ -492,7 +496,7 @@ main = do
           ,""
           ]
         cmd Shell
-          "m4 -P -DWEB -I" dir commonm4 packageversionm4 src "|"
+          m4 "-DWEB -I" dir commonm4 commandsm4 packageversionm4 src "|"
           pandoc fromsrcmd towebmd
           "--lua-filter tools/pandoc-demote-headers.lua"
           ">>" out

doc/common.m4

@@ -22,13 +22,6 @@ m4_define({{_notweb_}},      m4_ifdef({{WEB}},,{{$1}})   )m4_dnl
 m4_define({{_info_}},        m4_ifdef({{INFO}},{{$1}})   )m4_dnl
 m4_define({{_notinfo_}},     m4_ifdef({{INFO}},,{{$1}})  )m4_dnl
 m4_dnl 
-m4_dnl A command's heading and included doc source.
-m4_dnl Usage: _command_(## commandname, Markdownfilebasename)
-m4_define({{_command_}}, 
-{{$1
-_include_(Hledger/Cli/Commands/$2.md)
-}})m4_dnl
-m4_dnl 
 m4_dnl Two side-by-side columns.
 m4_define({{_col2_}},
 {{<div class="container-fluid">

hledger/Hledger/Cli/Commands/commands.m4

@@ -0,0 +1,36 @@
+m4_dnl _command_(NAME, MDFILE)
+m4_dnl Create a command heading and include its doc.
+m4_define({{_command_}}, 
+{{$1
+_include_(hledger/Hledger/Cli/Commands/$2.md)
+}})m4_dnl
+m4_dnl
+m4_dnl _commands_(HEADINGHASHES)
+m4_dnl Used in the hledger manual to include all command docs.
+m4_define({{_commands_}}, 
+{{
+_command_({{$1 accounts}}           ,{{Accounts}})
+_command_({{$1 activity}}           ,{{Activity}})
+_command_({{$1 add}}                ,{{Add}})
+_command_({{$1 aregister}}          ,{{Aregister}})
+_command_({{$1 balance}}            ,{{Balance}})
+_command_({{$1 balancesheet}}       ,{{Balancesheet}})
+_command_({{$1 balancesheetequity}} ,{{Balancesheetequity}})
+_command_({{$1 cashflow}}           ,{{Cashflow}})
+_command_({{$1 check}}              ,{{Check}})
+_command_({{$1 close}}              ,{{Close}})
+_command_({{$1 codes}}              ,{{Codes}})
+_command_({{$1 commodities}}        ,{{Commodities}})
+_command_({{$1 descriptions}}       ,{{Descriptions}})
+_command_({{$1 diff}}               ,{{Diff}})
+_command_({{$1 files}}              ,{{Files}})
+_command_({{$1 help}}               ,{{Help}})
+_command_({{$1 import}}             ,{{Import}})
+_command_({{$1 incomestatement}}    ,{{Incomestatement}})
+_command_({{$1 notes}}              ,{{Notes}})
+_command_({{$1 rewrite}}            ,{{Rewrite}})
+_command_({{$1 roi}}                ,{{Roi}})
+_command_({{$1 stats}}              ,{{Stats}})
+_command_({{$1 tags}}               ,{{Tags}})
+_command_({{$1 test}}               ,{{Test}})
+}})m4_dnl

hledger/hledger.m4.md

@@ -1642,33 +1642,8 @@ m4_dnl _notman_({{
 
 Next, the detailed command docs, in alphabetical order.
 
-m4_dnl    commandnameheading:     Commandmdfile:
+m4_dnl cf Hledger/Cli/Commands/commands.m4:
-_command_({{## accounts}}           ,{{Accounts}})
+_commands_({{##}})
-_command_({{## activity}}           ,{{Activity}})
-_command_({{## add}}                ,{{Add}})
-_command_({{## aregister}}          ,{{Aregister}})
-_command_({{## balance}}            ,{{Balance}})
-_command_({{## balancesheet}}       ,{{Balancesheet}})
-_command_({{## balancesheetequity}} ,{{Balancesheetequity}})
-_command_({{## cashflow}}           ,{{Cashflow}})
-_command_({{## check}}              ,{{Check}})
-_command_({{## close}}              ,{{Close}})
-_command_({{## codes}}              ,{{Codes}})
-_command_({{## commodities}}        ,{{Commodities}})
-_command_({{## descriptions}}       ,{{Descriptions}})
-_command_({{## diff}}               ,{{Diff}})
-_command_({{## files}}              ,{{Files}})
-_command_({{## help}}               ,{{Help}})
-_command_({{## import}}             ,{{Import}})
-_command_({{## incomestatement}}    ,{{Incomestatement}})
-_command_({{## notes}}              ,{{Notes}})
-_command_({{## rewrite}}            ,{{Rewrite}})
-_command_({{## roi}}                ,{{Roi}})
-_command_({{## stats}}              ,{{Stats}})
-_command_({{## tags}}               ,{{Tags}})
-_command_({{## test}}               ,{{Test}})
-
-m4_dnl }})
 
 ## Add-on commands