bug#4419: 23.1.50; Emacs manual "Invoking `emacsclient'" is unclear

[Eli Zaretskii]

Please write in English if possible, because the Emacs maintainers
usually do not have translators to read other languages for them.

Your bug report will be posted to the emacs-pretest-bug@gnu.org mailing list.

Please describe exactly what actions triggered the bug
and the precise symptoms of the bug:

"(emacs) Invoking emacsclient" says:

  The simplest way to use the `emacsclient' program is to run the shell
  command `emacsclient FILE', where FILE is a file name.  This connects
  to an Emacs server, and tells that Emacs process to visit FILE in one
  of its existing frames--either a graphical frame, or one in a text-only
  terminal (*note Frames::).  You can then select that frame to begin
  editing.

     If there is no Emacs server, the `emacsclient' program halts with an
  error message.  If the Emacs process has no existing frame--which can
  happen if it was started as a daemon (*note Emacs Server::)--then Emacs
  opens a frame on the terminal in which you called `emacsclient', as
  though you had used the `-t' option (*note emacsclient Options::).

     On a graphical display, switching to the Emacs server is
  straightforward--just select its (system-level) window.  If you are
  using a text-only terminal, there are two ways to switch between
  `emacsclient''s shell and the Emacs server: (i) run the Emacs server
  and `emacsclient' on different virtual terminals, and switch to the
  Emacs server's virtual terminal after calling `emacsclient'; or (ii)
  call `emacsclient' from within the Emacs server itself, using Shell
  mode (*note Interactive Shell::) or Term mode (*note Term Mode::);
  `emacsclient' blocks only the subshell under Emacs, and you can still
  use Emacs to edit the file.

This description has several problems:

 . The last paragraph explains how to ``switch to the Emacs server''.
   It does not explain what does it mean, nor why would the user want
   to do that, after invoking emacsclient.  I'm guessing this text
   wants to tell how to switch to an existing frame where FILE is
   displayed; if this is true, the text should say that explicitly,
   since ``switching to the server'' is not something the user would
   necessarily think of as useful.  In particular, the first paragraph
   correctly says ``you can then select that frame to begin editing'',
   so the last paragraph should pick up the same wording to indicate
   to the reader that it continues where the 1st left off.

 . AFAIU, if emacsclient is invoked with -t, the file will be
   displayed on the same terminal where emacsclient was invoked.  This
   is by far more useful (and much less obscure) way of getting to the
   frame where FILE is displayed, so the text should mention that as
   well, or at least say that the next section describes this method.

The last paragraph of this node, viz.

     If you set the variable `server-window' to a window or a frame, `C-x
  #' always displays the next server buffer in that window or in that
  frame.

uses ambiguous wording: it took me a few moments to realize that by
``setting a variable to a window or a frame'' it means setting the
_value_ of the variable.  I would suggest rephrasing as follows:

  If the value of the variable `server-window' is a window or a frame, ...

If Emacs crashed, and you have the Emacs process in the gdb debugger,
please include the output from the following gdb commands:
    `bt full' and `xbacktrace'.
If you would like to further debug the crash, please read the file
d:/gnu/emacs/etc/DEBUG for instructions.


In GNU Emacs 23.1.50.1 (i386-mingw-nt5.1.2600)
 of 2009-09-12 on HOME-C4E4A596F7
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: ENU
  value of $XMODIFIERS: nil
  locale-coding-system: cp1255
  default enable-multibyte-characters: t

Major mode: Info

Minor modes in effect:
  tooltip-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  global-auto-composition-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
C-u C-h i i n f <tab> e m a c s <return> i e m a c 
s c l <tab> <return> <next> 1 <down> <help-echo> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> M-x r e p o r t - e m <tab> <r
eturn>

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.
Found `emacsclient' in Concept Index.  (3 total; use `,' for next)

Load-path shadows:
None found.


> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Sat, 12 Sep 2009 00:08:41 -0400
> 
> I'll leave the code as is, then.  It's not like it's harmful.

I commented out the call to custom-reevaluate-setting.

> FWIW, I've just installed a few changes to handle such situations, which
> should now be done by setting the defcustom's initializer to
> custom-initialize-delay.

I will add to my TODO to go through defcustoms for possible users of
this facility.

In general, any file name that violates DOS 8+3 limitations (e.g.,
starts with a period) and uses convert-standard-filename in its
defcustom should use something like that, because what
convert-standard-filename does depends on what the underlying
filesystem, which could be different at dump time and at run time.