From ce3b2a8091c99f738ec59acd6f6ebf0d84826e34 Mon Sep 17 00:00:00 2001 From: Martin Sukany Date: Fri, 27 Feb 2026 17:49:51 +0100 Subject: [PATCH 2/2] doc: add VoiceOver accessibility section to macOS appendix Document the new VoiceOver accessibility support in the Emacs manual. Add a new section to the macOS appendix covering screen reader usage, keyboard navigation feedback, completion announcements, Zoom cursor tracking, and the ns-accessibility-enabled user option. * doc/emacs/macos.texi (VoiceOver Accessibility): New section. --- doc/emacs/macos.texi | 53 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi index 6bd334f..1d969f9 100644 --- a/doc/emacs/macos.texi +++ b/doc/emacs/macos.texi @@ -36,6 +36,7 @@ Support}), but we hope to improve it in the future. * Mac / GNUstep Basics:: Basic Emacs usage under GNUstep or macOS. * Mac / GNUstep Customization:: Customizations under GNUstep or macOS. * Mac / GNUstep Events:: How window system events are handled. +* VoiceOver Accessibility:: Screen reader support on macOS. * GNUstep Support:: Details on status of GNUstep support. @end menu @@ -272,6 +273,58 @@ and return the result as a string. You can also use the Lisp function services and receive the results back. Note that you may need to restart Emacs to access newly-available services. +@node VoiceOver Accessibility +@section VoiceOver Accessibility (macOS) +@cindex VoiceOver +@cindex accessibility (macOS) +@cindex screen reader (macOS) + + When built with the Cocoa interface on macOS, Emacs exposes buffer +content, cursor position, mode lines, and interactive elements to the +macOS accessibility subsystem. This enables use with VoiceOver, +Apple's built-in screen reader, and with other assistive technology +such as macOS Zoom. + + Toggle VoiceOver with @kbd{Cmd-F5} (or via System Settings, +Accessibility, VoiceOver). When Emacs is focused, VoiceOver announces +the buffer name and current line. Standard Emacs navigation produces +speech feedback: + +@itemize @bullet +@item +Arrow keys read individual characters (left/right) or full lines +(up/down). +@item +@kbd{M-f} and @kbd{M-b} announce words. +@item +@kbd{C-n} and @kbd{C-p} read the destination line. +@item +Shift-modified movement announces selected or deselected text. +@item +@key{TAB} and @kbd{S-@key{TAB}} navigate interactive elements +(buttons, links, completion candidates) within a buffer. +@end itemize + + The @file{*Completions*} buffer announces each completion candidate +as you navigate, even while keyboard focus remains in the minibuffer. + + macOS Zoom (System Settings, Accessibility, Zoom) tracks the Emacs +cursor automatically when set to follow keyboard focus. The cursor +position is communicated via @code{UAZoomChangeFocus} and the +@code{AXBoundsForRange} accessibility attribute. + +@vindex ns-accessibility-enabled + To disable the accessibility interface entirely (for instance, to +eliminate overhead on systems where assistive technology is not in +use), set @code{ns-accessibility-enabled} to @code{nil}. The default +is @code{t}. + + This support is available only on the Cocoa build; GNUstep has a +different accessibility model and is not yet supported +(@pxref{GNUstep Support}). Evil-mode block cursors are handled +correctly: character navigation announces the character at the cursor +position, not the character before it. + @node GNUstep Support @section GNUstep Support -- 2.43.0