tools: make/shake cleanups

Makefile

@@ -1,24 +1,20 @@
-###############################################################################
+# One of two project scripts files (Makefile, Shake.hs).
-# hledger project makefile
+# This one is usually the simplest to use.
-#
+# It requires GNU Make (https://www.gnu.org/software/make/).
-# This is a reboot of Makefile.old. The old rules are commented out below,
+# Also, some rules require:
+# - stack (http://haskell-lang.org/get-started, installs libs and runs ghc)
+# - shelltestrunner (hackage, runs functional tests)
+# - quickbench (hackage/stackage, runs benchmarks)
+# - hasktags (hackage, generates tag files for code navigation)
+# - profiteur (hackage/stackage, renders profiles as html)
+# - hpack (hackage/stackage, generates cabal files from package.yaml files)
+# - site/hakyll-std/hakyll-std (generic site-building hakyll script)
+# - perl
+
+# This was a reboot of Makefile.old. The old rules were commented out below,
 # to be removed or updated over the next while.
 #
-# Users of this makefile: hledger developers, contributors, probably not end-users.
+# Target users: hledger developers, contributors, probably not end-users.
-#
-# Every user-relevant rule in this makefile should use def-help to define
-# a help string. Use "make help" to see the available rules.
-#
-# Supplementary tools used:
-#
-# - stack, installs dependencies and drives cabal & ghc
-# - shelltestrunner (latest version from hackage or possibly git), runs functional tests
-# - quickbench (from git), runs benchmarks
-# - hasktags, generates tag files for code navigation
-# - profiteur, renders profiles as interactive html
-# - hpack, generates cabal files from package.yaml files
-# - hakyll-std, my generic site-building hakyll script
-# - perl, currently used by a few rules (setversion)
 #
 # Kinds of hledger builds:
 #
@@ -33,6 +29,9 @@
 # This makefile mostly uses stack to get things done (slow but robust).
 # Secondarily it uses ghc directly to do some developer tasks (faster).
 # # Also if needed it uses cabal directly for a few tasks.
+#
+# Every user-relevant rule in this makefile should use def-help to define
+# a help string. Use "make help" to see the available rules.
 
 # def-help* functions for documenting make rules. See the file for usage.
 include help-system.mk

Shake.hs

@@ -3,54 +3,61 @@
    --package base-prelude
    --package directory
    --package extra
-   --package here
+   --package pandoc
    --package safe
    --package shake
    --package time
-   --package pandoc
 -}
 {-
-Usage: see below.
+One of two project scripts files (Makefile, Shake.hs).
-Shake.hs is a more powerful Makefile, providing a number of commands
+This one provides a stronger programming language and more
-for performing useful tasks. Compiling this script is suggested, so that
+platform independence than Make. It will build needed packages (above)
-it runs quicker and will not be affected eg when exploring old code versions.
+on first run and whenever the resolver in stack.yaml changes.
-More about Shake: http://shakebuild.com/manual
+To minimise such startup delays, and reduce sensitivity to git checkout,
-Requires: https://www.haskell.org/downloads#stack
+compiling is recommended: ./Shake.hs compile
 
-Shake notes:
+It requires stack (https://haskell-lang.org/get-started) and
- wishlist:
+auto-installs the packages above. Also, some rules require:
-  just one shake import
+- groff
-  wildcards in phony rules
+- m4
-  multiple individually accessible wildcards
+- makeinfo
-  not having to write :: Action ExitCode after a non-final cmd
+- site/hakyll-std/hakyll-std
+
+Usage: see below.
+
+Shake wishes:
+just one shake import
+wildcards in phony rules
+multiple individually accessible wildcards
+not having to write :: Action ExitCode after a non-final cmd
 -}
 
-{-# LANGUAGE PackageImports, QuasiQuotes #-}
+{-# LANGUAGE PackageImports #-}
-
 import                Prelude ()
 import "base-prelude" BasePrelude
--- import "base"         System.Console.GetOpt
 import "extra"        Data.List.Extra
-import "here"         Data.String.Here
 import "safe"         Safe
 import "shake"        Development.Shake
 import "shake"        Development.Shake.FilePath
 import "time"         Data.Time
 import "directory"    System.Directory as S (getDirectoryContents)
 
-usage = [i|Usage:
+usage = unlines
- ./Shake.hs compile       # compile this script (optional)
+  ["Usage:"
- ./Shake --help           # show options, eg --color
+  ,"./Shake.hs compile       # compile this script (recommended)"
- ./Shake                  # show commands
+  ,"./Shake                  # show commands"
- ./Shake all              # generate everything
+  ,"./Shake all              # generate everything"
- ./Shake docs             # generate general docs
+  ,"./Shake docs             # generate general docs"
- ./Shake website          # generate the web site
+  ,"./Shake website          # generate the web site"
- ./Shake manpages         # generate nroff files for man
+  ,"./Shake manpages         # generate nroff files for man"
- ./Shake txtmanpages      # generate text man pages for embedding
+  ,"./Shake txtmanpages      # generate text man pages for embedding"
- ./Shake infomanpages     # generate info files for info
+  ,"./Shake infomanpages     # generate info files for info"
- ./Shake webmanpages      # generate web man pages for hakyll
+  ,"./Shake webmanpages      # generate web man pages for hakyll"
- ./Shake webmanual        # generate combined web man page for hakyll
+  ,"./Shake webmanual        # generate combined web man page for hakyll"
-|]
+  ,"./Shake clean            # clean generated files"
+  ,"./Shake Clean            # clean harder"
+  ,"./Shake --help           # show options, eg --color"
+  ]
 
 pandoc = "pandoc"                   -- pandoc from PATH (faster)
          --  "stack exec -- pandoc" -- pandoc from project's stackage snapshot
@@ -80,7 +87,7 @@ main = do
     "Shake" %> \out -> do
       need [out <.> "hs"]
       cmd "stack ghc Shake.hs" :: Action ExitCode
-      putLoud "Compiled ./Shake, you can now use this instead of ./Shake.hs"
+      putLoud "You can now run ./Shake instead of ./Shake.hs"
 
     phony "all" $ need ["docs", "website"]
 
@@ -191,7 +198,7 @@ main = do
     -- web site
 
     phony "website" $ do
-      need $ 
+      need $
         webmanpages ++
         [webmanual
         ,"releasemanual"
@@ -226,7 +233,7 @@ main = do
     -- adjust and combine man page mds for single-page web output, using pandoc
     phony "webmanual" $ need [ webmanual ]
 
-    webmanual %> \out -> do 
+    webmanual %> \out -> do
       need webmanpages
       liftIO $ writeFile webmanual "* toc\n\n"
       forM_ webmanpages $ \f -> do -- site/hledger.md, site/journal.md