# EmacsW32 - Adjustments for Emacs on MS Windows

Version 1.58 2008-06-07

For latest info, downloading etc, see the home page at http://ourcomments.org/Emacs/EmacsW32.html
See also the wiki page at http://www.emacswiki.org/cgi-bin/wiki/EmacsW32.

On THIS Page:

- Introduction
- Using Emacs On MS Windows
- - EmacsW32 Helps
  - Using the Keyboard in Emacs
- Getting Started with Emacs+EmacsW32
- - Installing and Setting Up Emacs+EmacsW32
  - Opening Files from outside Emacs
  - Learning to use Emacs
- Features Added by EmacsW32
- - Features Summary
  - Features Details
- Changes made by EmacsW32
- - Menu Changes by EmacsW32
  - Keyboard Keys Changes by EmacsW32
  - The Alt-key War between Emacs and MS Windows
  - Patches in Emacs+EmacsW32 distribution
- Files that Comes with EmacsW32
- Also in the Installation: nXml/nXhtml

This version is for Emacs 22. If you are using Emacs 21.3 then look for EmacsW32 version 0.92.

## Introduction

EmacsW32 tries to make it easier for an MS Windows user to get used to Emacs. (W32 is Emacs' abbreviation for MS Windows.)

- EmacsW32 (described on this page) is a collection of Emacs lisp modules and MS Windows programs. It can make the keyboard and other things in Emacs function more like they do usually in MS Windows programs. It also makes Emacs more easy to setup by providing unix utilities commonly used by Emacs.
- EmacsW32 is not Emacs for MS Windows. Instead it is an addon to Emacs for MS Windows.
- EmacsW32 Install Wizard is what you use to install and setup EmacsW32 on MS Windows. They can also be used to install Emacs itself. Note that you can even easily build your own installation program.

EmacsW32 was written primarily for MS Windows, but parts of it (see the list of packages) can be used on other platforms too.

You may wonder if there is any reason to use Emacs on MS Windows, is it not an editor for GNU/Linux? The answer is yes, it is a very good editor for GNU/Linux - and for a lot of other operating systems too. And maybe, some day you will be using GNU/Linux?

Please notice that EmacsW32 is essentially a combination of some good packages already made available. What it offers is trying to bring all these enhancement together in a simple fashion.

## Using Emacs On MS Windows

If you use plain Emacs on MS Windows you will soon notice that it does not really behave as other MS Windows applications. You can not access the menus from the keyboard with Alt+letter. The CUA keys (C-c, C-x, C-v and C-z) whichs works in nearly all applications does not work. A networked printer may not work. And even if you happen to get used to those anomalities there are still problems because Emacs uses some external utilities that are not there on MS Windows (to begin with).

### EmacsW32 Helps

You may want the power of Emacs. You may wish to learn Emacs because it is available on GNU/Linux too. Seems good to prepare for a move. Still you may get desperate over all this trouble and just give it up. But don't panic, EmacsW32 will help you with part of it. CUA keys can work. (You can also use vi keys, even together with CUA keys!) And to make it easier to get started some of the most commonly used unix utility programs are already included in EmacsW32. (If you want more see Unix Utilities for Emacs on MS Windows.) The ftp program that comes with MS Windows does not behave as Emacs expects. Therefore EmacsW32 includes a more unix-like ftp program!

By default you can not access the menus with Alt+letter as 508 requires, but with the patched version of Emacs that you can get together with EmacsW32 you can do that too (even with StickyKeys on which is otherwise a problem in current Emacs on MS Windows).

Another problem is line endings. On MS Windows this is normally CR-LF while it on unix-like operating systems (like GNU/Linux) is only LF. Some files on MS Windows needs CR-LF while other files (like XHTML files for example) can use just LF instead. Using just LF instead makes it a bit easier to transfer those files to other operating systems. Emacs has good support for changing line endings and some support for telling which files should or can have LF line endings. EmacsW32 extends the latter a little bit.

### Using the Keyboard in Emacs

Emacs uses a lot of keyboard commands. It combines control, meta and shift to make it easy to access a lot of often used commands. (Meta is by default Alt - that is why you can not access the menus with Alt+letter.) That takes some time to get used to, but you can do a lot without learning them because the CUA keys can be used in Emacs. (Or, if you are used to vi its keyboard keys can be used too.)

#### Accessibility Feature StickyKeys can Help You

StickyKeys is a feature on MS Windows for people with a disability that makes it hard to type key combinations. It is actually mentioned in 508 requirements for making information technology accessible to people with disabilities. StickyKeys is a feature of MS Windows that works also in Emacs.

StickyKeys can be a great help for anyone using Emacs on MS Windows. Some key combinations can be very hard to type, especially on a national keyboard. If you use StickyKeys you can (but does not have too) type the keys one by one and that makes it much simpler. As a positive side effect this may perhaps also help saving your hands from problems.

For more information about StickyKeys see StickyKeys on MS Windows. See also GNOME User Interface Guidelines to learn about how this works in GNOME on GNU/Linux.

#### AltGr+Control - Is That Possible?

Emacs uses some keys that are a combination of AltGr+Control. Those keys might seem impossible to type on MS Windows since you might have heard that AltGr is the same as Alt+Control. The truth is that AltGr is the same as Alt+Left Control. You can still use the AltGr+Right Control.

Important: You must type Right Control before AltGr ! Normally the order between shift, control etc does not matter, but here they do. (Previously it was the other way round, AltGr before Right Control, but something seems to have changed now (2006-12-17).

## Getting Started with Emacs+EmacsW32

### Installing and Setting Up Emacs+EmacsW32

Please see EmacsW32 Install Wizard for how to get and install Emacs+EmacsW32. Please observe that you need not start emacs server in any of the startup files for Emacs (unless you are using the unpatched version of Emacs)! Instead Emacs and emacs server will be started automatically when you start emacsclient.

Important: At the end of installation you must activate the EmacsW32 specific options inside Emacs to take advantage of them. Or, after installation start Emacs and in the menus choose Options - Customize EmacsW32.

#### Determine Which Emacs to Start

If you want to switch to another version of Emacs run the file usethis.exe in the Emacs bin directory and restart Emacs. This will tell emacsclient to use that version of Emacs.

Since none of the startup files should start emacs server you can run a second copy of Emacs without problems if you want to for some reason. Just use emacs.exe then.

### Opening Files from outside Emacs

To start Emacs and edit a file you can use the various shortcuts created at the installation, for example the Send To shortcut in Explorer. There is also a file e.cmd that you can copy to your path for open files from the command line. Note that this calls emacsclient.exe, not emacs. So you can not use the command line switches for emacs.exe, but you can use those for emacsclinet.exe instead. (Emacs default installation adds a Start menu entry called GNU Emacs. You should not use this if you are using EmacsW32 and the patched version of Emacs.)

When Emacs is started you can of course open files from within Emacs. If you do not want to start Emacs by opening a file as above you can use the shortcuts that just starts Emacs or e.cmd.

During the installation you also have the choice to associate files with Emacs (or really emacsclient).

#### Emacs is an Edit Server

The shortcuts and e.cmd will only start one copy of Emacs for you. If you try to open a file that you are already editing Emacs will only switch to the buffer containting that file.

If you want to use Emacs as an external editor in some program you would probably want to enter something like "YOUR-PATH\emacsclientw.exe" %* for the edit command. For just viewing you can include the --no-wait (short form -n) argument which means "do not wait".

#### Opening and Comparing Files with Ediff

As a small convenience you can start Emacs ediff directly from the command line with the command file ediff.cmd.

### Learning to use Emacs

Now you are ready to learn Emacs! Emacs has a builtin tutorial and builtin documentation. From the tutorial you can learn about how to use Emacs from the keyboard. Emacs has its own key bindings choosen for what many people have found to be fast and efficient for editing. You can however also use CUA keys or vi keys and even those two together with Emacs.

A good starting place for documentation is to choose Help - Read Emacs Manual from the menus. Another good place to start from is EmacsWiki.

## Features Added by EmacsW32

### Features Summary

Here is a summary of the features you get with EmacsW32.

- Adjustments inside Emacs:
  - Keyboard and mouse handling, you get the common w32 keys for cut, copy, paste and undo plus some others.
  - Selection is visible.
  - Recent files list.
  - Buffer switching with C-Tab.
  - Standard use of Alt key in MS Windows: Emacs normally grabs the Alt key for use as Meta key. You can instead use the Windows keys for Meta and leave Alt to MS Windows. However this currently requires that you also use a patched version of Emacs which you can find at EmacsW32 home page. (If you download the prepackaged and prebuild CVS version of Emacs with EmacsW32 this includes the patch.)
  - Extended support for telling which files should have unix line endings.
  - Commands to create *Shell* style buffers: cmd-shell, msys-shell, cygwin-shell. They are replacements for `M-x shell'. Hopefully their names tells what they does.
  - File name completion with Tab/Shift-Tab in a *Shell* buffer started with `M-x shell' running cmd is broken in Emacs. Use `M-x cmd-shell' instead. The *Shell* style buffer will be running cmd and have Tab/Shift-Tab completion in Windows Command Prompt style.
- Integration with MS Windows:
  - Automatic start of editing server, both from command line and shortcuts. Note: You need the patched version of emacsclient that comes with the patched version of Emacs+EmacsW32 for this to work.
  - Shortcuts (Taskbar, Send To, Desktop).
  - Command line files for opening files and running scripts (e.cmd), running Emacs' ediff to compare and edit two files (ediff.cmd) and elisp compiling (elc.cmd). These all uses emacsclient. You can copy them to somewhere in your PATH if you want to.
  - File associations.
  - Simple printing to MS Windows printer (not fancy, but in colors, preview possible).
  - Automatically lookup of Registry values (currently only GhostScript, GSview and paper size) for advanced printing.
  - Support for finding Cygwin/MSYS directories automatically.
  - w32shell-cmd-here: Command for starting a Command Prompt in the current default-directory and with Emacs in the path.
  - w32shell-explorer-here: Start explorer in the current default-directory.
- Commonly Used Unix Programs are Included:
  - Emacs uses some unix programs for certain commands. The most commonly used includes grep, diff, patch etc. To make it easier to get started some of these programs comes with EmacsW32.
  - The ftp program can be very useful in Emacs. Unfortunately Emacs have problems using the ftp.exe that comes with MS Windows. EmacsW32 therefore includes a more unix-like ftp.exe that fits Emacs better.

All the adjustments inside Emacs can be set by options that you find under Options - Customize EmacsW32 on the menus. There you also find the automatic lookup of the registry values. Some of the things in integration with MS Windows (like shortcuts) most be selected during the installation.

### Features Details

This list is rather technical and not at all required reading.

- Editing server capabilites: This important feature comes with Emacs itself and does two important things for you. First, Emacs remembers which files you are editing. You can not by mistake have several copies of the same file in different editing states. Second, you can let other programs ask Emacs to let you edit a file. Emacs will tell them when you are ready.

  For this to work Emacs server must be started. If you are using the patched version of emacsclient the server will start automatically when you use emacsclient. (For unpatched Emacs see the documentation that comes with Emacs.)

- Printing: Quick and easy simple color printing to MS Windows default printer (w32-print.el) without using external programs. There has been a long discussion on the help-gnu-emacs mailing list on whether this approach is good or not. Important to me is that it works reliably and integrates well with the printing system on MS Windows. The printing possibilities are approximately the same as those you get with the commands ps-print-buffer-with-faces or ps-print-region-with-faces in Emacs. On MS Windows however these commands in many cases requires that you install an external program for printing. (Surprisingly enough this can be the case even for a networked printer that is able to understand PostScript.)
- Ctrl-Tab buffer switching: You can have many files open for editing in Emacs. This package includes a fast and easy way to switch to another edited file. It can be done for example with Ctrl-Tab which propably feels rather natural for many MS Windows users (it is used for switching tabs normally). (swbuff-y.el)
- The Alt-key can be used to get to the menus. (If StickyKeys are used then unfortunately it must be pressed twice to reach the menus.) Note: The emacs.exe in the installation package with Emacs+EmacsW32 based on the CVS sources (next generation of Emacs) has been changed to allow Alt to be used for the menus and the left and right windows keys to be used as Emacs Meta. (Using this patched version there are no problems with StickyKeys.) The changes can be find in the file patch-<date>.diff that is available on the web site. This is MS Windows specific.
- Frame handling: A new file is shown in either the current frame (which is called "window" by normal MS Windows terminology) or in a new frame depending in customized settings.
- Maximized by default: New frames in Emacs can be opened maximized by default. Can be customized. Note that if you are using shortcuts in MS Windows those shortcuts decides whether the window that the shortcut think it is opening should be maximized, normal or minimized. Since Emacs is run as a server accessed with client programs through the shortcuts this confuses MS Windows so it changes the Emacs server window.
- Common MS Windows Keys: Several keyboard keys commonly used in MS Windows program are setup, including CUA-keys (Cut, copy, paste and undo works with Ctrl-X, Ctrl-C, Ctrl-V and Ctrl-Z). (cua.el)
- Selection of text behaves as expected in MS Windows. It can be done with the shift key and moving keys. It is visible. It can be erased with del and replaced with paste or by typing an insertable key. (cua.el)
- There is a Open Recent entry on the File menu to open recently opened files. (recentf.el)
- In EmacsW32 you can decide which files should have unix line endings based on the full file name. (emacsw32-eol.el)
- On MS Windows some options are automatically filled in by Emacs: On MS Windows Emacs can not automatically find programs like GhostScript, since they are normally not in the path. Some of these programs and other values can be found and entered into Emacs custom values using Options Related to EmacsW32 on the Options menu. Some programs that comes with EmacsW32 takes care of this.
- Comes with some unix utilities from Gnuwin32 . With these you can start using the Emacs commands grep, find-grep, ediff etc without having to install anything. It just works, as it should do.

## Changes made by EmacsW32

EmacsW32 does not change much if you do not want it too. Some changes are however always made when you use it.

### Menu Changes by EmacsW32

Changes to menus are small:

File Menu:
  The printing entries may be changed. An entry called Quick Print (to MS Windows printer) is added if w32-print.el is used. The default print entries are by default removed.
Options Menu:
  An entry for customization, Customize EmacsW32 is added at the bottom. Go there if you want to use the features that Emacs+EmacsW32 can give you.
Help Menu:
  Some help entries for EmacsW32 and W32 are added at the top.

### Keyboard Keys Changes by EmacsW32

Note that these changes are only made if you turn on the corresponding options in menu Options - Customize EmacsW32.

Notation explanation:

C-
  means press control-key
S-
  means press shift-key
M-
  means press alt-key
A-
  also means press alt-key, but in the state when Emacs sends this key to MS Windows (which it normally does not do, set with Emacs customization).
Words like f6, tab, delete
  means keyboard key usually named so

#### "CUA" Keyboard Keys (only when cua-mode on):

          C-c             copy
          C-x             cut
          C-v             paste
          C-z             undo

#### Other MS Windows Standard Keyboard Keys (only when emacsw32-mode on):

          C-a             mark whole buffer

#### Those are "mnemonics" (only when emacsw32-mode on):

          C-tab           switch to next buffer
          C-S-tab         switch to previous buffer

#### C-z and Viper

C-z is undo in most MS Windows programs. In viper this normally instead runs viper-toggle-key-action which temporary switches to Emacs default keypad map and back. EmacsW32 can change this to C-x C-z (which normally runs iconify-or-deiconify-frame, which is rather useless on MS Windows).

          C-x C-z        switch viper keymap on/off

#### Miscellaneous Keyboard Keys Defined by the Used Packages

In addition to provide the functionality wanted by emacsw32-mode the included packages gives some extra functionality, some of it available from the keyboard:

          C-return        cua-set-rectangle-mark (see cua-mode function inside Emacs for more info)

### The Alt-key War between Emacs and MS Windows

The design of Emacs makes it very hungry for keyboard keys. This unfortunately leads to some keyboard conflicts on MS Windows. On MS Windows Emacs by default uses the Alt keyboard key for what is in Emacs called the Meta key. However the Alt key is used by MS Windows itself and therefore Emacs does not see all Alt key combinations. One of these is Alt-Tab which switches between applications' top level windows. (Emacs could with its current design catch Alt-Tab prior to Windows 2000.)

Using the Alt key as Emacs Meta is also unfortunate since it prevents the use of Alt for the menus instead. (I think Microsoft would have prevented this if they could, since it their GUI guidelines says that Alt should be used for the menus. Since Alt also is used to move around between fields in an application it is however hard for them to do this.)

To get out of this problem I have done some changes to Emacs C sources that permits the right and left Window keyboard keys to be used as as Emacs Meta key. If you use this changed version of Emacs then there is an extra option that allows this feature to be turned on. Using that you can let the Alt key have its standard use in MS Windows and still have easy access to Emacs Meta key. (Of course you also need a keyboard with the Window keyboard keys, but all newer keyboards have this.)

Note: Emacs already without my patch allows the use of the Windows keys as Meta. This does unfortunately not work for all Meta key sequences. For example Right Window-key + e will bring up Windows Explorer. (With my patch it does forward-sentence as expected.)

### Patches in Emacs+EmacsW32 distribution

There are also some patches made to Emacs itself when you are using the patched version of Emacs+EmacsW32. See the information about patches on the EmacsW32 home page for more information and the documentation in the EmacsW32 subdirectory of your installation.

If you want to test from elisp if it is the patched version you are running then you can use the function (emacsw32-is-patched).

## Files that Comes with EmacsW32

Below is a list of some the special files and packages emacsw32-mode uses and some instruction about how to get them. Notice that if you got emacsw32-mode with the EmacsW32 Install Wizard then you have all those packages.

cua-mode.el
  CUA-keys, visible region etc. Comes with your Emacs installation.
htmlize.el, htmlize-view.el
  Used by w32-print.el for color printing. You can find htmlize.el on http://fly.srk.fer.hr/~hniksic/emacs/htmlize.el.
recentf.el
  List of recenctly used files. Comes with your Emacs installation.
emacsw32-eol.el
  Decide which files should have unix line endings based on the full file name.
swbuff-y.el, swbuff.el
  Buffer switching with C-tab/C-S-tab. You can find swbuff-y.el on EmacsW32 web site. You also needs swbuff.el which you can find on http://www.EmacsWiki.org/.
w32shell.el
  Helps you choose inferior shells to use from Emacs. Support for cmd.exe, Cygwin and MSYS.
w32-print.el, w32-integ.el
  Simple and easy printing. (MS Windows only.)
w32-regdat.el, w32-reg-iface.el, w32-reg-iface.exe, winforms.exe
  Fetches registry values. (MS Windows only.)
emacsw32.el
  Keeps the above together and offers some (very small) keyboard key adjustments.
emacs.exe
  Emacs main executable file. Comes with Emacs of course, but Emacs+EmacsW32 provides a patched version (and an unpatched too). To allow the Alt key to be passed to MS Windows and and use the Windows keyboard keys as Meta you must use the emacs.exe that comes with the Emacs+EmacsW32 installation package. (Or you can built it yourself, of course.) EmacsW32 will work with the standard emacs.exe too, but this feature will not be available. (MS Windows only.)
emacsclient.exe, emacsclientw.exe
  Comes with Emacs, but with Emacs+EmacsW32 you can get a patched version that starts Emacs automatically.
grep, find, diff etc
  With EmacsW32 comes some unix utility programs that you may need with Emacs.

## Also in the Installation: nXml/nXhtml

In the package I have also included nXml and nXhtml. These are Emacs modes for editing XML and XHTML files. They come with documentation inside (though it could be more in the case of nXhtml). To read the documentation enable the use of this modes through the menus in Emacs: Options - Customize EmacsW32. Then do C-h f nxhtml-mode RET.

See also NxmlMode and NxhtmlMode on EmacsWiki.