diff --git a/doc/common.m4 b/doc/common.m4 index 830d62c5f..9fa705556 100644 --- a/doc/common.m4 +++ b/doc/common.m4 @@ -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 }} )m4_dnl m4_dnl +m4_dnl BUGS boilerplate +m4_define({{_reportbugs_}}, +{{We welcome bug reports in the hledger issue tracker (shortcut: ), +or on the #hledger chat or hledger mail list ().}} )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 diff --git a/doc/manpage.nroff b/doc/manpage.nroff index 6453768c0..1e1a2bb3c 100644 --- a/doc/manpage.nroff +++ b/doc/manpage.nroff @@ -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$. diff --git a/hledger-ui/hledger-ui.m4.md b/hledger-ui/hledger-ui.m4.md index 78b808c64..234e697ef 100644 --- a/hledger-ui/hledger-ui.m4.md +++ b/hledger-ui/hledger-ui.m4.md @@ -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). diff --git a/hledger-web/hledger-web.m4.md b/hledger-web/hledger-web.m4.md index 58c639115..ea591896c 100644 --- a/hledger-web/hledger-web.m4.md +++ b/hledger-web/hledger-web.m4.md @@ -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. diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index bfb04d152..ef4c22f0f 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -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 @@ -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 ). +- 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.