Usage Notes =========== Notes on using the GNUstep / Cocoa port are summarized in the info file accessible through the command 'info-ns-emacs' (or the Help/Info menu), for usage information. However, that file is still in the process of being updated, so here are some of the essentials for quick reference. Font Backend and Fontsets ------------------------- With the 9.0-rc1 release comes support for the "font backend" framework developed by Kenichi Handa in the GNU Emacs CVS unicode-2 branch. This framework is much more accomodating to other font and text systems besides Xlib than the earlier framework is. Emacs.app implements a driver for it that is automatically enabled in the default build on OS X. As a result of the new driver, fontsets are now supported. Fontsets can be created manually as for other emacsen by using the family names of the desired fonts. However this should not be necessary in general because a full multilingual fontset is generated automatically whenever a font is selected in the font panel. To turn the new font driver off and go back to the old implementation, start Emacs from the command line with the --disable-font-backend option. On the other hand, if you build manually and you want the driver, make sure to enable it during configuration as shown in the nextstep/compile script. The new font driver does NOT work under GNUstep yet. There's no reason why it shouldn't, but it doesn't. Help debugging it is extremely welcome. For now support for the backend is NOT enabled during configuration for GNUstep in nextstep/compile. Preferences Panel ----------------- Most of the settings described below may be accessed through the Preferences panel, under the 'Emacs' menu or Cmd-, as for other OS X applications. Note, the Preferences panel has a couple of known issues: 1) After pushing the 'Default Font' button, you must click on an Emacs frame before selecting a font. 2) After pushing the help ('?') button, you must click on an Emacs frame and drag the cursor or hit a key to show the help. Also, for cases where you set things _without_ using the Preferences panel (such as popping up the Font or Color panels independently), you must explicitly choose 'Save Preferences' from the Help menu to save the settings. Fonts and Text -------------- Font can be set using the Font Panel (accessible through Preferences or by Cmd-t or under Windows menu). After you find a font you like, select "Save Preferences" from the Help menu (OS X), or Info menu (GNUstep). This saves a number of miscellaneous display parameters relating to fonts, colors, and window sizes. Both fixed width and proportional fonts can be used. Rendering of non-Latin text should mostly work (see KNOWN_ISSUES.txt) provided the font supports it. Emacs supports the concept of "fontsets" which automatically select the correct font for rendering each character, however this is not working in Emacs.app, and will not be supported. (Instead, a mechanism will be implemented to select fonts automatically.) For now, you must select a suitable font for the language being edited manually. Antialiasing can be turned on or off using the Preferences panel, and on OS X, Quickdraw-based font smoothing (less heavy antialiasing) can be selected. Colors ------ Colors can be customized using the color panel. Pull it up from the Preferences panel, or hit Shift-Cmd-C or choose it from the Windows menu, then choose colors and drag them to the active frame. Drag to a face to change that face's foreground color, or drag to a blank area to change the color of default (non-face) text. Hold down shift when dragging to change background colors. Drag onto the cursor to change the cursor's foreground color only. Choose Save Preferences from the Help menu to save for future sessions. Transparency ------------ The Color panel does not let you set transparency. To get a transparent window, use M-x ns-set-background-alpha, and enter a value between 0 (fully transparent) and 1 (fully opaque). Note that, unlike Emacs on Aqua, you CANNOT simply use set-background-color with a color of the form ARGBAARRGGBB, as this core emacs function no longer accepts numeric color names. Cursor ------ Cursor drawing works differently than in Emacs under X or Carbon -- the character beneath the cursor is not reverse-video'd, but instead changed to the default face (usually black text). This looks better, but it means some color combinations you are accustomed to may not work. Mouse ----- Wheel mouse support is activated by default. If something doesn't work, please report it. Keys ---- "Alt" or "Opt" should be acting as Emacs "meta", while "Cmd" should be acting as itself. Try turning off 'Alternate Is Meta' in the Preferences panel) if you prefer to use this key for accented character entry. Most standard OS X / GNUstep command keys are active. Note that panels for loading/saving files are used if you use these keys instead of the standard emacs versions. E.g., Ctrl-x,Ctrl-s will let you type in a file name, while Cmd-o (or using the menu) will pop up a panel. Clipboard --------- On GNUstep, you can transfer text to/from the primary X selection (instead of the clipboard) using Cmd-c and Cmd-y (instead of Meta-w and Ctrl-y). Cmd-c actually copies text to both primary and clipboard selection. Path ---- On OS X, if you start Emacs by clicking the icon, the executable path is not propagated to emacs. This can cause packages that depend on external binaries, such as SQL interfaces and email clients, to fail to find them. The solution is to place a special "plist" file at ~/.MacOSX/environment.plist. Emacs.app includes a utility to create such a file. Run it from the Terminal: /Applications/Emacs.app/Contents/MacOSX/bin/mac-fix-env (Replace "/Applications" with wherever you installed Emacs.) This puts your current path in that shell into the env file. You must log out and log back in to your OS X session for this to take effect. Another approach is to run "M-x ns-grab-env", which fires up a shell in the background and snarfs the environment variables that get set there (from your .login / .cshrc, etc.). You can put this in your .emacs, but it will add to startup time, so try the environment.plist approach if you can. See the info file accessible through the command 'info-ns-emacs' (or the Help/Info menu), for more information. Parentheses / Braces Display ---------------------------- The 'mic-paren' package is bundled and activated, causing entire expressions within parentheses or braces to light up. To deactivate this, do "M-x paren-deactivate". To customize, customize group 'mic-paren-matching'. Control-g --------- Emacs.app can now be compiled to use a different input mode that allows it to pick up Ctrl-g in more situations than before. However as there are a few quirks that arise in connection with normal input processing when this mode is used, it is not enabled by default. To try it out, add the "--enable-cocoa-experimental-ctrl-g" option to the configure line. You may experience scrolling anomalies as well as spurious frame switches. Please report any other issues.