From 761d912324b9d7f45758cbf910d4b448940c5637 Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Thu, 26 Jan 2017 15:25:06 -0800
Subject: [PATCH] doc: docs page, cookbook tweaks

---
 Shake.hs                |  5 ++---
 site/docs.md            | 10 +++++-----
 site/start-journal.md   |  6 +++++-
 site/version-control.md |  4 ++--
 4 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/Shake.hs b/Shake.hs
index 94e869aa9..e7662b75e 100755
--- a/Shake.hs
+++ b/Shake.hs
@@ -271,8 +271,7 @@ main = do
 
     webmanall %> \out -> do
       need webmanpages
-      -- avoid # Big Manual\n\n heading which will throw off the TOC style
-      liftIO $ writeFile webmanall "* toc\n\n"
+      liftIO $ writeFile webmanall "* toc\n\n" -- # Big Manual\n\n -- TOC style is better without main heading,
       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"
@@ -287,7 +286,7 @@ main = do
 
     cookbookall %> \out -> do
       need cookbookpages  -- XXX seems not to work, not rebuilt when a recipe changes 
-      liftIO $ writeFile cookbookall "# User Cookbook\n\n* toc\n\n"
+      liftIO $ writeFile cookbookall "* toc\n\n"  -- # User Cookbook\n\n -- TOC style is better without main heading, 
       forM_ cookbookpages $ \f -> do -- site/csv-import.md, site/account-aliases.md, ...
         cmd Shell ("printf '\\n\\n' >>") cookbookall :: Action ExitCode
         cmd Shell "pandoc" f "-t markdown --atx-headers"
diff --git a/site/docs.md b/site/docs.md
index 5b8623d3c..0b6395bd2 100644
--- a/site/docs.md
+++ b/site/docs.md
@@ -42,8 +42,8 @@ To get started as a developer, see [Contribute](developer-guide.html)!
 
 ## Reference
 
-#### [Big Manual](manual.html)
-All manuals on one page, including:
+#### [Manuals](manual.html)
+AKA The Law. One big page, including:
 
 <div style="padding-left:0em;">
 
@@ -84,10 +84,10 @@ A more human-friendly time logging format.
 </div>
 <div class="col-sm-3">
 
-## Day-to-day use
+## Doing stuff
 
-#### [User Cookbook](cookbook.html)
-Practical recipes on one page, including:
+#### [The Cookbook](cookbook.html)
+Practical user recipes, including:
 
 <div style="padding-left:0em;">
 
diff --git a/site/start-journal.md b/site/start-journal.md
index 325a24ae5..870d72892 100644
--- a/site/start-journal.md
+++ b/site/start-journal.md
@@ -7,6 +7,10 @@
 The simplest possible journal is just an empty file:\
 `echo >2017.journal`
 
+The name doesn't matter much and can be changed later. 
+One file per year is common, 
+and so is a `.journal` or `.hledger` extension.
+
 Record a transaction, using [journal format](/journal.html):
 ```shell
 $ cat >>2017.journal
@@ -25,7 +29,7 @@ perhaps with one extra subcategory as above.
 
 ## by text editor
 
-Use a [text editor](/journal.html#editor-support) to add transactions and save the file.
+Write transactions in a [text editor](/journal.html#editor-support) and save the file.
 
 ## by add
 
diff --git a/site/version-control.md b/site/version-control.md
index 3e30ae1e6..07b822438 100644
--- a/site/version-control.md
+++ b/site/version-control.md
@@ -5,7 +5,7 @@ You don't need to do this, but it's a nice way to keep track of changes to your
 ## git
 
 Start tracking changes:\
-`git init && git add 2017.journal && git commit 2017.journal -m "initial commit"`
+`git init && git add 2017.journal && git commit 2017.journal -m "first commit"`
 
 View uncommitted changes: `git status`, `git diff` 
 
@@ -15,7 +15,7 @@ View past commits: `git log`
 
 ## darcs
 
-`darcs init && darcs add 2017.journal && darcs record 2017.journal -m "initial commit"`
+`darcs init && darcs add 2017.journal && darcs record 2017.journal -m "first commit"`
 
 `darcs whatsnew`, `darcs diff`