docs(config): document the opt-in hint.enable key

commit: c17152b76ac55e2fa670740674041694efca614a
author: brice · 3d ago · 2026-10-19 15:01 UTC
parent: d5dd8bf
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

2 files · +10 -3

M docs/config.md +8 -3


@@ -55,6 +55,7 @@ See [examples/config](../examples/config) for every key with its default.
55	55		\| `focus.flash-opacity` \| `0.6` \| Starting opacity of the flash, `0.1` to `1` \|
56	56		\| `focus.flash-duration` \| `200ms` \| Fade duration, `50ms` to `1s`; not scaled by `animations.speed` \|
57	57		\| `focus.flash-color` \| `border.active` \| Flash color `#rrggbb`; empty uses `border.active` \|
	58	+	\| `hint.enable` \| `off` \| Turn on the experimental [hint mode](#hint-mode) (restart required) \|
58	59		\| `hint.targets` \| `clickable` \| What [hint mode](#hint-mode) labels: `clickable` (links, URLs and buttons) or `links` (links and URLs only) \|
59	60		\| `hint.text-click` \| `ctrl+shift` \| Modifiers held for clicks on links found by OCR (terminals open links on a modified click); `none` sends a plain click \|
60	61		\| `hint.size` \| `auto` \| Label text size in logical pixels (positive number), or `auto` for screen pixel density \|

@@ -304,6 +305,10 @@ Otherwise, left from the first column unfolds the stash. Up/down walk the cards,
304	305
305	306		## Hint mode
306	307
	308	+	Hint mode is experimental and off by default: set `hint.enable = on` and restart NeferWL.
	309	+	While it is off, nothing of hint mode runs or uses memory, and the `hint` bind
	310	+	logs a notice once and does nothing. A reload does not change it.
	311	+
307	312		`hint` labels the links and buttons on the focused output. Type a label to
308	313		click its target; BackSpace erases a letter, Escape cancels. No bind is set
309	314		by default; for example `bind.cmd+g = hint`.

@@ -332,9 +337,9 @@ or low-contrast text.
332	337		- Chromium: `--force-renderer-accessibility`
333	338		- Electron: `ACCESSIBILITY_ENABLED=1`
334	339		- Qt: `QT_LINUX_ACCESSIBILITY_ALWAYS_ON=1`
335		-	- OCR: `tesseract` and `tesseract-data-eng`. Without them, only apps with
336		-	accessibility get labels.
	340	+	- OCR: `tesseract` and `tesseract-data-eng`. Without tesseract, OCR is off
	341	+	and hint mode labels only apps that expose the accessibility tree.
337	342
338	343		### Debugging hint mode
339	344
340		-	With `NEFERWL_HINT_DEBUG=1` set when NeferWL starts (for example `NEFERWL_HINT_DEBUG=1 make tty`, or the variable in the launch environment), every successful scan writes three files to `$XDG_STATE_HOME/neferwl/hints/` (`~/.local/state/neferwl/hints/` when unset): `<time>-<output>.png`, the frame as scanned; `<time>-<output>.annotated.png`, the same with each target outlined (OCR links green, accessibility targets magenta, OCR window crops grey); and `<time>-<output>.json`, the targets (with their `source`, `atspi` or `ocr`) and timings. NeferWL keeps the 50 most recent scans and logs a warning at startup. The files contain the screen in clear: delete them after use.
	345	+	With `hint.enable = on` and `NEFERWL_HINT_DEBUG=1` set when NeferWL starts (for example `NEFERWL_HINT_DEBUG=1 make tty`, or the variable in the launch environment), every successful scan writes three files to `$XDG_STATE_HOME/neferwl/hints/` (`~/.local/state/neferwl/hints/` when unset): `<time>-<output>.png`, the frame as scanned; `<time>-<output>.annotated.png`, the same with each target outlined (OCR links green, accessibility targets magenta, OCR window crops grey); and `<time>-<output>.json`, the targets (with their `source`, `atspi` or `ocr`) and timings. NeferWL keeps the 50 most recent scans and logs a warning at startup. The files contain the screen in clear: delete them after use.

 | `focus.flash-opacity` | `0.6` | Starting opacity of the flash, `0.1` to `1` |
 | `focus.flash-duration` | `200ms` | Fade duration, `50ms` to `1s`; not scaled by `animations.speed` |
 | `focus.flash-color` | `border.active` | Flash color `#rrggbb`; empty uses `border.active` |
+| `hint.enable` | `off` | Turn on the experimental [hint mode](#hint-mode) (restart required) |
 | `hint.targets` | `clickable` | What [hint mode](#hint-mode) labels: `clickable` (links, URLs and buttons) or `links` (links and URLs only) |
 | `hint.text-click` | `ctrl+shift` | Modifiers held for clicks on links found by OCR (terminals open links on a modified click); `none` sends a plain click |
 | `hint.size` | `auto` | Label text size in logical pixels (positive number), or `auto` for screen pixel density |
 ## Hint mode
+Hint mode is experimental and off by default: set `hint.enable = on` and restart NeferWL.
+While it is off, nothing of hint mode runs or uses memory, and the `hint` bind
+logs a notice once and does nothing. A reload does not change it.
 `hint` labels the links and buttons on the focused output. Type a label to
 click its target; BackSpace erases a letter, Escape cancels. No bind is set
 by default; for example `bind.cmd+g = hint`.
   - Chromium: `--force-renderer-accessibility`
   - Electron: `ACCESSIBILITY_ENABLED=1`
   - Qt: `QT_LINUX_ACCESSIBILITY_ALWAYS_ON=1`
-- OCR: `tesseract` and `tesseract-data-eng`. Without them, only apps with
+- OCR: `tesseract` and `tesseract-data-eng`. Without tesseract, OCR is off
-  accessibility get labels.
+  and hint mode labels only apps that expose the accessibility tree.
 ### Debugging hint mode
-With `NEFERWL_HINT_DEBUG=1` set when NeferWL starts (for example `NEFERWL_HINT_DEBUG=1 make tty`, or the variable in the launch environment), every successful scan writes three files to `$XDG_STATE_HOME/neferwl/hints/` (`~/.local/state/neferwl/hints/` when unset): `<time>-<output>.png`, the frame as scanned; `<time>-<output>.annotated.png`, the same with each target outlined (OCR links green, accessibility targets magenta, OCR window crops grey); and `<time>-<output>.json`, the targets (with their `source`, `atspi` or `ocr`) and timings. NeferWL keeps the 50 most recent scans and logs a warning at startup. The files contain the screen in clear: delete them after use.
+With `hint.enable = on` and `NEFERWL_HINT_DEBUG=1` set when NeferWL starts (for example `NEFERWL_HINT_DEBUG=1 make tty`, or the variable in the launch environment), every successful scan writes three files to `$XDG_STATE_HOME/neferwl/hints/` (`~/.local/state/neferwl/hints/` when unset): `<time>-<output>.png`, the frame as scanned; `<time>-<output>.annotated.png`, the same with each target outlined (OCR links green, accessibility targets magenta, OCR window crops grey); and `<time>-<output>.json`, the targets (with their `source`, `atspi` or `ocr`) and timings. NeferWL keeps the 50 most recent scans and logs a warning at startup. The files contain the screen in clear: delete them after use.

M examples/config +2 -0


@@ -94,6 +94,8 @@ focus.flash-width = 2
94	94		focus.flash-opacity = 0.6
95	95		focus.flash-duration = 200ms
96	96		focus.flash-color =
	97	+	# Hint mode is experimental and off: turn it on here (restart required).
	98	+	# hint.enable = off
97	99		# Hint mode labels the links, URLs and buttons on the focused screen:
98	100		# clickable (links, URLs and buttons) or links (links and URLs only).
99	101		# hint.targets = clickable


@@ -94,6 +94,8 @@ focus.flash-width = 2
94	focus.flash-opacity = 0.6	94		focus.flash-opacity = 0.6
95	focus.flash-duration = 200ms	95		focus.flash-duration = 200ms
96	focus.flash-color =	96		focus.flash-color =
		97	+	# Hint mode is experimental and off: turn it on here (restart required).
		98	+	# hint.enable = off
97	# Hint mode labels the links, URLs and buttons on the focused screen:	99		# Hint mode labels the links, URLs and buttons on the focused screen:
98	# clickable (links, URLs and buttons) or links (links and URLs only).	100		# clickable (links, URLs and buttons) or links (links and URLs only).
99	# hint.targets = clickable	101		# hint.targets = clickable