diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index e6ef6dd6d..3af225d16 100644 --- a/hledger/hledger.m4.md +++ b/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`). + diff --git a/hledger/hledger_examples.m4.md b/hledger/hledger_examples.m4.md index 473ca1f4f..3138503c3 100644 --- a/hledger/hledger_examples.m4.md +++ b/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: -## 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. diff --git a/hledger/hledger_queries.m4.md b/hledger/hledger_queries.m4.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/hledger/hledger_troubleshooting.m4.md b/hledger/hledger_troubleshooting.m4.md deleted file mode 100644 index cdf42eb7e..000000000 --- a/hledger/hledger_troubleshooting.m4.md +++ /dev/null @@ -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`). -