matplotlib · andrzejnovak · Aug 28, 2019 · Aug 28, 2019 · Aug 28, 2019 · Aug 28, 2019
diff --git a/doc/users/next_whats_new/option_between_for_step_fill_between.rst b/doc/users/next_whats_new/option_between_for_step_fill_between.rst
@@ -0,0 +1,22 @@
+New drawstyles for steps - "steps-between", "steps-edges"
+------------------------------------------------------------------------
+They are asymmetrical such that abs(len(x) - len(y)) == 1.  Typically
+to enable plotting histograms with step() and fill_between().
+
+  .. plot::
+
+    import numpy as np
+    import matplotlib.pyplot as plt
+
+    x = np.arange(0,7,1)
+    y = np.array([2,3,4,5,4,3])
+
+    fig, ax = plt.subplots(constrained_layout=True)
+
+    ax.plot(x, y + 2, drawstyle='steps-between')
+    ax.plot(x, y, drawstyle='steps-edges')
+
+    plt.show()
+
+See :doc:`/gallery/lines_bars_and_markers/step_demo` and
+:doc:`/gallery/lines_bars_and_markers/filled_step` for examples.
diff --git a/examples/lines_bars_and_markers/filled_step.py b/examples/lines_bars_and_markers/filled_step.py
@@ -1,9 +1,9 @@
 """
 =========================
-Hatch-filled histograms
+Filled histograms
 =========================
 
-Hatching capabilities for plotting histograms.
+Filled histograms and hatching capabilities for plotting histograms.
 """
 
 import itertools
@@ -15,6 +15,30 @@
 import matplotlib.ticker as mticker
 from cycler import cycler
 
+###############################################################################
+# Plain filled steps
+
+# sphinx_gallery_thumbnail_number = 2
+
+fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(9, 4.5), tight_layout=True)
+ax1.fill_between([0, 1, 2, 3], [1, 2, 3], step='between')
+ax2.fill_betweenx([0, 1, 2, 3], [0, 1, 2], step='between')
+ax1.set_ylabel('counts')
+ax1.set_xlabel('edges')
+ax2.set_xlabel('counts')
+ax2.set_ylabel('edges')
+
+fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(9, 4.5), tight_layout=True)
+ax1.fill_between([0, 1, 2, 3], [1, 2, 3], [0, 1, 0], step='between')
+ax2.fill_betweenx([0, 1, 2, 3], [1, 2, 3], [0, 1, 0], step='between')
+ax1.set_ylabel('counts')
+ax1.set_xlabel('edges')
+ax2.set_xlabel('counts')
+ax2.set_ylabel('edges')
+
+
+###############################################################################
+# Hatches
 
 def filled_hist(ax, edges, values, bottoms=None, orientation='v',
                 **kwargs):

diff --git a/examples/lines_bars_and_markers/step_demo.py b/examples/lines_bars_and_markers/step_demo.py
@@ -49,6 +49,20 @@
 plt.title('plt.plot(drawstyle=...)')
 plt.show()
 
+# Plotting with where='between'/'edges'
+x = np.arange(0, 7, 1)
+y = np.array([2, 3, 4, 5, 4, 3])
+
+fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 5))
+ax1.step(x, y + 2, where='between', label='between')
+ax1.step(x, y, where='edges', label='edges')
+ax1.legend(title='Parameter where:')
+
+ax2.step(y + 2, x, where='between', label='between')
+ax2.step(y, x, where='edges', label='edges')
+ax2.legend(title='Parameter where:')
+
+plt.show()
 #############################################################################
 #
 # ------------