Update documentation for gmt themes (#4717)

* List all parameters alphabetically * Start descriptions for themes and auto settings * Complete auto scaling documentation * Add FONT_SUBTITLE to tables * Fix classic default * Update auto scaling description * Fix font settings * Update FONT_SUBTITLE default * Update MAP_TICK_PEN_PRIMARY default docs * Update theme dependent defaults * Fix a typo * Format defaults documentation * Move theme-settings to separate docs page * Update auto scaling links * Update auto scaling documentation * Link themes table to gmt.conf keywords * Add more links between auto, gmt.conf, and themes * Fix formatting * Update MAP_ANNOT_MIN_SPACING default * Format doc/rst/source/cookbook/features.rst
GenericMappingTools · Jan 31, 2021 · 3214e29 · 3214e29
1 parent c70b5b6
commit 3214e29
Show file tree

Hide file tree

Showing 6 changed files with 215 additions and 109 deletions.
diff --git a/doc/rst/source/cookbook/features.rst b/doc/rst/source/cookbook/features.rst
@@ -270,61 +270,54 @@ placed in a separate parameter file:
    scenarios into separate ``gmt.conf`` files will minimize headaches associated with
    micro-editing of illustrations.
 
+
+.. _auto-scaling:
+
 Automatic GMT settings
 ~~~~~~~~~~~~~~~~~~~~~~
 
-In modern mode (as well as in classic when **GMT_THEME** is set to *modern*), a series of
-dimensions for items affecting plots are set to *auto*.  This flag signals that suitable
-dimensions will be automatically computed when the plot dimensions are known. The items
-affected by this mechanism are:
+The **auto** flag for :doc:`GMT parameters </gmt.conf>` signals that suitable
+dimensions will be automatically computed when the plot dimensions are known.
+Automatic scaling is supported for the following parameters:
 
 ================================== ===============================================
-:term:`FONT_LOGO`                  Logo font [8p,Helvetica]
-:term:`FONT_ANNOT_PRIMARY`         Primary annotation font [10p,AvantGarde-Book]
-:term:`FONT_ANNOT_SECONDARY`       Secondary annotation font [12p,AvantGarde-Book]
-:term:`FONT_LABEL`                 Axis label font [14p,AvantGarde-Book]
-:term:`FONT_TAG`                   Tag/labeling font [18p,AvantGarde-Book]
-:term:`FONT_TITLE`                 Plot title font [22p,AvantGarde-Demi]
-:term:`FONT_HEADING`               Subplot heading font [28p,AvantGarde-Demi]
-:term:`MAP_ANNOT_MIN_SPACING`      Minimum spacing between annotations [36p]
-:term:`MAP_ANNOT_OFFSET_PRIMARY`   Primary annotation offset from axis [3p]
-:term:`MAP_ANNOT_OFFSET_SECONDARY` Secondary annotation offset from axis [3p]
-:term:`MAP_FRAME_WIDTH`            Width of fancy frame [3p]
-:term:`MAP_HEADING_OFFSET`         Heading offset from subplot [16p]
-:term:`MAP_LABEL_OFFSET`           Label offset from annotations [6p]
-:term:`MAP_TICK_LENGTH_PRIMARY`    Length of primary tick marks [3p/1.5p]
-:term:`MAP_TICK_LENGTH_SECONDARY`  Length of secondary tick marks [12p/3p]
-:term:`MAP_TITLE_OFFSET`           Title offset from plot [12p]
-:term:`MAP_FRAME_PEN`              Pen width of plain frame [thicker]
-:term:`MAP_TICK_PEN_PRIMARY`       Pen width of primary tick marks [thinner]
-:term:`MAP_TICK_PEN_SECONDARY`     Pen width of secondary tick marks [thinner]
-:term:`MAP_GRID_PEN_PRIMARY`       Pen width of primary gridline [default]
-:term:`MAP_GRID_PEN_SECONDARY`     Pen width of secondary gridline [thinner]
+:term:`FONT_ANNOT_PRIMARY`         Primary annotation font [11.00p]
+:term:`FONT_ANNOT_SECONDARY`       Secondary annotation font [13.20p]
+:term:`FONT_HEADING`               Subplot heading font [30.80p]
+:term:`FONT_LABEL`                 Axis label font [15.40p]
+:term:`FONT_LOGO`                  Logo font [8.80p]
+:term:`FONT_SUBTITLE`              Plot subtitle font [19.80p]
+:term:`FONT_TAG`                   Tag/labeling font [17.60p]
+:term:`FONT_TITLE`                 Plot title font [24.20p]
+:term:`MAP_ANNOT_OFFSET_PRIMARY`   Primary annotation offset from axis [3.30p]
+:term:`MAP_ANNOT_OFFSET_SECONDARY` Secondary annotation offset from axis [3.30p]
+:term:`MAP_FRAME_PEN`              Pen width of plain frame [1.65p]
+:term:`MAP_FRAME_WIDTH`            Width of fancy frame [3.30p]
+:term:`MAP_GRID_PEN_PRIMARY`       Pen width of primary gridline [0.28p]
+:term:`MAP_GRID_PEN_SECONDARY`     Pen width of secondary gridline [0.55p]
+:term:`MAP_HEADING_OFFSET`         Heading offset from subplot [17.60p]
+:term:`MAP_LABEL_OFFSET`           Label offset from annotations [6.60p]
+:term:`MAP_TICK_LENGTH_PRIMARY`    Length of primary tick marks [2.2p/1.1p]
+:term:`MAP_TICK_LENGTH_SECONDARY`  Length of secondary tick marks [6.60p/1.65p]
+:term:`MAP_TICK_PEN_PRIMARY`       Pen width of primary tick marks [0.55p]
+:term:`MAP_TICK_PEN_SECONDARY`     Pen width of secondary tick marks [0.28p]
+:term:`MAP_TITLE_OFFSET`           Title offset from plot [13.20p]
 ================================== ===============================================
 
-The fonts and reference dimensions listed in brackets are the values you get for a plot
-that has a maximum dimension of exactly 25 cm.  Larger and smaller illustrations
+The reference dimensions listed in brackets are the values for a plot
+with a height and width of 25 cm.  Larger and smaller illustrations
 will see a linear magnification or attenuation of these dimensions. The primary
 annotation font size will be computed as::
 
-    size = (2/15) * (map_size_in_cm - 10) + 8 [in points]
-
-and all other items will have their reference sizes scaled by *scale = size / 10*.
-If you do nothing then all of the above dimensions will be automatically set
-based on your plot dimensions.  However, you are free to override any of them
-using the methods described in the next section. **Note**: The particular scaling
-relationship is experimental in 6.1 and we reserve the right to adjust it pending
-further experimentation and user feedback.
-
-A few default settings items have different values as well but are not subject
-to any scaling:
+    size = (2/15) * (map_size_in_cm - 10) + 9 [in points]
 
-========================== =========================================
-:term:`FORMAT_GEO_MAP`     Geographic annotation format [ddd:mm:ssF]
-:term:`MAP_FRAME_AXES`     Axes selection and draw mode [WrStZ]
-:term:`MAP_FRAME_TYPE`     Style of geographic map frame [plain]
-:term:`MAP_VECTOR_SHAPE`   Vector head shape parameter [0.5]
-========================== =========================================
+where *map_size_in_cm = sqrt(map_height \* map_width)*.  All other items will have
+their reference sizes scaled by *scale = size / 10*. In modern mode, if you do
+nothing then all of the above dimensions will be automatically set based on your
+plot dimensions.  However, you are free to override any of them using the methods
+described in the next section. **Note**: The particular scaling relationship is
+experimental in 6.2 and we reserve the right to adjust it pending further
+experimentation and user feedback.
 
 Changing GMT defaults
 ~~~~~~~~~~~~~~~~~~~~~