[Emacs-diffs] /srv/bzr/emacs/emacs-23 r100259: Describe MS-Windows specific startup issues, incl. emacsclientw.exe

[Eli Zaretskii]

------------------------------------------------------------
revno: 100259
committer: Eli Zaretskii <address@hidden>
branch nick: emacs-23
timestamp: Sat 2010-12-04 13:25:09 +0200
message:
  Describe MS-Windows specific startup issues, incl. emacsclientw.exe
  
   msdog.texi (Windows Startup): New node.  Move the stuff about the current
   directory from "Windows HOME", and explain all possible ways of invoking
   Emacs on Windows.
modified:
  doc/emacs/ChangeLog
  doc/emacs/emacs.texi
  doc/emacs/msdog.texi

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2010-12-04 10:22:45 +0000
+++ b/doc/emacs/ChangeLog       2010-12-04 11:25:09 +0000
@@ -2,6 +2,8 @@
 
        * msdog.texi (Windows HOME): Mention that HOME can also be set in the
        registry, with a cross-reference.
+       (Windows Startup): New node.  Move the stuff about the current
+       directory from "Windows HOME".
 
 2010-11-23  Bob Rogers  <address@hidden>
 

=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi      2010-11-20 23:16:10 +0000
+++ b/doc/emacs/emacs.texi      2010-12-04 11:25:09 +0000
@@ -1191,6 +1191,7 @@
 
 Emacs and Microsoft Windows/MS-DOS
 
+* Windows Startup::     How to start Emacs on Windows.
 * Text and Binary::     Text files use CRLF to terminate lines.
 * Windows Files::       File-name conventions on Windows.
 * ls in Lisp::          Emulation of @code{ls} for Dired.

=== modified file 'doc/emacs/msdog.texi'
--- a/doc/emacs/msdog.texi      2010-12-04 10:22:45 +0000
+++ b/doc/emacs/msdog.texi      2010-12-04 11:25:09 +0000
@@ -28,6 +28,7 @@
 here.
 
 @menu
+* Windows Startup::     How to start Emacs on Windows.
 * Text and Binary::     Text files use CRLF to terminate lines.
 * Windows Files::       File-name conventions on Windows.
 * ls in Lisp::          Emulation of @code{ls} for Dired.
@@ -44,6 +45,68 @@
 @end ifnottex
 @end menu
 
address@hidden Windows Startup
address@hidden How to Start Emacs on MS-Windows
address@hidden starting Emacs on MS-Windows
+
+  There are several ways of starting Emacs on MS-Windows:
+
address@hidden
address@hidden
address@hidden runemacs.exe
address@hidden desktop shortcut, MS-Windows
address@hidden start directory, MS-Windows
address@hidden directory where Emacs starts on MS-Windows
+From the desktop shortcut icon: either double-click the left mouse
+button on the icon, or click once, then press @key{RET}.  The desktop
+shortcut should specify as its ``Target'' (in the ``Properties'' of
+the shortcut) the full absolute file name of @file{runemacs.exe},
address@hidden of @file{emacs.exe}.  This is because @file{runemacs.exe}
+hides the console window that would have been created if the target of
+the shortcut were @file{emacs.exe} (which is a console program, as far
+as Windows is concerned).  If you use this method, Emacs starts in the
+directory specified by the shortcut.  To control where that is,
+right-click on the shortcut, select ``Properties'', and in the
+``Shortcut'' tab modify the ``Start in'' field to your liking.
+
address@hidden
+From the Command Prompt window, by typing @kbd{emacs @key{RET}} at the
+prompt.  The Command Prompt window where you did that will not be
+available for invoking other commands until Emacs exits.  In this
+case, Emacs will start in the current directory of the Windows shell.
+
address@hidden
+From the Command Prompt window, by typing @kbd{runemacs @key{RET}} at
+the prompt.  The Command Prompt window where you did that will be
+immediately available for invoking other commands.  In this case,
+Emacs will start in the current directory of the Windows shell.
+
address@hidden
address@hidden invoking Emacs from Windows Explorer
address@hidden emacsclient.exe
address@hidden emacsclientw.exe
+Via the Emacs client program, @file{emacsclient.exe} or
address@hidden  This allows to invoke Emacs from other
+programs, and to reuse a running Emacs process for serving editing
+jobs required by other programs.  @xref{Emacs Server}.  The difference
+between @file{emacsclient.exe} and @file{emacsclientw.exe} is that the
+former waits for Emacs to signal that the editing job is finished,
+while the latter does not wait.  Which one of them to use in each case
+depends on the expectations of the program that needs editing
+services.  If the program will use the edited files, it needs to wait
+for Emacs, so you should use @file{emacsclient.exe}.  By contrast, if
+the results of editing are not needed by the invoking program, you
+will be better off using @file{emacsclientw.exe}.  A notable situation
+where you would want @file{emacsclientw.exe} is when you right-click
+on a file in the Windows Explorer and select ``Open With'' from the
+pop-up menu.  Use the @samp{--alternate-editor=} or @samp{-a} options
+if Emacs might not be running (or not running as a server) when
address@hidden is invoked---that will always give you an
+editor.  When invoked via @command{emacsclient}, Emacs will start in
+the current directory of the program that invoked
address@hidden
address@hidden enumerate
+
 @node Text and Binary
 @section Text Files and Binary Files
 @cindex text and binary files on MS-DOS/MS-Windows
@@ -375,13 +438,6 @@
 @file{_emacs} as a fallback, if such a file exists in the home
 directory, whereas @file{.emacs} does not.
 
address@hidden start directory, MS-Windows
address@hidden directory where Emacs starts on MS-Windows
-  If you use a Windows desktop shortcut to start Emacs, it starts in
-the directory specified by the shortcut.  To control where that is,
-right-click on the shortcut, select ``Properties'', and in the
-``Shortcut'' tab modify the ``Start in'' field to your liking.
-
 @node Windows Keyboard
 @section Keyboard Usage on MS-Windows
 @cindex keyboard, MS-Windows