doc: tail: semi-deprecate --sleep-interval and --max-unchanged-stats

Those options are useful only on systems that lack inotify support
and in the unusual event that a system with inotify support must
resort to polling.
* src/tail.c (usage): Note that the --max-unchanged-stats=N and
--sleep-interval=N options are rarely useful on systems with
inotify support.
* doc/coreutils.texi (tail invocation): Likewise.

2 files changed, 7 insertions, 3 deletions

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 34d9ff031..76fdce165 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -2821,6 +2821,7 @@ Historical implementations of @command{tail} have required that
 @var{number} be an integer.  However, GNU @command{tail} accepts
 an arbitrary floating point number (using a period before any
 fractional digits).
+When @command{tail} uses inotify, this polling-related option is ignored.
 
 @itemx --pid=@var{pid}
 @opindex --pid
@@ -2855,7 +2856,8 @@ still associated with the same device/inode-number pair as before.
 When following a log file that is rotated, this is approximately the
 number of seconds between when tail prints the last pre-rotation lines
 and when it prints the lines that have accumulated in the new log file.
-This option is meaningful only when following by name.
+This option is meaningful only when polling (i.e., without inotify)
+and when following by name.
 
 @itemx -n @var{k}
 @itemx --lines=@var{k}
diff --git a/src/tail.c b/src/tail.c
index 924221016..2af9693de 100644
--- a/src/tail.c
+++ b/src/tail.c
@@ -286,7 +286,8 @@ Mandatory arguments to long options are mandatory for short options too.\n\
                            with --follow=name, reopen a FILE which has not\n\
                            changed size after N (default %d) iterations\n\
                            to see if it has been unlinked or renamed\n\
-                           (this is the usual case of rotated log files)\n\
+                           (this is the usual case of rotated log files).\n\
+                           With inotify, this option is rarely useful.\n\
 "),
              DEFAULT_N_LINES,
              DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS
@@ -300,7 +301,8 @@ Mandatory arguments to long options are mandatory for short options too.\n\
 "), stdout);
      fputs (_("\
   -s, --sleep-interval=N   with -f, sleep for approximately N seconds\n\
-                             (default 1.0) between iterations\n\
+                             (default 1.0) between iterations.\n\
+                             With inotify, this option is rarely useful.\n\
   -v, --verbose            always output headers giving file names\n\
 "), stdout);
      fputs (HELP_OPTION_DESCRIPTION, stdout);