docs: OSC 133 shell config #32771

2 files changed, 35 insertions, 8 deletions

diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt
index 284be09121..48fa723800 100644
--- a/runtime/doc/motion.txt
+++ b/runtime/doc/motion.txt
@@ -455,6 +455,8 @@ between Vi and Vim.
 			first column.  When used after an operator, then also
 			stops below a "}" in the first column.  |exclusive|
 			Note that |exclusive-linewise| often applies.
+			In a :terminal buffer each shell prompt is treated as
+			a section. |terminal_]]|
 
 							*][*
 ][			[count] |section|s forward or to the next '}' in the
@@ -465,6 +467,8 @@ between Vi and Vim.
 [[			[count] |section|s backward or to the previous "{" in
 			the first column.  |exclusive|
 			Note that |exclusive-linewise| often applies.
+			In a :terminal buffer each shell prompt is treated as
+			a section. |terminal_]]|
 
 							*[]*
 []			[count] |section|s backward or to the previous "}" in
@@ -498,6 +502,7 @@ A section begins after a form-feed (<C-L>) in the first column and at each of
 a set of section macros, specified by the pairs of characters in the
 'sections' option.  The default is "SHNHH HUnhsh", which defines a section to
 start at the nroff macros ".SH", ".NH", ".H", ".HU", ".nh" and ".sh".
+In a :terminal buffer each shell prompt is treated as a section. |terminal_]]|
 
 The "]]" and "[[" commands stop at the '{' in the first column.  This is
 useful to find the start of a function in a C program.  To search for a '}' in
diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt
index 99761c9c80..ea8a1c2565 100644
--- a/runtime/doc/terminal.txt
+++ b/runtime/doc/terminal.txt
@@ -187,26 +187,48 @@ event. The event is handled directly by Nvim and is not forwarded to plugins.
 
 OSC 133: shell integration			*terminal-osc133*
 
-Some shells will emit semantic escape sequences (OSC 133) to mark the
-beginning and end of a prompt. The start of a prompt is marked with the
-sequence `OSC 133 ; A`. Nvim can be configured to create signs in terminal
-buffers marking shell prompts. Example: >lua
+Shells can emit semantic escape sequences (OSC 133) to mark where each prompt
+starts and ends. The start of a prompt is marked by sequence `OSC 133 ; A ST`,
+and the end by `OSC 133 ; B ST`.
+
+                                                *shell-prompt-config*
+You can configure your shell "rc" (e.g. ~/.bashrc) to emit OSC 133 sequences,
+or your terminal may attempt to do it for you (assuming your shell config
+doesn't interfere).
+
+- fish: https://fishshell.com/docs/current/relnotes.html#improved-terminal-support
+- kitty: https://sw.kovidgoyal.net/kitty/shell-integration/
+- vscode: https://code.visualstudio.com/docs/terminal/shell-integration
+
+To configure bash to mark the start/end of each prompt, set $PROMPT_COMMAND
+and $PS1 as follows: >bash
+
+    # Prompt start:
+    PROMPT_COMMAND='printf "\033]133;A\007"'
+    # Prompt end:
+    PS1="$PS1"'\033]133;B\007'
+<
+                                                *terminal_]]* *terminal_[[*
+The |]]| and |[[| motions jump to the next/previous prompts, if your shell
+emits OSC 133 as described above.
+
+						*terminal-shell-prompt-signs*
+To annotate each terminal prompt with a sign, call |nvim_buf_set_extmark()|
+from a |TermRequest| handler: >lua
 
-    local ns = vim.api.nvim_create_namespace('terminal_prompt_markers')
+    local ns = vim.api.nvim_create_namespace('my.terminal.prompt')
     vim.api.nvim_create_autocmd('TermRequest', {
       callback = function(args)
         if string.match(args.data.sequence, '^\027]133;A') then
           local lnum = args.data.cursor[1]
           vim.api.nvim_buf_set_extmark(args.buf, ns, lnum - 1, 0, {
-            -- Replace with sign text and highlight group of choice
             sign_text = '▶',
             sign_hl_group = 'SpecialChar',
           })
         end
       end,
     })
-
-    -- Enable signcolumn in terminal buffers
+    -- Enable signcolumn in terminal buffers.
     vim.api.nvim_create_autocmd('TermOpen', {
       command = 'setlocal signcolumn=auto',
     })