matplotlib
diff --git a/‎tutorials/introductory/usage.py
Lines changed: 81 additions & 1 deletion b/‎tutorials/introductory/usage.py
Lines changed: 81 additions & 1 deletion
@@ -250,18 +250,98 @@ def my_plotter(ax, data1, data2, param_dict):
 #
 # Multiple axes can be added a number of ways, but the most basic is
 # ``plt.subplots()`` as used above.  One can achieve more complex layouts,
-# with axes spanning columns or rows, using `~.pyplot.subplot_mosaic`:
+# with axes spanning columns or rows, using `~.pyplot.subplot_mosaic`.
 
 fig, axd = plt.subplot_mosaic([['upleft', 'right'],
                                ['lowleft', 'right']], constrained_layout=True)
 axd['upleft'].set_title('upleft')
 axd['lowleft'].set_title('lowleft')
 axd['right'].set_title('right')
 
+###############################################################################
+# Matplotlib has quite sophisticated tools for arranging axes: See
+# :doc:`/tutorials/intermediate/arranging_axes` and
+# :doc:`/tutorials/provisional/mosaic`.
+#
+# Working with text
+# =================
+#
+# `~.Axes.text` can be used to add text in an arbitrary location, and
+# `~.Axes.set_xlabel`, `~.Axes.set_ylabel` and `~.Axes.set_title` are used to
+# add text in the indicated locations (see :doc:`/tutorials/text/text_intro` for
+# more discussion)
 
+mu, sigma = 100, 15
+x = mu + sigma * np.random.randn(10000)
+fig, ax = plt.subplots()
+# the histogram of the data
+n, bins, patches = ax.hist(x, 50, density=1, facecolor='g', alpha=0.75)
 
+ax.set_xlabel('Smarts')
+ax.set_ylabel('Probability')
+ax.set_title('Histogram of IQ')
+ax.text(60, .025, r'$\mu=100,\ \sigma=15$')
+ax.axis([40, 160, 0, 0.03])
+ax.grid(True)
+plt.show()
 
+###############################################################################
+# All of the `~.pyplot.text` functions return a `matplotlib.text.Text`
+# instance.  Just as with lines above, you can customize the properties by
+# passing keyword arguments into the text functions::
+#
+#   t = ax.set_xlabel('my data', fontsize=14, color='red')
+#
+# These properties are covered in more detail in :doc:`/tutorials/text/text_props`.
+#
+# Using mathematical expressions in text
+# --------------------------------------
+#
+# matplotlib accepts TeX equation expressions in any text expression.
+# For example to write the expression :math:`\sigma_i=15` in the title,
+# you can write a TeX expression surrounded by dollar signs::
+#
+#     ax.set_title(r'$\sigma_i=15$')
 #
+# The ``r`` preceding the title string signifies that the string is a
+# *raw* string and not to treat backslashes as python escapes.
+# Matplotlib has a built-in TeX expression parser and
+# layout engine, and ships its own math fonts -- for details see
+# :doc:`/tutorials/text/mathtext`.  Thus you can use mathematical text across
+# platforms without requiring a TeX installation.  For those who have LaTeX and
+# dvipng installed, you can also use LaTeX to format your text and
+# incorporate the output directly into your display figures or saved
+# postscript -- see :doc:`/tutorials/text/usetex`.
+#
+#
+# Annotations
+# -----------
+#
+# We can also annotate points on a plot.  There are
+# two points to consider: the location being annotated represented by
+# the argument ``xy`` and the location of the text ``xytext``.  Both of
+# these arguments are ``(x, y)`` tuples:
+
+fig, ax = plt.subplots()
+
+t = np.arange(0.0, 5.0, 0.01)
+s = np.cos(2*np.pi*t)
+line, = ax.plot(t, s, lw=2)
+
+ax.annotate('local max', xy=(2, 1), xytext=(3, 1.5),
+             arrowprops=dict(facecolor='black', shrink=0.05),
+             )
+
+ax.set_ylim(-2, 2)
+plt.show()
+
+###############################################################################
+# In this basic example, both the ``xy`` (arrow tip) and ``xytext``
+# locations (text location) are in data coordinates.  There are a
+# variety of other coordinate systems one can choose -- see
+# :ref:`annotations-tutorial` and :ref:`plotting-guide-annotation` for
+# details.  More examples can be found in
+# :doc:`/gallery/text_labels_and_annotations/annotation_demo`.
 #
 # More reading
 # ============