FInished implementing the modern mode inset module (#220)

Required fixes to pstext -F..+c as well so quite a few files are involved.  A few examples are failing and I will work on this (they may just be improved versions and not failures) but will check this as well.

doc_modern/rst/source/GMT_Docs.rst

@@ -491,7 +491,7 @@ modern mode is activated and deactivated by the new commands **gmt begin** and *
 respectively. Since these are not part of the classic repertoire one cannot
 accidentally execute a classic mode script in modern mode (or vice versa).
 We will discuss these two commands later. Finally, there are some new features in GMT that
-are only accessible under modern mode, such as subplots, new ways to specify the map domain and to
+are only accessible under modern mode, such as subplots, new ways to specify the map domain, map insets, and to
 get multiple output formats from the same plot.
 
 

doc_modern/rst/source/basemap.rst

@@ -1,8 +1,8 @@
 .. index:: ! basemap
 
-*********
+*******
 basemap
-*********
+*******
 
 .. only:: not man
 
@@ -15,10 +15,8 @@ Synopsis
 
 **gmt basemap** |-J|\ *parameters*
 |SYN_OPT-Rz|
-[ |SYN_OPT-B| ]
 [ |-A|\ [*file*] ]
-[ |-D|\ *inset box* ]
-[ |-F|\ *box* ]
+[ |SYN_OPT-B| ]
 [ |-J|\ **z**\ \|\ **Z**\ *parameters* ]
 [ |-L|\ *scalebar* ]
 [ |SYN_OPT-U| ]
@@ -75,55 +73,6 @@ Optional Arguments
 
 .. include:: explain_-B.rst_
 
-.. _-D:
-
-**-D**\ [*unit*]\ *xmin/xmax/ymin/ymax*\ [**r**][**+s**\ *file*][**+t**] \| **-D**\ [**g**\ \|\ **j**\ \|\ **J**\ \|\ **n**\ \|\ **x**]\ *refpoint*\ **+w**\ *width*\ [/*height*][**+j**\ *justify*][**+o**\ *dx*\ [/*dy*]][**+s**\ *file*][**+t**]
- Draw a simple map inset box on the map. Requires **-F**. Specify the box in one of three ways:
- (a) Give *west/east/south/north* of geographic rectangle bounded by parallels
- and meridians; append **r** if the coordinates instead are the lower left and
- upper right corners of the desired rectangle. (b) Give **u**\ *xmin/xmax/ymin/ymax*
- of bounding rectangle in projected coordinates (here, **u** is the coordinate unit).
- (c) Give the reference point on the map for the inset using one of four coordinate systems:
- (1) Use **-Dg** for map (user) coordinates, (2) use **-Dj** or **-DJ** for setting *refpoint* via
- a 2-char justification code that refers to the (invisible) map domain rectangle,
- (3) use **-Dn** for normalized (0-1) coordinates, or (4) use **-Dx** for plot coordinates
- (inches, cm, etc.).
- Append **+w**\ *width*\ [/*height*] of bounding rectangle or box in plot coordinates (inches, cm, etc.).
- By default, the anchor point on the scale is assumed to be the bottom left corner (BL), but this
- can be changed by appending **+j** followed by a 2-char justification code *justify* (see :doc:`text`).
- Note: If **-Dj** is used then *justify* defaults to the same as *refpoint*,
- if **-DJ** is used then *justify* defaults to the mirror opposite of *refpoint*.
- Add **+o** to offset the inset fig by *dx*/*dy* away from the *refpoint* point in
- the direction implied by *justify* (or the direction implied by **-Dj** or **-DJ**).
- If you need access to the placement of the lower left corner of the map inset and
- its dimensions in the current map unit, use **+s**\ *file* to write this information
- to *file*. Alternatively, you may append **+t** to translate the plot origin to
- the lower left corner of the map inset.
- Specify inset box attributes via the **-F** option [outline only].
-
-.. _-F:
-
-**-F**\ [**d**\ \|\ **l**\ \|\ **t**][\ **+c**\ *clearances*][\ **+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]][\ **+p**\ [*pen*]][\ **+r**\ [*radius*\ ]][\ **+s**\ [[*dx*/*dy*/][*shade*\ ]]]
- Without further options, draws a rectangular border around any map inset (**-D**),
- map scale (**-L**) or map rose (**-T**) using
- :ref:`MAP_FRAME_PEN <MAP_FRAME_PEN>`; specify a different pen with **+p**\ *pen*.
- Add **+g**\ *fill* to fill the logo box [no fill].
- Append **+c**\ *clearance* where *clearance* is either *gap*, *xgap*\ /\ *ygap*,
- or *lgap*\ /\ *rgap*\ /\ *bgap*\ /\ *tgap* where these items are uniform, separate in
- x- and y-direction, or individual side spacings between logo and border.
- Append **+i** to draw a secondary, inner border as well. We use a uniform
- *gap* between borders of 2\ **p** and the :ref:`MAP_DEFAULT_PEN <MAP_DEFAULT_PEN>`
- unless other values are specified. Append **+r** to draw rounded
- rectangular borders instead, with a 6\ **p** corner radius. You can
- override this radius by appending another value. Finally, append
- **+s** to draw an offset background shaded region. Here, *dx*/*dy*
- indicates the shift relative to the foreground frame
- [4\ **p**/-4\ **p**] and *shade* sets the fill style to use for shading [gray50].
- Used in combination with **-D**, **-L** or **-T**. To specify separate parameters
- for the various map features, append **d**\ \|\ **l**\ \|\ **t** to **-F**
- to specify panel parameters for just that panel [Default uses the same panel
- parameters for all selected map features].
-
 .. include:: explain_-Jz.rst_
 
 .. _-L:

doc_modern/rst/source/begin.rst_

@@ -97,5 +97,6 @@ See Also
 :doc:`docs`,
 :doc:`end`,
 :doc:`figure`,
+:doc:`inset`,
 :doc:`subplot`,
 :doc:`gmt`

doc_modern/rst/source/clear.rst_

@@ -89,5 +89,6 @@ See Also
 :doc:`docs`,
 :doc:`end`,
 :doc:`figure`,
+:doc:`inset`,
 :doc:`subplot`,
 :doc:`gmt`

doc_modern/rst/source/docs.rst_

@@ -67,5 +67,6 @@ See Also
 :doc:`clear`,
 :doc:`end`,
 :doc:`figure`,
+:doc:`inset`,
 :doc:`subplot`,
 :doc:`gmt`

doc_modern/rst/source/end.rst_

@@ -47,5 +47,6 @@ See Also
 :doc:`clear`,
 :doc:`docs`,
 :doc:`figure`,
+:doc:`inset`,
 :doc:`subplot`,
 :doc:`gmt`

doc_modern/rst/source/index.rst

@@ -14,12 +14,12 @@ Quick Reference [MODERN MODE]
 Session management
 ==================
 
-+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+
-| .. toctree:: | .. toctree:: | .. toctree:: | .. toctree:: | .. toctree:: | .. toctree:: |
-| :maxdepth: 1 | :maxdepth: 1 | :maxdepth: 1 | :maxdepth: 1 | :maxdepth: 1 | :maxdepth: 1 |
-| | | | | | |
-| begin | end | docs | figure | subplot | clear |
-+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+
++-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+
+| .. toctree:: | .. toctree:: | .. toctree:: | .. toctree:: | .. toctree:: | .. toctree:: | .. toctree:: |
+| :maxdepth: 1 | :maxdepth: 1 | :maxdepth: 1 | :maxdepth: 1 | :maxdepth: 1 | :maxdepth: 1 | :maxdepth: 1 |
+| | | | | | | |
+| begin | end | docs | figure | inset | subplot | clear |
++-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+
 
 .. toctree::
  :hidden:

doc_modern/rst/source/inset.rst

@@ -0,0 +1,5 @@
+#####
+inset
+#####
+
+.. include:: inset.rst_

doc_modern/rst/source/inset.rst_

@@ -0,0 +1,149 @@
+.. index:: ! inset
+
+.. only:: not man
+
+ Manage figure inset setup and completion
+
+The **inset** module is used to carve out a sub-region of the current plot and
+limit further plotting to that section of the canvas. The inset setup is started with the **begin**
+mode that defines the placement and size of the inset. Subsequent plot commands will be directed
+to that window. The inset is completed via the **end** mode, which reverts operations to the full
+canvas and restores the plot region and projection that was in effect prior to the setup of the inset.
+
+Synopsis (begin mode)
+---------------------
+
+.. include:: common_SYN_OPTs.rst_
+
+**gmt inset begin**
+|-D|\ *inset-box*
+[ |-F|\ *box* ]
+[ |-M|\ *margins* ]
+[ |SYN_OPT-V| ]
+[ |SYN_OPT--| ]
+
+|No-spaces|
+
+Description
+-----------
+
+The **begin** mode of inset defines the dimension and placement of the inset canvas. It
+makes a note of the current region and projection so that we may return to the initial
+plot environment when the inset is completed.
+
+Required Arguments
+------------------
+
+.. _-D:
+
+**-D**\ [*unit*]\ *xmin/xmax/ymin/ymax*\ [**r**][**+s**\ *file*][**+t**] \| **-D**\ [**g**\ \|\ **j**\ \|\ **J**\ \|\ **n**\ \|\ **x**]\ *refpoint*\ **+w**\ *width*\ [/*height*][**+j**\ *justify*][**+o**\ *dx*\ [/*dy*]][**+s**\ *file*][**+t**]
+ Define the map inset box on the map. Specify the box in one of three ways:
+ (a) Give *west/east/south/north* of geographic rectangle bounded by parallels
+ and meridians; append **r** if the coordinates instead are the lower left and
+ upper right corners of the desired rectangle. (b) Give **u**\ *xmin/xmax/ymin/ymax*
+ of bounding rectangle in projected coordinates (here, **u** is the coordinate unit).
+ (c) Give the reference point on the map for the inset using one of four coordinate systems:
+ (1) Use **-Dg** for map (user) coordinates, (2) use **-Dj** or **-DJ** for setting *refpoint* via
+ a 2-char justification code that refers to the (invisible) map domain rectangle,
+ (3) use **-Dn** for normalized (0-1) coordinates, or (4) use **-Dx** for plot coordinates
+ (inches, cm, etc.).
+ Append **+w**\ *width*\ [/*height*] of bounding rectangle or box in plot coordinates (inches, cm, etc.).
+ By default, the anchor point on the scale is assumed to be the bottom left corner (BL), but this
+ can be changed by appending **+j** followed by a 2-char justification code *justify* (see :doc:`text`).
+ Note: If **-Dj** is used then *justify* defaults to the same as *refpoint*,
+ if **-DJ** is used then *justify* defaults to the mirror opposite of *refpoint*.
+ Add **+o** to offset the inset fig by *dx*/*dy* away from the *refpoint* point in
+ the direction implied by *justify* (or the direction implied by **-Dj** or **-DJ**).
+ If you need access to the placement of the lower left corner of the map inset and
+ its dimensions in the current map unit, use **+s**\ *file* to write this information
+ to *file*. Alternatively, you may append **+t** to translate the plot origin to
+ the lower left corner of the map inset.
+ Specify inset box attributes via the **-F** option [outline only].
+
+Optional Arguments
+------------------
+
+.. _inset_begin-F:
+
+**-F**\ [**d**\ \|\ **l**\ \|\ **t**][\ **+c**\ *clearances*][\ **+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]][\ **+p**\ [*pen*]][\ **+r**\ [*radius*\ ]][\ **+s**\ [[*dx*/*dy*/][*shade*\ ]]]
+ Without further options, draws a rectangular border around any map inset (**-D**),
+ map scale (**-L**) or map rose (**-T**) using
+ :ref:`MAP_FRAME_PEN <MAP_FRAME_PEN>`; specify a different pen with **+p**\ *pen*.
+ Add **+g**\ *fill* to fill the logo box [no fill].
+ Append **+c**\ *clearance* where *clearance* is either *gap*, *xgap*\ /\ *ygap*,
+ or *lgap*\ /\ *rgap*\ /\ *bgap*\ /\ *tgap* where these items are uniform, separate in
+ x- and y-direction, or individual side spacings between logo and border.
+ Append **+i** to draw a secondary, inner border as well. We use a uniform
+ *gap* between borders of 2\ **p** and the :ref:`MAP_DEFAULT_PEN <MAP_DEFAULT_PEN>`
+ unless other values are specified. Append **+r** to draw rounded
+ rectangular borders instead, with a 6\ **p** corner radius. You can
+ override this radius by appending another value. Finally, append
+ **+s** to draw an offset background shaded region. Here, *dx*/*dy*
+ indicates the shift relative to the foreground frame
+ [4\ **p**/-4\ **p**] and *shade* sets the fill style to use for shading [gray50].
+ Used in combination with **-D**, **-L** or **-T**. To specify separate parameters
+ for the various map features, append **d**\ \|\ **l**\ \|\ **t** to **-F**
+ to specify panel parameters for just that panel [Default uses the same panel
+ parameters for all selected map features].
+
+.. _inset_begin-M:
+
+**-M**\ *margins*
+ This is clearance that is added around the inside of the inset. Plotting will take place
+ within the inner region only.
+ The margins can be a single value, a pair of values separated by slashes
+ (for setting separate horizontal and vertical margins), or the full set of four margins (for setting
+ separate left, right, bottom, and top margins) [0.5c].
+
+.. _inset_begin-V:
+
+.. |Add_-V| unicode:: 0x20 .. just an invisible code
+.. include:: explain_-V.rst_
+
+.. include:: explain_help.rst_
+
+Synopsis (end mode)
+-------------------
+
+**gmt inset end** [ |SYN_OPT-V| ]
+
+This command finalizes the current inset, which returns the plotting environment to
+the setup prior to the start of the inset. The previous region and projection will be
+in effect going forward.
+
+Optional Arguments
+------------------
+
+.. _inset_end-V:
+
+.. include:: explain_-V.rst_
+.. include:: explain_help.rst_
+
+
+Examples
+--------
+
+To make a simple basemap layout with an inset called inset.pdf, try
+
+ ::
+
+ gmt begin inset pdf
+ gmt psbasemap -R0/40/20/60 -JM6.5i -Bafg -B+glightgreen
+ gmt inset begin -DjTR+w2.5i+o0.2i -F+gpink+p0.5p -M0.25i
+ gmt psbasemap -Rg -JA20/20/2i -Bafg
+ echo INSET | gmt pstext -F+f18p+cTR -Dj-0.15i
+ gmt inset end
+ echo MAP | gmt pstext -F+f18p+cBL -Dj0.2i
+ gmt end
+
+
+See Also
+--------
+
+:doc:`begin`,
+:doc:`clear`,
+:doc:`docs`,
+:doc:`end`,
+:doc:`figure`,
+:doc:`gmt`,
+:doc:`inset`

doc_modern/rst/source/quick_ref.rst_

@@ -9,6 +9,8 @@
 +-----------------------+---------------------------------------------------------------------+
 | :doc:`figure` | Set attributes for the current figure |
 +-----------------------+---------------------------------------------------------------------+
+| :doc:`inset` | Manage figure inset setup and completion |
++-----------------------+---------------------------------------------------------------------+
 | :doc:`subplot` | Manage figure subplot configuration and selection |
 +-----------------------+---------------------------------------------------------------------+
 | | **Filtering of 1-D and 2-D Data** |

doc_modern/rst/source/subplot.rst_

@@ -251,4 +251,5 @@ See Also
 :doc:`docs`,
 :doc:`end`,
 :doc:`figure`,
+:doc:`inset`,
 :doc:`gmt`

doc_modern/rst/source/summary.rst_

@@ -129,6 +129,8 @@
 +-----------------------+---------------------------------------------------------------------+
 | :doc:`image` | Plot Sun raster files on a map |
 +-----------------------+---------------------------------------------------------------------+
+| :doc:`inset` | Manage figure inset setup and completion |
++-----------------------+---------------------------------------------------------------------+
 | :doc:`legend` | Plot a legend on a map |
 +-----------------------+---------------------------------------------------------------------+
 | :doc:`mask` | Create overlay to mask out regions on maps |

doc_modern/scripts/GMT_App_K_1.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 gmt begin GMT_App_K_1 ps
-gmt set MAP_GRID_CROSS_SIZE_PRIMARY 0 MAP_ANNOT_OBLIQUE 22 MAP_ANNOT_MIN_SPACING 0.3i
-gmt coast -Rk-9000/9000/-9000/9000 -JE130.35/-0.2/3.5i -Dc \
- -A500 -Gburlywood -Sazure -Wthinnest -N1/thinnest,- -B20g20 -BWSne 
-gmt basemap -Dg130.35/-0.2+w4000k+jCM -F+pthicker
+ gmt set MAP_GRID_CROSS_SIZE_PRIMARY 0 MAP_ANNOT_OBLIQUE 22 MAP_ANNOT_MIN_SPACING 0.3i
+ gmt coast -Rk-9000/9000/-9000/9000 -JE130.35/-0.2/3.5i -Dc \
+  -A500 -Gburlywood -Sazure -Wthinnest -N1/thinnest,- -B20g20 -BWSne 
+ echo 130.35 -0.2 | gmt psxy -SJ-4000 -Wthicker
 gmt end

doc_modern/scripts/GMT_App_K_2.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 gmt begin GMT_App_K_2 ps
-gmt coast -Rk-2000/2000/-2000/2000 -JE130.35/-0.2/3.5i -Dl -A100 \
+ gmt coast -Rk-2000/2000/-2000/2000 -JE130.35/-0.2/3.5i -Dl -A100 \
  -Gburlywood -Sazure -Wthinnest -N1/thinnest,- -B10g5 -BWSne 
-gmt basemap -Dg130.35/-0.2+w1000k+jCM -F+pthicker
+ echo 130.35 -0.2 | gmt psxy -SJ-1000 -Wthicker
 gmt end

doc_modern/scripts/GMT_App_K_3.sh

@@ -1,9 +1,9 @@
 #!/bin/bash
 gmt begin GMT_App_K_3 ps
-gmt coast -Rk-500/500/-500/500 -JE130.35/-0.2/3.5i -Di -A20 \
- -Gburlywood -Sazure -Wthinnest -N1/thinnest,- -B2g1 -BWSne
-echo 133 2 | gmt plot -Sc1.4i -Gwhite 
-gmt basemap -Tm133/2+w1i+t45/10/5+jCM --FONT_TITLE=12p --MAP_TICK_LENGTH_PRIMARY=0.05i \
- --FONT_ANNOT_SECONDARY=8p 
-gmt basemap -Dg130.35/-0.2+w200k+jCM -F+pthicker 
+ gmt coast -Rk-500/500/-500/500 -JE130.35/-0.2/3.5i -Di -A20 \
+  -Gburlywood -Sazure -Wthinnest -N1/thinnest,- -B2g1 -BWSne
+ echo 133 2 | gmt plot -Sc1.4i -Gwhite 
+ gmt basemap -Tm133/2+w1i+t45/10/5+jCM --FONT_TITLE=12p --MAP_TICK_LENGTH_PRIMARY=0.05i \
+  --FONT_ANNOT_SECONDARY=8p 
+ echo 130.35 -0.2 | gmt psxy -SJ-200 -Wthicker
 gmt end

doc_modern/scripts/GMT_App_K_4.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 gmt begin GMT_App_K_4 ps
-gmt coast -Rk-100/100/-100/100 -JE130.35/-0.2/3.5i -Dh -A1 \
- -Gburlywood -Sazure -Wthinnest -N1/thinnest,- -B30mg10m -BWSne 
-gmt basemap -Dg130.35/-0.2+w40k+jCM -F+pthicker 
+ gmt coast -Rk-100/100/-100/100 -JE130.35/-0.2/3.5i -Dh -A1 \
+  -Gburlywood -Sazure -Wthinnest -N1/thinnest,- -B30mg10m -BWSne 
+ echo 130.35 -0.2 | gmt psxy -SJ-40 -Wthicker
 gmt end

doc_modern/scripts/GMT_anchor.sh

@@ -1,6 +1,8 @@
 #!/bin/bash
 gmt begin GMT_anchor ps
-gmt basemap -R0/1/0/1 -JX5i/2i -Ba1f0.5 -BwSnE+gbisque -DjTL+o0.7i/0.5i+w1.5i/0.75i -F+glightgreen+p1p 
+gmt basemap -R0/1/0/1 -JX5i/2i -Ba1f0.5 -BwSnE+gbisque
+gmt inset begin -DjTL+o0.7i/0.5i+w1.5i/0.75i -F+glightgreen+p1p
+gmt inset end 
 gmt plot -W0.25p,- << EOF 
 0 0.75
 0.14 0.75

doc_modern/scripts/GMT_inset.sh

@@ -5,8 +5,7 @@
 gmt begin GMT_inset ps
 # Bottom map of Australia
 gmt coast -R110E/170E/44S/9S -JM6i -Baf -BWSne -Wfaint -N2/1p -EAU+gbisque -Gbrown -Sazure1 -Da -Xc --FORMAT_GEO_MAP=dddF
-gmt basemap -DjTR+w1.5i+o0.15i+stmp -F+gwhite+p1p+c0.1c+s
-read x0 y0 w h < tmp
-gmt coast -Rg -JG120/30S/$w -Da -Gbrown -A5000 -Bg -Wfaint -EAU+gbisque -X$x0 -Y$y0 
-gmt plot -T -X-${x0} -Y-${y0} 
+gmt inset begin -DjTR+w1.5i+o0.15i -F+gwhite+p1p+s -M0.05i
+gmt coast -Rg -JG120/30S/1.4i -Da -Gbrown -A5000 -Bg -Wfaint -EAU+gbisque 
+gmt inset end 
 gmt end

doc_modern/scripts/GMT_mag_rose.sh

@@ -6,7 +6,8 @@ gmt basemap -Tmg-2/0.5+w2.5i+d-14.5+t45/10/5+i0.25p,blue+p0.25p,red+l+jCM \
  --FONT_ANNOT_PRIMARY=9p,Helvetica,blue --FONT_ANNOT_SECONDARY=12p,Helvetica,red --FONT_LABEL=14p,Times-Italic,darkgreen --FONT_TITLE=24p \
  --MAP_TITLE_OFFSET=7p --MAP_FRAME_WIDTH=10p --COLOR_BACKGROUND=green --MAP_DEFAULT_PEN=2p,darkgreen --COLOR_BACKGROUND=darkgreen \
  --MAP_VECTOR_SHAPE=0.5 --MAP_TICK_PEN_SECONDARY=thinner,red --MAP_TICK_PEN_PRIMARY=thinner,blue 
-gmt basemap -DjTR+w2.9i/3.9i+o0.05i -F+p+ggray95 
+gmt inset begin -DjTR+w2.9i/3.9i+o0.05i -F+p+ggray95 
+gmt inset end
 echo "5.5 3.8 GMT DEFAULTS" | gmt text -R0/7/0/5 -Jx1i -F+f14p,Helvetica-Bold+jCM 
 gmt text -F+f12p+jLM << EOF 
 4.1 3.50 FONT_TITLE