-This directory contains files needed to build Emacs on Nextstep-based
-platforms, including GNUstep and Mac OS X (using the Cocoa libraries).
-See the INSTALL file in this directory for compilation instructions.
+ NS -- the Cocoa interface for OS X and compatible systems
+ ---------------------------------------------------------
+
+This directory contains files needed to build Emacs on system based on
+NextStep (NS), including OS X (Mac) and GNUstep, using the Cocoa API.
+
+
+ HISTORY
+
+Up to Emacs 22, the OS X interface was implemented using the C-based
+Carbon API. Starting with Emacs 23, the interface was rewritten in
+Objective-C using the Cocoa API. Meanwhile, the Carbon interface has
+been maintained independently under the name "mac".
+
+
+ OVERVIEW OF COCOA AND OBJECTIVE-C
+
+Cocoa is an API for the Objective-C language, an objective oriented
+superset of C. Anybody with experience with iOS or modern OS X
+application development should feel at home.
+
+A method call in Objective-C differs from most other languages in the
+fact that it doesn't have a normal name. Instead, the method name is
+made up of the name of each parameter. An exception to this rule are
+methods without parameters.
+
+The following calls a method in the object `anObject'.
+
+ [anObject alpha:1 beta:2 gamma:3];
+
+Classes are declared like the following:
+
+ @interface AClassName
+ {
+ // A class method.
+ + (TYPE)name1:(TYPE)param1
+
+ // An object method.
+ - (TYPE)name1:(TYPE)param1 name2:(TYPE)param2;
+ }
+ @end
+
+
+ GUIDELINES
+
+* Adhere the to the FSF philosophy that a feature in GNU software
+ should not only be available on non-free systems.
+
+* People with varying Cocoa and Objective-C skills will read and
+ modify the NS code over a long period of time. Keep the code simple
+ and avoid language constructs that makes the code hard to maintain.
+
+* Don't use macros and types intended for the XCode Interface Builder,
+ like `IBAction'.
+
+* The NS interface should work on all version of OS X from 10.6.8
+ (Snow Leopard) to the latest official release.
+
+* Under OS X, it is possible to build Emacs using NS, X11, or console
+ only. A new OS X feature should work in all appropriate builds.
+
+
+ TRACING SUPPORT
+
+The NS interface features a printf-based trace package that prints the
+call tree of selected functions in the Cocoa interface, plus various
+extra information. It can be enabled by uncommenting the line
+defining `NSTRACE_ENABLED' in "nsterm.h". To enable more output,
+uncomment the lines defining symbols starting with `NSTRACE_GROUP'.
+
+
+ GNUSTEP AND OTHER COMPATIBLE SYSTEMS
+
+The NS interface works on system compatible with OS X, for example
+GNUstep. Even though they are less frequently used, this is important
+for a number of reasons:
+
+* It supports the GNUstep project and provides an Emacs with the same
+ look-and-feel as the rest of the system.
+
+* This allows other Emacs developers to test their changes on the NS
+ interface without having access to an OS X machine.
+
+* If a feature in the NS interface work on free systems like GNUstep,
+ this meets the FSF requirement that features in GNU software should
+ not only be available on non-free systems.
+
+
+ SEE ALSO
+
+The src/ns... files contains the C and Objective-C parts.
+
+The lisp/term/ns-win.el file contains the lisp part of the NS
+interface.
+
+The INSTALL file in this directory for compilation instructions.
+
+The WISHLIST file in this directory for a list of ideas for future
+development of the NS interface.
--- /dev/null
+ -*- org -*-
+
+ Wish list for the "NS" OS X Emacs port
+ --------------------------------------
+
+ Note: This document is written using "org-mode", a plain-text
+ format supporting outlines. To expand a heading, press TAB. To
+ expand all headings and subheadings, press S-TAB until Emacs
+ responds "SHOW ALL".
+
+* Introduction
+
+This is a wishlist for future development of the "NS" Emacs user
+interface whose primary use is the official Emacs version on OS X.
+
+This list should be seen as a complement to the bug- and wishlist on
+[[http://debbugs.gnu.org/cgi/pkgreport.cgi?package%3Demacs][debbugs]], the Emacs bug tracker.
+
+* Missing features
+
+This sections contains features found in other official Emacs ports.
+
+** Support for "xwidget"
+
+Emacs 25 has support for "xwidgets", a system to include operating
+system components into an Emacs buffer. The components range from
+simple buttons to "webkit" (effectively, a web browser).
+
+Currently, "xwidget" only works for the "gtk+" framework but it is
+designed to be compatible with multiple Emacs ports.
+
+** Respect `frame-inhibit-implied-resize'
+
+When the variable `frame-inhibit-implied-resize' is non-nil, frames
+should not be resized when operations like changing font or toggling
+the tool bar is performed.
+
+Unfortunately, the tool bar (and possible other operations) always
+resize the frame.
+
+** Support `proced' (implement `process-attributes')
+
+Unfortunately, a user-level process like Emacs does not have the
+privileges to get information about other processes under OS X.
+
+There are other ways to do this:
+
+ 1) Spawn "ps" and parse the output ("ps" has superuser privileges).
+
+ 2) Sign Emacs as part of the distribution process.
+
+ 3) Ask the user to self-sign Emacs, if this feature is of interest.
+
+Anders Lindgren <andlind@gmail.com> has implemented
+`process-attributes' for OS X -- which currently only work when
+running Emacs as root.
+
+[[http://emacsredux.com/blog/2013/05/02/manage-processes-with-proced/][See this article by Bozhidar Batsov for an overview of Proced.]]
+
+** Tooltip properties
+
+Tooltip properties like the background color and font are hard wired,
+even though Emacs allow a user to customize such features.
+
+* New features
+
+This section contains features unique to the NS and/or OS X.
+
+** PressAndHold for writing accented character
+
+On OS X, many application supports the press and hold pattern to
+invoke a menu of accented characters. (See example at [[https://support.apple.com/en-us/HT201586][Apple]].)
+
+Currently, this doesn't work in Emacs.
+
+Note that "ns-win.el" explicitly disables this.
+
+Note: This feature might not be allowed to be implemented until also
+implemented in Emacs for a free system.
+
+** Floating scroll bars
+
+In modern OS X applications, the scroll bar often float over the
+content, and is invisible unless actually used. This makes user
+interface less cluttered and more area could be used to contain text.
+
+With floating scroll bars, the user interface would look like it does
+when they are disabled today. However, they will be made visible when
+a scroll action is initiated, e.g. by putting two fingers on a
+trackpad.
+
+Note: This feature might not be allowed to be implemented until also
+implemented in Emacs for a free system.
+
+* Features from the "mac" port
+
+This section contains features available in the "mac" Emacs port.
+
+As the "mac" port (as of this writing) isn't an official Emacs port,
+it might contain features not following the FSF rule "must exist on
+free systems".
+
+The "mac" port is based on the Emacs 22 C-based Carbon interface. It
+has been maintained in parallel to the official Cocoa-based NS
+interface. The Carbon interface has been enhanced, and a number of the
+features of that interface could be implemented NS.
+
+** Smooth scrolling -- maybe not a good idea
+
+Today, by default, scrolling with a trackpad makes the text move in
+steps of five lines. (Scrolling with SHIFT scrolls one line at a
+time.)
+
+The "mac" port provides smooth, pixel-based, scrolling. This is a very
+popular features. However, there are drawbacks to this method: what
+happens if only a fraction of a line is visible at the top of a
+window, is the partially visible text considered part of the window or
+not? (Technically, what should `window-start' return.)
+
+An alternative would be to make one-line scrolling the default on NS
+(or in Emacs in general).
+
+Note: This feature might not be allowed to be implemented until also
+implemented in Emacs for a free system.
+
+** Mouse gestures
+
+The "mac" port defines the gestures `swipe-left/right/up/down',
+`magnify-up/down', and `rotate-left/right'.
+
+It also binds the magnification commands to change the font
+size. (This should be not be done in a specific interface, instead
+Emacs should do this binding globally.)
+
+Note: This feature might not be allowed to be implemented until also
+implemented in Emacs for a free system.
+
+** Synthesize bold fonts
+
+* Open issues
+
+This section contains issues where there is an ongoing debate.
+
+** Key bindings of CMD and ALT
+
+Currently in the "ns" port, ALT is bound to Meta and CMD is bound to
+Super -- allowing the user to use typical OS X commands like CMD-A to
+mark everything.
+
+Unfortunately, when using an international keyboard, you can't type
+normal characters like "(" etc.
+
+There are many alternative key bindings. One solution is to bind CMD
+to Meta and pass ALT to the system. In fact, this is what Emacs did up
+to, and including, version 22. Also, this is how the "mac" port binds
+the keys.
+
+One could envision asymmetrical variants as well, however, this is
+inappropriate for the default setting.
+
+See the discussion on emacs-devel [[https://lists.gnu.org/archive/html/emacs-devel/2015-12/msg01575.html][part 1]] and [[https://lists.gnu.org/archive/html/emacs-devel/2016-01/msg00008.html][part 2]].
+
+* Bugs
+
+This sections contains a small selection of bugs which are hard to
+fix. For other bugs, see the official bug tracker debbugs.gnu.org.
+
+** Incorrect translation of Super modifier with Ctrl or Meta on OS X
+
+When pressing `M-s-a', Emacs replies "M-s-å is undefined". What
+happened is a mix of Emacs view that Meta and Super has been pressed,
+and OS X view that ALT-a should yield "å".
+
+The bug reports suggests two different patched, unfortunately, none
+work properly. For example:
+
+ Use a Swedish keyboard layout
+
+ (setq ns-alternate-modifier nil)
+
+ "CMD-ALT-9"
+
+Today, this correctly yields that s-] is undefined. With the either
+of the two patches, Emacs responds that s-9 was pressed.
+
+More investigation is needed to fix this problem.
+
+Links:
+- [[http://debbugs.gnu.org/cgi/bugreport.cgi?bug%3D19977][bug#19977]]
+- [[http://debbugs.gnu.org/cgi/bugreport.cgi?bug%3D21330][bug#21330]]
+- [[http://debbugs.gnu.org/cgi/bugreport.cgi?bug%3D21551][bug#21551]]
+
+** Toggline the toolbar in fullheight or maximized modes
+
+The toolbar, in the NS interface, is not considered part of the text
+area. When it is toggled, the Emacs frame change height accordingly.
+
+Unfortunately, this also occurs when the frame is in fullheight or
+maximized modes (N.B. this is not the same as "fullscreen"). The
+effect is that the full frame size either increases (stretching down
+below the lower edge of the screen) or decreases (leaving space
+between the lower edge of the frame and the lower edge of the screen).
+
+A better solution would be for the frame to retain its size,
+i.e. change the text area.
+
+This is related to the `frame-inhibit-implied-resize' issue.
+
+* Internal development features
+
+** Regression test system (or at least a checklist)
+
+Today, after each change to the user interface, Emacs must be manually
+tested. Often, small details are overlooked ("Oh, I didn't test
+toggling the tool-bar in one of the full screen modes, when multiple
+frame were open -- silly me.")
+
+It would be an enormous help if this could be tested automatically.
+Many features are generic, however, the NS interface provides a number
+of unique features.
+
+*** Existing packages
+
+Note that there is a generic UI test named "[[http://debbugs.gnu.org/cgi/bugreport.cgi?bug%3D21415#284][frame-test.el]]". The NS
+interface pass this, with the exception of two toolbar related
+errors.
+
+*** Anders frame test
+
+Anders Lindgren <andlind@gmail.com> has implmented some (very basic)
+tests for full screen, toolbar, and auto-hiding the menu bar.
+
+** Make sure all build variants work
+
+Emacs can be build in a number of different ways. For each feature,
+consider if is really is "NS" specific, or if it should be applied to
+all build versions.
+
+- With the "NS" interface. This is the normal way to build Emacs on
+ OS X.
+
+- With the "X11" interface. On OS X, this is mainly of interest to
+ developers of Emacs to get a "reference" interface implementations.
+ However, it might be of interest for people working remotely, as X11
+ applications can be used over a network connection.
+
+- Console only.
projects / emacs.git / commitdiff