diff --git a/hledger-ui/doc/hledger-ui.1 b/hledger-ui/doc/hledger-ui.1
index 7ea1816f3..b319475e6 100644
--- a/hledger-ui/doc/hledger-ui.1
+++ b/hledger-ui/doc/hledger-ui.1
@@ -436,8 +436,17 @@ is awkward.
 \f[C]\-V\f[] affects only the accounts screen.
 .PP
 When you press \f[C]g\f[], the current and all previous screens are
-regenerated, which may cause a noticeable pause.
+regenerated, which may cause a noticeable pause with large files.
 Also there is no visual indication that this is in progress.
+.PP
+\f[C]\-\-watch\f[] 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.
 
 
 .SH "REPORTING BUGS"
diff --git a/hledger-ui/doc/hledger-ui.1.m4.md b/hledger-ui/doc/hledger-ui.1.m4.md
index 1f0231819..efc60816a 100644
--- a/hledger-ui/doc/hledger-ui.1.m4.md
+++ b/hledger-ui/doc/hledger-ui.1.m4.md
@@ -259,7 +259,15 @@ The need to precede options with `--` when invoked from hledger is awkward.
 `-V` affects only the accounts screen.
 
 When you press `g`, the current and all previous screens are
-regenerated, which may cause a noticeable pause. Also there is no
-visual indication that this is in progress.
+regenerated, which may cause a noticeable pause with large files.
+Also there is no visual indication that this is in progress.
+
+`--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.
 
 }})
diff --git a/hledger-ui/doc/hledger-ui.1.txt b/hledger-ui/doc/hledger-ui.1.txt
index 4a0393252..1a05e55f6 100644
--- a/hledger-ui/doc/hledger-ui.1.txt
+++ b/hledger-ui/doc/hledger-ui.1.txt
@@ -326,8 +326,16 @@ BUGS
        -V affects only the accounts screen.
 
        When you press g, the current and all previous screens are regenerated,
-       which may cause a noticeable pause.  Also there is no visual indication
-       that this is in progress.
+       which may cause a noticeable pause with large files.  Also there is  no
+       visual indication that this is in progress.
+
+       --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.  Symp-
+       toms include: unresponsive UI, periodic resetting of the  cursor  posi-
+       tion, momentary display of parse errors, high CPU usage eventually sub-
+       siding, and possibly a small but persistent build-up of CPU usage until
+       the program is restarted.