From f351ffee14af06ec2062a643735d7befcdca8b90 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 30 Mar 2021 22:41:19 +0200
Subject: [PATCH] Backport PR #19822: Clarify default backend selection doc.

---
 doc/sphinxext/custom_roles.py   | 4 +++-
 tutorials/introductory/usage.py | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/doc/sphinxext/custom_roles.py b/doc/sphinxext/custom_roles.py
index 5faa42172a64..0734f2b15ac3 100644
--- a/doc/sphinxext/custom_roles.py
+++ b/doc/sphinxext/custom_roles.py
@@ -16,7 +16,9 @@ def rcparam_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
 
     ref = nodes.reference(rawtext, rendered, refuri=refuri)
     node_list = [nodes.literal('', '', ref)]
-    if text in rcParamsDefault:
+    # The default backend would be printed as "agg", but that's not correct (as
+    # the default is actually determined by fallback).
+    if text in rcParamsDefault and text != "backend":
         node_list.extend([
             nodes.Text(' (default: '),
             nodes.literal('', repr(rcParamsDefault[text])),
diff --git a/tutorials/introductory/usage.py b/tutorials/introductory/usage.py
index 2403d3f0ba5b..5f234e366ce6 100644
--- a/tutorials/introductory/usage.py
+++ b/tutorials/introductory/usage.py
@@ -304,7 +304,9 @@ def my_plotter(ax, data1, data2, param_dict):
 # backend based on what is available on your system and on whether a GUI event
 # loop is already running. On Linux, if the environment variable
 # :envvar:`DISPLAY` is unset, the "event loop" is identified as "headless",
-# which causes a fallback to a noninteractive backend (agg).
+# which causes a fallback to a noninteractive backend (agg); in all other
+# cases, an interactive backend is preferred (usually, at least tkagg will be
+# available).
 #
 # Here is a detailed description of the configuration methods:
 #