Fix bugs with buffer-local tags tables

* lisp/progmodes/etags.el (visit-tags-table): After
'visit-tags-table-buffer' returns, retrieve the value of
'tags-file-name' from the buffer we started in.  Force
recomputation of 'tags-completion-table' next time it is used,
since the list of tags table has changed.
(visit-tags-table-buffer): Accept an additional optional argument
CBUF, the buffer in which to start processing, and switch to that
buffer if CBUF is non-nil.  All callers changed to supply a
non-nil CBUF when they call 'visit-tags-table-buffer' in a loop.
Doc fix.
(tags-completion-table): Accept an optional argument, the buffer
for which to build 'tags-completion-table', and build that
buffer's completion table.
(tags-lazy-completion-table): Pass the current buffer to
'tags-completion-table'.
(tags-file-name): Don't say in the doc string that setting this
variable directly is enough; say that 'visit-tags-table' should be
used for that.  (Bug#158)  (Bug#17326)  (Bug#23164)

* doc/emacs/maintaining.texi (Select Tags Table): Delete the
advice to set 'tags-file-name' directly.

* test/lisp/progmodes/etags-tests.el: New tests.

1 files changed, 4 insertions, 4 deletions

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 13668cc9269..de4fb43ec1d 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -2552,10 +2552,10 @@ directory as the default.
 @vindex tags-file-name
   Emacs does not actually read in the tags table contents until you
 try to use them; all @code{visit-tags-table} does is store the file
-name in the variable @code{tags-file-name}, and setting the variable
-yourself is just as good.  The variable's initial value is @code{nil};
-that value tells all the commands for working with tags tables that
-they must ask for a tags table file name to use.
+name in the variable @code{tags-file-name}, and not much more.  The
+variable's initial value is @code{nil}; that value tells all the
+commands for working with tags tables that they must ask for a tags
+table file name to use.
 
   Using @code{visit-tags-table} when a tags table is already loaded
 gives you a choice: you can add the new tags table to the current list