From c9ec4ffe51c5e1587b286d3296e405c2038bcc57 Mon Sep 17 00:00:00 2001 From: Paul Wessel Date: Tue, 12 Dec 2023 18:44:15 +0100 Subject: [PATCH] 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 | 23 ++++----- doc/rst/source/supplements/seis/sac.rst | 4 +- src/psimage.c | 62 +++++++++++++++---------- 3 files changed, 51 insertions(+), 38 deletions(-) diff --git a/doc/rst/source/image.rst b/doc/rst/source/image.rst index 39b3c82777f..f48abcb6f58 100644 --- a/doc/rst/source/image.rst +++ b/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: diff --git a/doc/rst/source/supplements/seis/sac.rst b/doc/rst/source/supplements/seis/sac.rst index bef85e497ff..73524c0662c 100644 --- a/doc/rst/source/supplements/seis/sac.rst +++ b/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: diff --git a/src/psimage.c b/src/psimage.c index 11b7d97a017..50340d2d04a 100644 --- a/src/psimage.c +++ b/src/psimage.c @@ -38,7 +38,7 @@ struct PSIMAGE_CTRL { bool active; char *file; } In; - struct PSIMAGE_D { /* -D[g|j|n|x]+w[-][/][+j][+n[/]][+o[/]][+r] */ + struct PSIMAGE_D { /* -D[g|j|n|x]+w[-][/][+j][+n[/]][+o[/]][+r[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 [%s] [-D%s+w[-][/][+n[/]]%s+r] [-F%s] " + GMT_Usage (API, 0, "usage: %s [%s] [-D%s+w[-][/][+n[/]]%s+r[c]] [-F%s] " "[-G[][+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/[/]. If = 0 or = 0 " + GMT_Usage (API, -2, "Set width (and height) of image with +w[-]/[/]. If = 0 or = 0 " "then the original aspect ratio is maintained. If (or ) 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 [/] to replicate image by 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 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[][+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 */ + if (gmt_M_compat_check (GMT, 5) && opt->arg[0] != '+') { /* Warn but process old -F */ + GMT_Report (API, GMT_MSG_COMPAT, "The -F option is deprecated but was accepted. Use -F modifier +p 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][+o[/]][+n[/]][+r] */ + else { /* args are now [+j][+n[/]][+o[/]][+r[c]][+[-]] */ + 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 */ - 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++; }