Let psconvert -N+kfill set alternate fade fill

doc/rst/source/figure.rst

@@ -59,7 +59,7 @@ Optional Arguments
     Sets one or more comma-separated options (and possibly arguments) that
     can be passed to :doc:`psconvert` when preparing this figure [**A**].
     The valid subset of options are
-    **A**\ [*args*],\ **C**\ *args*,\ **D**\ *dir*,\ **E**\ *dpi*,\ **H**\ *factor*,\ **M**\ *args*,\ **Q**\ *args*,\ **S**.
+    **A**\ [*args*],\ **C**\ *args*,\ **D**\ *dir*,\ **E**\ *dpi*,\ **H**\ *factor*,\ **I**\ *args*,\ **M**\ *args*,\ **N**\ *args*,\ **Q**\ *args*,\ **S**.
     See the :doc:`psconvert` documentation for details on these options.
 
 .. |Add_-V| replace:: |Add_-V_links|

doc/rst/source/psconvert.rst

@@ -23,7 +23,7 @@ Synopsis
 [ |-I|\ [**+m**\ *margins*][**+s**\ [**m**]\ *width*\ [/\ *height*]][**+S**\ *scale*] ]
 [ |-L|\ *list* ]
 [ |-M|\ **b**\|\ **f**\ *pslayer* ]
-[ |-N|\ [**+f**\ *fade*][**+g**\ *paint*][**+i**][**+p**\ [*pen*]] ]
+[ |-N|\ [**+f**\ *fade*][**+g**\ *background*][**+k**\ *fadecolor*][**+p**\ [*pen*]] ]
 [ |-Q|\ [**g**\|\ **p**\|\ **t**][1\|2\|4] ]
 [ |-S| ]
 [ |-T|\ **b**\|\ **e**\|\ **E**\|\ **f**\|\ **F**\|\ **j**\|\ **g**\|\ **G**\|\ **m**\|\ **s**\|\ **t**\ [**+m**][**+q**\ *quality*] ]
@@ -157,20 +157,13 @@ Optional Arguments
 
 .. _-N:
 
-**-N**\ [**+f**\ *fade*][**+g**\ *paint*][**+i**][**+p**\ [*pen*]]
-    Set optional BoundingBox fill color, fading, or draw the outline of the BoundingBox.
-    Append **+f**\ *fade* to fade the entire plot towards black (100%) [no fading, 0].
-    Append **+g**\ *paint* to paint the BoundingBox behind the illustration and
-    append **+p**\ [*pen*] to draw the BoundingBox outline (append a pen or accept
-    the default pen of 0.25p,black).  **Note**: If both **+g** and **+f** are used
-    then we use *paint* as the fade color instead of black.
-    Append **+i**  to enforce gray-shades by using ICC profiles.  Ghostscript versions
-    >= 9.00 change gray-shades by using ICC profiles.  Ghostscript 9.05
-    and above provide the '-dUseFastColor=true' option to prevent that
-    and that is what **psconvert** does by default, unless modifier **+i** is
-    set.  Note that for Ghostscript >= 9.00 and < 9.05 the gray-shade
-    shifting is applied to all but PDF format.  We have no solution to
-    offer other than suggesting you upgrade Ghostscript.
+**-N**\ [**+f**\ *fade*][**+g**\ *background*][**+k**\ *fadecolor*][**+p**\ [*pen*]]
+    Set optional BoundingBox background fill color, fading, or draw the outline of the BoundingBox.
+    Append **+f**\ *fade* to fade the entire plot towards *fadecolor* [black] (100%) [no fading, 0].
+    Append **+g**\ *background* to paint the BoundingBox behind the illustration.
+    Append **+k**\ *fadecolor* to set the fade color if **+f** is set [black]/
+    Append **+p**\ [*pen*] to draw the BoundingBox outline (append a pen or accept
+    the default pen of 0.25p,black).
 
 .. _-Q:
 
@@ -426,6 +419,7 @@ use it.
 Deprecations
 ------------
 
+- 6.5.0: Modifier +i of the |-N| option is deprecated (but honored). `#7972 <https://github.com/GenericMappingTools/gmt/pull/7972>`_
 - 6.3.0: Modifiers +m, +g et al of |-A| option are moved to |-I|, |-N|, or |-W| option. `#5583 <https://github.com/GenericMappingTools/gmt/pull/5583>`_
 
 See Also

src/figure.c

@@ -65,7 +65,7 @@ static int usage (struct GMTAPI_CTRL *API, int level) {
 	GMT_Usage (API, -2,	"Contains one or more comma-separated options that"
 		" will be passed to psconvert when preparing this figure [%s].", GMT_SESSION_CONVERT);
 	GMT_Usage (API, -2, "\nThe valid subset of psconvert options are");
-	GMT_Usage (API, -3, "A[<args>],C<args>,D<dir>,E<dpi>,H<factor>,Mb|f<file>,Q<args>,S");
+	GMT_Usage (API, -3, "A[<args>],C<args>,D<dir>,E<dpi>,H<factor>,I<args>,Mb|f<file>,N<args>,Q<args>,S");
 	GMT_Usage (API, -2, "See the psconvert documentation for details.");
 	GMT_Option (API, "V,;");
 

src/movie.c

@@ -1994,7 +1994,7 @@ EXTERN_MSC int GMT_movie (void *V_API, int mode, void *args) {
 			goto out_of_here;
 		}
 		sprintf (extra, "A+M+r,N+f%s", gmt_place_var (Ctrl->In.mode, "MOVIE_FADE"));	/* No cropping, image size is fixed, possibly fading */
-		if (Ctrl->E.fill) {strcat (extra, "+g"); strcat (extra, Ctrl->E.fill);}	/* Chose another fade color than black */
+		if (Ctrl->E.fill) {strcat (extra, "+k"); strcat (extra, Ctrl->E.fill);}	/* Chose another fade color than black */
 		if (Ctrl->E.PS) {	/* Need to place a background title first (which will be in parent dir when loop script is run) */
 			strcat (extra, ",Mb../../");
 			strcat (extra, Ctrl->E.file);
@@ -2280,7 +2280,7 @@ EXTERN_MSC int GMT_movie (void *V_API, int mode, void *args) {
 		}
 		else if (Ctrl->K.active) {
 			sprintf (extra, "A+M+r,N+f%s", gmt_place_var (Ctrl->In.mode, "MOVIE_FADE"));	/* No cropping, image size is fixed, but fading may be in effect for some frames */
-			if (Ctrl->K.fill) {strcat (extra, "+g"); strcat (extra, Ctrl->K.fill);}	/* Chose another fade color than black */
+			if (Ctrl->K.fill) {strcat (extra, "+k"); strcat (extra, Ctrl->K.fill);}	/* Chose another fade color than black */
 		}
 		else
 			sprintf (extra, "A+M+r");	/* No cropping, image size is fixed */
@@ -2483,7 +2483,7 @@ EXTERN_MSC int GMT_movie (void *V_API, int mode, void *args) {
 	}
 	if (Ctrl->K.active) {
 		sprintf (extra, "A+M+r,N+f%s", gmt_place_var (Ctrl->In.mode, "MOVIE_FADE"));	/* No cropping, image size is fixed, but fading may be in effect for some frames */
-		if (Ctrl->K.fill) {strcat (extra, "+g"); strcat (extra, Ctrl->K.fill);}	/* Chose another fade color than black */
+		if (Ctrl->K.fill) {strcat (extra, "+k"); strcat (extra, Ctrl->K.fill);}	/* Chose another fade color than black */
 	}
 	else
 		sprintf (extra, "A+M+r");	/* No cropping, image size is fixed */

src/psconvert.c

@@ -146,15 +146,16 @@ struct PSCONVERT_CTRL {
 		bool active;
 		char *file;
 	} M[2];
-	struct PSCONVERT_N {             /* -N[+f<fade>][+g<fill>][+i][+p<pen>] */
+	struct PSCONVERT_N {             /* -N[+f<fade>][+g<backfill>][+k<fadefill>][+p<pen>] with deprecated [+i] */
 		bool active;
 		bool outline;      /* Draw frame around plot with selected pen (+p) [0.25p] */
-		bool paint;        /* Paint box behind plot with selected fill (+g) */
-		bool fade;         /* If true we must fade out the plot to black */
+		bool BB_paint;        /* Paint box behind plot with selected fill (+g) */
+		bool fade;         /* If true we must fade out the plot to black [or what +kfill says] */
 		bool use_ICC_profiles;
 		double fade_level;      /* Fade to black at this level of transparency */
 		struct GMT_PEN pen;
-		struct GMT_FILL fill;
+		struct GMT_FILL back_fill;	/* Initialized to black */
+		struct GMT_FILL fade_fill;	/* Initialized to black */
 	} N;
 	struct PSCONVERT_P {	/* -P */
 		bool active;
@@ -346,14 +347,14 @@ GMT_LOCAL int psconvert_parse_new_I_settings (struct GMT_CTRL *GMT, char *arg, s
 }
 
 GMT_LOCAL int psconvert_parse_new_N_settings (struct GMT_CTRL *GMT, char *arg, struct PSCONVERT_CTRL *Ctrl) {
-	/* Syntax: -N[+f<fade>][+g<fill>][+i][+p<pen>] */
+	/* Syntax: -N[+f<fade>][+g<backfill>][+k<fadefill>][+p<pen>]  with deprecated [+i] */
 
 	unsigned int pos = 0, error = 0;
 	char p[GMT_LEN128] = {""};
 
-	if (gmt_validate_modifiers (GMT, arg, 'N', "fgip", GMT_MSG_ERROR)) return (1);	/* Bail right away */
+	if (gmt_validate_modifiers (GMT, arg, 'N', "fgikp", GMT_MSG_ERROR)) return (1);	/* Bail right away */
 
-	while (gmt_getmodopt (GMT, 'N', arg, "fgip", &pos, p, &error) && error == 0) {
+	while (gmt_getmodopt (GMT, 'N', arg, "fgikp", &pos, p, &error) && error == 0) {
 		switch (p[0]) {
 			case 'f':	/* Fade out */
 				if (!p[1]) {
@@ -368,13 +369,13 @@ GMT_LOCAL int psconvert_parse_new_N_settings (struct GMT_CTRL *GMT, char *arg, s
 				Ctrl->N.fade = true;
 				break;
 			case 'g':	/* Fill background */
-				Ctrl->N.paint = true;
+				Ctrl->N.BB_paint = true;
 				if (!p[1]) {
 					GMT_Report (GMT->parent, GMT_MSG_ERROR, "-N+g: Append the background fill\n");
 					error++;
 				}
-				else if (gmt_getfill (GMT, &p[1], &Ctrl->N.fill)) {
-					gmt_pen_syntax (GMT, 'N', NULL, "sets background fill attributes", NULL, 0);
+				else if (gmt_getfill (GMT, &p[1], &Ctrl->N.back_fill)) {
+					gmt_rgb_syntax (GMT, 'N', "Modifier +g sets background fill attributes");
 					error++;
 				}
 				break;
@@ -384,7 +385,17 @@ GMT_LOCAL int psconvert_parse_new_N_settings (struct GMT_CTRL *GMT, char *arg, s
 				   and that is what psconvert does by default, unless option -I is set.
 				   Note that for GS >= 9.00 and < 9.05 the gray-shade shifting is applied
 				   to all but PDF format. We have no solution to offer other than ... upgrade GS. */
-				Ctrl->N.use_ICC_profiles = true;
+				Ctrl->N.use_ICC_profiles = true;	/* Deprecated in docs but still honored under hood */
+				break;
+			case 'k':	/* Fill for fading */
+				if (!p[1]) {
+					GMT_Report (GMT->parent, GMT_MSG_ERROR, "-N+k: Append the fade fill [black]\n");
+					error++;
+				}
+				else if (gmt_getfill (GMT, &p[1], &Ctrl->N.fade_fill)) {
+					gmt_rgb_syntax (GMT, 'N', "Modifier +k sets background fill attributes");
+					error++;
+				}
 				break;
 			case 'p':	/* Draw outline */
 				Ctrl->N.outline = true;
@@ -399,7 +410,7 @@ GMT_LOCAL int psconvert_parse_new_N_settings (struct GMT_CTRL *GMT, char *arg, s
 				break;
 		}
 	}
-	if (Ctrl->N.fade) Ctrl->N.paint = false;	/* With fading, the paint color is the terminal color */
+	//if (Ctrl->N.fade) Ctrl->N.BB_paint = false;	/* With fading, the paint color is the terminal color */
 
 	return (error);
 }
@@ -460,6 +471,10 @@ GMT_LOCAL int psconvert_parse_A_settings (struct GMT_CTRL *GMT, char *arg, struc
 		strcat (N_option, "+g");
 		strcat (N_option, string);
 	}
+	if (gmt_get_modifier (arg, 'k', string)) {
+		strcat (N_option, "+k");
+		strcat (N_option, string);
+	}
 	if (gmt_get_modifier (arg, 'p', string)) {
 		strcat (N_option, "+p");
 		strcat (N_option, string);
@@ -651,7 +666,7 @@ static int usage (struct GMTAPI_CTRL *API, int level) {
 	if (level == GMT_MODULE_PURPOSE) return (GMT_NOERROR);
 	GMT_Usage (API, 0, "usage: %s <psfiles> [-A[+r][+u]] [-C<gs_option>] [-D<dir>] [-E<resolution>] "
 		"[-F<out_name>] [-G<gs_path>] [-H<scale>] [-I[+m<margins>][+s[m]<width>[/<height>]][+S<scale>]] [-L<list>] [-Mb|f<psfile>] "
-		"[-N[+f<fade>][+g<fill>][+i][+p[<pen>]]] [-P] [-Q[g|p|t]1|2|4] [-S] [-Tb|e|E|f|F|g|G|j|m|s|t[+m][+q<quality>]] [%s] "
+		"[-N[+f<fade>][+g<backfill>][+k<fadefill>][+p[<pen>]]] [-P] [-Q[g|p|t]1|2|4] [-S] [-Tb|e|E|f|F|g|G|j|m|s|t[+m][+q<quality>]] [%s] "
 		"[-W[+a<mode>[<alt>]][+c][+f<minfade>/<maxfade>][+g][+k][+l<lodmin>/<lodmax>][+n<name>][+o<folder>][+t<title>][+u<URL>]]%s "
 		"[%s]\n", name, GMT_V_OPT, Z, GMT_PAR_OPT);
 
@@ -715,12 +730,11 @@ static int usage (struct GMTAPI_CTRL *API, int level) {
 	GMT_Usage (API, -2, "Sandwich current psfile between background and foreground plots:");
 	GMT_Usage (API, 3, "b: Append the name of a background PostScript plot [none].");
 	GMT_Usage (API, 3, "f: Append name of foreground PostScript plot [none].");
-	GMT_Usage (API, 1, "\n-N[+f<fade>][+g<fill>][+i][+p[<pen>]]");
+	GMT_Usage (API, 1, "\n-N[+f<fade>][+g<backfill>][+k<fadefill>][+p[<pen>]]");
 	GMT_Usage (API, -2, "Specify painting, fading, or outline of the BoundingBox via optional modifiers:");
-	GMT_Usage (API, 3, "+f Append <fade> (0-100) to fade entire plot to black (100%% fade)[no fading]. "
-		"Use +g to change the fade color [black].");
-	GMT_Usage (API, 3, "+g Append <fill> to paint the BoundingBox [no fill].");
-	GMT_Usage (API, 3, "+i Change gray-shades by using ICC profiles [Default sets -dUseFastColor=true].");
+	GMT_Usage (API, 3, "+f Append <fade> (0-100) to fade entire plot to black (100%% fade)[no fading].");
+	GMT_Usage (API, 3, "+g Append <backfill> to paint the BoundingBox first [no fill].");
+	GMT_Usage (API, 3, "+k Append <fadefill> to indicate color at full fade [black].");
 	GMT_Usage (API, 3, "+p Outline the BoundingBox, optionally append <pen> [%s].",
 		gmt_putpen (API->GMT, &API->GMT->current.setting.map_default_pen));
 	GMT_Usage (API, 1, "\n-P Force Portrait mode. All Landscape mode plots will be rotated back "
@@ -1133,10 +1147,10 @@ GMT_LOCAL void psconvert_possibly_fill_or_outline_BB (struct GMT_CTRL *GMT, stru
 	/* Check if user wanted to paint or outline the BoundingBox - otherwise do nothing */
 	char *ptr = NULL;
 	GMT->PSL->internal.dpp = PSL_DOTS_PER_INCH / 72.0;	/* Dots pr. point resolution of output device, set here since no PSL initialization */
-	if (N->paint) {	/* Paint the background of the page */
-		GMT_Report (GMT->parent, GMT_MSG_INFORMATION, "Paint background BoundingBox using paint %s\n", gmt_putrgb (GMT, N->fill.rgb));
-		if (GMT->PSL->internal.comments) fprintf (fp, "%% Paint background BoundingBox using paint %s\n", gmt_putrgb (GMT, N->fill.rgb));
-		ptr = PSL_makecolor (GMT->PSL, N->fill.rgb);
+	if (N->BB_paint) {	/* Paint the background of the page */
+		GMT_Report (GMT->parent, GMT_MSG_INFORMATION, "Paint background BoundingBox using paint %s\n", gmt_putrgb (GMT, N->back_fill.rgb));
+		if (GMT->PSL->internal.comments) fprintf (fp, "%% Paint background BoundingBox using paint %s\n", gmt_putrgb (GMT, N->back_fill.rgb));
+		ptr = PSL_makecolor (GMT->PSL, N->back_fill.rgb);
 		fprintf (fp, "gsave clippath %s F N U\n", ptr);
 	}
 	if (N->outline) {	/* Draw the outline of the page */
@@ -2203,7 +2217,7 @@ EXTERN_MSC int GMT_psconvert (void *V_API, int mode, void *args) {
 		/* To produce non-PDF output from PS with transparency we must determine if transparency is requested in the PS */
 		look_for_transparency = Ctrl->T.device != GS_DEV_PDF && Ctrl->T.device != -GS_DEV_PDF;
 		has_transparency = transparency = add_grestore = false;
-		set_background = (Ctrl->N.paint || Ctrl->N.outline);
+		set_background = (Ctrl->N.BB_paint || Ctrl->N.outline);
 		trans_line = 0;
 
 		while (psconvert_file_line_reader (GMT, &line, &line_size, fp, PS->data, &pos) != EOF) {
@@ -2427,8 +2441,8 @@ EXTERN_MSC int GMT_psconvert (void *V_API, int mode, void *args) {
 			}
 			else if (Ctrl->N.fade && !strncmp (line, "%%PageTrailer", 13) && Ctrl->N.fade_level > 0.0) {
 				/* Place a transparent black rectangle over everything, at level of transparency */
-				char *ptr = PSL_makecolor (GMT->PSL, Ctrl->N.fill.rgb);
-				GMT_Report (API, GMT_MSG_INFORMATION, "Append fading to %s at %d%%.\n", gmt_putrgb (GMT, Ctrl->N.fill.rgb), irint (100.0*Ctrl->N.fade_level));
+				char *ptr = PSL_makecolor (GMT->PSL, Ctrl->N.fade_fill.rgb);
+				GMT_Report (API, GMT_MSG_INFORMATION, "Append fading to %s at %d%%.\n", gmt_putrgb (GMT, Ctrl->N.fade_fill.rgb), irint (100.0*Ctrl->N.fade_level));
 				fprintf (fpo, "V clippath %s %g %g /Normal PSL_transp F N U\n", ptr, Ctrl->N.fade_level, Ctrl->N.fade_level);
 				transparency = true;
 			}