Enable -l<label> auto-legend in plot

doc/examples/ex03/ex03.sh

@@ -42,16 +42,13 @@ gmt begin ex03
 	# Now to do the cross-spectra, assuming that the ship is the input and the sat is the output
 	# data, we do this:
 	gmt convert -A samp_ship.pg samp_sat.pg -o1,3 | gmt spectrum1d -S256 -D1 -W -C -T
-	# Time to plot spectra
+	# Time to plot spectra, use -l to build a legend
 	gmt set FONT_TAG 18p,Helvetica-Bold
 	gmt subplot begin 2x1 -M0.1i -SCb+l"Wavelength (km)" -T"Ship and Satellite Gravity" -Fs4i/3.75i -A+jTR+o0.1i -BWeSn+g240/255/240 -X2i -Y1.5i
 		gmt subplot set 0,0 -A"Input Power"
-		gmt plot spectrum.xpower -JX-?l/?l -Bxa1f3p -Bya1f3p+l"Power (mGal@+2@+km)" -Gred -ST0.07i -R1/1000/0.1/10000 -Ey+p0.5p
-		gmt plot spectrum.ypower -Gblue -Sc0.07i -Ey+p0.5p
-		gmt legend -DjBL+w1.2i+o0.25i -F+gwhite+pthicker --FONT_ANNOT_PRIMARY=14p,Helvetica-Bold <<- EOF
-		S 0.1i T 0.07i red  - 0.3i Ship
-		S 0.1i c 0.07i blue - 0.3i Satellite
-		EOF
+		gmt plot spectrum.xpower -JX-?l/?l -Bxa1f3p -Bya1f3p+l"Power (mGal@+2@+km)" -Gred -ST0.07i -R1/1000/0.1/10000 -Ey+p0.5p -lShip
+		gmt plot spectrum.ypower -Gblue -Sc0.07i -Ey+p0.5p -lSatellite
+		gmt legend -DjBL+w1.2i+o0.25i -F+gwhite+pthicker --FONT_ANNOT_PRIMARY=14p,Helvetica-Bold
 		gmt subplot set 1,0 -A"Coherency@+2@+"
 		gmt plot spectrum.coh -JX-?l/? -Bxa1f3p -Bya0.25f0.05+l"Coherency@+2@+" -R1/1000/0/1 -Sc0.07i -Gpurple -Ey+p0.5p
 	gmt subplot end

doc/examples/ex07/ex07.sh

@@ -7,12 +7,10 @@
 gmt begin ex07
 	gmt coast -R-50/0/-10/20 -JM9i -Slightblue -GP26+r300+ftan+bdarkbrown -Dl -Wthinnest -B --FORMAT_GEO_MAP=dddF
 	gmt plot @fz_07.txt -Wthinner,-
-	gmt plot @quakes_07.txt -h1 -Sci -i0,1,2+s0.01 -Gred -Wthinnest
+	gmt plot @quakes_07.txt -h1 -Sci -i0,1,2+s0.01 -Gred -Wthinnest -l"ISC Earthquakes"+s0.08i
 	gmt plot @isochron_07.txt -Wthin,blue
 	gmt plot @ridge_07.txt -Wthicker,orange
-	gmt legend -DjTR+w2.2i+o0.2i -F+pthick+ithinner+gwhite --FONT_ANNOT_PRIMARY=18p,Times-Italic <<- EOF
-	S 0.1i c 0.08i red thinnest 0.3i ISC Earthquakes
-	EOF
+	gmt legend -DjTR+w2i+o0.2i -F+pthick+ithinner+gwhite --FONT_ANNOT_PRIMARY=18p,Times-Italic
 	gmt text -F+f30,Helvetica-Bold,white=thin <<- END
 	-43 -5 SOUTH
 	-43 -8 AMERICA

doc/rst/source/common_SYN_OPTs.rst_

@@ -42,6 +42,8 @@
 
 .. |SYN_OPT-j| replace:: **-j**\ :ref:`flags <-j_full>`
 
+.. |SYN_OPT-l| replace:: **-l**\ :ref:`flags <-l_full>`
+
 .. |SYN_OPT-n| replace:: **-n**\ :ref:`flags <-n_full>`
 
 .. |SYN_OPT-o| replace:: **-o**\ :ref:`flags <-ocols_full>`

doc/rst/source/cookbook/options.rst

@@ -2,7 +2,7 @@ Standardized command line options
 =================================
 
 Most of the programs take many of the same arguments such as those related
-to setting the data region, the map projection, etc. The 24 switches in
+to setting the data region, the map projection, etc. The switches in
 Table :ref:`switches <tbl-switches>` have the same meaning in all the programs (although
 some programs may not use all of them). These options will be described
 here as well as in the manual pages, as is vital that you understand how
@@ -45,6 +45,8 @@ importance (some are used a lot more than others).
 +----------+--------------------------------------------------------------------+
 | **-j**   | Specify how spherical distances should be computed                 |
 +----------+--------------------------------------------------------------------+
+| **-l**   | Add a legend entry for the symbol or line being plotted            |
++----------+--------------------------------------------------------------------+
 | **-n**   | Specify grid interpolation settings                                |
 +----------+--------------------------------------------------------------------+
 | **-o**   | Specify which output columns to write                              |
@@ -1023,6 +1025,42 @@ slightly different meaning. Now, the *n_recs* argument is taken to mean
 how many *bytes* should be skipped (on input) or padded with the space
 character (on output).
 
+.. _option_-l:
+
+Setting automatic legend entries: The **-l** option
+---------------------------------------------------
+
+Map or plot legends are created by :doc:`legend` and normally this module
+will read a *specfile* that outlines how the legend should look.  You can
+make very detailed and complicated legends by mixing a variety of items,
+such as symbol, free text, colorbars, scales, images, and more.  Yet, for
+the vast majority of plots displaying symbols or lines a simple legend will suffice.
+The **-l** option is used to automatically build the *specfile* as we plot
+the various layers that will make up our illustration.  Apart from setting
+the label string that goes with the current symbol or line, you can select
+from a series of modifiers that mirror the effect of control codes normally
+added to the *specfile* by hand.  For instance, a simple plot with two
+symbols can obtain a legend by using this option and modifiers and is shown
+in Figure :ref:`Auto Legend <auto_legend>`::
+
+   gmt begin fruit
+     gmt plot -R0/7.2/3/7.2 -Jx2c @Table_5_11.txt -Sc0.35c -Glightgreen -Wfaint -lApples+h"LEGEND"+f16p+d
+     gmt plot @Table_5_11.txt -St0.35c -Gorange -B -BWStr -lOranges
+     gmt legend -DjTR+w3c+o0.25c -F+p1p+ggray95+s
+   gmt end show
+
+As the script shows, when no *specfile* is given to :doc:`legend` then we
+look for the automatically generated on in the session directory.
+
+.. _auto_legend:
+
+.. figure:: /_images/GMT_autolegend.*
+   :width: 500 px
+   :align: center
+
+   Each of the two :doc:`plot` commands use **-l** to add a symbol to the
+   auto legend; the first also sets a legend header of given size and draws a horizontal line.
+
 .. _option_-i:
 
 Input columns selection: The **-i** option

doc/rst/source/explain_-l.rst_

@@ -0,0 +1,2 @@
+**-l**\ [*label*]\ [**+d**\ *pen*][**+f**\ *font*][**+g**\ *gap*][**+h**\ *header*\ ][**+j**\ *just*][**+n**\ *cols*][**+s**\ *size*\ ][**+v**\ [*pen*]][**+w**\ *width*][**+x**\ *scale*\ ] :ref:`(more ...) <-l_full>`
+    Add a legend entry for the symbol or line being plotted. |Add_-l|

doc/rst/source/explain_-l_full.rst_

@@ -0,0 +1,23 @@
+.. _-l_full:
+
+**-l**\ [*label*]\ [**+d**\ *pen*][**+f**\ *font*][**+g**\ *gap*][**+h**\ *header*\ ][**+j**\ *just*][**+n**\ *cols*][**+s**\ *size*\ ][**+v**\ [*pen*]][**+w**\ *width*][**+x**\ *scale*\ ]
+    [**beta version**] Add a map legend entry to the session legend information file for the
+    current plot.  Optionally append a text *label* to describe the entry.
+    Several modifiers allow further changes to the legend (to be built
+    when :doc:`legend` is called): Use **+d** to draw a horizontal line before the
+    legend entry is placed [no line], use **+f** to set the font used for the legend header [:ref:`FONT_TITLE <FONT_TITLE>`],
+    use **+g** to add some vertical space [0], use **+h** to add a legend header [no header],
+    **+j** to set placement of the legend [TR], use **+n** to change the number of columns used to
+    set the following legend items [1], use **+s** to override the size of the
+    current symbol for the legend or set a length if plotting a line or contour [same as plotted],
+    use **+v** to start and **+v**\ *pen* to stop drawing vertical line from
+    previous to current horizontal line [no vertical line], use **+w** to set legend width [auto],
+    and use **+x**\ *scale* to resize all symbol and length sizes in the legend.  Default pen is
+    given by :ref:`MAP_DEFAULT_PEN <MAP_DEFAULT_PEN>`.  Note that **+h**, **+j**, **+w**, and **+x**
+    will only take effect if given on the very first **-l** option for a plot.  The **+n** modifier,
+    if used on the first **-l** option, affects the legend width (unless set via **+w**); otherwise it
+    just subdivides the available width among the specified columns.
+    The automatic legend has a fixed white background with a solid black pen outline and offset 0.2 cm from the map frame.
+    The modifiers largely reflect legend codes described in :doc:`legend`, which provide more details and
+    customization.  If **legend** is not called explicitly we will call it implicitly when finishing the plot
+    via :doc:`end`.

doc/rst/source/gallery/ex03.rst

@@ -6,8 +6,7 @@
 In this example we will show how to use the GMT programs
 :doc:`fitcircle </fitcircle>`, :doc:`project </project>`,
 :doc:`sample1d </sample1d>`, :doc:`spectrum1d </spectrum1d>`,
-:doc:`plot </plot>`, and
-:doc:`text </text>`. Suppose you have (lon, lat,
+and :doc:`plot </plot>`. Suppose you have (lon, lat,
 gravity) along a satellite track in a file called ``sat.xyg``, and (lon, lat,
 gravity) along a ship track in a file called ``ship.xyg``. You want to make a
 cross-spectral analysis of these data. First, you will have to get the
@@ -21,19 +20,11 @@ ranges are in the projected coordinate. The
 :doc:`gmtinfo </gmtinfo>` utility will report the minimum
 and maximum values for multi-column ASCII tables. Use this information
 to select the range of the projected distance coordinate they have in
-common. The script prompts you for that information after reporting the
-values. We decide to make a file of equidistant sampling points spaced 1
-km apart from -1167 to +1169, and use the UNIX utility **awk** to
-accomplish this step. We can then resample the projected data, and carry
+common. The script computes the common range. We can then resample the projected data, and carry
 out the cross-spectral calculations, assuming that the ship is the input
-and the satellite is the output data. There are several intermediate
-steps that produce helpful plots showing the effect of the various
-processing steps (``example_03[a-f].ps``), while the final plot ``example_03.ps`` shows the ship and sat power
+and the satellite is the output data. The final plot ``example_03.ps`` shows the ship and sat power
 in one diagram and the coherency on another diagram, both on the same
-page. Note the extended use of :doc:`text </text>`
-and :doc:`plot </plot>` to put labels and legends
-directly on the plots. For that purpose we often use **-Jx**\ 1i and
-specify positions in inches directly. Thus, the complete automated script reads:
+page, with an auto-generated legend. Thus, the complete automated script reads:
 
 .. literalinclude:: /_verbatim/ex03.txt
    :language: bash

doc/rst/source/gmt.rst

@@ -225,6 +225,8 @@ programs. No space between the option flag and the associated arguments.
 .. |Add_-j| unicode:: 0x20 .. just an invisible code
 .. include:: explain_distcalc_full.rst_
 
+.. include:: explain_-l_full.rst_
+
 .. include:: explain_-n_full.rst_
 
 .. include:: explain_-ocols_full.rst_

doc/rst/source/legend.rst

@@ -20,6 +20,8 @@ Synopsis
 [ |-F|\ *box* ]
 [ |-J|\ *parameters* ]
 [ |SYN_OPT-R| ]
+[ |-S|\ *scale* ]
+[ |-T|\ *file* ]
 [ |SYN_OPT-U| ]
 [ |SYN_OPT-V| ]
 [ |SYN_OPT-X| ]
@@ -74,6 +76,18 @@ specifications, use::
      T so we may have to adjust the box height to get the right size box.
      EOF
 
+Auto-legends
+------------
+
+In modern mode, some modules can access the **-l** option and build the legend
+*specfile* from individual entries per command.  The **-l** option takes a
+label and allows optional modifiers **+d**, **+g**, **+n**, **+h**, **+j**, and **+v**
+that follows the corresponding uppercase legend codes discussed above.  In addition,
+there is **+f** to set current font and **+s** to set the symbol size (or line length)
+to use for the current entry.  Some defaults are hardwired: We draw a white panel with
+a 1 point outline offset from the justification point (**+j**) by 0.2 cm.  To use
+different settings you must call **legend** explicitly instead.
+
 See Also
 --------
 

doc/rst/source/legend_common.rst_

@@ -72,6 +72,16 @@ Optional Arguments
 .. |Add_-R| unicode:: 0x20 .. just an invisible code
 .. include:: explain_-R.rst_
 
+.. _-S:
+
+**-S**\ *scale*
+    Scale all symbol sizes by a common *scale* [1].
+
+.. _-T:
+
+**-T**\ *file*
+    Modern mode only: Write hidden legend specification file to *file*.
+
 .. _-U:
 
 .. include:: explain_-U.rst_

doc/rst/source/plot.rst

@@ -40,6 +40,7 @@ Synopsis
 [ |SYN_OPT-g| ]
 [ |SYN_OPT-h| ]
 [ |SYN_OPT-i| ]
+[ |SYN_OPT-l| ]
 [ |SYN_OPT-p| ]
 [ |SYN_OPT-t| ]
 [ |SYN_OPT-:| ]

doc/rst/source/plot_common.rst_

@@ -219,6 +219,9 @@ Optional Arguments
 
 .. include:: explain_-icols.rst_
 
+.. |Add_-l| unicode:: 0x20 .. just an invisible code
+.. include:: explain_-l.rst_
+
 .. include:: explain_colon.rst_
 
 .. |Add_perspective| unicode:: 0x20 .. just an invisible code