From 402e57ae2d0e45ec8b95fcffc3d34ae3279ae152 Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Wed, 19 Mar 2025 14:43:34 +0530 Subject: [PATCH] Improve docs formatting --- docs/shell-integration.rst | 35 +++++++++++++++++++++++++---------- 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/docs/shell-integration.rst b/docs/shell-integration.rst index b403139fc..04a96ec47 100644 --- a/docs/shell-integration.rst +++ b/docs/shell-integration.rst @@ -421,19 +421,27 @@ The protocol used for marking the prompt is very simple. You should consider adding it to your shell as a builtin. Many modern terminals make use of it, for example: kitty, iTerm2, WezTerm, DomTerm -Just before starting to draw the PS1 prompt send the escape code:: +Just before starting to draw the PS1 prompt send the escape code: + +.. code-block:: none 133;A -Just before starting to draw the PS2 prompt send the escape code:: +Just before starting to draw the PS2 prompt send the escape code: + +.. code-block:: none 133;A;k=s -Just before running a command/program, send the escape code:: +Just before running a command/program, send the escape code: + +.. code-block:: none 133;C -Optionally, when a command is finished its "exit status" can be reported as:: +Optionally, when a command is finished its "exit status" can be reported as: + +.. code-block:: none 133;D;exit status as base 10 integer @@ -443,27 +451,34 @@ full protocol, that also marks the command region, see `the iTerm2 docs `_. kitty additionally supports several extra fields for the ``133;A`` command -to control its behavior, separated by semi-colons. They are:: +to control its behavior, separated by semi-colons. They are: - redraw=0 - this tells kitty that the shell will not redraw the prompt on + +``redraw=0`` + this tells kitty that the shell will not redraw the prompt on resize so it should not erase it - special_key=1 - this tells kitty to use a special key instead of arrow keys +``special_key=1`` + this tells kitty to use a special key instead of arrow keys to move the cursor on mouse click. Useful if arrow keys have side-effects like triggering auto complete. The shell integration script then binds the special key, as needed. - k=s - this tells kitty that the secondary (PS2) prompt is starting at the +``k=s`` + this tells kitty that the secondary (PS2) prompt is starting at the current line. - click_events=1 - this tells kitty that the shell is capable of handling +``click_events=1`` + this tells kitty that the shell is capable of handling mouse click events. kitty will thus send a click event to the shell when the user clicks somewhere in the prompt. The shell can then move the cursor to that position or perform some other appropriate action. Without this, kitty will instead generate a number of fake key events to move the cursor to the clicked location, which is not fully robust. -kitty also optionally supports sending the cmdline going to be executed with ``133;C`` as:: +kitty also optionally supports sending the cmdline going to be executed with ``133;C`` as: + +.. code-block:: none 133;C;cmdline=cmdline encoded by %q or