From fe5cf32041c1afe09ecaec08f157d0da3b0e8fa3 Mon Sep 17 00:00:00 2001
From: Paul Wessel <pwessel@hawaii.edu>
Date: Tue, 28 Nov 2023 10:50:38 +0100
Subject: [PATCH] Fix incomplete -Q in docs and usage messages

The -Q option can either take an integer (number of points a contour has to have to be plotted) or a minimum length in a variety of units.  The code parsed that but apart from the usage message the synopsis and docs did not mention the length choice.  This PR updates the synopsis and docs.
---
 doc/rst/source/contour.rst    | 6 +++---
 doc/rst/source/grdcontour.rst | 6 +++---
 doc/rst/source/pscontour.rst  | 2 +-
 src/grdcontour.c              | 6 +++---
 src/pscontour.c               | 4 ++--
 5 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/doc/rst/source/contour.rst b/doc/rst/source/contour.rst
index e5a00665dab..1091c7d601f 100644
--- a/doc/rst/source/contour.rst
+++ b/doc/rst/source/contour.rst
@@ -26,7 +26,7 @@ Synopsis
 [ |-J|\ **z**\|\ **Z**\ *parameters* ]
 [ |-L|\ *pen* ]
 [ |-N| ]
-[ |-Q|\ [*n*][**+z**] ]
+[ |-Q|\ [*n*\|\ *length*\ [*unit*]][**+z**] ]
 [ |-S|\ [*p*\|\ *t*] ]
 [ |-T|\ [**h**\|\ **l**][**+a**][**+d**\ *gap*\ [/*length*]][**+l**\ [*labels*]] ]
 [ |SYN_OPT-U| ]
@@ -185,9 +185,9 @@ Optional Arguments
 
 .. _-Q:
 
-**-Q**\ [*n*][**+z**]
+**-Q**\ [*n*\|\ *length*\ [*unit*]][**+z**]
     Do not draw contours with less than *n* number of points [Draw all contours].
-    Alternatively, give instead a minimum contour length in distance units
+    Alternatively, give instead a minimum contour *length* in distance units
     (see `Units`_ for available units and how distances are computed),
     including **c** (Cartesian distances using user coordinates) or **C** for plot
     length units in current plot units after projecting the coordinates.
diff --git a/doc/rst/source/grdcontour.rst b/doc/rst/source/grdcontour.rst
index ef9f527ba0d..b7ad517ad9f 100644
--- a/doc/rst/source/grdcontour.rst
+++ b/doc/rst/source/grdcontour.rst
@@ -21,7 +21,7 @@ Synopsis
 [ |-G|\ [**d**\|\ **f**\|\ **n**\|\ **l**\|\ **L**\|\ **x**\|\ **X**]\ *params* ]
 [ |-L|\ *low/high*\|\ **n**\|\ **N**\|\ **P**\|\ **p** ]
 [ |-N|\ [*cpt*] ]
-[ |-Q|\ [*n*][**+z**] ]
+[ |-Q|\ [*n*\|\ *length*\ [*unit*]][**+z**] ]
 [ |SYN_OPT-Rz| ]
 [ |-S|\ *smoothfactor* ]
 [ |-T|\ [**h**\|\ **l**][**+a**][**+d**\ *gap*\ [/*length*]][**+l**\ [*labels*]] ]
@@ -177,9 +177,9 @@ Optional Arguments
 
 .. _-Q:
 
-**-Q**\ [*n*][**+z**]
+**-Q**\ [*n*\|\ *length*\ [*unit*]][**+z**]
     Do not draw contours with less than *n* number of points [Draw all contours].
-    Alternatively, give instead a minimum contour length in distance units
+    Alternatively, give instead a minimum contour *length* in distance units
     (see `Units`_ for available units and how distances are computed),
     including **c** (Cartesian distances using user coordinates) or **C** for plot
     length units in current plot units after projecting the coordinates.
diff --git a/doc/rst/source/pscontour.rst b/doc/rst/source/pscontour.rst
index 06bf89dede5..97bda351eb3 100644
--- a/doc/rst/source/pscontour.rst
+++ b/doc/rst/source/pscontour.rst
@@ -29,7 +29,7 @@ Synopsis
 [ |-N| ]
 [ |-O| ]
 [ |-P| ]
-[ |-Q|\ [*n*][**+z**] ]
+[ |-Q|\ [*n*\|\ *length*\ [*unit*]][**+z**] ]
 [ |-S|\ [**p**\|\ **t**] ]
 [ |-T|\ [**h**\|\ **l**][**+a**][**+d**\ *gap*\ [/*length*]][**+l**\ [*labels*]] ]
 [ |SYN_OPT-U| ]
diff --git a/src/grdcontour.c b/src/grdcontour.c
index 2d041a592f5..142f52eadd2 100644
--- a/src/grdcontour.c
+++ b/src/grdcontour.c
@@ -172,7 +172,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 %s [-A[n|[+]<int>|<list>][<labelinfo>]] [%s] [-C<contours>] "
-		"[-D<template>] [-F[l|r]] [%s] %s[-L<low>/<high>|n|N|P|p] [-N[<cpt>]] %s%s[-Q[<n>][+z]] [%s] "
+		"[-D<template>] [-F[l|r]] [%s] %s[-L<low>/<high>|n|N|P|p] [-N[<cpt>]] %s%s[-Q[<n>|<length>[unit]][+z]] [%s] "
 		"[-S<smooth>] [%s] [%s] [%s] [-W[a|c]<pen>[+c[l|f]]] [%s] [%s] [-Z[+o<shift>][+p][+s<fact>]] "
 		"[%s] %s[%s] [%s] [%s] [%s] [%s] [%s]\n", name, GMT_INGRID, GMT_J_OPT, GMT_B_OPT, GMT_CONTG, API->K_OPT, API->O_OPT,
 		API->P_OPT, GMT_Rgeoz_OPT, GMT_CONTT, GMT_U_OPT, GMT_V_OPT, GMT_X_OPT, GMT_Y_OPT, GMT_bo_OPT, API->c_OPT,
@@ -233,9 +233,9 @@ static int usage (struct GMTAPI_CTRL *API, int level) {
 	GMT_Usage (API, -2, "Fill area between contour with the colors in a discrete CPT. If <cpt> is given the "
 		"we use that <cpt> for the fill, else -C<cpt> must be given and used instead [no fill].");
 	GMT_Option (API, "O,P");
-	GMT_Usage (API, 1, "\n-Q[<n>][+z]");
+	GMT_Usage (API, 1, "\n-Q[<n>|<length>[unit]][+z]");
 	GMT_Usage (API, -2, "Do not draw closed contours with less than <n> points [Draw all contours]. "
-		"Alternatively, give a minimum contour length and append a unit (%s, or c for Cartesian). "
+		"Alternatively, give a minimum contour <length> and append a unit (%s, or c for Cartesian). "
 		"Unit C means Cartesian distances after first projecting the input coordinates. "
 		"Optionally, append +z to skip tracing the zero-contour.", GMT_LEN_UNITS_DISPLAY);
 	GMT_Option (API, "R");
diff --git a/src/pscontour.c b/src/pscontour.c
index 0b56d41019e..380b89d8f97 100644
--- a/src/pscontour.c
+++ b/src/pscontour.c
@@ -389,7 +389,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 <table> %s %s [-A[n|<contours>][<labelinfo>]] [%s] [-C<contours>] [-D<template>] "
-		"[-E<indextable>[+b]] [%s] [-I] %s[-L<pen>] [-N] %s%s[-Q[<n>][+z]] [-S[p|t]] [%s] [%s] [-W[a|c]<pen>[+c[l|f]]] "
+		"[-E<indextable>[+b]] [%s] [-I] %s[-L<pen>] [-N] %s%s[-Q[<n>|<length>[unit]][+z]] [-S[p|t]] [%s] [%s] [-W[a|c]<pen>[+c[l|f]]] "
 		"[%s] [%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, GMT_CONTG, API->K_OPT, API->O_OPT, API->P_OPT, GMT_CONTT, GMT_U_OPT,
 	     GMT_V_OPT, GMT_X_OPT, GMT_Y_OPT, GMT_b_OPT, API->c_OPT, GMT_d_OPT, GMT_e_OPT, GMT_f_OPT, GMT_h_OPT, GMT_i_OPT,
@@ -445,7 +445,7 @@ static int usage (struct GMTAPI_CTRL *API, int level) {
 	gmt_pen_syntax (API->GMT, 'L', NULL, "Draws the triangular mesh with the specified pen.", NULL, 0);
 	GMT_Usage (API, 1, "\n-N Do NOT clip contours/image at the border [Default clips].");
 	GMT_Option (API, "O,P");
-	GMT_Usage (API, 1, "\n-Q[<n>][+z]");
+	GMT_Usage (API, 1, "\n-Q[<n>|<length>[unit]][+z]");
 	GMT_Usage (API, -2, "Do not draw closed contours with less than <n> points [Draw all contours]. "
 		"Alternatively, give a minimum contour length and append a unit (%s, or c for Cartesian). "
 		"Unit C means Cartesian distances after first projecting the input coordinates. "