@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Microsoft Windows, Manifesto, Mac OS / GNUstep, Top
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.
@end ifnottex
@end menu
+@node Windows Startup
+@section How to Start Emacs on MS-Windows
+@cindex starting Emacs on MS-Windows
+
+ There are several ways of starting Emacs on MS-Windows:
+
+@enumerate
+@item
+@pindex runemacs.exe
+@cindex desktop shortcut, MS-Windows
+@cindex start directory, MS-Windows
+@cindex 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},
+@emph{not} 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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+@cindex invoking Emacs from Windows Explorer
+@pindex emacsclient.exe
+@pindex emacsclientw.exe
+Via @file{emacsclient.exe} or @file{emacsclientw.exe}, which allow you
+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 is a console program,
+while the latter is a Windows GUI program. Both programs wait for
+Emacs to signal that the editing job is finished, before they exit and
+return control to the program that invoked them. Which one of them to
+use in each case depends on the expectations of the program that needs
+editing services. If that program is itself a console (text-mode)
+program, you should use @file{emacsclient.exe}, so that any of its
+messages and prompts appear in the same command window as those of the
+invoking program. By contrast, if the invoking program is a GUI
+program, you will be better off using @file{emacsclientw.exe}, because
+@file{emacsclient.exe} will pop up a command window if it is invoked
+from a GUI program. 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 @command{emacsclient} 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 @command{emacsclient}.
+@end enumerate
+
@node Text and Binary
@section Text Files and Binary Files
@cindex text and binary files on MS-DOS/MS-Windows
attributes are displayed.
@vindex ls-lisp-emulation
- The variable @code{ls-lisp-emulation} controls the flavour of the
+ The variable @code{ls-lisp-emulation} controls the flavor of the
@code{ls} emulation by setting the defaults for the 3 options
described above: @code{ls-lisp-ignore-case},
@code{ls-lisp-dirs-first}, and @code{ls-lisp-verbosity}. The value of
@end table
@noindent
-Any other value of @code{ls-lisp-emulation} means the same as
-@code{GNU}. Note that this option needs to be set @emph{before}
-@file{ls-lisp.el} is loaded, which means that on MS-Windows and MS-DOS
-you will have to set the value from your @file{.emacs} file and then
-restart Emacs, since @file{ls-lisp.el} is preloaded.
+Any other value of @code{ls-lisp-emulation} means the same as @code{GNU}.
+Customizing this option calls the function @code{ls-lisp-set-options} to
+update the 3 dependent options as needed. If you change the value of
+this variable without using customize after @file{ls-lisp.el} is loaded
+(note that it is preloaded on MS-Windows and MS-DOS), you can call that
+function manually for the same result.
@vindex ls-lisp-support-shell-wildcards
The variable @code{ls-lisp-support-shell-wildcards} controls how
The Windows equivalent of the @code{HOME} directory is the
@dfn{user-specific application data directory}. The actual location
-depends on your Windows version and system configuration; typical values
-are @file{C:\Documents and Settings\@var{username}\Application Data} on
-Windows 2K/XP and later, and either @file{C:\WINDOWS\Application Data}
-or @file{C:\WINDOWS\Profiles\@var{username}\Application Data} on the
-older Windows 9X/ME systems.
-
-@cindex init file @file{.emacs} on MS-Windows
- The home directory is where your init file @file{.emacs} is stored.
-When Emacs starts, it first checks whether the environment variable
-@env{HOME} is set. If it is, it looks for the init file in the
-directory pointed by @env{HOME}. If @env{HOME} is not defined, Emacs
-checks for an existing @file{.emacs} file in @file{C:\}, the root
-directory of drive @file{C:}@footnote{
-The check in @file{C:\} is for compatibility with older versions of Emacs,
-which didn't check the application data directory.
-}. If there's no such file in @file{C:\}, Emacs next uses the Windows
-system calls to find out the exact location of your application data
-directory. If that system call fails, Emacs falls back to @file{C:\}.
-
- Whatever the final place is, Emacs sets the value of the @env{HOME}
-environment variable to point to it, and it will use that location for
-other files and directories it normally creates in the user's home
-directory.
+depends on the Windows version; typical values are @file{C:\Documents
+and Settings\@var{username}\Application Data} on Windows 2K/XP/2K3,
+@file{C:\Users\@var{username}\AppData\Roaming} on Windows Vista/7/2K8,
+and either @file{C:\WINDOWS\Application Data} or
+@file{C:\WINDOWS\Profiles\@var{username}\Application Data} on the
+older Windows 9X/ME systems. If this directory does not exist or
+cannot be accessed, Emacs falls back to @file{C:\} as the default
+value of @code{HOME}.
+
+ You can override this default value of @code{HOME} by explicitly
+setting the environment variable @env{HOME} to point to any directory
+on your system. @env{HOME} can be set either from the command shell
+prompt or from the @samp{My Computer}s @samp{Properties} dialog.
+@code{HOME} can also be set in the system registry, for details see
+@ref{MS-Windows Registry}.
+
+ For compatibility with older versions of Emacs@footnote{
+Older versions of Emacs didn't check the application data directory.
+}, if there is a file named @file{.emacs} in @file{C:\}, the root
+directory of drive @file{C:}, and @env{HOME} is set neither in the
+environment nor in the Registry, Emacs will treat @file{C:\} as the
+default @code{HOME} location, and will not look in the application
+data directory, even if it exists. Note that only @file{.emacs} is
+looked for in @file{C:\}; the older name @file{_emacs} (see below) is
+not. This use of @file{C:\.emacs} to define @code{HOME} is
+deprecated.
+
+ Whatever the final place is, Emacs sets the internal value of the
+@env{HOME} environment variable to point to it, and it will use that
+location for other files and directories it normally looks for or
+creates in the user's home directory.
You can always find out where Emacs thinks is your home directory's
location by typing @kbd{C-x d ~/ @key{RET}}. This should present the
list of files in the home directory, and show its full name on the
first line. Likewise, to visit your init file, type @kbd{C-x C-f
-~/.emacs @key{RET}}.
+~/.emacs @key{RET}} (assuming the file's name is @file{.emacs}).
+
+@cindex init file @file{.emacs} on MS-Windows
+ The home directory is where your init file is stored. It can have
+any name mentioned in @ref{Init File}.
@cindex @file{_emacs} init file, MS-Windows
Because MS-DOS does not allow file names with leading dots, and
-because older Windows systems made it hard to create files with such
-names, the Windows port of Emacs supports an alternative name
-@file{_emacs} as a fallback, if such a file exists in the home
-directory, whereas @file{.emacs} does not.
-
-@cindex start directory, MS-Windows
-@cindex 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.
+older Windows systems made it hard to create files with such names,
+the Windows port of Emacs supports an init file name @file{_emacs}, if
+such a file exists in the home directory and @file{.emacs} does not.
+This name is considered obsolete.
@node Windows Keyboard
@section Keyboard Usage on MS-Windows
The old XLFD based format is also supported for backwards compatibility.
- Emacs 23 supports a number of backends. Currently, the @code{gdi}
-and @code{uniscribe} font backends are supported on Windows. The
-@code{gdi} font backend is available on all versions of Windows, and
-supports all fonts that are natively supported by Windows. The
+@cindex font backend selection (MS-Windows)
+ Emacs 23 and later supports a number of font backends. Currently,
+the @code{gdi} and @code{uniscribe} backends are supported on Windows.
+The @code{gdi} font backend is available on all versions of Windows,
+and supports all fonts that are natively supported by Windows. The
@code{uniscribe} font backend is available on Windows 2000 and later,
-and supports Truetype and Opentype fonts. Some languages requiring
-complex layout can only be properly supported by the uniscribe
+and supports TrueType and OpenType fonts. Some languages requiring
+complex layout can only be properly supported by the Uniscribe
backend. By default, both backends are enabled if supported, with
-@code{uniscribe} taking priority over @code{gdi}.
+@code{uniscribe} taking priority over @code{gdi}. To override that
+and use the GDI backend even if Uniscribe is available, invoke Emacs
+with the @kbd{-xrm Emacs.fontBackend:gdi} command-line argument, or
+add a @code{Emacs.fontBackend} resource with the value @code{gdi} in
+the Registry under either the
+@samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} or the
+@samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs} key (@pxref{Resources}).
@cindex font properties (MS Windows)
@noindent
@vindex w32-charset-info-alist
@item registry
Specifies the character set registry that the font is
-expected to cover. Most Truetype and Opentype fonts will be unicode fonts
+expected to cover. Most TrueType and OpenType fonts will be Unicode fonts
that cover several national character sets, but you can narrow down the
selection of fonts to those that support a particular character set by
using a specific registry from @code{w32-charset-info-alist} here.
@table @code
@cindex font scripts (MS Windows)
-@cindex font unicode subranges (MS Windows)
+@cindex font Unicode subranges (MS Windows)
@item script
-Specifies a unicode subrange the font should support.
+Specifies a Unicode subrange the font should support.
The following scripts are recognized on Windows: @code{latin}, @code{greek},
@code{coptic}, @code{cyrillic}, @code{armenian}, @code{hebrew}, @code{arabic},
@cindex font antialiasing (MS Windows)
@item antialias
-Specifies the antialiasing to use for the font. The value @code{none}
-means no antialiasing, @code{standard} means use standard antialiasing,
-@code{subpixel} means use subpixel antialiasing (known as Cleartype on Windows),
-and @code{natural} means use subpixel antialiasing with adjusted spacing between
-letters. If unspecified, the font will use the system default antialiasing.
+Specifies the antialiasing method. The value @code{none} means no
+antialiasing, @code{standard} means use standard antialiasing,
+@code{subpixel} means use subpixel antialiasing (known as Cleartype on
+Windows), and @code{natural} means use subpixel antialiasing with
+adjusted spacing between letters. If unspecified, the font will use
+the system default antialiasing.
@end table
@node Windows Misc
@ifnottex
@include msdog-xtra.texi
@end ifnottex
-
-@ignore
- arch-tag: f39d2590-5dcc-4318-88d9-0eb73ca10fa2
-@end ignore