Use MAP_SYMBOL_PEN_SCALE instead of MAP_STROKE_WIDTH (#7822)

* Use MAP_SYMBOL_STROKE_FACTOR instead of MAP_STROKE_WIDTH

See #7788 for discussion at end.  Note the internal variable is map_stroke_width. wo questions:

1. Rename map_stroke_width to map_stroke_factor
2. Consider SCALE instead of FACTOR?

See also here (#7822) how we came to MAP_SYMBOL_PEN_SCALE

* finalize names

doc/rst/source/explain_symbols.rst_

@@ -90,7 +90,7 @@
     **x**, **y**, **+** and **-** will derive their pen widths from the symbol size
     and their pen color from |-G| or |-C|. In that sense they behave as the other
     symbols (but no outline).  You can override this behavior by specifying |-W|,
-    modify it by adjusting :term:`MAP_STROKE_WIDTH` [15%], or set it to zero to
+    modify it by adjusting :term:`MAP_SYMBOL_PEN_SCALE` [15%], or set it to zero to
     rely on pen defaults (and |-W|).
 
     The next collection shows five symbols that require two or more parameters, and

doc/rst/source/gmt.conf.rst

@@ -868,17 +868,17 @@ MAP Parameters
         cap is reversed, i.e., *85/90* will draw a r = 5 radius circle at the
         center of the map with less frequent radial lines there.
 
-    **MAP_STROKE_WIDTH**
+    **MAP_SCALE_HEIGHT**
+        Sets the height (> 0) on the map of the map scale bars drawn by
+        various programs [default is **5p**].
+
+    **MAP_SYMBOL_PEN_SCALE**
         Used to convert non-fillable (**x**, **y**, **+** and **-**) symbol sizes
         to the width of the pen used to stroke these symbols. Give a factor in the
         0-1 range (e.g., 0.18) or specify a percentage (e.g., 10%) [15%]. **Note**:
         If set to 0 then no such conversion takes place and pen settings must rely on
         **-W** or module defaults.
 
-    **MAP_SCALE_HEIGHT**
-        Sets the height (> 0) on the map of the map scale bars drawn by
-        various programs [default is **5p**].
-
     **MAP_TICK_LENGTH**
         Sets both :term:`MAP_TICK_LENGTH_PRIMARY` and :term:`MAP_TICK_LENGTH_SECONDARY`
         to the value specified. This setting is not included in the **gmt.conf** file.

src/gmt_defaults.h

@@ -154,8 +154,8 @@ struct GMT_DEFAULTS {
 	double map_graph_extension;		/* If map_frame_type is graph, how must longer to make axis length. [7.5%] */
 	double map_graph_origin[2];		/* x- and y-origin of graph axis if graph-origin is in use [data 0/0] */
 	double map_graph_shift;			/* Extra offset for title to avoid overwriting the centered y-axis */
-	double map_stroke_width;		/* Conversion factor from symbol size to stroke pen width (non-fillable symbols only) */
-	char map_stroke_width_unit;		/* Either % or not */
+	double map_symbol_pen_scale;		/* Conversion factor from symbol size to stroke pen width (non-fillable symbols only) */
+	char map_symbol_pen_scale_unit;		/* Either % or not */
 	unsigned int map_annot_oblique;	/* Controls annotations and tick angles etc. [GMT_OBL_ANNOT_ANYWHERE] */
 	unsigned int map_grid_cross_type[2];	/* 0 = normal cross, 1 = symmetric tick, 2 = asymmetric tick */
 	unsigned int map_logo_justify;		/* Justification of the GMT timestamp box [1 (BL)] */

src/gmt_init.c

@@ -314,7 +314,7 @@ static struct GMT_parameter GMT_keyword_active[]= {
 	{ 0, "MAP_ORIGIN_Y"},
 	{ 0, "MAP_POLAR_CAP"},
 	{ 0, "MAP_SCALE_HEIGHT"},
-	{ 0, "MAP_STROKE_WIDTH"},
+	{ 0, "MAP_SYMBOL_PEN_SCALE"},
 	{ 0, "MAP_TICK_LENGTH_PRIMARY"},
 	{ 0, "MAP_TICK_LENGTH_SECONDARY"},
 	{ 0, "MAP_TICK_PEN_PRIMARY"},
@@ -6617,9 +6617,9 @@ GMT_LOCAL void gmtinit_conf_classic (struct GMT_CTRL *GMT) {
 	/* MAP_POLAR_CAP */
 	GMT->current.setting.map_polar_cap[0] = 85;
 	GMT->current.setting.map_polar_cap[1] = 90;
-	/* MAP_STROKE_WIDTH */
-	GMT->current.setting.map_stroke_width = GMT_SYMBOL_SIZE_TO_PEN_WIDTH / 100.0;	/* Given as percentage */
-	GMT->current.setting.map_stroke_width_unit = '%';
+	/* MAP_SYMBOL_PEN_SCALE */
+	GMT->current.setting.map_symbol_pen_scale = GMT_SYMBOL_SIZE_TO_PEN_WIDTH / 100.0;	/* Given as percentage */
+	GMT->current.setting.map_symbol_pen_scale_unit = '%';
 	/* MAP_SCALE_HEIGHT */
 	GMT->current.setting.map_scale_height = 5 * pt;	/* 5p */
 	GMT->current.setting.given_unit[GMTCASE_MAP_SCALE_HEIGHT] = 'p';
@@ -11241,25 +11241,25 @@ unsigned int gmtlib_setparameter (struct GMT_CTRL *GMT, const char *keyword, cha
 				GMT->current.setting.map_polar_cap[1] = inc[GMT_X];
 			}
 			break;
-		case GMTCASE_MAP_STROKE_WIDTH:
+		case GMTCASE_MAP_SCALE_HEIGHT:
+			dval = gmt_M_to_inch (GMT, value);
+			if (dval <= 0.0)
+				error = true;
+			else
+				GMT->current.setting.map_scale_height = dval;
+			break;
+		case GMTCASE_MAP_SYMBOL_PEN_SCALE:
 			dval = atof (value);
 			if (value[len] == '%') {
 				dval /= 100.0;	/* Got factor as a percentage */
-				GMT->current.setting.map_stroke_width_unit = '%';
+				GMT->current.setting.map_symbol_pen_scale_unit = '%';
 			}
 			else	/* Got a fraction */
-				GMT->current.setting.map_stroke_width_unit = '\0';
+				GMT->current.setting.map_symbol_pen_scale_unit = '\0';
 			if (dval < 0.0)
 				error = true;
 			else
-				GMT->current.setting.map_stroke_width = dval;
-			break;
-		case GMTCASE_MAP_SCALE_HEIGHT:
-			dval = gmt_M_to_inch (GMT, value);
-			if (dval <= 0.0)
-				error = true;
-			else
-				GMT->current.setting.map_scale_height = dval;
+				GMT->current.setting.map_symbol_pen_scale = dval;
 			break;
 		case GMTCASE_TICK_LENGTH:
 			if (gmt_M_compat_check (GMT, 4)) {	/* GMT4: */
@@ -12815,15 +12815,15 @@ char *gmtlib_getparameter (struct GMT_CTRL *GMT, const char *keyword) {
 			else
 				snprintf (value, GMT_LEN256, "%g/%g", GMT->current.setting.map_polar_cap[0], GMT->current.setting.map_polar_cap[1]);
 			break;
-		case GMTCASE_MAP_STROKE_WIDTH:
-			if (GMT->current.setting.map_stroke_width_unit == '%')	/* Report as percentage */
-				snprintf (value, GMT_LEN256, "%g%%", GMT->current.setting.map_stroke_width * 100.0);
-			else	/* Just a factor */
-				snprintf (value, GMT_LEN256, "%g", GMT->current.setting.map_stroke_width);
-			break;
 		case GMTCASE_MAP_SCALE_HEIGHT:
 			snprintf (value, GMT_LEN256, "%g%c", GMT->current.setting.map_scale_height * gmt_M_def_scale(GMTCASE_MAP_SCALE_HEIGHT), gmt_M_def_unit(GMTCASE_MAP_SCALE_HEIGHT));
 			break;
+		case GMTCASE_MAP_SYMBOL_PEN_SCALE:
+			if (GMT->current.setting.map_symbol_pen_scale_unit == '%')	/* Report as percentage */
+				snprintf (value, GMT_LEN256, "%g%%", GMT->current.setting.map_symbol_pen_scale * 100.0);
+			else	/* Just a factor */
+				snprintf (value, GMT_LEN256, "%g", GMT->current.setting.map_symbol_pen_scale);
+			break;
 		case GMTCASE_MAP_TICK_LENGTH:
 		case GMTCASE_TICK_LENGTH:
 			if (gmt_M_compat_check (GMT, 4))	/* GMT4: */

src/gmt_keywords.txt

@@ -37,7 +37,7 @@ FONT_ANNOT_SECONDARY		# Font for secondary axes annotations
 FONT_HEADING			# Font for heading above subplots
 FONT_LABEL			# Font for axes labels
 FONT_LOGO			# Font for GMT logo
-FONT_SUBTITLE		# Font for plot subtitles
+FONT_SUBTITLE			# Font for plot subtitles
 FONT_TAG			# Font for panel figure tags
 FONT_TITLE			# Font for plot titles
 #-------------------------------------------------------
@@ -88,8 +88,8 @@ IO_HEADER			# Are there header records?
 IO_HEADER_MARKER		# 1st char in header records for input and output
 IO_N_HEADER_RECS		# How many header records to expect
 IO_NAN_RECORDS			# How NaNs in input should be interpreted
-IO_NC4_CHUNK_SIZE	# Chunk size (lat,lon) of netCDF output
-IO_NC4_DEFLATION_LEVEL	# Deflate level for netCDF output
+IO_NC4_CHUNK_SIZE		# Chunk size (lat,lon) of netCDF output
+IO_NC4_DEFLATION_LEVEL		# Deflate level for netCDF output
 IO_LONLAT_TOGGLE		# Expect lat-lon instead of lon-lat
 IO_SEGMENT_BINARY		# Determines how binary records with NaNs are interpreted
 IO_SEGMENT_MARKER		# 1st char in segment headers for input and output
@@ -105,7 +105,7 @@ MAP_ANNOT_MIN_ANGLE		# Cut-off angle to eliminate very oblique annotations
 MAP_ANNOT_MIN_SPACING		# Cut-off distance to eliminate crowding of annotations
 MAP_DEFAULT_PEN			# Default for all pens
 MAP_DEGREE_SYMBOL		# Symbol for "degree" to use on maps
-MAP_EMBELLISHMENT_MODE	# Whether map roses and scales shall be manually or automatically scaled
+MAP_EMBELLISHMENT_MODE		# Whether map roses and scales shall be manually or automatically scaled
 MAP_FRAME_AXES			# Which axes should be plotted [WESNZ]
 MAP_FRAME_PEN			# Pen used to draw plain map frame
 MAP_FRAME_TYPE			# Type of map frame (plain or fancy)
@@ -127,7 +127,7 @@ MAP_ORIGIN_X			# x-value of lower-left corner of map relative to page [1i]
 MAP_ORIGIN_Y			# y-value of lower-left corner of map relative to page [1i]
 MAP_POLAR_CAP			# Modify gridline spacing for polar caps
 MAP_SCALE_HEIGHT		# Height of scale bar on maps
-MAP_STROKE_WIDTH		# Percent of strokable-only symbol size for stroke pen width [15%]
+MAP_SYMBOL_PEN_SCALE		# Percent of strokable-only symbol size for stroke pen width [15%]
 MAP_TICK_LENGTH			# Length of major and minor frame axes ticks [does not go in gmt.conf]
 MAP_TICK_LENGTH_PRIMARY		# Length of major and minor primary frame axes ticks
 MAP_TICK_LENGTH_SECONDARY	# Length of major and minor secondary frame axes ticks

src/psxy.c

@@ -1718,7 +1718,7 @@ EXTERN_MSC int GMT_psxy (void *V_API, int mode, void *args) {
 			if (psxy_is_stroke_symbol (S.symbol)) {	/* These are only stroked, not filled */
 				/* Unless -W was set, compute pen width from symbol size and get pen color from G or z->CPT */
 				if (!outline_active)	/* No pen width given, compute from symbol size unless conversion factor is 0 */
-					current_pen.width = (gmt_M_is_zero (GMT->current.setting.map_stroke_width)) ? GMT->current.setting.map_default_pen.width : GMT->current.setting.map_stroke_width * S.size_x * PSL_POINTS_PER_INCH;
+					current_pen.width = (gmt_M_is_zero (GMT->current.setting.map_symbol_pen_scale)) ? GMT->current.setting.map_default_pen.width : GMT->current.setting.map_symbol_pen_scale * S.size_x * PSL_POINTS_PER_INCH;
 				if (current_fill.rgb[0] > -0.5) {	/* Color given, use it for the stroke */
 					save_pen = current_pen;
 					gmt_M_rgb_copy (current_pen.rgb, current_fill.rgb);

src/psxyz.c

@@ -1364,7 +1364,7 @@ EXTERN_MSC int GMT_psxyz (void *V_API, int mode, void *args) {
 			if (psxyz_is_stroke_symbol (S.symbol)) {	/* These are only stroked, not filled */
 				/* Unless -W was set, compute pen width from symbol size and get pen color from G or z->CPT */
 				if (!outline_active)	/* No pen width given, compute from symbol size */
-					current_pen.width = (gmt_M_is_zero (GMT->current.setting.map_stroke_width)) ? GMT->current.setting.map_default_pen.width : GMT->current.setting.map_stroke_width * S.size_x * PSL_POINTS_PER_INCH;
+					current_pen.width = (gmt_M_is_zero (GMT->current.setting.map_symbol_pen_scale)) ? GMT->current.setting.map_default_pen.width : GMT->current.setting.map_symbol_pen_scale * S.size_x * PSL_POINTS_PER_INCH;
 				if (current_fill.rgb[0] > -0.5) {	/* Color given, use it for the stroke */
 					save_pen = current_pen;
 					gmt_M_rgb_copy (current_pen.rgb, current_fill.rgb);