Update docs for transient prompt

Closes #11153

CHANGELOG.rst

@@ -4,7 +4,7 @@ fish 4.1.0 (released ???)
 Notable improvements and fixes
 ------------------------------
 - Compound commands (``begin; echo 1; echo 2; end``) can now be now be abbreviated using braces (``{ echo1; echo 2 }``), like in other shells.
-- Fish now supports transient prompts: if ``fish_transient_prompt`` is set to 1, fish will reexecute prompt functions with the ``--final-rendering`` argument before running a commandline.
+- Fish now supports transient prompts: if :envvar:`fish_transient_prompt` is set to 1, fish will reexecute prompt functions with the ``--final-rendering`` argument before running a commandline.
 - When tab completion results are truncated, any common directory name is omitted. E.g. if you complete "share/functions", and it includes the files "foo.fish" and "bar.fish",
   the completion pager will now show "…/foo.fish" and "…/bar.fish". This will make the candidates shorter and allow for more to be shown at once.
 - The self-installing configuration introduced in fish 4.0 has been changed.

doc_src/cmds/fish_mode_prompt.rst

@@ -31,6 +31,8 @@ You can also define an empty ``fish_mode_prompt`` function to remove the vi mode
 
 ``fish_mode_prompt`` will be executed when the vi mode changes. If it produces any output, it is displayed and used. If it does not, the other prompt functions (:doc:`fish_prompt <fish_prompt>` and :doc:`fish_right_prompt <fish_right_prompt>`) will be executed as well in case they contain a mode display.
 
+If :envvar:`fish_transient_prompt` is set to 1, ``fish_mode_prompt --final-rendering`` is run before executing the commandline.
+
 Example
 -------
 

doc_src/cmds/fish_prompt.rst

@@ -20,11 +20,11 @@ Synopsis
 Description
 -----------
 
-The ``fish_prompt`` function is executed when the prompt is to be shown and, if ``fish_transient_prompt`` is set to 1, before running a commandline. The output of this function is used as a prompt.
+The ``fish_prompt`` function is executed when the prompt is to be shown, and the output is used as a prompt.
 
 The exit status of commands within ``fish_prompt`` will not modify the value of :ref:`$status <variables-status>` outside of the ``fish_prompt`` function.
 
-When the function is executed before running a commandline, it is passed a ``--final-rendering`` argument.
+If :envvar:`fish_transient_prompt` is set to 1, ``fish_prompt --final-rendering`` is run before executing the commandline.
 
 ``fish`` ships with a number of example prompts that can be chosen with the ``fish_config`` command.
 

doc_src/cmds/fish_right_prompt.rst

@@ -20,6 +20,8 @@ Description
 
 Multiple lines are not supported in ``fish_right_prompt``.
 
+If :envvar:`fish_transient_prompt` is set to 1, ``fish_right_prompt --final-rendering`` is run before executing the commandline.
+
 
 Example
 -------

doc_src/interactive.rst

@@ -217,7 +217,7 @@ This prompt is determined by running the :doc:`fish_prompt <cmds/fish_prompt>` a
 The output of the former is displayed on the left and the latter's output on the right side of the terminal.
 For :ref:`vi mode <vi-mode>`, the output of :doc:`fish_mode_prompt <cmds/fish_mode_prompt>` will be prepended on the left.
 
-If ``fish_transient_prompt`` is set to 1, fish will redraw the prompt with a ``--final-rendering`` argument before running a commandline, allowing you to change it before pushing it to the scrollback.
+If :envvar:`fish_transient_prompt` is set to 1, fish will redraw the prompt with a ``--final-rendering`` argument before running a commandline, allowing you to change it before pushing it to the scrollback.
 
 Fish ships with a few prompts which you can see with :doc:`fish_config <cmds/fish_config>`. If you run just ``fish_config`` it will open a web interface [#]_ where you'll be shown the prompts and can pick which one you want. ``fish_config prompt show`` will show you the prompts right in your terminal.
 

doc_src/language.rst

@@ -1585,6 +1585,10 @@ You can change the settings of fish by changing the values of certain variables.
 
    controls if :ref:`autosuggestions` are enabled. Set it to 0 to disable, anything else to enable. By default they are on.
 
+.. envvar:: fish_transient_prompt
+
+   If this is set to 1, fish will redraw prompts with a ``--final-rendering`` argument before running a commandline, allowing you to change it before pushing it to the scrollback. This enables :ref:`transient prompts <transient-prompt>`.
+
 .. envvar:: fish_handle_reflow
 
    determines whether fish should try to repaint the commandline when the terminal resizes. In terminals that reflow text this should be disabled. Set it to 1 to enable, anything else to disable.

doc_src/prompt.rst

@@ -153,10 +153,12 @@ And it looks like:
 
 after we run ``false`` (which returns 1).
 
+.. _transient-prompt:
+
 Transient prompt
 ----------------
 
-To enable transient prompt functionality, set the ``fish_transient_prompt`` variable to 1::
+To enable transient prompt functionality, set the :envvar:`fish_transient_prompt` variable to 1::
 
   set -g fish_transient_prompt 1
 
@@ -181,7 +183,7 @@ So you can use it to declutter your old prompts. For example if you want to see
       string join '' -- (set_color green) $pwd (set_color normal) $stat '>'
   end
 
-Now this would print:
+Now running two commands in the same directory could result in this screen:
 
 .. role:: green
 .. role:: red

doc_src/tutorial.rst

@@ -649,31 +649,10 @@ This prompt would look like:
     :purple:`02/06/13`
     :red:`/home/tutorial >` _
 
-You can make your prompt transient by setting ``fish_transient_prompt`` to 1. That means fish will redraw the prompt before running a commandline, so you can change it then. Usually this is used to trim it down to declutter your terminal's scrollback history. When it runs the prompt again, it will pass a ``--final-rendering`` argument, so check for this to distinguish::
 
-    function fish_prompt
-        if contains -- --final-rendering $argv
-            set_color F00
-            echo '$' (set_color normal)
-        else
-            set_color purple
-            date "+%m/%d/%y"
-            set_color F00
-            echo (pwd) '>' (set_color normal)
-        end
-    end
+See also :doc:`Writing your own prompt <prompt>`.
 
-
-This would look like:
-
-.. parsed-literal::
-    :class: highlight
-
-    :red:`$` command
-    :purple:`02/06/13`
-    :red:`/home/tutorial >` _
-
-You can choose among some sample prompts by running ``fish_config`` for a web UI or ``fish_config prompt`` for a simpler version inside your terminal.
+You can choose among sample prompts by running ``fish_config`` for a web UI or ``fish_config prompt`` for a simpler version inside your terminal.
 
 $PATH
 -----