Expand 3-D basemap properties with back-walls and gridlines

doc/rst/source/cookbook/options.rst

@@ -287,23 +287,27 @@ tick, and gridline intervals, axes labels, and annotation units.
 
 The Frame settings are specified by
 
--  **-B**\ [*axes*][**+b**][**+g**\ *fill*][**+i**\ [*val*]][**+n**][**+o**\ *lon/lat*][**+t**\ *title*]
+-  **-B**\ [*axes*][**+b**][**+g**\ *fill*][**+i**\ [*val*]][**+n**][**+o**\ *lon/lat*][**+t**\ *title*][**+w**\ [*pen*]][**+x**\ [*fill*]][**+y**\ [*fill*]]
 
 Here, the optional *axes* dictates which of the axes should be drawn
-and possibly annotated.  By default, all 4 map boundaries (or plot axes)
+and possibly annotated.  By default, all four map boundaries (or plot axes)
 are plotted (denoted **W**, **E**, **S**, **N**). To change this selection,
 append the codes for those you want (e.g., **WSn**). In this example,
 the lower case **n** denotes to draw the axis and (major and minor) tick
 marks on the "northern" (top) edge of the plot. The upper case **WS** will
 annotate the "western" and "southern" axes with numerals and plot the
 any axis labels in addition to draw axis/tick-marks.  For 3-D plots you can
-also specify **Z** or **z**.  By default a single vertical axes will then be
+also specify **Z** or **z**.  To *just* draw an axis without annotation and
+ticks you can use the **l**\ (eft), **r**\ (ight), **b**\ (ottom), **t**\ (op)
+and (for 3-D) **u**\ (p) codes. By default, a single vertical axes will then be
 plotted at the most suitable map corner.  You can override this by appending
 any combination of corner ids **1234**, where **1** represents the lower left
-corner and the order goes counter-clockwise.  Append **+b** to draw the outline
-of the 3-D box defined by **-R**; this modifier is also needed to display
-gridlines in the x–z, y–z planes.  You may paint the
-map canvas by appending the **+g**\ *fill* modifier [Default is no fill].
+corner and the order goes counter-clockwise.  Use **+w** to draw the outlines of
+the x-z and y-z planes [no outlines] and optionally append the *pen* to use
+[:term:`MAP_GRID_PEN_PRIMARY`]. Alternatively, append **+b** to also draw the front lines
+of the 3-D cube defined by **-R**.  By default the back-walls are transparent.
+Use **+x** and **+y** to paint them, using the same fill as the x-y plane if no fill
+is appended. You may paint the map canvas by appending the **+g**\ *fill* modifier [Default is no fill].
 Use **+i** to annotate an internal meridian or parallel when the axis that normally
 would be drawn and annotated does not exist (e.g., azimuthal map with 360-degree range
 has no latitude axis, and a global Hammer map has no longitude axis);

doc/rst/source/explain_-B_full.rst_

@@ -3,22 +3,24 @@
 **-B**\ [**p**\|\ **s**]\ *parameters*
     Set map Frame and Axes parameters. The Frame parameters are specified by
 
-    **-B**\ [*axes*][**+b**][**+g**\ *fill*][**+i**\ [*val*]][**+n**][**+o**\ *lon/lat*][**+t**\ *title*]
+    **-B**\ [*axes*][**+b**][**+g**\ *fill*][**+i**\ [*val*]][**+n**][**+o**\ *lon/lat*][**+t**\ *title*][**+w**\ [*pen*]][**+x**\ [*fill*]][**+y**\ [*fill*]]
 
-    where *axes* selects which axes to plot. By default, all 4 map boundaries
+    where *axes* selects which axes to plot. By default, all four map boundaries
     (or plot axes) are plotted (named **W**, **E**, **S**, **N**). To customize,
     append the codes for those you want (e.g., **WSn**). Upper case means plot
     and annotate while lower case just plots and ticks the specified axes.
     To *just* draw an axis without annotation and ticks you can use the **l**\ (eft),
-    **r**\ (ight), **b**\ (ottom), **t**\ (opt) and (for 3-D) **u**\ (p) codes. If a 3-D basemap
-    is selected with **-p** and **-Jz**, append **Z**, **z**, or **u** to control the
-    appearance of the vertical axis. By default a single vertical axes will be
-    plotted at the most suitable map corner. Override the default by appending
+    **r**\ (ight), **b**\ (ottom), **t**\ (op) and (for 3-D) **u**\ (p) codes.
+    If a 3-D basemap is selected with **-p** and **-Jz**, append **Z**, **z**, or
+    **u** to control the appearance of the vertical axis. By default a single vertical
+    axes will be plotted at the most suitable map corner. Override the default by appending
     any combination of corner ids **1234**, where **1** represents the lower left
-    corner and the order goes counter-clockwise. Append **+b** to draw the outline of the 3-D
-    cube defined by **-R**; this modifier is also needed to display gridlines in
-    the x-z, y-z planes. Note that for 3-D views the title, if given, will be
-    suppressed. You can paint the interior of the canvas with **+g**\ *fill*.
+    corner and the order goes counter-clockwise.  Use **+w** to draw the outlines of
+    the x-z and y-z planes [no outline] and optionally append the *pen* to use
+    [:term:`MAP_GRID_PEN_PRIMARY`]. Alternatively, append **+b** to also draw the front lines
+    of the 3-D cube defined by **-R**. By default, the back-walls are transparent.
+    Use **+x** and **+y** to paint them, using the same fill as the x-y plane if no fill
+    is appended. You can paint the interior of the canvas with **+g**\ *fill*.
     Use **+i** to annotate an internal meridian or parallel when the axis that normally
     would be drawn and annotated does not exist (e.g., azimuthal map with 360-degree range
     has no latitude axis, and a global Hammer map has no longitude axis); optionally append the parallel or meridian [0].