slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;imp:doc:manuals: consolidate, update BUGS sections

Browse Source
This commit is contained in:
Simon Michael 2023-05-25 14:45:07 -10:00
parent a717cbd300
commit fda15f808c
5 changed files with 96 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/common.m4
View File

@ -239,7 +239,6 @@ m4_define({{_inputfileswithptr_}},
{{_inputfiles_ {{_inputfiles_
(See hledger(1) -> Input for details.)}} )m4_dnl (See hledger(1) -> Input for details.)}} )m4_dnl
m4_dnl m4_dnl
m4_dnl A standard description of the LEDGER_FILE environment variable. m4_dnl A standard description of the LEDGER_FILE environment variable.
m4_define({{_LEDGER_FILE_}}, {{ m4_define({{_LEDGER_FILE_}}, {{
**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 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 The _FLAGS marker is used in generating command help (see
m4_dnl CliOptions.parseCommandDoc), but should be removed when generating manuals. m4_dnl CliOptions.parseCommandDoc), but should be removed when generating manuals.
m4_dnl Just one underscore here, so pandoc doesn't strip them m4_dnl Just one underscore here, so pandoc doesn't strip them

4
doc/manpage.nroff
View File

@ -18,10 +18,6 @@ $for(include-after)$
$include-after$ $include-after$
$endfor$ $endfor$
.SH "REPORTING BUGS"
Report bugs at http://bugs.hledger.org
(or on the #hledger chat or hledger mail list)
.SH AUTHORS .SH AUTHORS
$if(author)$ $if(author)$
$for(author)$$author$$sep$; $endfor$. $for(author)$$author$$sep$; $endfor$.

48
hledger-ui/hledger-ui.m4.md
View File

@ -345,19 +345,23 @@ This leaves more mental bandwidth for your accounting.
Of course you can still interact with hledger-ui when needed, Of course you can still interact with hledger-ui when needed,
eg to toggle cleared mode, or to explore the history. 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 It may not work correctly for you, depending on platform or system configuration.
Jetbrains IDEs, `gedit`, other Gnome applications; or on certain unusual filesystems. (Eg [#836](https://github.com/simonmichael/hledger/issues/836).)
([#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.)
CPU and memory usage can sometimes gradually increase, if `hledger-ui --watch` is left running for days. At least on mac, there can be a slow build-up of CPU usage over time,
(Possibly correlated with certain platforms, many transactions, and/or large numbers of other files present). until the program is restarted (or, suspending and restarting with
To work around, `q`uit and restart it, `CTRL-z` `fg` may be enough).
or (where supported) suspend (`CTRL-z`) and restart it (`fg`).
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 ## Debug output
@ -379,21 +383,15 @@ It _inputfileswithptr_
# BUGS # BUGS
_reportbugs_
Some known issues:
`-f-` doesn't work (hledger-ui can't read from stdin). `-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 The Transaction screen does not update from file changes
regenerated, which may cause a noticeable pause with large files. until you exit and re-endter it (see SCREENS > Transaction above).
Also there is no visual indication that this is in progress.
`--watch` is not yet fully robust. It works well for normal usage, but `--watch` is not yet fully robust on all platforms (see Watch mode above).
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.

8
hledger-web/hledger-web.m4.md
View File

@ -425,10 +425,8 @@ It _inputfileswithptr_
# BUGS # 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, or in text-mode browsers.
Does not work well on small screens.

158
hledger/hledger.m4.md
View File

@ -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 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 # PART 2: DATA FORMATS
<a name="journal-format"></a> <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. 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 Some common markdown links.
m4_dnl These are also usable in hledger/Hledger/Cli/Commands/*.md. 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. m4_dnl Some are defined there also - don't remove, they are needed there for Shake cmdhelp eg.