doc: docs page, cookbook tweaks

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" -- # Big Manual\n\n -- TOC style is better without main heading,
-      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"
@@ -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"

site/docs.md

@@ -42,8 +42,8 @@ To get started as a developer, see [Contribute](developer-guide.html)!
 
 ## Reference
 
-#### [Big Manual](manual.html)
+#### [Manuals](manual.html)
-All manuals on one page, including:
+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)
+#### [The Cookbook](cookbook.html)
-Practical recipes on one page, including:
+Practical user recipes, including:
 
 <div style="padding-left:0em;">
 

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
 

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`