patches: split VoiceOver into 3-patch series, improve docs

Split the monolithic 3011-line patch into logical pieces:
  0001: All new accessibility code (infrastructure, no existing code modified)
  0002: EmacsView integration + cursor tracking (wiring only)
  0003: Documentation (expanded with known limitations)

Improvements:
- Comprehensive commit messages with testing methodology
- Known limitations documented (text cap, bidi, mode-line icons)
- Documentation expanded with Known Limitations section
- Each patch is self-contained and reviewable

patches/0003-doc-add-VoiceOver-accessibility-section-to-macOS-app.patch

@@ -0,0 +1,113 @@
+From 12440652eb52520da0714f1762e037836bda7b5b Mon Sep 17 00:00:00 2001
+From: Martin Sukany <martin@sukany.cz>
+Date: Sat, 28 Feb 2026 09:33:23 +0100
+Subject: [PATCH 3/3] 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, the ns-accessibility-enabled user option, and known
+limitations (text cap, mode-line icon fonts, bidi hit-testing).
+
+* doc/emacs/macos.texi (VoiceOver Accessibility): New section.
+---
+ doc/emacs/macos.texi | 75 ++++++++++++++++++++++++++++++++++++++++++++
+ 1 file changed, 75 insertions(+)
+
+diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi
+index 6bd334f..c4dced5 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,80 @@ 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)
++@cindex Zoom, cursor tracking (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}.
++
++@subheading Known Limitations
++
++@itemize @bullet
++@item
++Accessibility text is capped at 100,000 UTF-16 units per window.
++Buffers exceeding this limit are truncated for accessibility purposes;
++VoiceOver will announce ``end of text'' at the cap boundary.
++@item
++Mode-line text extraction handles only character glyphs.  Mode lines
++using icon fonts (e.g., @code{doom-modeline} with nerd-font icons)
++produce incomplete accessibility text.
++@item
++The accessibility virtual element tree is rebuilt automatically on
++window configuration changes (splits, deletions, new buffers).
++@item
++Right-to-left (bidi) text is exposed correctly as buffer content,
++but @code{accessibilityRangeForPosition} hit-testing assumes
++left-to-right glyph layout.
++@end itemize
++
++  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
+