From d4654d46af82e0a185a6a7067b0ebcc12fcdaa3a Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Thu, 26 Jan 2017 09:50:06 -0800
Subject: [PATCH] doc: cookbook tweaks, simpler titles

Also drop the main heading from the big manual again,
it disrupted the TOC style.

[ci skip]
---
 Shake.hs                  | 13 +++++++++----
 site/account-aliases.md   |  2 +-
 site/account-separator.md |  2 +-
 site/csv-import.md        |  2 +-
 site/docs.md              |  6 +++---
 site/entries.md           |  4 ++--
 6 files changed, 17 insertions(+), 12 deletions(-)

diff --git a/Shake.hs b/Shake.hs
index d1d56a996..5962d7406 100755
--- a/Shake.hs
+++ b/Shake.hs
@@ -133,8 +133,12 @@ main = do
 
       -- cookbook pages in markdown, ready for web output by hakyll (site/csv-import.md).
       -- Keeping these in the main site directory allows hakyll-std to see them (and simpler urls).
-      -- These should be ordered like the links on the docs page, so that the combined
-      -- cookbook follows the same order.
+      -- These should be kept ordered like the links on the docs page, so that the 
+      -- combined cookbook follows the same order.
+      -- XXX This, as well as keeping page link, heading, and filename synced, will be a bit tricky.
+      -- Current policy:
+      -- filenames are simple and stable as possible, beginning with TOPIC- prefix when appropriate
+      -- titles are succinct and practical/action-oriented 
       cookbookpages = [
          "site/entries.md"
         ,"site/csv-import.md"
@@ -265,7 +269,8 @@ main = do
 
     webmanall %> \out -> do
       need webmanpages
-      liftIO $ writeFile webmanall "# Big Manual\n\n* toc\n\n"
+      -- avoid # Big Manual\n\n heading which will throw off the TOC style
+      liftIO $ writeFile webmanall "* toc\n\n"
       forM_ webmanpages $ \f -> do -- site/hledger.md, site/journal.md
         cmd Shell ("printf '\\n\\n' >>") webmanall :: Action ExitCode
         cmd Shell "pandoc" f "-t markdown --atx-headers"
@@ -279,7 +284,7 @@ main = do
     phony "cookbookall" $ need [ cookbookall ]
 
     cookbookall %> \out -> do
-      need cookbookpages
+      need cookbookpages  -- XXX seems not to work, not rebuilt when a recipe changes 
       liftIO $ writeFile cookbookall "# User Cookbook\n\n* toc\n\n"
       forM_ cookbookpages $ \f -> do -- site/csv-import.md, site/account-aliases.md, ...
         cmd Shell ("printf '\\n\\n' >>") cookbookall :: Action ExitCode
diff --git a/site/account-aliases.md b/site/account-aliases.md
index 5e7000bad..a2df9fbd9 100644
--- a/site/account-aliases.md
+++ b/site/account-aliases.md
@@ -1,4 +1,4 @@
-# How to use account aliases
+# Rewrite account names
 
 Here's an example of using [account aliases](manual.html#account-aliases).
 
diff --git a/site/account-separator.md b/site/account-separator.md
index 3ce4436be..4b0966c8d 100644
--- a/site/account-separator.md
+++ b/site/account-separator.md
@@ -1,4 +1,4 @@
-# How to use another account separator character
+# Use another account separator character
 
 [Timedot format](manual.html#timedot) makes me want to use dots (`.`) for separating account components, instead of colon (`:`). 
 For example, instead of `fos:hledger:timedot` I'd like to write `fos.hledger.timedot`.
diff --git a/site/csv-import.md b/site/csv-import.md
index d654da80c..be594aa8b 100644
--- a/site/csv-import.md
+++ b/site/csv-import.md
@@ -1,4 +1,4 @@
-# How to read CSV files
+# Convert CSV files
 
 Here's a quick example of [converting a CSV file](manual.html#csv-format).
 
diff --git a/site/docs.md b/site/docs.md
index a7b1e306d..b170facf5 100644
--- a/site/docs.md
+++ b/site/docs.md
@@ -90,9 +90,9 @@ Practical recipes on one page, including:
 <div style="padding-left:0em;">
 
 [Common journal entries](entries.html)\
-[How to read CSV files](csv-import.html)\
-[How to use account aliases](account-aliases.html)\
-[How to use another account separator character](account-separator.html)\
+[Convert CSV files](csv-import.html)\
+[Rewrite account names](account-aliases.html)\
+[Use another account separator character](account-separator.html)\
 
 </div>
 
diff --git a/site/entries.md b/site/entries.md
index 77de5790b..55fdd2ab8 100644
--- a/site/entries.md
+++ b/site/entries.md
@@ -1,12 +1,12 @@
-# Common Journal Entries
+# Common journal entries
 
 Example hledger journal entries for various kinds of transaction.
  
 A purchase:
+
 ```journal
 2017/1/26 market
   expenses:food    $10
   assets:cash
 ```
 
-Please add more.
\ No newline at end of file