Better handling of deprecated strings (#8189)

* Better handling of deprecated strings

Both -C and -F (deprecated versions) sat the same string.  Now they use separate strings.

* Update sac.rst

* Handle random option order for deprecated -C, D and -F

Prescan to set cstring and fstring, if needed. Also improved doc laoyout.

* Update image.rst

doc/rst/source/image.rst

@@ -68,7 +68,7 @@ Optional Arguments
 
 .. _-D:
 
-**-D**\ [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\ **+r**\ *dpi*\ **+w**\ [**-**]\ *width*\ [/*height*]\ [**+j**\ *justify*]\ [**+n**\ *nx*\ [/*ny*] ]\ [**+o**\ *dx*\ [/*dy*]]
+**-D**\ [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\ **+r**\ *dpi*\ [**c**]\ **+w**\ [**-**]\ *width*\ [/*height*]\ [**+j**\ *justify*]\ [**+n**\ *nx*\ [/*ny*] ]\ [**+o**\ *dx*\ [/*dy*]]
     Sets reference point on the map for the image using one of four coordinate systems:
 
     .. include:: explain_refpoint.rst_
@@ -78,16 +78,17 @@ Optional Arguments
     **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*.
     Specify image size in one of two ways:
-    Use **+r**\ *dpi* to set the dpi of the image in dots per inch, or use
-    **+w**\ [**-**]\ *width*\ [/*height*] to
-    set the width (and height) of the image in plot coordinates
-    (inches, cm, etc.). If *height* (or *width*) is set to 0, then the original aspect
-    ratio of the image is maintained. If *width* (or *height*) is negative we use the
-    absolute value and interpolate image to the device resolution using
-    the PostScript image operator. If neither dimensions nor *dpi* are set then we
-    revert to the default dpi [:term:`GMT_GRAPHICS_DPU`].  Optionally, use
-    **+n**\ *nx*\ [/*ny*] to replicate the image *nx* times horizontally and *ny* times
-    vertically. If *ny* is omitted, it will be identical to *nx* [Default is 1/1].
+
+    - **+n** - Append \ *nx*\ [/*ny*] to replicate the (scaled) image *nx* times horizontally and
+      *ny* times vertically. If *ny* is omitted, it will be identical to *nx* [Default is 1/1].
+    - **+r** - Specify *dpi* to set the dpi of the image in dots per inch, or append **c**
+      to indicate this is dots per cm [inches].
+    - **+w** - Append [**-**]\ *width*\ [/*height*] to set the width (and height) of the
+      image in plot coordinates (inches, cm, etc.). If *height* (or *width*) is set to 0,
+      then the original aspect ratio of the image is maintained. If *width* (or *height*)
+      is negative we use the absolute value and interpolate image to the device resolution
+      using the PostScript image operator. If neither dimensions nor *dpi* are set then we
+      revert to the default dpi [:term:`GMT_GRAPHICS_DPU`].
 
 .. _-F:
 

doc/rst/source/supplements/seis/sac.rst

@@ -90,8 +90,8 @@ Optional Arguments
 
 .. _-D:
 
-**-D**\ *dx*\ [**/**\ *dy*]
-    Offset seismogram positions by the given mount *dx/dy* [Default is no offset].
+**-D**\ *dx*\ [/*dy*]
+    Offset seismogram positions by the given mount *dx*\ /*dy* [Default is no offset].
     If *dy* is not given it is set equal to *dx*.
 
 .. _-E:

src/psimage.c

@@ -38,7 +38,7 @@ struct PSIMAGE_CTRL {
 		bool active;
 		char *file;
 	} In;
-	struct PSIMAGE_D {	/* -D[g|j|n|x]<refpoint>+w[-]<width>[/<height>][+j<justify>][+n<n_columns>[/<n_rows>]][+o<dx>[/<dy>]][+r<dpi>] */
+	struct PSIMAGE_D {	/* -D[g|j|n|x]<refpoint>+w[-]<width>[/<height>][+j<justify>][+n<n_columns>[/<n_rows>]][+o<dx>[/<dy>]][+r<dpi>[c]] */
 		bool active;
 		struct GMT_REFPOINT *refpoint;
 		double off[2];
@@ -93,7 +93,7 @@ static int usage (struct GMTAPI_CTRL *API, int level) {
 
 	const char *name = gmt_show_name_and_purpose (API, THIS_MODULE_LIB, THIS_MODULE_CLASSIC_NAME, THIS_MODULE_PURPOSE);
 	if (level == GMT_MODULE_PURPOSE) return (GMT_NOERROR);
-	GMT_Usage (API, 0, "usage: %s <imagefile> [%s] [-D%s+w[-]<width>[/<height>][+n<n_columns>[/<n_rows>]]%s+r<dpi>] [-F%s] "
+	GMT_Usage (API, 0, "usage: %s <imagefile> [%s] [-D%s+w[-]<width>[/<height>][+n<n_columns>[/<n_rows>]]%s+r<dpi>[c]] [-F%s] "
 		"[-G[<color>][+b|f|t]] [-I] [%s] %s[-M] %s%s[%s] [%s] [%s] [%s] [%s] %s[%s] [%s] [%s]\n",
 		name, GMT_B_OPT, GMT_XYANCHOR, GMT_OFFSET, GMT_PANEL, GMT_J_OPT, API->K_OPT, API->O_OPT, API->P_OPT,
 		GMT_Rgeoz_OPT, GMT_U_OPT, GMT_V_OPT, GMT_X_OPT, GMT_Y_OPT, API->c_OPT, GMT_p_OPT, GMT_t_OPT, GMT_PAR_OPT);
@@ -105,12 +105,13 @@ static int usage (struct GMTAPI_CTRL *API, int level) {
 	GMT_Message (API, GMT_TIME_NONE, "\n  OPTIONAL ARGUMENTS:\n");
 	GMT_Option (API, "B-");
 	gmt_refpoint_syntax (API->GMT, "\n-D", "Specify reference point for the image", GMT_ANCHOR_IMAGE, 3);
-	GMT_Usage (API, -2, "Set width (and height) of image with +w<width>/[/<height>].  If <width> = 0 or <height> = 0 "
+	GMT_Usage (API, -2, "Set width (and height) of image with +w[-]<width>/[/<height>].  If <width> = 0 or <height> = 0 "
 		"then the original aspect ratio is maintained.  If <width> (or <height>) is < 0 "
 		"then we use absolute value as width (or height) and interpolate the image in PostScript. Alternatively:");
-	GMT_Usage (API, 3, "+r Append image dpi (dots per inch).");
+	GMT_Usage (API, 3, "+r Append image dpi (dots per inch) or append c if dots per cm.");
 	GMT_Usage (API, 3, "+n Append <n_columns>[/<n_rows>] to replicate image <n_columns> by <n_rows> times [Default is no replication].");
-	GMT_Usage (API, -2, "Note: if neither +w nor +r is set we default to the default dpu [%lg%c]\n",
+	GMT_Usage (API, -2, "Notes:(1) If neither +w nor +r are set then we default to the default dpu [%lg%c] "
+		"(2) If <width> is negative then we interpolate image to device resolution.\n",
 		API->GMT->current.setting.graphics_dpu, API->GMT->current.setting.graphics_dpu_unit);
 	gmt_mappanel_syntax (API->GMT, 'F', "Specify a rectangular panel behind the image", 1);
 	GMT_Usage (API, 1, "\n-G[<color>][+b|f|t]");
@@ -138,11 +139,35 @@ static int parse (struct GMT_CTRL *GMT, struct PSIMAGE_CTRL *Ctrl, struct GMT_OP
 
 	unsigned int n_errors = 0, ind = PSIMAGE_FGD, k = 0;
 	int n;
-	char string[GMT_LEN256] = {""}, *p = NULL;
+	char cstring[GMT_LEN256] = {""}, fstring[GMT_LEN256] = {""}, *p = NULL;
 	char txt_a[GMT_LEN256] = {""}, txt_b[GMT_LEN256] = {""}, txt_c[4] = {""};
 	struct GMT_OPTION *opt = NULL;
 	struct GMTAPI_CTRL *API = GMT->parent;
 
+	/* Because of backwards compatibility with deprecated -C optino and upgraded -F option we need to
+	 * per-scane for those options and capture their arguments so that later we can handle the backwards
+	 * checking without worry about option order. */
+
+	for (opt = options; opt; opt = opt->next) {	/* Process all the options given */
+		if (opt->option == 'C') { /* Deprecated */
+			GMT_Report (API, GMT_MSG_COMPAT, "-C option is deprecated, use -Dx instead.\n");
+			n = sscanf (opt->arg, "%[^/]/%[^/]/%2s", txt_a, txt_b, txt_c);
+			sprintf (cstring, "x%s/%s", txt_a, txt_b);	/* Build +x modifier* for -D */
+			if (n == 3) {	/* Append modifier +j with given argument */
+				strcat (cstring, "+j");
+				strcat (cstring, txt_c);
+			}
+		}
+		else if (opt->option == 'F') {	/* Check for deprecated version of -F<pen> */
+			if (gmt_M_compat_check (GMT, 5) && opt->arg[0] != '+') { /* Warn but process old -F<pen> */
+				GMT_Report (API, GMT_MSG_COMPAT, "The -F<pen> option is deprecated but was accepted. Use -F modifier +p<pen> instead\n");
+				sprintf (fstring, "+c0+p%s", opt->arg);	/* Reformat using new syntax */
+			}
+			else	/* Expected syntax given (we hope) */
+				strncpy (fstring, opt->arg, GMT_LEN256-1);
+		}
+	}
+
 	for (opt = options; opt; opt = opt->next) {	/* Process all the options given */
 
 		switch (opt->option) {
@@ -154,24 +179,15 @@ static int parse (struct GMT_CTRL *GMT, struct PSIMAGE_CTRL *Ctrl, struct GMT_OP
 
 			/* Processes program-specific parameters */
 
-			case 'C':	/* Image placement (old syntax) */
-				GMT_Report (API, GMT_MSG_COMPAT, "-C option is deprecated, use -Dx instead.\n");
-				n = sscanf (opt->arg, "%[^/]/%[^/]/%2s", txt_a, txt_b, txt_c);
-				sprintf (string, "x%s/%s", txt_a, txt_b);
-				if (n == 3) {
-					strcat (string, "+j");
-					strcat (string, txt_c);
-				}
-				break;
 			case 'D':
 				n_errors += gmt_M_repeated_module_option (API, Ctrl->D.active);
-				strncpy(string, opt->arg, GMT_LEN256 - 1);
-				p = (string[0]) ? string : opt->arg;	/* If -C was used the string is set */
+				p = (cstring[0]) ? cstring : opt->arg;	/* If -C was used then cstring was set above */
 				if ((Ctrl->D.refpoint = gmt_get_refpoint (GMT, p, 'D')) == NULL) {	/* Failed basic parsing */
 					GMT_Report (API, GMT_MSG_ERROR, "Option -D: Basic parsing of reference point in %s failed\n", opt->arg);
 					n_errors++;
 				}
-				else {	/* args are now [+j<justify>][+o<dx>[/<dy>]][+n<n_columns>[/<n_rows>]][+r<dpi>] */
+				else {	/* args are now [+j<justify>][+n<n_columns>[/<n_rows>]][+o<dx>[/<dy>]][+r<dpi>[c]][+[-]<width>] */
+					char string[GMT_LEN256] = {""};
 					if (gmt_validate_modifiers (GMT, Ctrl->D.refpoint->args, 'D', "jnorw", GMT_MSG_ERROR)) n_errors++;
 					/* Required modifier +w OR +r */
 					if (gmt_get_modifier (Ctrl->D.refpoint->args, 'w', string)) {
@@ -206,16 +222,12 @@ static int parse (struct GMT_CTRL *GMT, struct PSIMAGE_CTRL *Ctrl, struct GMT_OP
 			case 'E':	/* Specify image dpi */
 				GMT_Report (API, GMT_MSG_COMPAT, "The -E option is deprecated but is accepted.\n");
 				GMT_Report (API, GMT_MSG_COMPAT, "For the current -D syntax you should use -D modifier +r instead.\n");
-				GMT_Report (API, GMT_MSG_COMPAT, "Note you cannot mix new-style modifiers (+r) with the old-style -C option.\n");
+				GMT_Report (API, GMT_MSG_COMPAT, "Note: You cannot mix new-style modifiers (+r) with the old-style -C option.\n");
 				Ctrl->D.dpi = atof (opt->arg);
 				break;
-			case 'F':	/* Specify frame pen */
+			case 'F':	/* Specify panel behind image */
 				n_errors += gmt_M_repeated_module_option (API, Ctrl->F.active);
-				if (gmt_M_compat_check (GMT, 5) && opt->arg[0] != '+') /* Warn but process old -F<pen> */
-					sprintf (string, "+c0+p%s", opt->arg);
-				else
-					strncpy (string, opt->arg, GMT_LEN256-1);
-				if (gmt_getpanel (GMT, opt->option, string, &(Ctrl->F.panel))) {
+				if (gmt_getpanel (GMT, opt->option, fstring, &(Ctrl->F.panel))) {	/* fstring set above */
 					gmt_mappanel_syntax (GMT, 'F', "Specify a rectangular panel behind the image", 1);
 					n_errors++;
 				}