Improve windbarb docs, synopsis and usage for -Q and parsing of -Q (#8314)

* Improve docs for -Q and parsing of -Q

THe -Q option now lists the modifiers, and +z only allowed in psbarb.  THe docs shows -Q modifiers under the -Q option and not a separate section.

* polish rst docs

* Pollish

* Constant -Q arg string added

* Update grdbarb.rst

* Update barb.rst

Author: PaulWessel

doc/rst/source/supplements/windbarbs/barb.rst

@@ -23,7 +23,7 @@ Synopsis
 [ |-G|\ *fill* ]
 [ |-I|\ *intens* ]
 [ |-N| ]
-[ |-Q|\ *parameters* ]
+[ |-Q|\ *length*\ [**+a**\ *angle*][**+g**\ -\|\ *fill*][**+jb**\|\ **c**\|\ **e**][**+p**\ -\|\ *pen*][**+s**\ *scale*][**+w**\ *width*][**+z**] ]
 [ |SYN_OPT-U| ]
 [ |SYN_OPT-V| ]
 [ |-W|\ [*pen*][*attr*] ]
@@ -56,7 +56,6 @@ interpret the third and fourth columns of the input data as barb length and
 width, respectively.
 Select a fill with |-G|. If |-G| is set, |-W| will control
 whether the outline is drawn or not.
-The PostScript code is written to standard output.
 
 Required Arguments
 ------------------
@@ -132,9 +131,24 @@ Optional Arguments
 
 .. _-Q:
 
-**-Q**\ *parameters*
+**-Q**\ *length*\ [**+a**\ *angle*][**+g**\ -\|\ *fill*][**+jb**\|\ **c**\|\ **e**][**+p**\ -\|\ *pen*][**+s**\ *scale*][**+w**\ *width*][**+z**]
     Modify wind barb parameters. Append wind barb *length* [Default is 0.5c].
-    See `Wind Barb Attributes`_ for specifying additional attributes.
+    Several modifiers may be appended to specify the placement of barbs, their shapes, and the
+    justification of the wind barb. Below, left and right refers to the
+    side of the wind barb line when viewed from the start point to the
+    end point of the segment. Chose among these modifiers:
+
+    - **+a** - Set the angle of the wind barb [120].
+    - **+g** - Turn off *fill* (if -) or set the wind
+      barb fill [Default fill is used, which may be no fill].
+    - **+p** - Sets the wind barb pen attributes. If *pen* has a
+      leading - then the outline is not drawn [Default pen is used, and
+      outline is drawn].
+    - **+j** - Determines how the input *x*,\ *y* point relates to the
+      wind barb. Choose from **b**\ eginning [default], **e**\ nd, or **c**\ enter.
+    - **+s** - Set the wind speed which corresponds to a long barb [default 5].
+    - **+w** - Set the *width* of wind barbs.
+    - **+z** - Input (u,v) wind components instead of (azimuth,speed).
 
 .. |Add_-U| replace:: |Add_-U_links|
 .. include:: ../../explain_-U.rst_
@@ -188,9 +202,6 @@ Optional Arguments
 
 .. include:: ../../explain_help.rst_
 
-.. include:: explain_windbarbs.rst_
-**+z** to input (u,v) wind components instead of (azimuth,speed)
-
 .. module_common_ends
 
 Examples

doc/rst/source/supplements/windbarbs/explain_windbarbs.rst_

@@ -23,7 +23,7 @@ Synopsis
 [ |-G|\ *fill* ]
 [ |-I|\ [**x**]\ *dx*\ [/*dy*] ]
 [ |-N| ]
-[ |-Q|\ *parameters* ]
+[ |-Q|\ *length*\ [**+a**\ *angle*][**+g**\ -\|\ *fill*][**+jb**\|\ **c**\|\ **e**][**+p**\ -\|\ *pen*][**+s**\ *scale*][**+w**\ *width*] ]
 [ |SYN_OPT-R| ]
 [ |-T| ]
 [ |SYN_OPT-U| ]
@@ -112,10 +112,24 @@ Optional Arguments
 
 .. _-Q:
 
-**-Q**\ *parameters*
+**-Q**\ *length*\ [**+a**\ *angle*][**+g**\ -\|\ *fill*][**+jb**\|\ **c**\|\ **e**][**+p**\ -\|\ *pen*][**+s**\ *scale*][**+w**\ *width*]
     Modify wind barb parameters. Append wind barb *length* [Default is 0.5c].
-    See `Wind Barb Attributes`_ for specifying additional attributes.
-
+    Several modifiers may be appended to specify the placement of barbs, their shapes, and the
+    justification of the wind barb. Below, left and right refers to the
+    side of the wind barb line when viewed from the start point to the
+    end point of the segment. Chose among these modifiers:
+
+    - **+a** - Set the angle of the wind barb [120].
+    - **+g** - Turn off *fill* (if -) or set the wind
+      barb fill [Default fill is used, which may be no fill].
+    - **+p** - Sets the wind barb pen attributes. If *pen* has a
+      leading - then the outline is not drawn [Default pen is used, and
+      outline is drawn].
+    - **+j** - Determines how the input *x*,\ *y* point relates to the
+      wind barb. Choose from **b**\ eginning [default], **e**\ nd, or **c**\ enter.
+    - **+s** - Set the wind speed which corresponds to a long barb [default 5].
+    - **+w** - Set the *width* of wind barbs.
+ 
 .. _-R:
 
 .. |Add_-Rgeo| replace:: |Add_-R_auto_table|
@@ -167,8 +181,6 @@ Optional Arguments
 
 .. include:: ../../explain_grd_inout.rst_
 
-.. include:: explain_windbarbs.rst_
-
 
 Examples
 --------
@@ -191,4 +203,4 @@ See Also
 --------
 
 :doc:`gmt </gmt>`, :doc:`gmtcolors </gmtcolors>`,
-:doc:`grdvector </grdvector>`, :doc:`psbarb`
+:doc:`grdvector </grdvector>`, :doc:`barb`

doc/rst/source/supplements/windbarbs/grdbarb.rst

@@ -100,8 +100,8 @@ GMT_LOCAL 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 <gridx> <gridy> %s [-A] [%s] [-C[<cpt>]] [-G<fill>] [-I[x]<dx>/<dy>] "
-		"%s[-N] %s%s[-Q<params>] [%s] [-T] [%s] [%s] [-W<pen>] [%s] [%s] [-Z] "
-		"%s [%s] [%s] [%s] [%s]\n", name, GMT_J_OPT, GMT_B_OPT, API->K_OPT, API->O_OPT, API->P_OPT,
+		"%s[-N] %s%s[-Q%s] [%s] [-T] [%s] [%s] [-W<pen>] [%s] [%s] [-Z] "
+		"%s [%s] [%s] [%s] [%s]\n", name, GMT_J_OPT, GMT_B_OPT, API->K_OPT, API->O_OPT, API->P_OPT, GMT_BARG_PARAMS,
 		GMT_Rgeo_OPT, GMT_U_OPT, GMT_V_OPT, GMT_X_OPT, GMT_Y_OPT, API->c_OPT, GMT_f_OPT, GMT_p_OPT, GMT_t_OPT, GMT_PAR_OPT);
 
 	if (level == GMT_SYNOPSIS) return (GMT_MODULE_SYNOPSIS);
@@ -197,7 +197,7 @@ GMT_LOCAL int parse (struct GMT_CTRL *GMT, struct GRDBARB_CTRL *Ctrl, struct GMT
 				Ctrl->N.active = true;
 				break;
 			case 'Q':	/* Set wind barb parameters */
-				n_errors += gmt_parse_barb (GMT, opt->arg, &Ctrl->Q.B);
+				n_errors += gmt_parse_barb (GMT, opt->arg, &Ctrl->Q.B, 0);
 				break;
 			case 'T':	/* Rescale Cartesian angles */
 				Ctrl->T.active = true;

src/windbarbs/grdbarb.c

@@ -112,9 +112,9 @@ GMT_LOCAL 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 [<table>] %s %s [%s] [-C<cpt>] [-D<dx>/<dy>] [-G<fill>|+z] "
-		"[-I[<intens>]] %s [-N[c|r]] %s%s [-Q[<params>]] [%s] [%s] [-W[<pen>][<attr>]] [%s] [%s] "
+		"[-I[<intens>]] %s [-N[c|r]] %s%s [-Q[%s[+z]] [%s] [%s] [-W[<pen>][<attr>]] [%s] [%s] "
 		"[-Z<value>|<file>[+t|T]] [%s] [%s] %s[%s] [%s] [%s] [%s] [%s] [%s] [%s] [%s] [%s] [%s] [%s] [%s] [%s]\n",
-		name, GMT_J_OPT, GMT_Rgeoz_OPT, GMT_B_OPT, API->K_OPT, API->O_OPT, API->P_OPT,
+		name, GMT_J_OPT, GMT_Rgeoz_OPT, GMT_B_OPT, API->K_OPT, API->O_OPT, API->P_OPT, GMT_BARG_PARAMS,
 		GMT_U_OPT, GMT_V_OPT, GMT_X_OPT, GMT_Y_OPT, GMT_a_OPT, GMT_bi_OPT, API->c_OPT,
 		GMT_di_OPT, GMT_e_OPT, GMT_f_OPT, GMT_g_OPT, GMT_h_OPT, GMT_i_OPT, GMT_l_OPT, GMT_p_OPT, GMT_q_OPT, GMT_tv_OPT,
 		GMT_w_OPT, GMT_colon_OPT, GMT_PAR_OPT);
@@ -242,7 +242,7 @@ GMT_LOCAL int parse (struct GMT_CTRL *GMT, struct PSBARB_CTRL *Ctrl, struct GMT_
 				}
 				break;
 			case 'Q':	/* Set wind barb parameters */
-				n_errors += gmt_parse_barb (GMT, opt->arg, &Ctrl->Q.B);
+				n_errors += gmt_parse_barb (GMT, opt->arg, &Ctrl->Q.B, 1);
 				break;
 			case 'T':		/* Skip all input files */
 				Ctrl->T.active = true;

src/windbarbs/psbarb.c

@@ -44,15 +44,15 @@ void gmt_barb_syntax (struct GMT_CTRL *GMT, char option, char *string, unsigned
 	 * 1	= Accepts +z (not mathangle)
 	 */
 	struct GMTAPI_CTRL *API = GMT->parent;
-	GMT_Usage (API, 1, "\n-%c<params>", option);
+	GMT_Usage (API, 1, "\n-%c%s[+z]", option, GMT_BARG_PARAMS);
 	GMT_Usage (API, -2, "%s Append length of wind barbs, with optional modifiers:", string);
-	GMT_Usage (API, 3, "+a<angle> to set angle of wind barb [120]");
-	GMT_Usage (API, 3, "+g<fill> to set fill or use - to turn off fill [default fill].");
-	GMT_Usage (API, 3, "+j<just> to justify wind barb at (b)eginning [default], (e)nd, or (c)enter.");
-	GMT_Usage (API, 3, "+p[-][<pen>] to set pen attributes, prepend - to turn off outlines [default pen and outline].");
-	GMT_Usage (API, 3, "+s[scale] to set the wind speed which corresponds to a long wind barb [default 5]");
-	GMT_Usage (API, 3, "+w[width] to set the width of wind barbs");
-	if (mode & 1) GMT_Usage (API, 3, "+z if (u,v) wind components are given instead of (azimuth,speed) on input.");
+	GMT_Usage (API, 3, "+a Append angle of wind barb [120]");
+	GMT_Usage (API, 3, "+g Set fill or use - to turn off fill [default fill].");
+	GMT_Usage (API, 3, "+j Append b|c|e to justify wind barb at (b)eginning [default], (e)nd, or (c)enter.");
+	GMT_Usage (API, 3, "+p Set pen attributes, or prepend - to turn off outlines [default pen and outline].");
+	GMT_Usage (API, 3, "+s Set the wind speed scale which corresponds to a long wind barb [default 5]");
+	GMT_Usage (API, 3, "+w Set the width of wind barbs");
+	if (mode & 1) GMT_Usage (API, 3, "+z Wind components (u,v) are given instead of (azimuth,speed) on input.");
 }
 
 int gmt_draw_barb (struct GMT_CTRL *GMT, double x0, double y0, double lat, double theta, double spd, struct GMT_BARB_ATTR B, struct GMT_PEN *pen, struct GMT_FILL *fill, unsigned int outline)
@@ -169,7 +169,7 @@ int gmt_init_barb_param (struct GMT_CTRL *GMT, struct GMT_BARB_ATTR *B, bool set
 }
 
 /*! Parser for -Q */
-GMT_LOCAL int gmt_parse_barb_v5 (struct GMT_CTRL *GMT, char *text, struct GMT_BARB_ATTR *B) {
+GMT_LOCAL int gmt_parse_barb_v5 (struct GMT_CTRL *GMT, char *text, struct GMT_BARB_ATTR *B, unsigned int mode) {
 
 	unsigned int pos = 0, k, error = 0;
 	bool p_opt = false, g_opt = false;
@@ -191,7 +191,7 @@ GMT_LOCAL int gmt_parse_barb_v5 (struct GMT_CTRL *GMT, char *text, struct GMT_BA
 				B->status |= PSL_VEC_FILL;
 				if (p[1]) {
 					if (gmt_getfill (GMT, &p[1], &B->fill)) {
-						GMT_Report (GMT->parent, GMT_MSG_NORMAL, "Bad +g<fill> modifier %c\n", &p[1]);
+						GMT_Report (GMT->parent, GMT_MSG_NORMAL, "Option -Q: Bad +g-|<fill> modifier %c\n", &p[1]);
 						error++;
 					}
 					B->status |= PSL_VEC_FILL2;
@@ -203,7 +203,7 @@ GMT_LOCAL int gmt_parse_barb_v5 (struct GMT_CTRL *GMT, char *text, struct GMT_BA
 					case 'c': B->status |= PSL_VEC_JUST_C;	break;	/* Input (x,y) refers to center point */
 					case 'e': B->status |= PSL_VEC_JUST_E;	break;	/* Input (x,y) refers to end point */
 					default:  /* Bad justifier code */
-						GMT_Report (GMT->parent, GMT_MSG_NORMAL, "Bad +j<just> modifier %c\n", p[1]);
+						GMT_Report (GMT->parent, GMT_MSG_NORMAL, "Option -Q: Bad +j<just> modifier %c\n", p[1]);
 						error++;
 						break;
 				}
@@ -218,7 +218,7 @@ GMT_LOCAL int gmt_parse_barb_v5 (struct GMT_CTRL *GMT, char *text, struct GMT_BA
 				}
 				if (p[j]) {	/* Change default pen */
 					if (gmt_getpen (GMT, &p[j], &B->pen)) {
-						GMT_Report (GMT->parent, GMT_MSG_NORMAL, "Bad +p<pen> modifier %c\n", &p[1]);
+						GMT_Report (GMT->parent, GMT_MSG_NORMAL, "Option -Q: Bad +p-|<pen> modifier %c\n", &p[1]);
 						error++;
 					}
 					B->status |= PSL_VEC_OUTLINE2;	/* Flag that a pen specification was given */
@@ -231,10 +231,15 @@ GMT_LOCAL int gmt_parse_barb_v5 (struct GMT_CTRL *GMT, char *text, struct GMT_BA
 				B->width = (float)gmt_M_to_inch (GMT, &p[1]);
 				break;
 			case 'z':	/* Input (angle,length) are vector components (dx,dy) instead */
-				B->status |= PSL_VEC_COMPONENTS;
+				if (mode == 1)	/* Only psbarb can take +z */
+					B->status |= PSL_VEC_COMPONENTS;
+				else {	/* grdbarb does not take -Q+z */
+					GMT_Report (GMT->parent, GMT_MSG_NORMAL, "Option -Q: Bad modifier +z\n");
+					error++;
+				}
 				break;
 			default:
-				GMT_Report (GMT->parent, GMT_MSG_NORMAL, "Bad modifier +%c\n", p[0]);
+				GMT_Report (GMT->parent, GMT_MSG_NORMAL, "Option -Q: Bad modifier +%c\n", p[0]);
 				error++;
 				break;
 		}
@@ -252,7 +257,7 @@ GMT_LOCAL int gmt_parse_barb_v5 (struct GMT_CTRL *GMT, char *text, struct GMT_BA
 }
 
 /*! Parser for -Q */
-int gmt_parse_barb (struct GMT_CTRL *GMT, char *text, struct GMT_BARB_ATTR *B) {
+int gmt_parse_barb (struct GMT_CTRL *GMT, char *text, struct GMT_BARB_ATTR *B, unsigned int mode) {
 
 	char txt_a[GMT_LEN256] = {""}, txt_b[GMT_LEN256] = {""}, txt_c[GMT_LEN256] = {""}, txt_d[GMT_LEN256] = {""};
 	unsigned int error = 0;
@@ -276,13 +281,13 @@ int gmt_parse_barb (struct GMT_CTRL *GMT, char *text, struct GMT_BARB_ATTR *B) {
 	}
 	else {
 		if (text[0] == '+') {	/* No size (use default), just attributes */
-			error += gmt_parse_barb_v5 (GMT, text, B);
+			error += gmt_parse_barb_v5 (GMT, text, B, mode);
 		}
 		else {	/* Size, plus possible attributes */
 			j = sscanf (text, "%[^+]%s", txt_a, txt_b);	/* txt_a should be symbols size with any +<modifiers> in txt_b */
 			if (j == 1) txt_b[0] = 0;	/* No modifiers present, set txt_b to empty */
 			if (j >= 1) B->length = gmt_M_to_inch (GMT, txt_a);	/* Length of barb */
-			error += gmt_parse_barb_v5 (GMT, txt_b, B);
+			error += gmt_parse_barb_v5 (GMT, txt_b, B, mode);
 		}
 	}
 

src/windbarbs/windbarb.c

@@ -18,6 +18,8 @@
 #ifndef _GMT_WINDBARB_H
 #define _GMT_WINDBARB_H
 
+#define GMT_BARG_PARAMS "<length>[+a<angle>][+g[<fill>|-][+jb|c|e][+p[-|<pen>][+s<scale>][+w>width>]"
+
 struct GMT_BARB_ATTR {
 	/* Container for common attributes for plot attributes of wind barbs */
 	unsigned int status;	/* Bit flags for barb position information (see GMT_enum_vecattr above) */
@@ -33,6 +35,6 @@ struct GMT_BARB_ATTR {
 EXTERN_MSC void gmt_barb_syntax (struct GMT_CTRL *GMT, char option, char *string, unsigned int mode);
 EXTERN_MSC int gmt_draw_barb (struct GMT_CTRL *GMT, double x0, double y0, double lat, double theta, double spd, struct GMT_BARB_ATTR B, struct GMT_PEN *pen, struct GMT_FILL *fill, unsigned int outline);
 EXTERN_MSC int gmt_init_barb_param (struct GMT_CTRL *GMT, struct GMT_BARB_ATTR *B, bool set, bool outline, struct GMT_PEN *pen, bool do_fill, struct GMT_FILL *fill);
-EXTERN_MSC int gmt_parse_barb (struct GMT_CTRL *GMT, char *text, struct GMT_BARB_ATTR *B);
+EXTERN_MSC int gmt_parse_barb (struct GMT_CTRL *GMT, char *text, struct GMT_BARB_ATTR *B, unsigned int mode);
 
 #endif /* _GMT_WINDBARB_H */