@anntzer recently pointed out that we've got a lot of documentation on legends scattered throughout the website. Some has higher quality than others, some has mixed levels of user expertise, some are in unintuitive places. I'm putting a list that @anntzer collected below in case somebody wants to take a stab.

Tutorial:

• Legend guide: http://matplotlib.org/tutorials/intermediate/legend_guide.html#sphx-glr-tutorials-intermediate-legend-guide-py
  quite advanced, probably can use some rewriting but OK.

Examples:

• Legend demo: http://matplotlib.org/gallery/text_labels_and_annotations/legend_demo.html#sphx-glr-gallery-text-labels-and-annotations-legend-demo-py
  Looks somewhere between what this PR proposes and the legend guide. I think this PR is a nice piece of work but I would suggest trying not to spread the same information too thinly across many examples; perhaps the three "narrative" legend examples/tutorials could be merged into two?
• What's new in 0.98.4 legend: http://matplotlib.org/gallery/pyplots/whats_new_98_4_legend.html#sphx-glr-gallery-pyplots-whats-new-98-4-legend-py
  Can probably be deleted and the relevant features split across other examples.
• Polar legend: http://matplotlib.org/gallery/pie_and_polar_charts/polar_legend.html#sphx-glr-gallery-pie-and-polar-charts-polar-legend-py
  Can probably deleted, there's nothing special about legends in polar plots.
• Simple legend 1 and 2: http://matplotlib.org/gallery/userdemo/simple_legend01.html#sphx-glr-gallery-userdemo-simple-legend01-py http://matplotlib.org/gallery/userdemo/simple_legend02.html#sphx-glr-gallery-userdemo-simple-legend02-py
  Should probably be unified.
• Legend picking: http://matplotlib.org/gallery/event_handling/legend_picking.html#sphx-glr-gallery-event-handling-legend-picking-py
  Is really about event handling so can stand by itself.
• Figure legend: http://matplotlib.org/gallery/text_labels_and_annotations/figlegend_demo.html#sphx-glr-gallery-text-labels-and-annotations-figlegend-demo-py
  Should probably be rewritten to use a single legend for the whole figure...
• Transparent, fancy legends: http://matplotlib.org/gallery/recipes/transparent_legends.html#sphx-glr-gallery-recipes-transparent-legends-py
  Is basically the default now... probably doesn't need to exist by itself.
• Scatter legend: http://matplotlib.org/gallery/lines_bars_and_markers/scatter_with_legend.html#sphx-glr-gallery-lines-bars-and-markers-scatter-with-legend-py
  Heh, why not.
• Legend using predefined labels: http://matplotlib.org/gallery/api/legend.html#sphx-glr-gallery-api-legend-py
• and the change in custom legends example #9451

Suggestions:

• Add relevant documentation to address legend handle size does not automatically scale with linewidth #8789 (i.e. the improper scaling of the legend handles with default values for the legend parameters)