mirror of
https://github.com/simonmichael/hledger.git
synced 2024-10-06 10:57:30 +03:00
;imp:doc:manuals: consolidate, update BUGS sections
This commit is contained in:
Simon Michael
parent
a717cbd300
commit
fda15f808c
@ -239,7 +239,6 @@ m4_define({{_inputfileswithptr_}},
|
||||
{{_inputfiles_
|
||||
(See hledger(1) -> Input for details.)}} )m4_dnl
|
||||
m4_dnl
|
||||
|
||||
m4_dnl A standard description of the LEDGER_FILE environment variable.
|
||||
m4_define({{_LEDGER_FILE_}}, {{
|
||||
**LEDGER_FILE**
|
||||
@ -278,6 +277,11 @@ Or, change it in settings: see <https://www.java.com/en/download/help/path.html>
|
||||
|
||||
}} )m4_dnl
|
||||
m4_dnl
|
||||
m4_dnl BUGS boilerplate
|
||||
m4_define({{_reportbugs_}},
|
||||
{{We welcome bug reports in the hledger issue tracker (shortcut: <http://bugs.hledger.org>),
|
||||
or on the #hledger chat or hledger mail list (<https://hledger.org/support>).}} )m4_dnl
|
||||
m4_dnl
|
||||
m4_dnl The _FLAGS marker is used in generating command help (see
|
||||
m4_dnl CliOptions.parseCommandDoc), but should be removed when generating manuals.
|
||||
m4_dnl Just one underscore here, so pandoc doesn't strip them
|
||||
|
||||
@ -18,10 +18,6 @@ $for(include-after)$
|
||||
$include-after$
|
||||
$endfor$
|
||||
|
||||
.SH "REPORTING BUGS"
|
||||
Report bugs at http://bugs.hledger.org
|
||||
(or on the #hledger chat or hledger mail list)
|
||||
|
||||
.SH AUTHORS
|
||||
$if(author)$
|
||||
$for(author)$$author$$sep$; $endfor$.
|
||||
|
||||
@ -345,19 +345,23 @@ This leaves more mental bandwidth for your accounting.
|
||||
Of course you can still interact with hledger-ui when needed,
|
||||
eg to toggle cleared mode, or to explore the history.
|
||||
|
||||
Here are some current limitations to be aware of:
|
||||
There are currently some limitations with `--watch`:
|
||||
|
||||
Changes might not be detected with certain editors, possibly including
|
||||
Jetbrains IDEs, `gedit`, other Gnome applications; or on certain unusual filesystems.
|
||||
([#1617](https://github.com/simonmichael/hledger/issues/1617),
|
||||
[#911](https://github.com/simonmichael/hledger/issues/911)).
|
||||
To work around, reload manually by pressing `g` in the hledger-ui window.
|
||||
(Or see #1617 for another workaround, and let us know if it works for you.)
|
||||
It may not work correctly for you, depending on platform or system configuration.
|
||||
(Eg [#836](https://github.com/simonmichael/hledger/issues/836).)
|
||||
|
||||
CPU and memory usage can sometimes gradually increase, if `hledger-ui --watch` is left running for days.
|
||||
(Possibly correlated with certain platforms, many transactions, and/or large numbers of other files present).
|
||||
To work around, `q`uit and restart it,
|
||||
or (where supported) suspend (`CTRL-z`) and restart it (`fg`).
|
||||
At least on mac, there can be a slow build-up of CPU usage over time,
|
||||
until the program is restarted (or, suspending and restarting with
|
||||
`CTRL-z` `fg` may be enough).
|
||||
|
||||
It will not detect file changes made
|
||||
by certain editors, such as Jetbrains IDEs or `gedit`,
|
||||
or on certain less common filesystems.
|
||||
(To work around, press `g` to reload manually,
|
||||
or try [#1617](https://github.com/simonmichael/hledger/issues/1617)'s `fs.inotify.max_user_watches` workaround and let us know.)
|
||||
|
||||
If you are viewing files mounted from another machine, the system
|
||||
clocks on both machines should be roughly in agreement.
|
||||
|
||||
## Debug output
|
||||
|
||||
@ -379,21 +383,15 @@ It _inputfileswithptr_
|
||||
|
||||
# BUGS
|
||||
|
||||
_reportbugs_
|
||||
|
||||
Some known issues:
|
||||
|
||||
`-f-` doesn't work (hledger-ui can't read from stdin).
|
||||
|
||||
`-V` affects only the accounts screen.
|
||||
If you press `g` with large files, there could be a noticeable pause.
|
||||
|
||||
When you press `g`, the current and all previous screens are
|
||||
regenerated, which may cause a noticeable pause with large files.
|
||||
Also there is no visual indication that this is in progress.
|
||||
The Transaction screen does not update from file changes
|
||||
until you exit and re-endter it (see SCREENS > Transaction above).
|
||||
|
||||
`--watch` is not yet fully robust. It works well for normal usage, but
|
||||
many file changes in a short time (eg saving the file thousands of
|
||||
times with an editor macro) can cause problems at least on OSX.
|
||||
Symptoms include: unresponsive UI, periodic resetting of the cursor
|
||||
position, momentary display of parse errors, high CPU usage eventually
|
||||
subsiding, and possibly a small but persistent build-up of CPU usage
|
||||
until the program is restarted.
|
||||
|
||||
Also, if you are viewing files mounted from another machine, `-w/--watch`
|
||||
requires that both machine clocks are roughly in step.
|
||||
`--watch` is not yet fully robust on all platforms (see Watch mode above).
|
||||
|
||||
@ -425,10 +425,8 @@ It _inputfileswithptr_
|
||||
|
||||
# BUGS
|
||||
|
||||
`-f-` doesn't work (hledger-web can't read from stdin).
|
||||
_reportbugs_
|
||||
|
||||
Query arguments and some hledger options are ignored.
|
||||
Some known issues:
|
||||
|
||||
Does not work in text-mode browsers.
|
||||
|
||||
Does not work well on small screens.
|
||||
Does not work well on small screens, or in text-mode browsers.
|
||||
|
||||
@ -697,99 +697,6 @@ To capture debug output in a log file instead, you can usually redirect stderr,
|
||||
hledger bal --debug=3 2>hledger.log
|
||||
```
|
||||
|
||||
# Limitations
|
||||
|
||||
The need to precede add-on command options with `--` when invoked from hledger is awkward.
|
||||
|
||||
When input data contains non-ascii characters, a suitable system locale must be configured (or there will be an unhelpful error).
|
||||
Eg on POSIX, set LANG to something other than C.
|
||||
|
||||
In a Microsoft Windows CMD window, non-ascii characters and colours are not supported.
|
||||
|
||||
On Windows, non-ascii characters may not display correctly when running a hledger built
|
||||
in CMD in MSYS/CYGWIN, or vice-versa.
|
||||
|
||||
In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger add.
|
||||
|
||||
Not all of Ledger's journal file syntax is supported.
|
||||
See [hledger and Ledger > Differences > journal format](/ledger.html#journal-format).
|
||||
|
||||
On large data files, hledger is slower and uses more memory than Ledger.
|
||||
|
||||
# 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).
|
||||
|
||||
**Getting errors like "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" or "commitAndReleaseBuffer: invalid argument (invalid character)"**\
|
||||
Programs compiled with GHC (hledger, haskell build tools, etc.)
|
||||
need to have a UTF-8-aware locale configured in the environment,
|
||||
otherwise they will fail with these kinds of errors when they encounter non-ascii characters.
|
||||
|
||||
To fix it, set the LANG environment variable to some locale which supports UTF-8.
|
||||
The locale you choose must be installed on your system.
|
||||
|
||||
Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux:
|
||||
|
||||
```shell
|
||||
$ file my.journal
|
||||
my.journal: UTF-8 Unicode text # the file is UTF8-encoded
|
||||
$ echo $LANG
|
||||
C # LANG is set to the default locale, which does not support UTF8
|
||||
$ locale -a # which locales are installed ?
|
||||
C
|
||||
en_US.utf8 # here's a UTF8-aware one we can use
|
||||
POSIX
|
||||
$ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command
|
||||
```
|
||||
|
||||
If available, `C.UTF-8` will also work.
|
||||
If your preferred locale isn't listed by `locale -a`, you might need to install it. Eg on Ubuntu/Debian:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Here's how you could set it permanently, if you use a bash shell:
|
||||
|
||||
```shell
|
||||
$ echo "export LANG=en_US.utf8" >>~/.bash_profile
|
||||
$ bash --login
|
||||
```
|
||||
|
||||
Exact spelling and capitalisation may be important. Note the difference on MacOS (`UTF-8`, not `utf8`).
|
||||
Some platforms (eg ubuntu) allow variant spellings, but others (eg macos) require it to be exact:
|
||||
|
||||
```shell
|
||||
$ locale -a | grep -iE en_us.*utf
|
||||
en_US.UTF-8
|
||||
$ LANG=en_US.UTF-8 hledger -f my.journal print
|
||||
```
|
||||
|
||||
|
||||
# PART 2: DATA FORMATS
|
||||
|
||||
<a name="journal-format"></a>
|
||||
@ -6314,6 +6221,71 @@ See the [close command](#close).
|
||||
If using version control, don't forget to `git add` the new file.
|
||||
|
||||
|
||||
# BUGS
|
||||
|
||||
_reportbugs_
|
||||
|
||||
Some known issues and limitations:
|
||||
|
||||
The need to precede add-on command options with `--` when invoked from hledger is awkward.
|
||||
(See Command options, Constructing command lines.)
|
||||
|
||||
A UTF-8-aware system locale must be configured to work with non-ascii data.
|
||||
(See Unicode characters, Troubleshooting.)
|
||||
|
||||
On Microsoft Windows, depending whether you are running in a CMD window or a Cygwin/MSYS/Mintty window
|
||||
and how you installed hledger,
|
||||
non-ascii characters and colours may not be supported,
|
||||
and the tab key may not be supported by `hledger add`.
|
||||
(Running in a WSL window should resolve these.)
|
||||
|
||||
When processing large data files, hledger uses more memory than Ledger.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Here are some common issues you might encounter when you run hledger,
|
||||
and how to resolve them
|
||||
(and remember also you can usually get quick [Support](support.md)):
|
||||
|
||||
**PATH issues: I get an error like "No command 'hledger' found"**\
|
||||
Depending how you installed hledger, the executables may not be in your shell's PATH.
|
||||
Eg on unix systems, stack installs hledger in `~/.local/bin`
|
||||
and cabal installs it in `~/.cabal/bin`.
|
||||
You may need to add one of these directories to your shell's PATH,
|
||||
and/or open a new terminal window.
|
||||
|
||||
**LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not using it**\
|
||||
|
||||
- `LEDGER_FILE` should be a real environment variable, not just a shell variable.
|
||||
Eg on unix, the command `env | grep LEDGER_FILE` should show it.
|
||||
You may need to use `export` (see <https://stackoverflow.com/a/7411509>).
|
||||
- You may need to force your shell to see the new configuration.
|
||||
A simple way is to close your terminal window and open a new one.
|
||||
|
||||
**LANG issues: I get errors like "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" or "commitAndReleaseBuffer: invalid argument (invalid character)"**\
|
||||
Programs compiled with GHC (hledger, haskell build tools, etc.) need the system locale to be UTF-8-aware,
|
||||
or they will fail when they encounter non-ascii characters.
|
||||
To fix it, set the LANG environment variable to a locale which supports UTF-8
|
||||
and which is installed on your system.
|
||||
|
||||
On unix, `locale -a` lists the installed locales.
|
||||
Look for one which mentions `utf8`, `UTF-8` or similar.
|
||||
Some examples: `C.UTF-8`, `en_US.utf-8`, `fr_FR.utf8`.
|
||||
If necessary, use your system package manager to install one.
|
||||
Then select it by setting the `LANG` environment variable.
|
||||
Note, exact spelling and capitalisation of the locale name may be important:
|
||||
Here's one common way to configure this permanently for your shell:
|
||||
|
||||
```shell
|
||||
$ echo "export LANG=en_US.utf8" >>~/.profile
|
||||
# close and re-open terminal window
|
||||
```
|
||||
|
||||
**COMPATIBILITY ISSUES: hledger gives an error with my Ledger file**\
|
||||
Not all of Ledger's journal file syntax or feature set is supported.
|
||||
See [hledger and Ledger](ledger.md) for full details.
|
||||
|
||||
|
||||
m4_dnl Some common markdown links.
|
||||
m4_dnl These are also usable in hledger/Hledger/Cli/Commands/*.md.
|
||||
m4_dnl Some are defined there also - don't remove, they are needed there for Shake cmdhelp eg.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user