;doc: hledger: inline troubleshooting, cleanups, m4 docs
[ci skip]
This commit is contained in:
Simon Michael
parent
9a52523438
commit
e52a6281fb
@ -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`).
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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`).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user