;doc: hledger: inline troubleshooting, cleanups, m4 docs

[ci skip]

hledger/hledger.m4.md

@@ -2,14 +2,20 @@
 % _author_
 % _monthyear_
 
-m4_dnl This man page is composed from multiple files as follows:
+m4_dnl Quick hledger m4 intro:
+m4_dnl  .m4.md are hledger docs source, processed with m4 to generate markdown.
+m4_dnl  Lines beginning with m4_dnl are comments.
+m4_dnl  Words enclosed in underscores are macros, defined in doc/common.m4.
+m4_dnl  Macro arguments are enclosed in (). Text literals are enclosed in {{}}.
+m4_dnl  Macros may depend on command line flags, configured in Shake.hs.
 m4_dnl
+m4_dnl This file includes others:
 m4_dnl hledger.1.m4.md
 m4_dnl  hledger_examples.m4.md
 m4_dnl  hledger_options.m4.md
 m4_dnl  hledger_commands.m4.md
-m4_dnl  hledger_troubleshooting.m4.md
 
+m4_dnl Show these first headings only in man pages:
 _man_({{
 # NAME
 }})
@@ -28,6 +34,7 @@ _man_({{
 # DESCRIPTION
 }})
 
+m4_dnl Include the standard description:
 _hledgerdescription_
 
 This is hledger’s command-line interface (there are also terminal and web
@@ -46,6 +53,7 @@ You can specify standard input with `-f-`.
 Transactions are dated movements of money between two (or more) named
 accounts, and are recorded with journal entries like this:
 
+m4_dnl Format as a journal snippet:
 _journal_({{
 2015/10/16 bought food
  expenses:food          $10
@@ -64,10 +72,9 @@ To get started, you can either save some entries like the above in
 try some commands like `hledger print` or `hledger balance`.
 Run `hledger` with no arguments for a list of commands.
  
+m4_dnl Include these subfiles:
 _include_(hledger_examples.m4.md)
-
 _include_(hledger_options.m4.md)
-
 _include_(hledger_commands.m4.md)
 
 # ENVIRONMENT
@@ -76,10 +83,12 @@ _include_(hledger_commands.m4.md)
 The screen width used by the register command. 
 Default: the full terminal width.
 
+m4_dnl Standard LEDGER_FILE description:
 _LEDGER_FILE_
 
 # FILES
 
+m4_dnl Standard input files description:
 Reads _files_
 
 # LIMITATIONS
@@ -100,4 +109,66 @@ Not all of Ledger's journal file syntax is supported. See [file format differenc
 
 On large data files, hledger is slower and uses more memory than Ledger.
 
-_include_(hledger_troubleshooting.m4.md)
+# TROUBLESHOOTING
+
+Here are some issues you might encounter when you run hledger
+(and remember you can also seek help from the
+[IRC channel](http://irc.hledger.org),
+[mail list](http://list.hledger.org) or
+[bug tracker](http://bugs.hledger.org)):
+
+**Successfully installed, but "No command 'hledger' found"**  
+stack and cabal install binaries into a special directory, which
+should be added to your PATH environment variable.  Eg on unix-like
+systems, that is ~/.local/bin and ~/.cabal/bin respectively.
+
+**I set a custom LEDGER_FILE, but hledger is still using the default file**  
+`LEDGER_FILE` should be a real environment variable, not just a shell variable.
+The command `env | grep LEDGER_FILE` should show it.
+You may need to use `export`. Here's an [explanation](http://stackoverflow.com/a/7411509).
+
+**"Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors**  
+In order to handle non-ascii letters and symbols (like £), hledger needs
+an appropriate locale. This is usually configured system-wide; you can
+also configure it temporarily.  The locale may need to be one that
+supports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
+I'm not sure yet).
+
+Here's an example of setting the locale temporarily, on ubuntu gnu/linux:
+
+```shell
+$ file my.journal
+my.journal: UTF-8 Unicode text                 # <- the file is UTF8-encoded
+$ locale -a
+C
+en_US.utf8                             # <- a UTF8-aware locale is available
+POSIX
+$ LANG=en_US.utf8 hledger -f my.journal print   # <- use it for this command
+```
+
+Here's one way to set it permanently, there are probably better ways:
+
+```shell
+$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
+$ bash --login
+```
+
+If we preferred to use eg `fr_FR.utf8`, we might have to install that first:
+
+```shell
+$ apt-get install language-pack-fr
+$ locale -a
+C
+en_US.utf8
+fr_BE.utf8
+fr_CA.utf8
+fr_CH.utf8
+fr_FR.utf8
+fr_LU.utf8
+POSIX
+$ LANG=fr_FR.utf8 hledger -f my.journal print
+```
+
+Note some platforms allow variant locale spellings, but not all (ubuntu
+accepts `fr_FR.UTF8`, mac osx requires exactly `fr_FR.UTF-8`).
+

hledger/hledger_examples.m4.md

@@ -1,7 +1,3 @@
-m4_dnl Quick examples included early in the manual
-m4_dnl TODO make these and all the command examples pasteable/doctestable ?
-m4_dnl   eg include -f FILE or $LEDGER_FILE details
-
 # COMMON TASKS
 
 Here are some quick examples of how to do some basic tasks with hledger.
@@ -23,7 +19,7 @@ $ hledger help --help     # show more detailed help for the help command
 Find more docs, chat, mail list, reddit, issue tracker:
 <https://hledger.org#help-feedback>
 
-## Constructing a command line
+## Constructing command lines
 
 hledger has an extensive and powerful command line interface. We
 strive to keep it simple and ergonomic, but you may run into one of
@@ -36,7 +32,7 @@ If that happens, here are some tips that may help:
 - if needed, also add a backslash to hide regular expression metacharacters from the shell
 - to see how a misbehaving command is being parsed, add `--debug=2`.
 
-## Starting a Journal
+## Starting a journal file
 
 hledger looks for your accounting data in a journal file, `$HOME/.hledger.journal` by default:
 ```shell
@@ -71,7 +67,7 @@ Commodities              : 0 ()
 Market prices            : 0 ()
 ```
 
-## Setting Opening Balances
+## Setting opening balances
 
 Pick a starting date for which you can look up the balances of some
 real-world assets (bank accounts, wallet..) and liabilities (credit cards..).
@@ -147,7 +143,7 @@ If you're using version control, this could be a good time to commit the journal
 $ git commit -m 'initial balances' 2020.journal
 ```
 
-## Recording Transactions
+## Recording transactions
 
 As you spend or receive money, you can record these transactions
 using one of the methods above (text editor, hledger add)
@@ -371,9 +367,11 @@ $ hledger activity -W
 2020-01-06 ****
 2020-01-13 ****
 ```
-## Starting a New File
+## Migrating to a new file
 
 At the end of the year, you may want to continue your journal in a new file,
 so that old transactions don't slow down or clutter your reports,
 and to help ensure the integrity of your accounting history.
 See the [close command](#close).
+
+If using version control, don't forget to `git add` the new file.

hledger/hledger_troubleshooting.m4.md

@@ -1,63 +0,0 @@
-# TROUBLESHOOTING
-
-Here are some issues you might encounter when you run hledger
-(and remember you can also seek help from the
-[IRC channel](http://irc.hledger.org),
-[mail list](http://list.hledger.org) or
-[bug tracker](http://bugs.hledger.org)):
-
-**Successfully installed, but "No command 'hledger' found"**  
-stack and cabal install binaries into a special directory, which
-should be added to your PATH environment variable.  Eg on unix-like
-systems, that is ~/.local/bin and ~/.cabal/bin respectively.
-
-**I set a custom LEDGER_FILE, but hledger is still using the default file**  
-`LEDGER_FILE` should be a real environment variable, not just a shell variable.
-The command `env | grep LEDGER_FILE` should show it.
-You may need to use `export`. Here's an [explanation](http://stackoverflow.com/a/7411509).
-
-**"Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors**  
-In order to handle non-ascii letters and symbols (like £), hledger needs
-an appropriate locale. This is usually configured system-wide; you can
-also configure it temporarily.  The locale may need to be one that
-supports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
-I'm not sure yet).
-
-Here's an example of setting the locale temporarily, on ubuntu gnu/linux:
-
-```shell
-$ file my.journal
-my.journal: UTF-8 Unicode text                 # <- the file is UTF8-encoded
-$ locale -a
-C
-en_US.utf8                             # <- a UTF8-aware locale is available
-POSIX
-$ LANG=en_US.utf8 hledger -f my.journal print   # <- use it for this command
-```
-
-Here's one way to set it permanently, there are probably better ways:
-
-```shell
-$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
-$ bash --login
-```
-
-If we preferred to use eg `fr_FR.utf8`, we might have to install that first:
-
-```shell
-$ apt-get install language-pack-fr
-$ locale -a
-C
-en_US.utf8
-fr_BE.utf8
-fr_CA.utf8
-fr_CH.utf8
-fr_FR.utf8
-fr_LU.utf8
-POSIX
-$ LANG=fr_FR.utf8 hledger -f my.journal print
-```
-
-Note some platforms allow variant locale spellings, but not all (ubuntu
-accepts `fr_FR.UTF8`, mac osx requires exactly `fr_FR.UTF-8`).
-