0001: @c This is part of the Emacs manual.
0002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software
0003: @c Foundation, Inc.
0004: @c See file emacs.texi for copying conditions.
0005: @node Microsoft Windows
0006: @appendix Emacs and Microsoft Windows/MS-DOS
0007: @cindex Microsoft Windows
0008: @cindex MS-Windows, Emacs peculiarities
0009: 
0010:   This section describes peculiarities of using Emacs on Microsoft
0011: Windows.  Some of these peculiarities are also relevant to Microsoft's
0012: older MS-DOS operating system.
0013: However, Emacs features that are relevant @emph{only} to MS-DOS are
0014: described in a separate
0015: @iftex
0016: manual (@pxref{MS-DOS,,, emacs-xtra, Specialized Emacs Features}).
0017: @end iftex
0018: @ifnottex
0019: section (@pxref{MS-DOS}).
0020: @end ifnottex
0021: 
0022:   MS-Windows is a non-free operating system; that means it denies its
0023: users the freedom that every computer user deserves.  That is an
0024: injustice.  For your freedom's sake, we urge you to switch to a free
0025: operating system.
0026: 
0027:   We support GNU Emacs on proprietary operating systems because we
0028: hope this taste of freedom will inspire users to escape from them.
0029: 
0030:   The behavior of Emacs on MS-Windows is reasonably similar to what is
0031: documented in the rest of the manual, including support for long file
0032: names, multiple frames, scroll bars, mouse menus, and subprocesses.
0033: However, a few special considerations apply, and they are described
0034: here.
0035: 
0036: @menu
0037: * Windows Startup::     How to start Emacs on Windows.
0038: * Text and Binary::     Text files use CRLF to terminate lines.
0039: * Windows Files::       File-name conventions on Windows.
0040: * ls in Lisp::          Emulation of @code{ls} for Dired.
0041: * Windows HOME::        Where Emacs looks for your @file{.emacs} and
0042:                           where it starts up.
0043: * Windows Keyboard::    Windows-specific keyboard features.
0044: * Windows Mouse::       Windows-specific mouse features.
0045: * Windows Processes::   Running subprocesses on Windows.
0046: * Windows Printing::    How to specify the printer on MS-Windows.
0047: * Windows Fonts::       Specifying fonts on MS-Windows.
0048: * Windows Misc::        Miscellaneous Windows features.
0049: @ifnottex
0050: * MS-DOS::              Using Emacs on MS-DOS.
0051: @end ifnottex
0052: @end menu
0053: 
0054: @node Windows Startup
0055: @section How to Start Emacs on MS-Windows
0056: @cindex starting Emacs on MS-Windows
0057: 
0058:   There are several ways of starting Emacs on MS-Windows:
0059: 
0060: @enumerate
0061: @item
0062: @pindex runemacs.exe
0063: @cindex desktop shortcut, MS-Windows
0064: @cindex start directory, MS-Windows
0065: @cindex directory where Emacs starts on MS-Windows
0066: From the desktop shortcut icon: either double-click the left mouse
0067: button on the icon, or click once, then press @key{RET}.  The desktop
0068: shortcut should specify as its ``Target'' (in the ``Properties'' of
0069: the shortcut) the full absolute file name of @file{runemacs.exe},
0070: @emph{not} of @file{emacs.exe}.  This is because @file{runemacs.exe}
0071: hides the console window that would have been created if the target of
0072: the shortcut were @file{emacs.exe} (which is a console program, as far
0073: as Windows is concerned).  If you use this method, Emacs starts in the
0074: directory specified by the shortcut.  To control where that is,
0075: right-click on the shortcut, select ``Properties'', and in the
0076: ``Shortcut'' tab modify the ``Start in'' field to your liking.
0077: 
0078: @item
0079: @cindex pinning Emacs to Windows task bar
0080: From a task-bar shortcut icon, by clicking once the left mouse button.
0081: Windows versions since Vista allow you to create such shortcuts by
0082: @dfn{pinning} the icon of a running program that appears in the task
0083: bar.  You can do that with Emacs, but afterwards you will have to
0084: change the properties of the pinned shortcut to run
0085: @file{runemacs.exe}, @emph{not} of @file{emacs.exe}.  You can also pin
0086: Emacs to the task bar by clicking the right mouse button on its icon
0087: in the Start menu, then selecting @samp{Pin to taskbar}.  Once again,
0088: be sure to specify @file{runemacs.exe} as the program to run.  You can
0089: control where Emacs starts by setting the ``Start in'' field of the
0090: shortcut's Properties.
0091: 
0092: @item
0093: From the Command Prompt window, by typing @kbd{emacs @key{RET}} at the
0094: prompt.  The Command Prompt window where you did that will not be
0095: available for invoking other commands until Emacs exits.  In this
0096: case, Emacs will start in the current directory of the Windows shell.
0097: 
0098: @item
0099: From the Command Prompt window, by typing @kbd{runemacs @key{RET}} at
0100: the prompt.  The Command Prompt window where you did that will be
0101: immediately available for invoking other commands.  In this case,
0102: Emacs will start in the current directory of the Windows shell.
0103: 
0104: @item
0105: From the Windows @code{Run} dialog (normally reached by clicking the
0106: @code{Start} button).  Typing @kbd{runemacs @key{RET}} into the dialog
0107: will start Emacs in the parent directory of the Windows equivalent of
0108: your user's @code{HOME} directory, see @ref{Windows HOME}.
0109: 
0110: @item
0111: @cindex invoking Emacs from Windows Explorer
0112: @pindex emacsclient.exe
0113: @pindex emacsclientw.exe
0114: Via @file{emacsclient.exe} or @file{emacsclientw.exe}, which allow you
0115: to invoke Emacs from other programs, and to reuse a running Emacs
0116: process for serving editing jobs required by other programs.
0117: @xref{Emacs Server}.  The difference between @file{emacsclient.exe}
0118: and @file{emacsclientw.exe} is that the former is a console program,
0119: while the latter is a Windows GUI program.  Both programs wait for
0120: Emacs to signal that the editing job is finished, before they exit and
0121: return control to the program that invoked them.  Which one of them to
0122: use in each case depends on the expectations of the program that needs
0123: editing services.  If that program is itself a console (text-mode)
0124: program, you should use @file{emacsclient.exe}, so that any of its
0125: messages and prompts appear in the same command window as those of the
0126: invoking program.  By contrast, if the invoking program is a GUI
0127: program, you will be better off using @file{emacsclientw.exe}, because
0128: @file{emacsclient.exe} will pop up a command window if it is invoked
0129: from a GUI program.  A notable situation where you would want
0130: @file{emacsclientw.exe} is when you right-click on a file in the
0131: Windows Explorer and select ``Open With'' from the pop-up menu.  Use
0132: the @samp{--alternate-editor=} or @samp{-a} options if Emacs might not
0133: be running (or not running as a server) when @command{emacsclient} is
0134: invoked---that will always give you an editor.  When invoked via
0135: @command{emacsclient}, Emacs will start in the current directory of
0136: the program that invoked @command{emacsclient}.
0137: @end enumerate
0138: 
0139: @cindex @command{emacsclient}, on MS-Windows
0140: Note that, due to limitations of MS-Windows, Emacs cannot have both
0141: GUI and text-mode frames in the same session.  It also cannot open
0142: text-mode frames on more than a single @dfn{Command Prompt} window,
0143: because each Windows program can have only one console at any given
0144: time.  For these reasons, if you invoke @command{emacsclient} with the
0145: @option{-c} option, and the Emacs server runs in a text-mode session,
0146: Emacs will always create a new text-mode frame in the same
0147: @dfn{Command Prompt} window where it was started; a GUI frame will be
0148: created only if the server runs in a GUI session.  Similarly, if you
0149: invoke @command{emacsclient} with the @option{-t} option, Emacs will
0150: create a GUI frame if the server runs in a GUI session, or a text-mode
0151: frame when the session runs in text mode in a @dfn{Command Prompt}
0152: window.  @xref{emacsclient Options}.
0153: 
0154: @node Text and Binary
0155: @section Text Files and Binary Files
0156: @cindex text and binary files on MS-DOS/MS-Windows
0157: 
0158:   GNU Emacs uses newline characters to separate text lines.  This is the
0159: convention used on GNU, Unix, and other POSIX-compliant systems.
0160: 
0161: @cindex end-of-line conversion on MS-DOS/MS-Windows
0162:   By contrast, MS-DOS and MS-Windows normally use carriage return
0163: followed by linefeed, a two-character sequence, to separate text
0164: lines.  (Linefeed is the same character as newline.)  Therefore,
0165: convenient editing of typical files with Emacs requires conversion of
0166: these end-of-line (EOL) sequences.  And that is what Emacs normally
0167: does: it converts carriage return followed by linefeed into newline
0168: when reading files, and converts newline into carriage return followed
0169: by linefeed when writing files.  The same mechanism that handles
0170: conversion of international character codes does this conversion also
0171: (@pxref{Coding Systems}).
0172: 
0173: @cindex cursor location, on MS-DOS
0174: @cindex point location, on MS-DOS
0175:   One consequence of this special format-conversion of most files is
0176: that character positions as reported by Emacs (@pxref{Position Info}) do
0177: not agree with the file size information known to the operating system.
0178: 
0179:   In addition, if Emacs recognizes from a file's contents that it uses
0180: newline rather than carriage return followed by linefeed as its line
0181: separator, it does not perform EOL conversion when reading or writing
0182: that file.  Thus, you can read and edit files from GNU and Unix
0183: systems on MS-DOS with no special effort, and they will retain their
0184: Unix-style end-of-line convention after you edit them.
0185: 
0186:   The mode line indicates whether end-of-line translation was used for
0187: the current buffer.  If MS-DOS end-of-line translation is in use for the
0188: buffer, the MS-Windows build of Emacs displays a backslash @samp{\} after
0189: the coding system mnemonic near the beginning of the mode line
0190: (@pxref{Mode Line}).  If no EOL translation was performed, the string
0191: @samp{(Unix)} is displayed instead of the backslash, to alert you that the
0192: file's EOL format is not the usual carriage return followed by linefeed.
0193: 
0194: @cindex DOS-to-Unix conversion of files
0195:   To visit a file and specify whether it uses DOS-style or Unix-style
0196: end-of-line, specify a coding system (@pxref{Text Coding}).  For
0197: example, @kbd{C-x @key{RET} c unix @key{RET} C-x C-f foobar.txt}
0198: visits the file @file{foobar.txt} without converting the EOLs; if some
0199: line ends with a carriage return followed by linefeed pair, Emacs will
0200: display @samp{^M} at the end of that line.  Similarly, you can direct
0201: Emacs to save a buffer in a specified EOL format with the @kbd{C-x
0202: @key{RET} f} command.  For example, to save a buffer with Unix EOL
0203: format, type @kbd{C-x @key{RET} f unix @key{RET} C-x C-s}.  If you
0204: visit a file with DOS EOL conversion, then save it with Unix EOL
0205: format, that effectively converts the file to Unix EOL style, like the
0206: @code{dos2unix} program.
0207: 
0208: @cindex untranslated file system
0209: @findex add-untranslated-filesystem
0210:   When you use NFS, Samba, or some other similar method to access file
0211: systems that reside on computers using GNU or Unix systems, Emacs
0212: should not perform end-of-line translation on any files in these file
0213: systems---not even when you create a new file.  To request this,
0214: designate these file systems as @dfn{untranslated} file systems by
0215: calling the function @code{add-untranslated-filesystem}.  It takes one
0216: argument: the file system name, including a drive letter and
0217: optionally a directory.  For example,
0218: 
0219: @example
0220: (add-untranslated-filesystem "Z:")
0221: @end example
0222: 
0223: @noindent
0224: designates drive Z as an untranslated file system, and
0225: 
0226: @example
0227: (add-untranslated-filesystem "Z:\\foo")
0228: @end example
0229: 
0230: @noindent
0231: designates directory @file{\foo} on drive Z as an untranslated file
0232: system.
0233: 
0234:   Most often you would use @code{add-untranslated-filesystem} in your
0235: @file{.emacs} or @file{init.el} init file, or in @file{site-start.el}
0236: so that all the users at your site get the benefit of it.
0237: 
0238: @findex remove-untranslated-filesystem
0239:   To countermand the effect of @code{add-untranslated-filesystem}, use
0240: the function @code{remove-untranslated-filesystem}.  This function takes
0241: one argument, which should be a string just like the one that was used
0242: previously with @code{add-untranslated-filesystem}.
0243: 
0244:   Designating a file system as untranslated does not affect character
0245: set conversion, only end-of-line conversion.  Essentially, it directs
0246: Emacs to default to creating new files with the Unix-style convention
0247: of using newline at the end of a line.  @xref{Coding Systems}.
0248: 
0249: @node Windows Files
0250: @section File Names on MS-Windows
0251: @cindex file names on MS-Windows
0252: 
0253:   MS-Windows and MS-DOS normally use a backslash, @samp{\}, to
0254: separate name units within a file name, instead of the slash used on
0255: other systems.  Emacs on MS-DOS/MS-Windows permits use of either slash or
0256: backslash, and also knows about drive letters in file names.
0257: 
0258: @cindex file-name completion, on MS-Windows
0259:   On MS-DOS/MS-Windows, file names are case-insensitive, so Emacs by
0260: default ignores letter-case in file names during completion.  To this
0261: end, the default value of @code{read-file-name-completion-ignore-case}
0262: is non-@code{nil} on MS-DOS/MS-Windows.  @xref{Completion Options}.
0263: 
0264: @vindex w32-get-true-file-attributes
0265:   The variable @code{w32-get-true-file-attributes} controls whether
0266: Emacs should issue additional system calls to determine more
0267: accurately file attributes in primitives like @code{file-attributes}
0268: and @code{directory-files-and-attributes}.  These additional calls are
0269: needed to report correct file ownership, link counts and file types
0270: for special files such as pipes.  Without these system calls, file
0271: ownership will be attributed to the current user, link counts will be
0272: always reported as 1, and special files will be reported as regular
0273: files.
0274: 
0275:   If the value of this variable is @code{local} (the default), Emacs
0276: will issue these additional system calls only for files on local fixed
0277: drives.  Any other non-@code{nil} value means do this even for
0278: removable and remote volumes, where this could potentially slow down
0279: Dired and other related features.  The value of @code{nil} means never
0280: issue those system calls.  Non-@code{nil} values are more useful on
0281: NTFS volumes, which support hard links and file security, than on FAT,
0282: FAT32, and exFAT volumes.
0283: 
0284: @cindex file names, invalid characters on MS-Windows
0285:   Unlike Unix, MS-Windows file systems restrict the set of characters
0286: that can be used in a file name.  The following characters are not
0287: allowed:
0288: 
0289: @itemize @bullet
0290: @item
0291: Shell redirection symbols @samp{<}, @samp{>}, and @samp{|}.
0292: 
0293: @item
0294: Colon @samp{:} (except after the drive letter).
0295: 
0296: @item
0297: Forward slash @samp{/} and backslash @samp{\} (except as directory
0298: separators).
0299: 
0300: @item
0301: Wildcard characters @samp{*} and @samp{?}.
0302: 
0303: @item
0304: Control characters whose codepoints are 1 through 31 decimal.  In
0305: particular, newlines in file names are not allowed.
0306: 
0307: @item
0308: The null character, whose codepoint is zero (this limitation exists on
0309: Unix filesystems as well).
0310: @end itemize
0311: 
0312: @noindent
0313: In addition, referencing any file whose name matches a DOS character
0314: device, such as @file{NUL} or @file{LPT1} or @file{PRN} or @file{CON},
0315: with or without any file-name extension, will always resolve to those
0316: character devices, in any directory.  Therefore, only use such file
0317: names when you want to use the corresponding character device.
0318: 
0319: @node ls in Lisp
0320: @section Emulation of @code{ls} on MS-Windows
0321: @cindex Dired, and MS-Windows/MS-DOS
0322: @cindex @code{ls} emulation
0323: 
0324:   Dired normally uses the external program @code{ls}
0325: to produce the directory listing displayed in Dired
0326: buffers (@pxref{Dired}).  However, MS-Windows and MS-DOS systems don't
0327: come with such a program, although several ports of @sc{gnu} @code{ls}
0328: are available.  Therefore, Emacs on those systems @emph{emulates}
0329: @code{ls} in Lisp, by using the @file{ls-lisp.el} package.  While
0330: @file{ls-lisp.el} provides a reasonably full emulation of @code{ls},
0331: there are some options and features peculiar to that emulation;
0332: @iftex
0333: for more details, see the documentation of the variables whose names
0334: begin with @code{ls-lisp}.
0335: @end iftex
0336: @ifnottex
0337: they are described in this section.
0338: 
0339:   The @code{ls} emulation supports many of the @code{ls} switches, but
0340: it doesn't support all of them.  Here's the list of the switches it
0341: does support: @option{-A}, @option{-a}, @option{-B}, @option{-C},
0342: @option{-c}, @option{-G}, @option{-g}, @option{-h}, @option{-i}, @option{-n},
0343: @option{-R}, @option{-r}, @option{-S}, @option{-s}, @option{-t}, @option{-U},
0344: @option{-u}, @option{-v}, and @option{-X}.  The @option{-F} switch is
0345: partially supported (it appends the character that classifies the
0346: file, but does not prevent symlink following).
0347: 
0348: @vindex ls-lisp-use-insert-directory-program
0349:   On MS-Windows and MS-DOS, @file{ls-lisp.el} is preloaded when Emacs
0350: is built, so the Lisp emulation of @code{ls} is always used on those
0351: platforms.  If you have a ported @code{ls}, setting
0352: @code{ls-lisp-use-insert-directory-program} to a non-@code{nil} value
0353: will revert to using an external program named by the variable
0354: @code{insert-directory-program}.
0355: 
0356: @cindex Dired sorting order, on MS-Windows/MS-DOS
0357:   The order in which @file{ls-lisp.el} sorts files depends on several
0358: customizable options described below.
0359: 
0360: @vindex ls-lisp-use-string-collate
0361:   The default sorting order follows locale-specific rules derived from
0362: your system locale.  You can make the order locale-independent by
0363: customizing @code{ls-lisp-use-string-collate} to a @code{nil} value.
0364: 
0365: @cindex Unicode Collation Algorithm (UCA), and @file{ls-lisp.el}
0366: @vindex ls-lisp-UCA-like-collation
0367:   On GNU and Unix systems, when the locale's encoding is UTF-8, the
0368: collation order follows the Unicode Collation Algorithm
0369: (@acronym{UCA}).  To have a similar effect on MS-Windows, the variable
0370: @code{ls-lisp-UCA-like-collation} should have a non-@code{nil} value
0371: (this is the default).  The resulting sorting order ignores
0372: punctuation, symbol characters, and whitespace characters, so
0373: @file{.foobar}, @file{foobar} and @w{@file{foo bar}} will appear
0374: together rather than far apart.
0375: 
0376: @vindex ls-lisp-ignore-case
0377:   By default, @file{ls-lisp.el} uses a case-sensitive sort order for
0378: the directory listing it produces; this is so the listing looks the
0379: same as on other platforms.  If you wish that the files be sorted in
0380: case-insensitive order, set the variable @code{ls-lisp-ignore-case} to
0381: a non-@code{nil} value.
0382: 
0383: @vindex ls-lisp-dirs-first
0384:   By default, files and subdirectories are sorted together, to emulate
0385: the behavior of @code{ls}.  However, native MS-Windows/MS-DOS file
0386: managers list the directories before the files; if you want that
0387: behavior, customize the option @code{ls-lisp-dirs-first} to a
0388: non-@code{nil} value.
0389: 
0390: @vindex ls-lisp-verbosity
0391:   The variable @code{ls-lisp-verbosity} controls the file attributes
0392: that @file{ls-lisp.el} displays.  The value should be a list that
0393: contains one or more of the symbols @code{links}, @code{uid}, and
0394: @code{gid}.  @code{links} means display the count of different file
0395: names that are associated with (a.k.a.@: @dfn{links to}) the file's
0396: data; this is only useful on NTFS volumes.  @code{uid} means display
0397: the numerical identifier of the user who owns the file.  @code{gid}
0398: means display the numerical identifier of the file owner's group.  The
0399: default value is @code{(links uid gid)} i.e., all the 3 optional
0400: attributes are displayed.
0401: 
0402: @vindex ls-lisp-emulation
0403:   The variable @code{ls-lisp-emulation} controls the flavor of the
0404: @code{ls} emulation by setting the defaults for the 3 options
0405: described above: @code{ls-lisp-ignore-case},
0406: @code{ls-lisp-dirs-first}, and @code{ls-lisp-verbosity}.  The value of
0407: this option can be one of the following symbols:
0408: 
0409: @table @code
0410: @item GNU
0411: @itemx nil
0412: Emulate @sc{gnu} systems; this is the default.  This sets
0413: @code{ls-lisp-ignore-case} and @code{ls-lisp-dirs-first} to
0414: @code{nil}, and @code{ls-lisp-verbosity} to @code{(links uid gid)}.
0415: @item UNIX
0416: Emulate Unix systems.  Like @code{GNU}, but sets
0417: @code{ls-lisp-verbosity} to @code{(links uid)}.
0418: @item MacOS
0419: Emulate macOS@.  Sets @code{ls-lisp-ignore-case} to @code{t}, and
0420: @code{ls-lisp-dirs-first} and @code{ls-lisp-verbosity} to @code{nil}.
0421: @item MS-Windows
0422: Emulate MS-Windows.  Sets @code{ls-lisp-ignore-case} and
0423: @code{ls-lisp-dirs-first} to @code{t}, and @code{ls-lisp-verbosity} to
0424: @code{nil} on Windows 9X and to @code{t} on modern versions of
0425: Windows.  Note that the default emulation is @emph{not}
0426: @code{MS-Windows}, even on Windows, since many users of Emacs on those
0427: platforms prefer the @sc{gnu} defaults.
0428: @end table
0429: 
0430: @noindent
0431: Any other value of @code{ls-lisp-emulation} means the same as @code{GNU}.
0432: Customizing this option calls the function @code{ls-lisp-set-options} to
0433: update the 3 dependent options as needed.  If you change the value of
0434: this variable without using customize after @file{ls-lisp.el} is loaded
0435: (note that it is preloaded on MS-Windows and MS-DOS), you can call that
0436: function manually for the same result.
0437: 
0438: @vindex ls-lisp-support-shell-wildcards
0439:   The variable @code{ls-lisp-support-shell-wildcards} controls how
0440: file-name patterns are supported: if it is non-@code{nil} (the
0441: default), they are treated as shell-style wildcards; otherwise they
0442: are treated as Emacs regular expressions.
0443: 
0444: @vindex ls-lisp-format-time-list
0445:   The variable @code{ls-lisp-format-time-list} defines how to format
0446: the date and time of files.  @emph{The value of this variable is
0447: ignored}, unless Emacs cannot determine the current locale.  (However,
0448: if the value of @code{ls-lisp-use-localized-time-format} is
0449: non-@code{nil}, Emacs obeys @code{ls-lisp-format-time-list} even if
0450: the current locale is available; see below.)
0451: 
0452: The value of @code{ls-lisp-format-time-list} is a list of 2 strings.
0453: The first string is used if the file was modified within the current
0454: year, while the second string is used for older files.  In each of
0455: these two strings you can use @samp{%}-sequences to substitute parts
0456: of the time.  For example:
0457: @lisp
0458: ("%b %e %H:%M" "%b %e  %Y")
0459: @end lisp
0460: 
0461: @noindent
0462: Note that the strings substituted for these @samp{%}-sequences depend
0463: on the current locale.  @xref{Time Parsing,,, elisp, The Emacs Lisp
0464: Reference Manual}, for more about format time specs.
0465: 
0466: @vindex ls-lisp-use-localized-time-format
0467:   Normally, Emacs formats the file time stamps in either traditional
0468: or ISO-style time format.  However, if the value of the variable
0469: @code{ls-lisp-use-localized-time-format} is non-@code{nil}, Emacs
0470: formats file time stamps according to what
0471: @code{ls-lisp-format-time-list} specifies.  The @samp{%}-sequences in
0472: @code{ls-lisp-format-time-list} produce locale-dependent month and day
0473: names, which might cause misalignment of columns in Dired display.
0474: The default value of @code{ls-lisp-use-localized-time-format} is
0475: @code{nil}.
0476: @end ifnottex
0477: 
0478: @node Windows HOME
0479: @section HOME and Startup Directories on MS-Windows
0480: @cindex HOME directory on MS-Windows
0481: 
0482:   The Windows equivalent of @code{HOME} is the @dfn{user-specific
0483: application data directory}.  The actual location depends on the
0484: Windows version; typical values are @file{C:\Documents and
0485: Settings\@var{username}\Application Data} on Windows 2000 up to XP,
0486: @file{C:\Users\@var{username}\AppData\Roaming} on Windows Vista and
0487: later, and either @file{C:\WINDOWS\Application Data} or
0488: @file{C:\WINDOWS\Profiles\@var{username}\Application Data} on Windows
0489: 9X/ME@.  If this directory does not exist or cannot be accessed, Emacs
0490: falls back to @file{C:\} as the default value of @code{HOME}.
0491: 
0492:   You can override this default value of @code{HOME} by explicitly
0493: setting the environment variable @env{HOME} to point to any directory
0494: on your system.  @env{HOME} can be set either from the command shell
0495: prompt or from @samp{Properties} dialog of @samp{My Computer}.
0496: @code{HOME} can also be set in the system registry,
0497: @pxref{MS-Windows Registry}.
0498: 
0499:   For compatibility with older versions of Emacs@footnote{
0500: Older versions of Emacs didn't check the application data directory.
0501: }, if there is a file named @file{.emacs} in @file{C:\}, the root
0502: directory of drive @file{C:}, and @env{HOME} is set neither in the
0503: environment nor in the Registry, Emacs will treat @file{C:\} as the
0504: default @code{HOME} location, and will not look in the application
0505: data directory, even if it exists.  Note that only @file{.emacs} is
0506: looked for in @file{C:\}; the older name @file{_emacs} (see below) is
0507: not.  This use of @file{C:\.emacs} to define @code{HOME} is
0508: deprecated; Emacs will display a warning about its use during
0509: startup.
0510: 
0511:   Whatever the final place is, Emacs sets the internal value of the
0512: @env{HOME} environment variable to point to it, and it will use that
0513: location for other files and directories it normally looks for or
0514: creates in your home directory.
0515: 
0516:   You can always find out what Emacs thinks is your home directory's
0517: location by typing @kbd{C-x d ~/ @key{RET}}.  This should present the
0518: list of files in the home directory, and show its full name on the
0519: first line.  Likewise, to visit your init file, type @kbd{C-x C-f
0520: ~/.emacs @key{RET}} (assuming the file's name is @file{.emacs}).
0521: 
0522: @cindex init file @file{.emacs} on MS-Windows
0523:   Your init file can have any name mentioned in @ref{Init File}.
0524: 
0525: @cindex @file{_emacs} init file, MS-Windows
0526:   Because MS-DOS does not allow file names with leading dots, and
0527: older Windows systems made it hard to create files with such names,
0528: the Windows port of Emacs supports an init file name @file{_emacs}, if
0529: such a file exists in the home directory and @file{.emacs} does not.
0530: This name is considered obsolete, so Emacs will display a warning if
0531: it is used.
0532: 
0533: @node Windows Keyboard
0534: @section Keyboard Usage on MS-Windows
0535: @cindex keyboard, MS-Windows
0536: 
0537:   This section describes the Windows-specific features related to
0538: keyboard input in Emacs.
0539: 
0540: @cindex MS-Windows keyboard shortcuts
0541:   Many key combinations (known as ``keyboard shortcuts'') that have
0542: conventional uses in MS-Windows programs conflict with traditional
0543: Emacs key bindings.  (These Emacs key bindings were established years
0544: before Microsoft was founded.)  Examples of conflicts include
0545: @kbd{C-c}, @kbd{C-x}, @kbd{C-z}, @kbd{C-a}, and @kbd{W-@key{SPC}}.
0546: You can redefine some of them with meanings more like the MS-Windows
0547: meanings by enabling CUA Mode (@pxref{CUA Bindings}).  Another
0548: optional feature which will make Emacs behave like other Windows
0549: applications is Delete Selection mode (@pxref{Using Region}).
0550: 
0551: @iftex
0552: @inforef{Windows Keyboard, , emacs}, for information about additional
0553: Windows-specific variables in this category.
0554: @end iftex
0555: @ifnottex
0556: @vindex w32-alt-is-meta
0557: @cindex @code{Alt} key (MS-Windows)
0558:   By default, the key labeled @key{Alt} is mapped as the @key{Meta}
0559: key.  If you wish it to produce the @code{Alt} modifier instead, set
0560: the variable @code{w32-alt-is-meta} to a @code{nil} value.
0561: 
0562: @findex w32-register-hot-key
0563: @findex w32-unregister-hot-key
0564:   MS-Windows reserves certain key combinations, such as
0565: @kbd{@key{Alt}-@key{TAB}} and a number of Windows key combinations,
0566: for its own use.  These key combinations are intercepted by the system
0567: before Emacs can see them.  Also, on Windows 10, all Windows key
0568: combinations are reserved by the system in such a way that they are
0569: never propagated to applications, even if the system does not
0570: currently define a hotkey on the specific combination.  You can use
0571: the @code{w32-register-hot-key} function to allow a key sequence to be
0572: seen by Emacs instead of being grabbed by Windows.  When registered as
0573: a hot key, the key combination is pulled out of the system's input
0574: queue before it is handled by Windows, effectively overriding the
0575: special meaning of that key sequence for Windows.  The override is
0576: only effective when Emacs is active; with other applications on the
0577: foreground the keys behave normally.
0578: 
0579:   The argument to @code{w32-register-hot-key} must be a single key with a
0580: single modifier, in vector form that would be acceptable to
0581: @code{define-key}.  The control and shift modifiers have no effect on the
0582: argument.  The meta modifier is interpreted as the @key{Alt} key if
0583: @code{w32-alt-is-meta} is @code{t} (the default), and the super and hyper
0584: modifiers are interpreted according to the bindings of
0585: @code{w32-lwindow-modifier} and @code{w32-rwindow-modifier}.  Additionally, a
0586: modifier with the trailing dash but with no key indicates that all
0587: Windows defined hotkeys for that modifier are to be overridden in the
0588: favor of Emacs.
0589: 
0590: @kindex M-TAB@r{, (MS-Windows)}
0591: @cindex @kbd{M-@key{TAB}} vs @kbd{@key{Alt}-@key{TAB}} (MS-Windows)
0592: @cindex @kbd{@key{Alt}-@key{TAB}} vs @kbd{M-@key{TAB}} (MS-Windows)
0593:   For example, @code{(w32-register-hot-key [M-tab])} lets you use
0594: @kbd{M-@key{TAB}} normally in Emacs; for instance, to complete the
0595: word or symbol at point at top level, or to complete the current
0596: search string against previously sought strings during incremental
0597: search.  @code{(w32-register-hot-key [s-])} with
0598: @code{w32-lwindow-modifier} bound to @code{super} disables all the
0599: Windows' own Windows key based shortcuts.@footnote{There is one known
0600: exception: The combination @kbd{@key{Windows}-L} that locks the
0601: workstation is handled by the system on a lower level.  For this
0602: reason, @code{w32-register-hot-key} cannot override this key
0603: combination - it always locks the computer.}
0604: 
0605:   Note that @code{w32-register-hot-key} checks the
0606: @code{w32-[lr]window-modifier} values at the time of the function
0607: call.  Thus, you can set @code{w32-lwindow-modifier} as @code{super},
0608: then call @code{(w32-register-hot-key [s-r])}, and finally set
0609: @code{w32-rwindow-modifier} as @code{super} as well.  The result is
0610: that the left Windows key together with @kbd{R} invokes whichever
0611: function you have bound for the combination in Emacs, and the right
0612: Windows key and @kbd{R} opens the Windows @code{Run} dialog.
0613: 
0614:   The hotkey registrations always also include all the shift and
0615: control modifier combinations for the given hotkey; that is,
0616: registering @kbd{s-a} as a hotkey gives you @kbd{S-s-a},
0617: @kbd{C-s-a} and @kbd{C-S-s-a} as well.
0618: 
0619:   On Windows 98 and ME, the hotkey registration is more restricted.
0620: The desired hotkey must always be fully specified, and
0621: @code{w32-phantom-key-code} can be customized to achieve desired
0622: results.
0623: 
0624:   The function @code{w32-unregister-hot-key} reverses the effect of
0625: @code{w32-register-hot-key} for its argument key sequence.
0626: 
0627: @vindex w32-capslock-is-shiftlock
0628:   By default, the @key{CapsLock} key only affects normal character
0629: keys (it converts lower-case characters to their upper-case
0630: variants).  However, if you set the variable
0631: @code{w32-capslock-is-shiftlock} to a non-@code{nil} value, the
0632: @key{CapsLock} key will affect non-character keys as well, as if you
0633: pressed the @key{SHIFT} key while typing the non-character key.
0634: 
0635: @vindex w32-enable-caps-lock
0636:   If the variable @code{w32-enable-caps-lock} is set to a @code{nil}
0637: value, the @key{CapsLock} key produces the symbol @code{capslock}
0638: instead of the shifted version of typed keys.  The default value is
0639: @code{t}.
0640: 
0641: @vindex w32-enable-num-lock
0642: @cindex keypad keys (MS-Windows)
0643:   Similarly, if @code{w32-enable-num-lock} is @code{nil}, the
0644: @key{NumLock} key will produce the symbol @code{kp-numlock}.  The
0645: default is @code{t}, which causes @key{NumLock} to work as expected:
0646: toggle the meaning of the keys on the numeric keypad.
0647: @end ifnottex
0648: 
0649: @vindex w32-apps-modifier
0650:   The variable @code{w32-apps-modifier} controls the effect of the
0651: @key{Apps} key (usually located between the right @key{Alt} and the
0652: right @key{Ctrl} keys).  Its value can be one of the symbols
0653: @code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control},
0654: or @code{shift} for the respective modifier, or @code{nil} to appear
0655: as the key @code{apps}.  The default is @code{nil}.
0656: 
0657: @vindex w32-lwindow-modifier
0658: @vindex w32-rwindow-modifier
0659: @vindex w32-scroll-lock-modifier
0660:   The variable @code{w32-lwindow-modifier} determines the effect of
0661: the left Windows key (usually labeled with @key{start} and the Windows
0662: logo).  If its value is @code{nil} (the default), the key will produce
0663: the symbol @code{lwindow}.  Setting it to one of the symbols
0664: @code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control},
0665: or @code{shift} will produce the respective modifier.  A similar
0666: variable @code{w32-rwindow-modifier} controls the effect of the right
0667: Windows key, and @code{w32-scroll-lock-modifier} does the same for the
0668: @key{ScrLock} key.  If these variables are set to @code{nil}, the
0669: right Windows key produces the symbol @code{rwindow} and @key{ScrLock}
0670: produces the symbol @code{scroll}.  If you want @key{ScrLock} to
0671: produce the same effect as in other applications, i.e.@: toggle the
0672: Scroll Lock @acronym{LED} indication on the keyboard, set
0673: @code{w32-scroll-lock-modifier} to @code{t} or any non-@code{nil}
0674: value other than the above modifier symbols.
0675: 
0676: @vindex w32-pass-alt-to-system
0677: @cindex Windows system menu
0678: @cindex @code{Alt} key invokes menu (Windows)
0679:   Emacs compiled as a native Windows application normally turns off
0680: the Windows feature that tapping the @key{Alt} key invokes the Windows
0681: menu.  The reason is that the @key{Alt} serves as @key{Meta} in Emacs.
0682: When using Emacs, users often press the @key{Meta} key temporarily and
0683: then change their minds; if this has the effect of bringing up the
0684: Windows menu, it alters the meaning of subsequent commands.  Many
0685: users find this frustrating.
0686: 
0687:   You can re-enable Windows's default handling of tapping the @key{Alt}
0688: key by setting @code{w32-pass-alt-to-system} to a non-@code{nil}
0689: value.
0690: 
0691: @ifnottex
0692: @vindex w32-pass-lwindow-to-system
0693: @vindex w32-pass-rwindow-to-system
0694:   The variables @code{w32-pass-lwindow-to-system} and
0695: @code{w32-pass-rwindow-to-system} determine whether the respective
0696: keys are passed to Windows or swallowed by Emacs.  If the value is
0697: @code{nil}, the respective key is silently swallowed by Emacs,
0698: otherwise it is passed to Windows.  The default is @code{t} for both
0699: of these variables.  Passing each of these keys to Windows produces
0700: its normal effect: for example, @kbd{@key{Lwindow}} opens the
0701: @code{Start} menu, etc.
0702: 
0703: @vindex w32-recognize-altgr
0704: @kindex AltGr @r{(MS-Windows)}
0705: @cindex @key{AltGr} key (MS-Windows)
0706:   The variable @code{w32-recognize-altgr} controls whether the
0707: @key{AltGr} key (if it exists on your keyboard), or its equivalent,
0708: the combination of the right @key{Alt} and left @key{Ctrl} keys
0709: pressed together, is recognized as the @key{AltGr} key.  The default
0710: is @code{t}, which means these keys produce @code{AltGr}; setting it
0711: to @code{nil} causes @key{AltGr} or the equivalent key combination to
0712: be interpreted as the combination of @key{Ctrl} and @key{Meta}
0713: modifiers.
0714: @end ifnottex
0715: 
0716: @node Windows Mouse
0717: @section Mouse Usage on MS-Windows
0718: @cindex mouse, and MS-Windows
0719: 
0720:   This section describes the Windows-specific variables related to
0721: the mouse.
0722: 
0723: @vindex w32-mouse-button-tolerance
0724: @cindex simulation of middle mouse button
0725:   The variable @code{w32-mouse-button-tolerance} specifies the
0726: time interval, in milliseconds, for faking middle mouse button press
0727: on 2-button mice.  If both mouse buttons are depressed within this
0728: time interval, Emacs generates a middle mouse button click event
0729: instead of a double click on one of the buttons.
0730: 
0731: @vindex w32-pass-extra-mouse-buttons-to-system
0732:   If the variable @code{w32-pass-extra-mouse-buttons-to-system} is
0733: non-@code{nil}, Emacs passes the fourth and fifth mouse buttons to
0734: Windows.
0735: 
0736: @vindex w32-swap-mouse-buttons
0737:   The variable @code{w32-swap-mouse-buttons} controls which of the 3
0738: mouse buttons generates the @kbd{mouse-2} events.  When it is
0739: @code{nil} (the default), the middle button generates @kbd{mouse-2}
0740: and the right button generates @kbd{mouse-3} events.  If this variable
0741: is non-@code{nil}, the roles of these two buttons are reversed.
0742: 
0743: @node Windows Processes
0744: @section Subprocesses on Windows 9X/ME and Windows NT/2K/XP/Vista/7/8/10
0745: @cindex subprocesses on MS-Windows
0746: 
0747: @cindex DOS applications, running from Emacs
0748:   Emacs compiled as a native Windows application (as opposed to the
0749: DOS version) includes full support for asynchronous subprocesses.  In
0750: the Windows version, synchronous and asynchronous subprocesses work
0751: fine on all versions of MS-Windows, as long as you run only 32-bit or
0752: 64-bit Windows applications.  However, when you run a DOS application
0753: in a subprocess, you may encounter problems or be unable to run the
0754: application at all; and if you run two DOS applications at the same
0755: time in two subprocesses, you may have to reboot your system.
0756: 
0757: Since the standard command interpreter (and most command line utilities)
0758: on Windows 9X are DOS applications, these problems are significant when
0759: using that system.  But there's nothing we can do about them; only
0760: Microsoft can fix them.
0761: 
0762: If you run just one DOS application subprocess, the subprocess should
0763: work as expected as long as it is ``well-behaved'' and does not perform
0764: direct screen access or other unusual actions.  If you have a CPU
0765: monitor application, your machine will appear to be 100% busy even when
0766: the DOS application is idle, but this is only an artifact of the way CPU
0767: monitors measure processor load.
0768: 
0769: You must terminate the DOS application before you start any other DOS
0770: application in a different subprocess.  Emacs is unable to interrupt or
0771: terminate a DOS subprocess.  The only way you can terminate such a
0772: subprocess is by giving it a command that tells its program to exit.
0773: 
0774: If you attempt to run two DOS applications at the same time in separate
0775: subprocesses, the second one that is started will be suspended until the
0776: first one finishes, even if either or both of them are asynchronous.
0777: 
0778: @cindex kill DOS application
0779: If you can go to the first subprocess, and tell it to exit, the second
0780: subprocess should continue normally.  However, if the second
0781: subprocess is synchronous, Emacs itself will be hung until the first
0782: subprocess finishes.  If it will not finish without user input, then
0783: you have no choice but to reboot if you are running on Windows 9X@.
0784: If you are running on Windows NT and later, you can use a process
0785: viewer application to kill the appropriate instance of NTVDM instead
0786: (this will terminate both DOS subprocesses).
0787: 
0788: If you have to reboot Windows 9X in this situation, do not use the
0789: @code{Shutdown} command on the @code{Start} menu; that usually hangs the
0790: system.  Instead, type @kbd{@key{Ctrl}-@key{Alt}-@key{DEL}} and then choose
0791: @code{Shutdown}.  That usually works, although it may take a few minutes
0792: to do its job.
0793: 
0794: @vindex w32-quote-process-args
0795:   The variable @code{w32-quote-process-args} controls how Emacs quotes
0796: the process arguments.  Non-@code{nil} means quote with the @code{"}
0797: character.  If the value is a character, Emacs uses that character to escape
0798: any quote characters that appear; otherwise it chooses a suitable escape
0799: character based on the type of the program.
0800: 
0801: @vindex w32-pipe-buffer-size
0802:   The variable @code{w32-pipe-buffer-size} controls the size of the
0803: buffer Emacs requests from the system when it creates pipes for
0804: communications with subprocesses.  The default value is zero, which
0805: lets the OS choose the size.  Any valid positive value will request a
0806: buffer of that size in bytes.  This can be used to tailor
0807: communications with subprocesses to programs that exhibit unusual
0808: behavior with respect to buffering pipe I/O.
0809: 
0810: @ifnottex
0811: @vindex w32-pipe-read-delay
0812:   If you need to invoke MS-DOS programs as Emacs subprocesses, you may
0813: see low rate of reading data from such programs.  Setting the variable
0814: @code{w32-pipe-read-delay} to a non-zero value may improve throughput
0815: in these cases; we suggest the value of 50 for such situations.  The
0816: default is zero.
0817: 
0818: @findex w32-shell-execute
0819:   The function @code{w32-shell-execute} can be useful for writing
0820: customized commands that run MS-Windows applications registered to
0821: handle a certain standard Windows operation for a specific type of
0822: document or file.  This function is a wrapper around the Windows
0823: @code{ShellExecute} API@.  See the MS-Windows API documentation for
0824: more details.
0825: @end ifnottex
0826: 
0827: @node Windows Printing
0828: @section Printing and MS-Windows
0829: 
0830:   Printing commands, such as @code{lpr-buffer} (@pxref{Printing}) and
0831: @code{ps-print-buffer} (@pxref{PostScript}) work in MS-DOS and
0832: MS-Windows by sending the output to one of the printer ports, if a
0833: POSIX-style @code{lpr} program is unavailable.  The same Emacs
0834: variables control printing on all systems, but in some cases they have
0835: different default values on MS-DOS and MS-Windows.
0836: 
0837:   Emacs on MS Windows attempts to determine your default printer
0838: automatically (using the function @code{default-printer-name}).
0839: But in some rare cases this can fail, or you may wish to use a different
0840: printer from within Emacs.  The rest of this section explains how to
0841: tell Emacs which printer to use.
0842: 
0843: @vindex printer-name@r{, (MS-DOS/MS-Windows)}
0844:   If you want to use your local printer, then set the Lisp variable
0845: @code{lpr-command} to @code{""} (its default value on Windows) and
0846: @code{printer-name} to the name of the printer port---for example,
0847: @code{"PRN"}, the usual local printer port, or @code{"LPT2"}, or
0848: @code{"COM1"} for a serial printer.  You can also set
0849: @code{printer-name} to a file name, in which case ``printed'' output
0850: is actually appended to that file.  If you set @code{printer-name} to
0851: @code{"NUL"}, printed output is silently discarded (sent to the system
0852: null device).
0853: 
0854:   You can also use a printer shared by another machine by setting
0855: @code{printer-name} to the UNC share name for that printer---for
0856: example, @code{"//joes_pc/hp4si"}.  (It doesn't matter whether you use
0857: forward slashes or backslashes here.)  To find out the names of shared
0858: printers, run the command @samp{net view} from the command prompt to
0859: obtain a list of servers, and @samp{net view @var{server-name}} to see
0860: the names of printers (and directories) shared by that server.
0861: Alternatively, click the @samp{Network Neighborhood} icon on your
0862: desktop, and look for machines that share their printers via the
0863: network.
0864: 
0865: @cindex @samp{net use}, and printing on MS-Windows
0866: @cindex networked printers (MS-Windows)
0867:   If the printer doesn't appear in the output of @samp{net view}, or
0868: if setting @code{printer-name} to the UNC share name doesn't produce a
0869: hardcopy on that printer, you can use the @samp{net use} command to
0870: connect a local print port such as @code{"LPT2"} to the networked
0871: printer.  For example, typing @kbd{net use LPT2: \\joes_pc\hp4si}@footnote{
0872: Note that the @samp{net use} command requires the UNC share name to be
0873: typed with the Windows-style backslashes, while the value of
0874: @code{printer-name} can be set with either forward- or backslashes.}
0875: causes Windows to @dfn{capture} the @code{LPT2} port and redirect the
0876: printed material to the printer connected to the machine @code{joes_pc}.
0877: After this command, setting @code{printer-name} to @code{"LPT2"}
0878: should produce the hardcopy on the networked printer.
0879: 
0880:   With some varieties of Windows network software, you can instruct
0881: Windows to capture a specific printer port such as @code{"LPT2"}, and
0882: redirect it to a networked printer via the @w{@code{Control
0883: Panel->Printers}} applet instead of @samp{net use}.
0884: 
0885:   If you set @code{printer-name} to a file name, it's best to use an
0886: absolute file name.  Emacs changes the working directory according to
0887: the default directory of the current buffer, so if the file name in
0888: @code{printer-name} is relative, you will end up with several such
0889: files, each one in the directory of the buffer from which the printing
0890: was done.
0891: 
0892:   If the value of @code{printer-name} is correct, but printing does
0893: not produce the hardcopy on your printer, it is possible that your
0894: printer does not support printing plain text (some cheap printers omit
0895: this functionality).  In that case, try the PostScript print commands,
0896: described below.
0897: 
0898: @findex print-buffer @r{(MS-DOS)}
0899: @findex print-region @r{(MS-DOS)}
0900: @vindex lpr-headers-switches @r{(MS-DOS)}
0901:   The commands @code{print-buffer} and @code{print-region} call the
0902: @code{pr} program, or use special switches to the @code{lpr} program, to
0903: produce headers on each printed page.  MS-DOS and MS-Windows don't
0904: normally have these programs, so by default, the variable
0905: @code{lpr-headers-switches} is set so that the requests to print page
0906: headers are silently ignored.  Thus, @code{print-buffer} and
0907: @code{print-region} produce the same output as @code{lpr-buffer} and
0908: @code{lpr-region}, respectively.  If you do have a suitable @code{pr}
0909: program (for example, from GNU Coreutils), set
0910: @code{lpr-headers-switches} to @code{nil}; Emacs will then call
0911: @code{pr} to produce the page headers, and print the resulting output as
0912: specified by @code{printer-name}.
0913: 
0914: @vindex print-region-function @r{(MS-DOS)}
0915: @cindex lpr usage under MS-DOS
0916: @vindex lpr-command @r{(MS-DOS)}
0917: @vindex lpr-switches @r{(MS-DOS)}
0918:   Finally, if you do have an @code{lpr} work-alike, you can set the
0919: variable @code{lpr-command} to @code{"lpr"}.  Then Emacs will use
0920: @code{lpr} for printing, as on other systems.  (If the name of the
0921: program isn't @code{lpr}, set @code{lpr-command} to the appropriate value.)
0922: The variable @code{lpr-switches} has its standard meaning
0923: when @code{lpr-command} is not @code{""}.  If the variable
0924: @code{printer-name} has a string value, it is used as the value for the
0925: @code{-P} option to @code{lpr}, as on Unix.
0926: 
0927: @findex ps-print-buffer @r{(MS-DOS)}
0928: @findex ps-spool-buffer @r{(MS-DOS)}
0929: @vindex ps-printer-name @r{(MS-DOS)}
0930: @vindex ps-lpr-command @r{(MS-DOS)}
0931: @vindex ps-lpr-switches @r{(MS-DOS)}
0932:   A parallel set of variables, @code{ps-lpr-command},
0933: @code{ps-lpr-switches}, and @code{ps-printer-name} (@pxref{PostScript
0934: Variables}), defines how PostScript files should be printed.  These
0935: variables are used in the same way as the corresponding variables
0936: described above for non-PostScript printing.  Thus, the value of
0937: @code{ps-printer-name} is used as the name of the device (or file) to
0938: which PostScript output is sent, just as @code{printer-name} is used
0939: for non-PostScript printing.  (There are two distinct sets of
0940: variables in case you have two printers attached to two different
0941: ports, and only one of them is a PostScript printer.)
0942: 
0943: @cindex Ghostscript, use for PostScript printing
0944:   The default value of the variable @code{ps-lpr-command} is @code{""},
0945: which causes PostScript output to be sent to the printer port specified
0946: by @code{ps-printer-name}; but @code{ps-lpr-command} can also be set to
0947: the name of a program which will accept PostScript files.  Thus, if you
0948: have a non-PostScript printer, you can set this variable to the name of
0949: a PostScript interpreter program (such as Ghostscript).  Any switches
0950: that need to be passed to the interpreter program are specified using
0951: @code{ps-lpr-switches}.  (If the value of @code{ps-printer-name} is a
0952: string, it will be added to the list of switches as the value for the
0953: @code{-P} option.  This is probably only useful if you are using
0954: @code{lpr}, so when using an interpreter typically you would set
0955: @code{ps-printer-name} to something other than a string so it is
0956: ignored.)
0957: 
0958:   For example, to use Ghostscript for printing on the system's default
0959: printer, put this in your @file{.emacs} file:
0960: 
0961: @example
0962: (setq ps-printer-name t)
0963: (setq ps-lpr-command "D:/gs6.01/bin/gswin32c.exe")
0964: (setq ps-lpr-switches '("-q" "-dNOPAUSE" "-dBATCH"
0965:                         "-sDEVICE=mswinpr2"
0966:                         "-sPAPERSIZE=a4"))
0967: @end example
0968: 
0969: @noindent
0970: (This assumes that Ghostscript is installed in the
0971: @file{D:/gs6.01} directory.)
0972: 
0973: @node Windows Fonts
0974: @section Specifying Fonts on MS-Windows
0975: @cindex font specification (MS Windows)
0976: 
0977:   Starting with Emacs 23, fonts are specified by their name, size
0978: and optional properties.  The format for specifying fonts comes from the
0979: fontconfig library used in modern Free desktops:
0980: 
0981: @example
0982:   [Family[-PointSize]][:Option1=Value1[:Option2=Value2[...]]]
0983: @end example
0984: 
0985:   The old XLFD based format is also supported for backwards compatibility.
0986: 
0987: @cindex font backend selection (MS-Windows)
0988:   Emacs 23 and later supports a number of font backends.  Currently,
0989: the @code{gdi} and @code{uniscribe} backends are supported on Windows.
0990: The @code{gdi} font backend is available on all versions of Windows,
0991: and supports all fonts that are natively supported by Windows.  The
0992: @code{uniscribe} font backend is available on Windows 2000 and later,
0993: and supports TrueType and OpenType fonts.  Some languages requiring
0994: complex layout can only be properly supported by the Uniscribe
0995: backend.  By default, both backends are enabled if supported, with
0996: @code{uniscribe} taking priority over @code{gdi}.  To override that
0997: and use the GDI backend even if Uniscribe is available, invoke Emacs
0998: with the @kbd{-xrm Emacs.fontBackend:gdi} command-line argument, or
0999: add a @code{Emacs.fontBackend} resource with the value @code{gdi} in
1000: the Registry under either the
1001: @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} or the
1002: @samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs} key (@pxref{Resources}).
1003: 
1004: @cindex font properties (MS Windows)
1005: @noindent
1006: Optional properties common to all font backends on MS-Windows are:
1007: 
1008: @table @code
1009: 
1010: @vindex font-weight-table @r{(MS-Windows)}
1011: @item weight
1012: Specifies the weight of the font.  Special values @code{light},
1013: @code{medium}, @code{demibold}, @code{bold}, and @code{black} can be specified
1014: without @code{weight=} (e.g., @kbd{Courier New-12:bold}).  Otherwise,
1015: the weight should be a numeric value between 100 and 900, or one of the
1016: named weights in @code{font-weight-table}.  If unspecified, a regular font
1017: is assumed.
1018: 
1019: @vindex font-slant-table @r{(MS-Windows)}
1020: @item slant
1021: Specifies whether the font is italic.  Special values
1022: @code{roman}, @code{italic} and @code{oblique} can be specified
1023: without @code{slant=} (e.g., @kbd{Courier New-12:italic}).
1024: Otherwise, the slant should be a numeric value, or one of the named
1025: slants in @code{font-slant-table}.  On Windows, any slant above 150 is
1026: treated as italics, and anything below as roman.
1027: 
1028: @item family
1029: Specifies the font family, but normally this will be specified
1030: at the start of the font name.
1031: 
1032: @item pixelsize
1033: Specifies the font size in pixels.  This can be used instead
1034: of the point size specified after the family name.
1035: 
1036: @item adstyle
1037: Specifies additional style information for the font.
1038: On MS-Windows, the values @code{mono}, @code{sans}, @code{serif},
1039: @code{script} and @code{decorative} are recognized.  These are most useful
1040: as a fallback with the font family left unspecified.
1041: 
1042: @vindex w32-charset-info-alist
1043: @item registry
1044: Specifies the character set registry that the font is
1045: expected to cover.  Most TrueType and OpenType fonts will be Unicode fonts
1046: that cover several national character sets, but you can narrow down the
1047: selection of fonts to those that support a particular character set by
1048: using a specific registry from @code{w32-charset-info-alist} here.
1049: 
1050: @item spacing
1051: Specifies how the font is spaced.  The @code{p} spacing specifies
1052: a proportional font, and @code{m} or @code{c} specify a monospaced font.
1053: 
1054: @item foundry
1055: Not used on Windows, but for informational purposes and to
1056: prevent problems with code that expects it to be set, is set internally to
1057: @code{raster} for bitmapped fonts, @code{outline} for scalable fonts,
1058: or @code{unknown} if the type cannot be determined as one of those.
1059: @end table
1060: 
1061: @cindex font properties (MS Windows gdi backend)
1062: Options specific to @code{GDI} fonts:
1063: 
1064: @table @code
1065: 
1066: @cindex font scripts (MS Windows)
1067: @cindex font Unicode subranges (MS Windows)
1068: @item script
1069: Specifies a Unicode subrange the font should support.
1070: 
1071: The following scripts are recognized on Windows: @code{latin}, @code{greek},
1072: @code{coptic}, @code{cyrillic}, @code{armenian}, @code{hebrew}, @code{arabic},
1073: @code{syriac}, @code{nko}, @code{thaana}, @code{devanagari}, @code{bengali},
1074: @code{gurmukhi}, @code{gujarati}, @code{oriya}, @code{tamil}, @code{telugu},
1075: @code{kannada}, @code{malayam}, @code{sinhala}, @code{thai}, @code{lao},
1076: @code{tibetan}, @code{myanmar}, @code{georgian}, @code{hangul},
1077: @code{ethiopic}, @code{cherokee}, @code{canadian-aboriginal}, @code{ogham},
1078: @code{runic}, @code{khmer}, @code{mongolian}, @code{symbol}, @code{braille},
1079: @code{han}, @code{ideographic-description}, @code{cjk-misc}, @code{kana},
1080: @code{bopomofo}, @code{kanbun}, @code{yi}, @code{byzantine-musical-symbol},
1081: @code{musical-symbol}, and @code{mathematical}.
1082: 
1083: @cindex font antialiasing (MS Windows)
1084: @item antialias
1085: Specifies the antialiasing method.  The value @code{none} means no
1086: antialiasing, @code{standard} means use standard antialiasing,
1087: @code{subpixel} means use subpixel antialiasing (known as Cleartype on
1088: Windows), and @code{natural} means use subpixel antialiasing with
1089: adjusted spacing between letters.  If unspecified, the font will use
1090: the system default antialiasing.
1091: @end table
1092: 
1093: @node Windows Misc
1094: @section Miscellaneous Windows-specific features
1095: 
1096:   This section describes Windows-specific features that don't fit
1097: anywhere else.
1098: 
1099: @vindex w32-use-visible-system-caret
1100: @cindex screen reader software, MS-Windows
1101:   The variable @code{w32-use-visible-system-caret} is a flag that
1102: determines whether to make the system caret visible.  The default when
1103: no screen reader software is in use is @code{nil}, which means Emacs
1104: draws its own cursor to indicate the position of point.  A
1105: non-@code{nil} value means Emacs will indicate point location with the
1106: system caret; this facilitates use of screen reader software, and is
1107: the default when such software is detected when running Emacs.
1108: When this variable is non-@code{nil}, other variables affecting the
1109: cursor display have no effect.
1110: 
1111: @iftex
1112: @inforef{Windows Misc, , emacs}, for information about additional
1113: Windows-specific variables in this category.
1114: @end iftex
1115: 
1116: @ifnottex
1117: @vindex w32-grab-focus-on-raise
1118: @cindex frame focus policy, MS-Windows
1119:   The variable @code{w32-grab-focus-on-raise}, if set to a
1120: non-@code{nil} value causes a frame to grab focus when it is raised.
1121: The default is @code{t}, which fits well with the Windows default
1122: click-to-focus policy.
1123: @end ifnottex
1124: 
1125: @ifnottex
1126: @include msdos-xtra.texi
1127: @end ifnottex
1128: