From c5f72aa573bc45b82ad6479ae0eba5ffc7916fb9 Mon Sep 17 00:00:00 2001 From: Anders Lindgren Date: Sat, 20 Feb 2016 16:24:40 +0100 Subject: [PATCH] Update NextStep readme and add wish list. * nextstep/README: Rewritten from scratch. New sections on "History", "Overview of Cocoa and Objective-C", "Guidelines", "Tracing Support", and "GNUStep". Expanded the "See Also" section. * nextstep/WISHLIST: New file containing list of issues and ideas associated with the NS port of Emacs. --- nextstep/README | 102 ++++++++++++++++++- nextstep/WISHLIST | 247 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 346 insertions(+), 3 deletions(-) create mode 100644 nextstep/WISHLIST diff --git a/nextstep/README b/nextstep/README index 45b9b23ee10..c16d55b35b9 100644 --- a/nextstep/README +++ b/nextstep/README @@ -1,4 +1,100 @@ -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. diff --git a/nextstep/WISHLIST b/nextstep/WISHLIST new file mode 100644 index 00000000000..673f091b7b4 --- /dev/null +++ b/nextstep/WISHLIST @@ -0,0 +1,247 @@ + -*- 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 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 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. -- 2.39.2