msdos.texi 53 KB
Newer Older
Andrew Innes's avatar
Andrew Innes committed
1
@c This is part of the Emacs manual.
Paul Eggert's avatar
Paul Eggert committed
2
@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software
3
@c Foundation, Inc.
Andrew Innes's avatar
Andrew Innes committed
4
@c See file emacs.texi for copying conditions.
5
@node Microsoft Windows
6
@appendix Emacs and Microsoft Windows/MS-DOS
7
@cindex Microsoft Windows
8
@cindex MS-Windows, Emacs peculiarities
Andrew Innes's avatar
Andrew Innes committed
9

10
  This section describes peculiarities of using Emacs on Microsoft
11
Windows.  Some of these peculiarities are also relevant to Microsoft's
12
older MS-DOS operating system.
13
However, Emacs features that are relevant @emph{only} to MS-DOS are
14 15
described in a separate
@iftex
16
manual (@pxref{MS-DOS,,, emacs-xtra, Specialized Emacs Features}).
17 18 19 20 21
@end iftex
@ifnottex
section (@pxref{MS-DOS}).
@end ifnottex

22 23 24 25 26
  MS-Windows is a non-free operating system; that means it denies its
users the freedom that every computer user deserves.  That is an
injustice.  For your freedom's sake, we urge you to switch to a free
operating system.

27 28
  We support GNU Emacs on proprietary operating systems because we
hope this taste of freedom will inspire users to escape from them.
Andrew Innes's avatar
Andrew Innes committed
29

30 31 32 33 34
  The behavior of Emacs on MS-Windows is reasonably similar to what is
documented in the rest of the manual, including support for long file
names, multiple frames, scroll bars, mouse menus, and subprocesses.
However, a few special considerations apply, and they are described
here.
Andrew Innes's avatar
Andrew Innes committed
35 36

@menu
37
* Windows Startup::     How to start Emacs on Windows.
38 39
* Text and Binary::     Text files use CRLF to terminate lines.
* Windows Files::       File-name conventions on Windows.
Eli Zaretskii's avatar
Eli Zaretskii committed
40
* ls in Lisp::          Emulation of @code{ls} for Dired.
Eli Zaretskii's avatar
Eli Zaretskii committed
41 42
* Windows HOME::        Where Emacs looks for your @file{.emacs} and
                          where it starts up.
43
* Windows Keyboard::    Windows-specific keyboard features.
Eli Zaretskii's avatar
Eli Zaretskii committed
44
* Windows Mouse::       Windows-specific mouse features.
45 46
* Windows Processes::   Running subprocesses on Windows.
* Windows Printing::    How to specify the printer on MS-Windows.
47
* Windows Fonts::       Specifying fonts on MS-Windows.
Eli Zaretskii's avatar
Eli Zaretskii committed
48
* Windows Misc::        Miscellaneous Windows features.
49
@ifnottex
Glenn Morris's avatar
Glenn Morris committed
50
* MS-DOS::              Using Emacs on MS-DOS.
51
@end ifnottex
Andrew Innes's avatar
Andrew Innes committed
52 53
@end menu

54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
@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.

78 79 80 81 82 83 84 85 86 87 88 89 90 91
@item
@cindex pinning Emacs to Windows task bar
From a task-bar shortcut icon, by clicking once the left mouse button.
Windows versions since Vista allow you to create such shortcuts by
@dfn{pinning} the icon of a running program that appears in the task
bar.  You can do that with Emacs, but afterwards you will have to
change the properties of the pinned shortcut to run
@file{runemacs.exe}, @emph{not} of @file{emacs.exe}.  You can also pin
Emacs to the task bar by clicking the right mouse button on its icon
in the Start menu, then selecting @samp{Pin to taskbar}.  Once again,
be sure to specify @file{runemacs.exe} as the program to run.  You can
control where Emacs starts by setting the ``Start in'' field of the
shortcut's Properties.

92 93 94 95 96 97 98 99 100 101 102 103
@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.

104 105 106 107 108 109
@item
From the Windows @code{Run} dialog (normally reached by clicking the
@code{Start} button).  Typing @kbd{runemacs @key{RET}} into the dialog
will start Emacs in the parent directory of the Windows equivalent of
your user's @code{HOME} directory, see @ref{Windows HOME}.

110 111 112 113
@item
@cindex invoking Emacs from Windows Explorer
@pindex emacsclient.exe
@pindex emacsclientw.exe
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136
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}.
137 138
@end enumerate

139
@cindex @command{emacsclient}, on MS-Windows
140 141 142 143 144 145 146 147 148 149 150
Note that, due to limitations of MS-Windows, Emacs cannot have both
GUI and text-mode frames in the same session.  It also cannot open
text-mode frames on more than a single @dfn{Command Prompt} window,
because each Windows program can have only one console at any given
time.  For these reasons, if you invoke @command{emacsclient} with the
@option{-c} option, and the Emacs server runs in a text-mode session,
Emacs will always create a new text-mode frame in the same
@dfn{Command Prompt} window where it was started; a GUI frame will be
created only if the server runs in a GUI session.  Similarly, if you
invoke @command{emacsclient} with the @option{-t} option, Emacs will
create a GUI frame if the server runs in a GUI session, or a text-mode
151 152
frame when the session runs in text mode in a @dfn{Command Prompt}
window.  @xref{emacsclient Options}.
153

Andrew Innes's avatar
Andrew Innes committed
154 155 156 157 158
@node Text and Binary
@section Text Files and Binary Files
@cindex text and binary files on MS-DOS/MS-Windows

  GNU Emacs uses newline characters to separate text lines.  This is the
Paul Eggert's avatar
Paul Eggert committed
159
convention used on GNU, Unix, and other POSIX-compliant systems.
Andrew Innes's avatar
Andrew Innes committed
160 161

@cindex end-of-line conversion on MS-DOS/MS-Windows
162 163 164 165 166 167 168 169 170 171
  By contrast, MS-DOS and MS-Windows normally use carriage return
followed by linefeed, a two-character sequence, to separate text
lines.  (Linefeed is the same character as newline.)  Therefore,
convenient editing of typical files with Emacs requires conversion of
these end-of-line (EOL) sequences.  And that is what Emacs normally
does: it converts carriage return followed by linefeed into newline
when reading files, and converts newline into carriage return followed
by linefeed when writing files.  The same mechanism that handles
conversion of international character codes does this conversion also
(@pxref{Coding Systems}).
Andrew Innes's avatar
Andrew Innes committed
172

173 174
@cindex cursor location, on MS-DOS
@cindex point location, on MS-DOS
Andrew Innes's avatar
Andrew Innes committed
175 176 177 178 179
  One consequence of this special format-conversion of most files is
that character positions as reported by Emacs (@pxref{Position Info}) do
not agree with the file size information known to the operating system.

  In addition, if Emacs recognizes from a file's contents that it uses
180 181 182 183 184
newline rather than carriage return followed by linefeed as its line
separator, it does not perform EOL conversion when reading or writing
that file.  Thus, you can read and edit files from GNU and Unix
systems on MS-DOS with no special effort, and they will retain their
Unix-style end-of-line convention after you edit them.
Andrew Innes's avatar
Andrew Innes committed
185 186

  The mode line indicates whether end-of-line translation was used for
187
the current buffer.  If MS-DOS end-of-line translation is in use for the
188 189 190 191
buffer, the MS-Windows build of Emacs displays a backslash @samp{\} after
the coding system mnemonic near the beginning of the mode line
(@pxref{Mode Line}).  If no EOL translation was performed, the string
@samp{(Unix)} is displayed instead of the backslash, to alert you that the
192
file's EOL format is not the usual carriage return followed by linefeed.
193 194

@cindex DOS-to-Unix conversion of files
195
  To visit a file and specify whether it uses DOS-style or Unix-style
196
end-of-line, specify a coding system (@pxref{Text Coding}).  For
197 198
example, @kbd{C-x @key{RET} c unix @key{RET} C-x C-f foobar.txt}
visits the file @file{foobar.txt} without converting the EOLs; if some
199 200 201 202 203 204 205
line ends with a carriage return followed by linefeed pair, Emacs will
display @samp{^M} at the end of that line.  Similarly, you can direct
Emacs to save a buffer in a specified EOL format with the @kbd{C-x
@key{RET} f} command.  For example, to save a buffer with Unix EOL
format, type @kbd{C-x @key{RET} f unix @key{RET} C-x C-s}.  If you
visit a file with DOS EOL conversion, then save it with Unix EOL
format, that effectively converts the file to Unix EOL style, like the
Glenn Morris's avatar
Glenn Morris committed
206
@code{dos2unix} program.
Andrew Innes's avatar
Andrew Innes committed
207 208 209

@cindex untranslated file system
@findex add-untranslated-filesystem
210 211 212 213 214 215 216 217
  When you use NFS, Samba, or some other similar method to access file
systems that reside on computers using GNU or Unix systems, Emacs
should not perform end-of-line translation on any files in these file
systems---not even when you create a new file.  To request this,
designate these file systems as @dfn{untranslated} file systems by
calling the function @code{add-untranslated-filesystem}.  It takes one
argument: the file system name, including a drive letter and
optionally a directory.  For example,
Andrew Innes's avatar
Andrew Innes committed
218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234

@example
(add-untranslated-filesystem "Z:")
@end example

@noindent
designates drive Z as an untranslated file system, and

@example
(add-untranslated-filesystem "Z:\\foo")
@end example

@noindent
designates directory @file{\foo} on drive Z as an untranslated file
system.

  Most often you would use @code{add-untranslated-filesystem} in your
235 236
@file{.emacs} or @file{init.el} init file, or in @file{site-start.el}
so that all the users at your site get the benefit of it.
Andrew Innes's avatar
Andrew Innes committed
237 238 239 240 241 242 243

@findex remove-untranslated-filesystem
  To countermand the effect of @code{add-untranslated-filesystem}, use
the function @code{remove-untranslated-filesystem}.  This function takes
one argument, which should be a string just like the one that was used
previously with @code{add-untranslated-filesystem}.

244 245
  Designating a file system as untranslated does not affect character
set conversion, only end-of-line conversion.  Essentially, it directs
246 247
Emacs to default to creating new files with the Unix-style convention
of using newline at the end of a line.  @xref{Coding Systems}.
248

249 250 251 252 253 254 255 256 257 258 259
@node Windows Files
@section File Names on MS-Windows
@cindex file names on MS-Windows

  MS-Windows and MS-DOS normally use a backslash, @samp{\}, to
separate name units within a file name, instead of the slash used on
other systems.  Emacs on MS-DOS/MS-Windows permits use of either slash or
backslash, and also knows about drive letters in file names.

@cindex file-name completion, on MS-Windows
  On MS-DOS/MS-Windows, file names are case-insensitive, so Emacs by
260 261 262
default ignores letter-case in file names during completion.  To this
end, the default value of @code{read-file-name-completion-ignore-case}
is non-@code{nil} on MS-DOS/MS-Windows.  @xref{Completion Options}.
263

Eli Zaretskii's avatar
Eli Zaretskii committed
264
@vindex w32-get-true-file-attributes
265 266 267 268 269 270 271 272 273 274 275 276 277 278 279
  The variable @code{w32-get-true-file-attributes} controls whether
Emacs should issue additional system calls to determine more
accurately file attributes in primitives like @code{file-attributes}
and @code{directory-files-and-attributes}.  These additional calls are
needed to report correct file ownership, link counts and file types
for special files such as pipes.  Without these system calls, file
ownership will be attributed to the current user, link counts will be
always reported as 1, and special files will be reported as regular
files.

  If the value of this variable is @code{local} (the default), Emacs
will issue these additional system calls only for files on local fixed
drives.  Any other non-@code{nil} value means do this even for
removable and remote volumes, where this could potentially slow down
Dired and other related features.  The value of @code{nil} means never
280 281
issue those system calls.  Non-@code{nil} values are more useful on
NTFS volumes, which support hard links and file security, than on FAT,
282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317
FAT32, and exFAT volumes.

@cindex file names, invalid characters on MS-Windows
  Unlike Unix, MS-Windows file systems restrict the set of characters
that can be used in a file name.  The following characters are not
allowed:

@itemize @bullet
@item
Shell redirection symbols @samp{<}, @samp{>}, and @samp{|}.

@item
Colon @samp{:} (except after the drive letter).

@item
Forward slash @samp{/} and backslash @samp{\} (except as directory
separators).

@item
Wildcard characters @samp{*} and @samp{?}.

@item
Control characters whose codepoints are 1 through 31 decimal.  In
particular, newlines in file names are not allowed.

@item
The null character, whose codepoint is zero (this limitation exists on
Unix filesystems as well).
@end itemize

@noindent
In addition, referencing any file whose name matches a DOS character
device, such as @file{NUL} or @file{LPT1} or @file{PRN} or @file{CON},
with or without any file-name extension, will always resolve to those
character devices, in any directory.  Therefore, only use such file
names when you want to use the corresponding character device.
Eli Zaretskii's avatar
Eli Zaretskii committed
318

Eli Zaretskii's avatar
Eli Zaretskii committed
319 320 321 322 323
@node ls in Lisp
@section Emulation of @code{ls} on MS-Windows
@cindex Dired, and MS-Windows/MS-DOS
@cindex @code{ls} emulation

Glenn Morris's avatar
Glenn Morris committed
324 325
  Dired normally uses the external program @code{ls}
to produce the directory listing displayed in Dired
Eli Zaretskii's avatar
Eli Zaretskii committed
326 327 328 329 330
buffers (@pxref{Dired}).  However, MS-Windows and MS-DOS systems don't
come with such a program, although several ports of @sc{gnu} @code{ls}
are available.  Therefore, Emacs on those systems @emph{emulates}
@code{ls} in Lisp, by using the @file{ls-lisp.el} package.  While
@file{ls-lisp.el} provides a reasonably full emulation of @code{ls},
331 332 333 334 335 336 337
there are some options and features peculiar to that emulation;
@iftex
for more details, see the documentation of the variables whose names
begin with @code{ls-lisp}.
@end iftex
@ifnottex
they are described in this section.
Eli Zaretskii's avatar
Eli Zaretskii committed
338 339 340 341

  The @code{ls} emulation supports many of the @code{ls} switches, but
it doesn't support all of them.  Here's the list of the switches it
does support: @option{-A}, @option{-a}, @option{-B}, @option{-C},
Glenn Morris's avatar
Glenn Morris committed
342 343
@option{-c}, @option{-G}, @option{-g}, @option{-h}, @option{-i}, @option{-n},
@option{-R}, @option{-r}, @option{-S}, @option{-s}, @option{-t}, @option{-U},
344
@option{-u}, @option{-v}, and @option{-X}.  The @option{-F} switch is
345 346
partially supported (it appends the character that classifies the
file, but does not prevent symlink following).
Eli Zaretskii's avatar
Eli Zaretskii committed
347 348 349 350 351 352 353 354 355

@vindex ls-lisp-use-insert-directory-program
  On MS-Windows and MS-DOS, @file{ls-lisp.el} is preloaded when Emacs
is built, so the Lisp emulation of @code{ls} is always used on those
platforms.  If you have a ported @code{ls}, setting
@code{ls-lisp-use-insert-directory-program} to a non-@code{nil} value
will revert to using an external program named by the variable
@code{insert-directory-program}.

356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375
@cindex Dired sorting order, on MS-Windows/MS-DOS
  The order in which @file{ls-lisp.el} sorts files depends on several
customizable options described below.

@vindex ls-lisp-use-string-collate
  The default sorting order follows locale-specific rules derived from
your system locale.  You can make the order locale-independent by
customizing @code{ls-lisp-use-string-collate} to a @code{nil} value.

@cindex Unicode Collation Algorithm (UCA), and @file{ls-lisp.el}
@vindex ls-lisp-UCA-like-collation
  On GNU and Unix systems, when the locale's encoding is UTF-8, the
collation order follows the Unicode Collation Algorithm
(@acronym{UCA}).  To have a similar effect on MS-Windows, the variable
@code{ls-lisp-UCA-like-collation} should have a non-@code{nil} value
(this is the default).  The resulting sorting order ignores
punctuation, symbol characters, and whitespace characters, so
@file{.foobar}, @file{foobar} and @w{@file{foo bar}} will appear
together rather than far apart.

Eli Zaretskii's avatar
Eli Zaretskii committed
376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395
@vindex ls-lisp-ignore-case
  By default, @file{ls-lisp.el} uses a case-sensitive sort order for
the directory listing it produces; this is so the listing looks the
same as on other platforms.  If you wish that the files be sorted in
case-insensitive order, set the variable @code{ls-lisp-ignore-case} to
a non-@code{nil} value.

@vindex ls-lisp-dirs-first
  By default, files and subdirectories are sorted together, to emulate
the behavior of @code{ls}.  However, native MS-Windows/MS-DOS file
managers list the directories before the files; if you want that
behavior, customize the option @code{ls-lisp-dirs-first} to a
non-@code{nil} value.

@vindex ls-lisp-verbosity
  The variable @code{ls-lisp-verbosity} controls the file attributes
that @file{ls-lisp.el} displays.  The value should be a list that
contains one or more of the symbols @code{links}, @code{uid}, and
@code{gid}.  @code{links} means display the count of different file
names that are associated with (a.k.a.@: @dfn{links to}) the file's
396 397 398
data; this is only useful on NTFS volumes.  @code{uid} means display
the numerical identifier of the user who owns the file.  @code{gid}
means display the numerical identifier of the file owner's group.  The
399
default value is @code{(links uid gid)} i.e., all the 3 optional
400
attributes are displayed.
Eli Zaretskii's avatar
Eli Zaretskii committed
401 402

@vindex ls-lisp-emulation
Paul Eggert's avatar
Paul Eggert committed
403
  The variable @code{ls-lisp-emulation} controls the flavor of the
Eli Zaretskii's avatar
Eli Zaretskii committed
404 405 406 407 408 409 410 411 412 413 414 415 416 417 418
@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
this option can be one of the following symbols:

@table @code
@item GNU
@itemx nil
Emulate @sc{gnu} systems; this is the default.  This sets
@code{ls-lisp-ignore-case} and @code{ls-lisp-dirs-first} to
@code{nil}, and @code{ls-lisp-verbosity} to @code{(links uid gid)}.
@item UNIX
Emulate Unix systems.  Like @code{GNU}, but sets
@code{ls-lisp-verbosity} to @code{(links uid)}.
@item MacOS
419
Emulate macOS@.  Sets @code{ls-lisp-ignore-case} to @code{t}, and
Eli Zaretskii's avatar
Eli Zaretskii committed
420 421 422 423
@code{ls-lisp-dirs-first} and @code{ls-lisp-verbosity} to @code{nil}.
@item MS-Windows
Emulate MS-Windows.  Sets @code{ls-lisp-ignore-case} and
@code{ls-lisp-dirs-first} to @code{t}, and @code{ls-lisp-verbosity} to
424 425 426 427
@code{nil} on Windows 9X and to @code{t} on modern versions of
Windows.  Note that the default emulation is @emph{not}
@code{MS-Windows}, even on Windows, since many users of Emacs on those
platforms prefer the @sc{gnu} defaults.
Eli Zaretskii's avatar
Eli Zaretskii committed
428 429 430
@end table

@noindent
431 432 433 434 435 436
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.
Eli Zaretskii's avatar
Eli Zaretskii committed
437 438 439 440 441 442

@vindex ls-lisp-support-shell-wildcards
  The variable @code{ls-lisp-support-shell-wildcards} controls how
file-name patterns are supported: if it is non-@code{nil} (the
default), they are treated as shell-style wildcards; otherwise they
are treated as Emacs regular expressions.
443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473

@vindex ls-lisp-format-time-list
  The variable @code{ls-lisp-format-time-list} defines how to format
the date and time of files.  @emph{The value of this variable is
ignored}, unless Emacs cannot determine the current locale.  (However,
if the value of @code{ls-lisp-use-localized-time-format} is
non-@code{nil}, Emacs obeys @code{ls-lisp-format-time-list} even if
the current locale is available; see below.)

The value of @code{ls-lisp-format-time-list} is a list of 2 strings.
The first string is used if the file was modified within the current
year, while the second string is used for older files.  In each of
these two strings you can use @samp{%}-sequences to substitute parts
of the time.  For example:
@lisp
("%b %e %H:%M" "%b %e  %Y")
@end lisp

@noindent
Note that the strings substituted for these @samp{%}-sequences depend
on the current locale.  @xref{Time Parsing,,, elisp, The Emacs Lisp
Reference Manual}, for more about format time specs.

@vindex ls-lisp-use-localized-time-format
  Normally, Emacs formats the file time stamps in either traditional
or ISO-style time format.  However, if the value of the variable
@code{ls-lisp-use-localized-time-format} is non-@code{nil}, Emacs
formats file time stamps according to what
@code{ls-lisp-format-time-list} specifies.  The @samp{%}-sequences in
@code{ls-lisp-format-time-list} produce locale-dependent month and day
names, which might cause misalignment of columns in Dired display.
474 475
The default value of @code{ls-lisp-use-localized-time-format} is
@code{nil}.
476
@end ifnottex
Eli Zaretskii's avatar
Eli Zaretskii committed
477

478
@node Windows HOME
Eli Zaretskii's avatar
Eli Zaretskii committed
479
@section HOME and Startup Directories on MS-Windows
480
@cindex HOME directory on MS-Windows
481

482 483 484
  The Windows equivalent of @code{HOME} is the @dfn{user-specific
application data directory}.  The actual location depends on the
Windows version; typical values are @file{C:\Documents and
485 486 487
Settings\@var{username}\Application Data} on Windows 2000 up to XP,
@file{C:\Users\@var{username}\AppData\Roaming} on Windows Vista and
later, and either @file{C:\WINDOWS\Application Data} or
488
@file{C:\WINDOWS\Profiles\@var{username}\Application Data} on Windows
489
9X/ME@.  If this directory does not exist or cannot be accessed, Emacs
490
falls back to @file{C:\} as the default value of @code{HOME}.
491 492 493 494

  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
Glenn Morris's avatar
Glenn Morris committed
495 496 497
prompt or from @samp{Properties} dialog of @samp{My Computer}.
@code{HOME} can also be set in the system registry,
@pxref{MS-Windows Registry}.
498

499 500 501 502 503 504 505 506 507
  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
508 509
deprecated; Emacs will display a warning about its use during
startup.
510 511 512 513

  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
Glenn Morris's avatar
Glenn Morris committed
514
creates in your home directory.
515

Glenn Morris's avatar
Glenn Morris committed
516
  You can always find out what Emacs thinks is your home directory's
517 518 519
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
520 521 522
~/.emacs @key{RET}} (assuming the file's name is @file{.emacs}).

@cindex init file @file{.emacs} on MS-Windows
523
  Your init file can have any name mentioned in @ref{Init File}.
524 525 526

@cindex @file{_emacs} init file, MS-Windows
  Because MS-DOS does not allow file names with leading dots, and
527 528 529
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.
530 531
This name is considered obsolete, so Emacs will display a warning if
it is used.
532

533 534 535 536 537 538 539
@node Windows Keyboard
@section Keyboard Usage on MS-Windows
@cindex keyboard, MS-Windows

  This section describes the Windows-specific features related to
keyboard input in Emacs.

540
@cindex MS-Windows keyboard shortcuts
541 542
  Many key combinations (known as ``keyboard shortcuts'') that have
conventional uses in MS-Windows programs conflict with traditional
543 544 545 546
Emacs key bindings.  (These Emacs key bindings were established years
before Microsoft was founded.)  Examples of conflicts include
@kbd{C-c}, @kbd{C-x}, @kbd{C-z}, @kbd{C-a}, and @kbd{W-@key{SPC}}.
You can redefine some of them with meanings more like the MS-Windows
547 548 549
meanings by enabling CUA Mode (@pxref{CUA Bindings}).  Another
optional feature which will make Emacs behave like other Windows
applications is Delete Selection mode (@pxref{Using Region}).
550

551 552 553 554
@iftex
@inforef{Windows Keyboard, , emacs}, for information about additional
Windows-specific variables in this category.
@end iftex
555
@ifnottex
556 557
@vindex w32-alt-is-meta
@cindex @code{Alt} key (MS-Windows)
558
  By default, the key labeled @key{Alt} is mapped as the @key{Meta}
559 560 561
key.  If you wish it to produce the @code{Alt} modifier instead, set
the variable @code{w32-alt-is-meta} to a @code{nil} value.

562 563
@findex w32-register-hot-key
@findex w32-unregister-hot-key
564
  MS-Windows reserves certain key combinations, such as
565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588
@kbd{@key{Alt}-@key{TAB}} and a number of Windows key combinations,
for its own use.  These key combinations are intercepted by the system
before Emacs can see them.  Also, on Windows 10, all Windows key
combinations are reserved by the system in such a way that they are
never propagated to applications, even if the system does not
currently define a hotkey on the specific combination.  You can use
the @code{w32-register-hot-key} function to allow a key sequence to be
seen by Emacs instead of being grabbed by Windows.  When registered as
a hot key, the key combination is pulled out of the system's input
queue before it is handled by Windows, effectively overriding the
special meaning of that key sequence for Windows.  The override is
only effective when Emacs is active; with other applications on the
foreground the keys behave normally.

  The argument to @code{w32-register-hot-key} must be a single key with a
single modifier, in vector form that would be acceptable to
@code{define-key}.  The control and shift modifiers have no effect on the
argument.  The meta modifier is interpreted as the @key{Alt} key if
@code{w32-alt-is-meta} is @code{t} (the default), and the super and hyper
modifiers are interpreted according to the bindings of
@code{w32-lwindow-modifier} and @code{w32-rwindow-modifier}.  Additionally, a
modifier with the trailing dash but with no key indicates that all
Windows defined hotkeys for that modifier are to be overridden in the
favor of Emacs.
589

590
@kindex M-TAB@r{, (MS-Windows)}
591 592
@cindex @kbd{M-@key{TAB}} vs @kbd{@key{Alt}-@key{TAB}} (MS-Windows)
@cindex @kbd{@key{Alt}-@key{TAB}} vs @kbd{M-@key{TAB}} (MS-Windows)
593
  For example, @code{(w32-register-hot-key [M-tab])} lets you use
594 595 596 597 598 599
@kbd{M-@key{TAB}} normally in Emacs; for instance, to complete the
word or symbol at point at top level, or to complete the current
search string against previously sought strings during incremental
search.  @code{(w32-register-hot-key [s-])} with
@code{w32-lwindow-modifier} bound to @code{super} disables all the
Windows' own Windows key based shortcuts.@footnote{There is one known
600
exception: The combination @kbd{@key{Windows}-L} that locks the
601 602 603 604 605 606 607 608 609
workstation is handled by the system on a lower level.  For this
reason, @code{w32-register-hot-key} cannot override this key
combination - it always locks the computer.}

  Note that @code{w32-register-hot-key} checks the
@code{w32-[lr]window-modifier} values at the time of the function
call.  Thus, you can set @code{w32-lwindow-modifier} as @code{super},
then call @code{(w32-register-hot-key [s-r])}, and finally set
@code{w32-rwindow-modifier} as @code{super} as well.  The result is
610
that the left Windows key together with @kbd{R} invokes whichever
611
function you have bound for the combination in Emacs, and the right
612
Windows key and @kbd{R} opens the Windows @code{Run} dialog.
613 614 615

  The hotkey registrations always also include all the shift and
control modifier combinations for the given hotkey; that is,
616 617
registering @kbd{s-a} as a hotkey gives you @kbd{S-s-a},
@kbd{C-s-a} and @kbd{C-S-s-a} as well.
618 619 620 621 622

  On Windows 98 and ME, the hotkey registration is more restricted.
The desired hotkey must always be fully specified, and
@code{w32-phantom-key-code} can be customized to achieve desired
results.
623 624 625

  The function @code{w32-unregister-hot-key} reverses the effect of
@code{w32-register-hot-key} for its argument key sequence.
626

627 628 629 630 631 632
@vindex w32-capslock-is-shiftlock
  By default, the @key{CapsLock} key only affects normal character
keys (it converts lower-case characters to their upper-case
variants).  However, if you set the variable
@code{w32-capslock-is-shiftlock} to a non-@code{nil} value, the
@key{CapsLock} key will affect non-character keys as well, as if you
633
pressed the @key{SHIFT} key while typing the non-character key.
634 635 636 637

@vindex w32-enable-caps-lock
  If the variable @code{w32-enable-caps-lock} is set to a @code{nil}
value, the @key{CapsLock} key produces the symbol @code{capslock}
Charles A. Roelli's avatar
Charles A. Roelli committed
638
instead of the shifted version of typed keys.  The default value is
639 640 641 642 643 644 645 646
@code{t}.

@vindex w32-enable-num-lock
@cindex keypad keys (MS-Windows)
  Similarly, if @code{w32-enable-num-lock} is @code{nil}, the
@key{NumLock} key will produce the symbol @code{kp-numlock}.  The
default is @code{t}, which causes @key{NumLock} to work as expected:
toggle the meaning of the keys on the numeric keypad.
647
@end ifnottex
648

Eli Zaretskii's avatar
Eli Zaretskii committed
649 650 651 652 653 654 655 656
@vindex w32-apps-modifier
  The variable @code{w32-apps-modifier} controls the effect of the
@key{Apps} key (usually located between the right @key{Alt} and the
right @key{Ctrl} keys).  Its value can be one of the symbols
@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control},
or @code{shift} for the respective modifier, or @code{nil} to appear
as the key @code{apps}.  The default is @code{nil}.

657 658 659 660 661 662 663 664 665 666 667 668 669
@vindex w32-lwindow-modifier
@vindex w32-rwindow-modifier
@vindex w32-scroll-lock-modifier
  The variable @code{w32-lwindow-modifier} determines the effect of
the left Windows key (usually labeled with @key{start} and the Windows
logo).  If its value is @code{nil} (the default), the key will produce
the symbol @code{lwindow}.  Setting it to one of the symbols
@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control},
or @code{shift} will produce the respective modifier.  A similar
variable @code{w32-rwindow-modifier} controls the effect of the right
Windows key, and @code{w32-scroll-lock-modifier} does the same for the
@key{ScrLock} key.  If these variables are set to @code{nil}, the
right Windows key produces the symbol @code{rwindow} and @key{ScrLock}
670 671 672 673 674
produces the symbol @code{scroll}.  If you want @key{ScrLock} to
produce the same effect as in other applications, i.e.@: toggle the
Scroll Lock @acronym{LED} indication on the keyboard, set
@code{w32-scroll-lock-modifier} to @code{t} or any non-@code{nil}
value other than the above modifier symbols.
675 676

@vindex w32-pass-alt-to-system
Eli Zaretskii's avatar
Eli Zaretskii committed
677 678 679
@cindex Windows system menu
@cindex @code{Alt} key invokes menu (Windows)
  Emacs compiled as a native Windows application normally turns off
680
the Windows feature that tapping the @key{Alt} key invokes the Windows
681 682
menu.  The reason is that the @key{Alt} serves as @key{Meta} in Emacs.
When using Emacs, users often press the @key{Meta} key temporarily and
Eli Zaretskii's avatar
Eli Zaretskii committed
683 684 685 686
then change their minds; if this has the effect of bringing up the
Windows menu, it alters the meaning of subsequent commands.  Many
users find this frustrating.

687
  You can re-enable Windows's default handling of tapping the @key{Alt}
Eli Zaretskii's avatar
Eli Zaretskii committed
688 689 690
key by setting @code{w32-pass-alt-to-system} to a non-@code{nil}
value.

691
@ifnottex
692 693
@vindex w32-pass-lwindow-to-system
@vindex w32-pass-rwindow-to-system
Eli Zaretskii's avatar
Eli Zaretskii committed
694
  The variables @code{w32-pass-lwindow-to-system} and
695 696 697
@code{w32-pass-rwindow-to-system} determine whether the respective
keys are passed to Windows or swallowed by Emacs.  If the value is
@code{nil}, the respective key is silently swallowed by Emacs,
Eli Zaretskii's avatar
Eli Zaretskii committed
698 699 700
otherwise it is passed to Windows.  The default is @code{t} for both
of these variables.  Passing each of these keys to Windows produces
its normal effect: for example, @kbd{@key{Lwindow}} opens the
701
@code{Start} menu, etc.
702 703

@vindex w32-recognize-altgr
704
@kindex AltGr @r{(MS-Windows)}
705
@cindex @key{AltGr} key (MS-Windows)
706
  The variable @code{w32-recognize-altgr} controls whether the
707 708 709 710 711
@key{AltGr} key (if it exists on your keyboard), or its equivalent,
the combination of the right @key{Alt} and left @key{Ctrl} keys
pressed together, is recognized as the @key{AltGr} key.  The default
is @code{t}, which means these keys produce @code{AltGr}; setting it
to @code{nil} causes @key{AltGr} or the equivalent key combination to
712
be interpreted as the combination of @key{Ctrl} and @key{Meta}
713
modifiers.
714
@end ifnottex
715

Eli Zaretskii's avatar
Eli Zaretskii committed
716 717 718 719 720
@node Windows Mouse
@section Mouse Usage on MS-Windows
@cindex mouse, and MS-Windows

  This section describes the Windows-specific variables related to
Glenn Morris's avatar
Glenn Morris committed
721
the mouse.
Eli Zaretskii's avatar
Eli Zaretskii committed
722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741

@vindex w32-mouse-button-tolerance
@cindex simulation of middle mouse button
  The variable @code{w32-mouse-button-tolerance} specifies the
time interval, in milliseconds, for faking middle mouse button press
on 2-button mice.  If both mouse buttons are depressed within this
time interval, Emacs generates a middle mouse button click event
instead of a double click on one of the buttons.

@vindex w32-pass-extra-mouse-buttons-to-system
  If the variable @code{w32-pass-extra-mouse-buttons-to-system} is
non-@code{nil}, Emacs passes the fourth and fifth mouse buttons to
Windows.

@vindex w32-swap-mouse-buttons
  The variable @code{w32-swap-mouse-buttons} controls which of the 3
mouse buttons generates the @kbd{mouse-2} events.  When it is
@code{nil} (the default), the middle button generates @kbd{mouse-2}
and the right button generates @kbd{mouse-3} events.  If this variable
is non-@code{nil}, the roles of these two buttons are reversed.
742

Andrew Innes's avatar
Andrew Innes committed
743
@node Windows Processes
744
@section Subprocesses on Windows 9X/ME and Windows NT/2K/XP/Vista/7/8/10
745
@cindex subprocesses on MS-Windows
Andrew Innes's avatar
Andrew Innes committed
746

747
@cindex DOS applications, running from Emacs
748 749 750 751 752 753 754 755
  Emacs compiled as a native Windows application (as opposed to the
DOS version) includes full support for asynchronous subprocesses.  In
the Windows version, synchronous and asynchronous subprocesses work
fine on all versions of MS-Windows, as long as you run only 32-bit or
64-bit Windows applications.  However, when you run a DOS application
in a subprocess, you may encounter problems or be unable to run the
application at all; and if you run two DOS applications at the same
time in two subprocesses, you may have to reboot your system.
Andrew Innes's avatar
Andrew Innes committed
756 757

Since the standard command interpreter (and most command line utilities)
758
on Windows 9X are DOS applications, these problems are significant when
Andrew Innes's avatar
Andrew Innes committed
759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777
using that system.  But there's nothing we can do about them; only
Microsoft can fix them.

If you run just one DOS application subprocess, the subprocess should
work as expected as long as it is ``well-behaved'' and does not perform
direct screen access or other unusual actions.  If you have a CPU
monitor application, your machine will appear to be 100% busy even when
the DOS application is idle, but this is only an artifact of the way CPU
monitors measure processor load.

You must terminate the DOS application before you start any other DOS
application in a different subprocess.  Emacs is unable to interrupt or
terminate a DOS subprocess.  The only way you can terminate such a
subprocess is by giving it a command that tells its program to exit.

If you attempt to run two DOS applications at the same time in separate
subprocesses, the second one that is started will be suspended until the
first one finishes, even if either or both of them are asynchronous.

778
@cindex kill DOS application
Andrew Innes's avatar
Andrew Innes committed
779
If you can go to the first subprocess, and tell it to exit, the second
780 781 782 783 784 785 786
subprocess should continue normally.  However, if the second
subprocess is synchronous, Emacs itself will be hung until the first
subprocess finishes.  If it will not finish without user input, then
you have no choice but to reboot if you are running on Windows 9X@.
If you are running on Windows NT and later, you can use a process
viewer application to kill the appropriate instance of NTVDM instead
(this will terminate both DOS subprocesses).
Andrew Innes's avatar
Andrew Innes committed
787

788
If you have to reboot Windows 9X in this situation, do not use the
Andrew Innes's avatar
Andrew Innes committed
789
@code{Shutdown} command on the @code{Start} menu; that usually hangs the
790
system.  Instead, type @kbd{@key{Ctrl}-@key{Alt}-@key{DEL}} and then choose
Andrew Innes's avatar
Andrew Innes committed
791 792 793
@code{Shutdown}.  That usually works, although it may take a few minutes
to do its job.

Eli Zaretskii's avatar
Eli Zaretskii committed
794
@vindex w32-quote-process-args
795 796
  The variable @code{w32-quote-process-args} controls how Emacs quotes
the process arguments.  Non-@code{nil} means quote with the @code{"}
Glenn Morris's avatar
Glenn Morris committed
797 798
character.  If the value is a character, Emacs uses that character to escape
any quote characters that appear; otherwise it chooses a suitable escape
799
character based on the type of the program.
Eli Zaretskii's avatar
Eli Zaretskii committed
800

801 802 803 804 805 806 807 808 809
@vindex w32-pipe-buffer-size
  The variable @code{w32-pipe-buffer-size} controls the size of the
buffer Emacs requests from the system when it creates pipes for
communications with subprocesses.  The default value is zero, which
lets the OS choose the size.  Any valid positive value will request a
buffer of that size in bytes.  This can be used to tailor
communications with subprocesses to programs that exhibit unusual
behavior with respect to buffering pipe I/O.

810
@ifnottex
811 812 813 814 815 816 817
@vindex w32-pipe-read-delay
  If you need to invoke MS-DOS programs as Emacs subprocesses, you may
see low rate of reading data from such programs.  Setting the variable
@code{w32-pipe-read-delay} to a non-zero value may improve throughput
in these cases; we suggest the value of 50 for such situations.  The
default is zero.

818 819 820 821 822
@findex w32-shell-execute
  The function @code{w32-shell-execute} can be useful for writing
customized commands that run MS-Windows applications registered to
handle a certain standard Windows operation for a specific type of
document or file.  This function is a wrapper around the Windows
823
@code{ShellExecute} API@.  See the MS-Windows API documentation for
824 825 826
more details.
@end ifnottex

827 828 829 830 831 832
@node Windows Printing
@section Printing and MS-Windows

  Printing commands, such as @code{lpr-buffer} (@pxref{Printing}) and
@code{ps-print-buffer} (@pxref{PostScript}) work in MS-DOS and
MS-Windows by sending the output to one of the printer ports, if a
Paul Eggert's avatar
Paul Eggert committed
833
POSIX-style @code{lpr} program is unavailable.  The same Emacs
834 835 836
variables control printing on all systems, but in some cases they have
different default values on MS-DOS and MS-Windows.

837 838 839
  Emacs on MS Windows attempts to determine your default printer
automatically (using the function @code{default-printer-name}).
But in some rare cases this can fail, or you may wish to use a different
840 841 842
printer from within Emacs.  The rest of this section explains how to
tell Emacs which printer to use.

843
@vindex printer-name@r{, (MS-DOS/MS-Windows)}
844 845 846
  If you want to use your local printer, then set the Lisp variable
@code{lpr-command} to @code{""} (its default value on Windows) and
@code{printer-name} to the name of the printer port---for example,
Glenn Morris's avatar
Glenn Morris committed
847
@code{"PRN"}, the usual local printer port, or @code{"LPT2"}, or
848 849 850 851 852 853 854 855 856 857 858 859 860 861
@code{"COM1"} for a serial printer.  You can also set
@code{printer-name} to a file name, in which case ``printed'' output
is actually appended to that file.  If you set @code{printer-name} to
@code{"NUL"}, printed output is silently discarded (sent to the system
null device).

  You can also use a printer shared by another machine by setting
@code{printer-name} to the UNC share name for that printer---for
example, @code{"//joes_pc/hp4si"}.  (It doesn't matter whether you use
forward slashes or backslashes here.)  To find out the names of shared
printers, run the command @samp{net view} from the command prompt to
obtain a list of servers, and @samp{net view @var{server-name}} to see
the names of printers (and directories) shared by that server.
Alternatively, click the @samp{Network Neighborhood} icon on your
Glenn Morris's avatar
Glenn Morris committed
862
desktop, and look for machines that share their printers via the
863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891
network.

@cindex @samp{net use}, and printing on MS-Windows
@cindex networked printers (MS-Windows)
  If the printer doesn't appear in the output of @samp{net view}, or
if setting @code{printer-name} to the UNC share name doesn't produce a
hardcopy on that printer, you can use the @samp{net use} command to
connect a local print port such as @code{"LPT2"} to the networked
printer.  For example, typing @kbd{net use LPT2: \\joes_pc\hp4si}@footnote{
Note that the @samp{net use} command requires the UNC share name to be
typed with the Windows-style backslashes, while the value of
@code{printer-name} can be set with either forward- or backslashes.}
causes Windows to @dfn{capture} the @code{LPT2} port and redirect the
printed material to the printer connected to the machine @code{joes_pc}.
After this command, setting @code{printer-name} to @code{"LPT2"}
should produce the hardcopy on the networked printer.

  With some varieties of Windows network software, you can instruct
Windows to capture a specific printer port such as @code{"LPT2"}, and
redirect it to a networked printer via the @w{@code{Control
Panel->Printers}} applet instead of @samp{net use}.

  If you set @code{printer-name} to a file name, it's best to use an
absolute file name.  Emacs changes the working directory according to
the default directory of the current buffer, so if the file name in
@code{printer-name} is relative, you will end up with several such
files, each one in the directory of the buffer from which the printing
was done.

892 893 894
  If the value of @code{printer-name} is correct, but printing does
not produce the hardcopy on your printer, it is possible that your
printer does not support printing plain text (some cheap printers omit
895 896
this functionality).  In that case, try the PostScript print commands,
described below.
897

898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920
@findex print-buffer @r{(MS-DOS)}
@findex print-region @r{(MS-DOS)}
@vindex lpr-headers-switches @r{(MS-DOS)}
  The commands @code{print-buffer} and @code{print-region} call the
@code{pr} program, or use special switches to the @code{lpr} program, to
produce headers on each printed page.  MS-DOS and MS-Windows don't
normally have these programs, so by default, the variable
@code{lpr-headers-switches} is set so that the requests to print page
headers are silently ignored.  Thus, @code{print-buffer} and
@code{print-region} produce the same output as @code{lpr-buffer} and
@code{lpr-region}, respectively.  If you do have a suitable @code{pr}
program (for example, from GNU Coreutils), set
@code{lpr-headers-switches} to @code{nil}; Emacs will then call
@code{pr} to produce the page headers, and print the resulting output as
specified by @code{printer-name}.

@vindex print-region-function @r{(MS-DOS)}
@cindex lpr usage under MS-DOS
@vindex lpr-command @r{(MS-DOS)}
@vindex lpr-switches @r{(MS-DOS)}
  Finally, if you do have an @code{lpr} work-alike, you can set the
variable @code{lpr-command} to @code{"lpr"}.  Then Emacs will use
@code{lpr} for printing, as on other systems.  (If the name of the
Glenn Morris's avatar
Glenn Morris committed
921 922
program isn't @code{lpr}, set @code{lpr-command} to the appropriate value.)
The variable @code{lpr-switches} has its standard meaning
923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942
when @code{lpr-command} is not @code{""}.  If the variable
@code{printer-name} has a string value, it is used as the value for the
@code{-P} option to @code{lpr}, as on Unix.

@findex ps-print-buffer @r{(MS-DOS)}
@findex ps-spool-buffer @r{(MS-DOS)}
@vindex ps-printer-name @r{(MS-DOS)}
@vindex ps-lpr-command @r{(MS-DOS)}
@vindex ps-lpr-switches @r{(MS-DOS)}
  A parallel set of variables, @code{ps-lpr-command},
@code{ps-lpr-switches}, and @code{ps-printer-name} (@pxref{PostScript
Variables}), defines how PostScript files should be printed.  These
variables are used in the same way as the corresponding variables
described above for non-PostScript printing.  Thus, the value of
@code{ps-printer-name} is used as the name of the device (or file) to
which PostScript output is sent, just as @code{printer-name} is used
for non-PostScript printing.  (There are two distinct sets of
variables in case you have two printers attached to two different
ports, and only one of them is a PostScript printer.)

943
@cindex Ghostscript, use for PostScript printing
944 945
  The default value of the variable @code{ps-lpr-command} is @code{""},
which causes PostScript output to be sent to the printer port specified
Glenn Morris's avatar
Glenn Morris committed
946
by @code{ps-printer-name}; but @code{ps-lpr-command} can also be set to
947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964
the name of a program which will accept PostScript files.  Thus, if you
have a non-PostScript printer, you can set this variable to the name of
a PostScript interpreter program (such as Ghostscript).  Any switches
that need to be passed to the interpreter program are specified using
@code{ps-lpr-switches}.  (If the value of @code{ps-printer-name} is a
string, it will be added to the list of switches as the value for the
@code{-P} option.  This is probably only useful if you are using
@code{lpr}, so when using an interpreter typically you would set
@code{ps-printer-name} to something other than a string so it is
ignored.)

  For example, to use Ghostscript for printing on the system's default
printer, put this in your @file{.emacs} file:

@example
(setq ps-printer-name t)
(setq ps-lpr-command "D:/gs6.01/bin/gswin32c.exe")
(setq ps-lpr-switches '("-q" "-dNOPAUSE" "-dBATCH"
965 966
                        "-sDEVICE=mswinpr2"
                        "-sPAPERSIZE=a4"))
967 968 969 970 971 972
@end example

@noindent
(This assumes that Ghostscript is installed in the
@file{D:/gs6.01} directory.)

973 974 975 976 977
@node Windows Fonts
@section Specifying Fonts on MS-Windows
@cindex font specification (MS Windows)

  Starting with Emacs 23, fonts are specified by their name, size
978 979
and optional properties.  The format for specifying fonts comes from the
fontconfig library used in modern Free desktops:
980 981 982 983 984 985 986

@example
  [Family[-PointSize]][:Option1=Value1[:Option2=Value2[...]]]
@end example

  The old XLFD based format is also supported for backwards compatibility.

987
@cindex font backend selection (MS-Windows)
988 989 990 991 992 993 994 995 996 997 998
  Emacs on MS-Windows supports a number of font backends.  Currently,
the @code{gdi}, @code{uniscribe}, and @code{harfbuzz} backends are
available.  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.  The
@code{harfbuzz} font backend is available if Emacs was built with
HarfBuzz support, and if the HarfBuzz DLL is installed on your system;
like @code{uniscribe}, this backend supports only TrueType and
OpenType fonts.  Some languages requiring complex layout can only be
properly supported by the Uniscribe or HarfBuzz backends.  By default,
999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015
two backends are enabled for each frame: @code{gdi} and either
@code{harfbuzz} or @code{uniscribe}, depending on which one is
available (if both are available, only @code{harfbuzz} is enabled by
default).  The @code{harfbuzz} and @code{uniscribe} backends take
priority over @code{gdi} when Emacs looks for a suitable font.  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}).
Similarly, to use the Uniscribe backend even if HarfBuzz is available,
use @kbd{-xrm Emacs.fontBackend:uniscribe} on the command line that
invokes Emacs.  You can also request all the 3 backends via the
@code{font-backend} frame parameter, but be warned that in that case
font searches for characters for which no fonts are available on the
system will take longer.
1016 1017 1018 1019 1020

@cindex font properties (MS Windows)
@noindent
Optional properties common to all font backends on MS-Windows are:

1021 1022
@table @code

1023
@vindex font-weight-table @r{(MS-Windows)}
1024 1025 1026 1027
@item weight
Specifies the weight of the font.  Special values @code{light},
@code{medium}, @code{demibold}, @code{bold}, and @code{black} can be specified
without @code{weight=} (e.g., @kbd{Courier New-12:bold}).  Otherwise,
1028
the weight should be a numeric value between 100 and 900, or one of the
1029
named weights in @code{font-weight-table}.  If unspecified, a regular font
1030 1031 1032
is assumed.

@vindex font-slant-table @r{(MS-Windows)}
1033 1034
@item slant
Specifies whether the font is italic.  Special values
1035
@code{roman}, @code{italic} and @code{oblique} can be specified
1036 1037
without @code{slant=} (e.g., @kbd{Courier New-12:italic}).
Otherwise, the slant should be a numeric value, or one of the named
1038
slants in @code{font-slant-table}.  On Windows, any slant above 150 is
1039
treated as italics, and anything below as roman.
1040

1041 1042
@item family
Specifies the font family, but normally this will be specified
1043 1044
at the start of the font name.

1045 1046
@item pixelsize
Specifies the font size in pixels.  This can be used instead
1047 1048
of the point size specified after the family name.

1049 1050
@item adstyle
Specifies additional style information for the font.
1051
On MS-Windows, the values @code{mono}, @code{sans}, @code{serif},
1052
@code{script} and @code{decorative} are recognized.  These are most useful
1053 1054 1055
as a fallback with the font family left unspecified.

@vindex w32-charset-info-alist
1056 1057
@item registry
Specifies the character set registry that the font is
Juanma Barranquero's avatar
Juanma Barranquero committed
1058
expected to cover.  Most TrueType and OpenType fonts will be Unicode fonts
1059 1060 1061 1062
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.

1063
@item spacing
1064
Specifies how the font is spaced.  The @code{p} spacing specifies
1065 1066
a proportional font, and @code{m} or @code{c} specify a monospaced font.

1067 1068
@item foundry
Not used on Windows, but for informational purposes and to
1069 1070 1071
prevent problems with code that expects it to be set, is set internally to
@code{raster} for bitmapped fonts, @code{outline} for scalable fonts,
or @code{unknown} if the type cannot be determined as one of those.
1072
@end table
1073 1074

@cindex font properties (MS Windows gdi backend)
1075 1076 1077
Options specific to @code{GDI} fonts:

@table @code
1078 1079

@cindex font scripts (MS Windows)
Juanma Barranquero's avatar
Juanma Barranquero committed
1080
@cindex font Unicode subranges (MS Windows)
1081
@item script
Juanma Barranquero's avatar
Juanma Barranquero committed
1082
Specifies a Unicode subrange the font should support.
1083 1084 1085

The following scripts are recognized on Windows: @code{latin}, @code{greek},
@code{coptic}, @code{cyrillic}, @code{armenian}, @code{hebrew}, @code{arabic},
1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096
@code{syriac}, @code{nko}, @code{thaana}, @code{devanagari}, @code{bengali},
@code{gurmukhi}, @code{gujarati}, @code{oriya}, @code{tamil}, @code{telugu},
@code{kannada}, @code{malayam}, @code{sinhala}, @code{thai}, @code{lao},
@code{tibetan}, @code{myanmar}, @code{georgian}, @code{hangul},
@code{ethiopic}, @code{cherokee}, @code{canadian-aboriginal}, @code{ogham},
@code{runic}, @code{khmer}, @code{mongolian}, @code{symbol}, @code{braille},
@code{han}, @code{ideographic-description}, @code{cjk-misc}, @code{kana},
@code{bopomofo}, @code{kanbun}, @code{yi}, @code{byzantine-musical-symbol},
@code{musical-symbol}, and @code{mathematical}.

@cindex font antialiasing (MS Windows)
1097
@item antialias
1098 1099 1100 1101 1102 1103
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.
1104
@end table
1105

Eli Zaretskii's avatar
Eli Zaretskii committed
1106 1107 1108
@node Windows Misc
@section Miscellaneous Windows-specific features

1109 1110
  This section describes Windows-specific features that don't fit
anywhere else.
Eli Zaretskii's avatar
Eli Zaretskii committed
1111

1112 1113 1114
@vindex w32-use-visible-system-caret
@cindex screen reader software, MS-Windows
  The variable @code{w32-use-visible-system-caret} is a flag that
1115 1116 1117
determines whether to make the system caret visible.  The default when
no screen reader software is in use is @code{nil}, which means Emacs
draws its own cursor to indicate the position of point.  A
Glenn Morris's avatar
Glenn Morris committed
1118
non-@code{nil} value means Emacs will indicate point location with the
1119 1120 1121 1122
system caret; this facilitates use of screen reader software, and is
the default when such software is detected when running Emacs.
When this variable is non-@code{nil}, other variables affecting the
cursor display have no effect.
1123 1124 1125 1126 1127 1128

@iftex
@inforef{Windows Misc, , emacs}, for information about additional
Windows-specific variables in this category.
@end iftex

1129
@ifnottex
Eli Zaretskii's avatar
Eli Zaretskii committed
1130 1131 1132 1133 1134 1135
@vindex w32-grab-focus-on-raise
@cindex frame focus policy, MS-Windows
  The variable @code{w32-grab-focus-on-raise}, if set to a
non-@code{nil} value causes a frame to grab focus when it is raised.
The default is @code{t}, which fits well with the Windows default
click-to-focus policy.
1136
@end ifnottex
Eli Zaretskii's avatar
Eli Zaretskii committed
1137

1138
@ifnottex
1139
@include msdos-xtra.texi
1140
@end ifnottex