From e3edea11e80c1a25e12ffd8db3d5d5b2e7f388d6 Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Sun, 27 Jun 2021 19:31:15 -1000
Subject: [PATCH] doc: generate a single Info dir file, and commit it (#1585)

Avoids duplicate headings in info viewer, makes installing easier.
---
 Shake.hs | 26 ++++++++++----------------
 dir      | 20 ++++++++++++++++++++
 2 files changed, 30 insertions(+), 16 deletions(-)
 create mode 100644 dir

diff --git a/Shake.hs b/Shake.hs
index 27e393cb6..b29cd2df6 100755
--- a/Shake.hs
+++ b/Shake.hs
@@ -223,9 +223,8 @@ main = do
         infomanuals = [manualDir m </> m <.> "info" | m <- manualNames]
         -- an Info directory entry for each info manual (hledger/dir-entry.info)
         infodirentries = [manualDir m </> "dir-entry.info" | m <- manualNames]
-        -- an Info directory for each hledger package with info manuals, so hledger manuals
-        -- will appear in Info's directory after adding the package directories to INFOPATH.
-        infodirs    = [manualDir m </> "dir" | m <- manualNames]
+        -- an Info directory file which can be included with info -d or INFOPATH
+        infodir = "dir"
 
         -- manuals as sphinx-ready markdown, to be rendered as part of the website (hledger/hledger.md)
         webmanuals = [manualDir m </> m <.> "md" | m <- manualNames]
@@ -398,12 +397,13 @@ main = do
         need $ concat [
                nroffmanuals
               ,infomanuals
+              ,[infodir]
               ,txtmanuals
               ,webmanuals
               ]
         when commit $ do
           let msg = ";update manuals"
-          cmd Shell gitcommit ("-m '"++msg++"' --") packagemandatem4s nroffmanuals infomanuals infodirentries txtmanuals
+          cmd Shell gitcommit ("-m '"++msg++"' --") packagemandatem4s nroffmanuals infomanuals infodirentries infodir txtmanuals
 
       -- Update the dates to show in man pages, to the current month and year.
       -- Currently must be run manually when needed.
@@ -456,8 +456,6 @@ main = do
         cmd Shell "tbl" src "| eqn -Tascii | troff -Wall -mandoc -Tascii | grotty -cbuo >" out
 
       -- Generate Info manuals suitable for viewing with info, from the .m4.md source.
-      phony "infomanuals" $ need $ infomanuals ++ infodirs
-
       infomanuals |%> \out -> do -- hledger/hledger.info
         let src       = out -<.> "m4.md"
             commonm4  = "doc/common.m4"
@@ -489,17 +487,13 @@ main = do
         cmd_ Shell "cat" infodirentry tmp ">" out
         cmd_ Shell "rm -f" tmp
 
-      -- Generate an Info dir file for each info manual, so that they will appear
-      -- in Info's directory (table of contents) if these (filesystem) directories
-      -- are added to INFOPATH.
-      infodirs |%> \out -> do -- hledger/dir
-        let outdir     = takeDirectory out
-            infomanual = outdir </> outdir <.> "info"  -- XXX cutting corners
-            dirfile    = outdir </> "dir"
-        need [infomanual]
-        cmd_ Shell "rm -f" out
-        cmd Shell "install-info" infomanual dirfile
+      -- Generate an Info dir file which can be included with info -d
+      -- or INFOPATH to add hledger menu items in Info's Directory.
+      infodir %> \out -> do
+        need infomanuals
+        forM_ infomanuals $ \info -> cmd_ Shell "install-info" info out
 
+      phony "infomanuals" $ need $ infomanuals ++ [infodir]
 
       -- WEBSITE MARKDOWN SOURCE
 
diff --git a/dir b/dir
new file mode 100644
index 000000000..85cbe29e6
--- /dev/null
+++ b/dir
@@ -0,0 +1,20 @@
+This is the file .../info/dir, which contains the
+topmost node of the Info hierarchy, called (dir)Top.
+The first time you invoke Info you start off looking at this node.
+
+File: dir,	Node: Top	This is the top of the INFO tree
+
+  This (the Directory node) gives a menu of major topics.
+  Typing "q" exits, "H" lists all Info commands, "d" returns here,
+  "h" gives a primer for first-timers,
+  "mEmacs<Return>" visits the Emacs manual, etc.
+
+  In Emacs, you can click mouse button 2 on a menu item or cross reference
+  to select it.
+
+* Menu:
+
+User Applications
+* hledger: (hledger).           Command-line plain text accounting tool.
+* hledger-ui: (hledger-ui).     Terminal UI for the hledger accounting tool.
+* hledger-web: (hledger-web).   Web UI/API for the hledger accounting tool.