Split the excessively generic diagnostic message "invalid escape sequence"

into the more specific messages "invalid escape argument delimiter"
and "invalid escape sequence argument".

10 files changed, 49 insertions, 26 deletions

diff --git a/mandoc.1 b/mandoc.1
index e2cd0b5c..aa6274ae 100644
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,4 +1,4 @@
-.\" $Id: mandoc.1,v 1.259 2022/06/05 13:54:09 schwarze Exp $
+.\" $Id: mandoc.1,v 1.260 2022/06/07 09:54:40 schwarze Exp $
 .\"
 .\" Copyright (c) 2012, 2014-2022 Ingo Schwarze <schwarze@openbsd.org>
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: June 5 2022 $
+.Dd $Mdocdate: June 7 2022 $
 .Dt MANDOC 1
 .Os
 .Sh NAME
@@ -1797,10 +1797,9 @@ it is hard to predict which tab stop position the tab will advance to.
 .Pq mdoc
 A new sentence starts in the middle of a text line.
 Start it on a new input line to help formatters produce correct spacing.
-.It Sy "invalid escape sequence"
+.It Sy "invalid escape sequence argument"
 .Pq roff
-An escape sequence has an invalid opening argument delimiter
-or the argument is of an invalid form.
+The argument of an escape sequence is of an invalid form.
 Invalid escape sequences are ignored.
 .It Sy "undefined escape, printing literally"
 .Pq roff
@@ -2314,6 +2313,18 @@ The escape sequence is ignored.
 The name given in a special character escape sequence is not known to
 .Nm .
 The escape sequence is ignored.
+.It Sy "invalid escape argument delimiter"
+.Pq roff
+An escape sequence that expects a numerical argument
+attempts to employ one of the characters
+.Qq " %&()*+-./0123456789:<=>"
+as an argument delimiter.
+The escape sequence is ignored including the invalid opening delimiter
+and the rest of the argument may appear as output text.
+While various charcters can be used as argument delimiters,
+using the apostrophe-quote character
+.Pq Sq \(aq
+is recommended for readability and robustness.
 .El
 .Ss Unsupported features
 .Bl -ohang
diff --git a/mandoc.h b/mandoc.h
index f50405e9..7fd34ed4 100644
--- a/mandoc.h
+++ b/mandoc.h
@@ -1,4 +1,4 @@
-/* $Id: mandoc.h,v 1.278 2022/06/05 13:54:09 schwarze Exp $ */
+/* $Id: mandoc.h,v 1.279 2022/06/07 09:54:40 schwarze Exp $ */
 /*
  * Copyright (c) 2012-2022 Ingo Schwarze <schwarze@openbsd.org>
  * Copyright (c) 2010, 2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
@@ -172,7 +172,7 @@ enum	mandocerr {
 	MANDOCERR_FI_BLANK, /* blank line in fill mode, using .sp */
 	MANDOCERR_FI_TAB, /* tab in filled text */
 	MANDOCERR_EOS, /* new sentence, new line */
-	MANDOCERR_ESC_BAD, /* invalid escape sequence: esc */
+	MANDOCERR_ESC_ARG, /* invalid escape sequence argument: esc */
 	MANDOCERR_ESC_UNDEF, /* undefined escape, printing literally: char */
 	MANDOCERR_STR_UNDEF, /* undefined string, using "": name */
 
@@ -239,6 +239,7 @@ enum	mandocerr {
 	MANDOCERR_ESC_INCOMPLETE, /* incomplete escape sequence: esc */
 	MANDOCERR_ESC_BADCHAR, /* invalid special character: esc */
 	MANDOCERR_ESC_UNKCHAR, /* unknown special character: esc */
+	MANDOCERR_ESC_DELIM, /* invalid escape argument delimiter: esc */
 
 	MANDOCERR_UNSUPP, /* ===== start of unsupported features ===== */
 
diff --git a/mandoc_msg.c b/mandoc_msg.c
index 566a140e..baa709c7 100644
--- a/mandoc_msg.c
+++ b/mandoc_msg.c
@@ -173,7 +173,7 @@ static	const char *const type_message[MANDOCERR_MAX] = {
 	"blank line in fill mode, using .sp",
 	"tab in filled text",
 	"new sentence, new line",
-	"invalid escape sequence",
+	"invalid escape sequence argument",
 	"undefined escape, printing literally",
 	"undefined string, using \"\"",
 
@@ -240,6 +240,7 @@ static	const char *const type_message[MANDOCERR_MAX] = {
 	"incomplete escape sequence",
 	"invalid special character",
 	"unknown special character",
+	"invalid escape argument delimiter",
 
 	"unsupported feature",
 	"input too large",
diff --git a/regress/char/space/invalid.out_lint b/regress/char/space/invalid.out_lint
index 4c146853..38383759 100644
--- a/regress/char/space/invalid.out_lint
+++ b/regress/char/space/invalid.out_lint
@@ -1,4 +1,4 @@
-mandoc: invalid.in:7:15: WARNING: invalid escape sequence: \[ 
+mandoc: invalid.in:7:15: WARNING: invalid escape sequence argument: \[ 
 mandoc: invalid.in:8:14: ERROR: invalid special character: \[%]
 mandoc: invalid.in:9:16: ERROR: invalid special character: \[&]
 mandoc: invalid.in:10:12: ERROR: invalid special character: \[:]
diff --git a/regress/roff/esc/O1.out_lint b/regress/roff/esc/O1.out_lint
index a5b29379..032d1f13 100644
--- a/regress/roff/esc/O1.out_lint
+++ b/regress/roff/esc/O1.out_lint
@@ -1,5 +1,5 @@
-mandoc: O1.in:11:6: WARNING: invalid escape sequence: \O5
-mandoc: O1.in:12:7: WARNING: invalid escape sequence: \O(52
+mandoc: O1.in:11:6: WARNING: invalid escape sequence argument: \O5
+mandoc: O1.in:12:7: WARNING: invalid escape sequence argument: \O(52
 mandoc: O1.in:13:7: UNSUPP: unsupported escape sequence: \O[5dummy]
-mandoc: O1.in:14:6: WARNING: invalid escape sequence: \O6
+mandoc: O1.in:14:6: WARNING: invalid escape sequence argument: \O6
 mandoc: O1.in:15:6: UNSUPP: unsupported escape sequence: \O0
diff --git a/regress/roff/esc/h.out_lint b/regress/roff/esc/h.out_lint
index b32ea2d2..99d6a1d4 100644
--- a/regress/roff/esc/h.out_lint
+++ b/regress/roff/esc/h.out_lint
@@ -1 +1 @@
-mandoc: h.in:23:21: WARNING: invalid escape sequence: \h-
+mandoc: h.in:23:21: ERROR: invalid escape argument delimiter: \h-
diff --git a/regress/roff/esc/l.in b/regress/roff/esc/l.in
index d7a42e74..47b02d8c 100644
--- a/regress/roff/esc/l.in
+++ b/regress/roff/esc/l.in
@@ -1,5 +1,5 @@
-.\" $OpenBSD: l.in,v 1.2 2017/07/04 14:53:27 schwarze Exp $
-.Dd $Mdocdate: July 4 2017 $
+.\" $OpenBSD: l.in,v 1.3 2022/06/07 09:51:03 schwarze Exp $
+.Dd $Mdocdate: June 7 2022 $
 .Dt ESC-L 1
 .Os
 .Sh NAME
@@ -20,4 +20,4 @@ default unit and escape char: >\l'7n\(at'<
 .br
 rounding: >\l'0.26ix'<
 .br
-invalid delimiter: >\h-<
+invalid delimiter: >\l-<
diff --git a/regress/roff/esc/l.out_ascii b/regress/roff/esc/l.out_ascii
index fa052d22..9e34d79b 100644
--- a/regress/roff/esc/l.out_ascii
+++ b/regress/roff/esc/l.out_ascii
@@ -13,4 +13,4 @@ DDEESSCCRRIIPPTTIIOONN
      rounding: >xxx<
      invalid delimiter: ><
 
-OpenBSD                          July 4, 2017                          OpenBSD
+OpenBSD                          June 7, 2022                          OpenBSD
diff --git a/regress/roff/esc/l.out_lint b/regress/roff/esc/l.out_lint
index 00a8eaf2..87df1bdd 100644
--- a/regress/roff/esc/l.out_lint
+++ b/regress/roff/esc/l.out_lint
@@ -1 +1 @@
-mandoc: l.in:23:21: WARNING: invalid escape sequence: \h-
+mandoc: l.in:23:21: ERROR: invalid escape argument delimiter: \l-
diff --git a/roff_escape.c b/roff_escape.c
index 3fdcf8d2..333e0e3f 100644
--- a/roff_escape.c
+++ b/roff_escape.c
@@ -1,4 +1,4 @@
-/* $Id: roff_escape.c,v 1.12 2022/06/06 19:23:13 schwarze Exp $ */
+/* $Id: roff_escape.c,v 1.13 2022/06/07 09:54:40 schwarze Exp $ */
 /*
  * Copyright (c) 2011, 2012, 2013, 2014, 2015, 2017, 2018, 2020, 2022
  *               Ingo Schwarze <schwarze@openbsd.org>
@@ -272,6 +272,7 @@ roff_escape(const char *buf, const int ln, const int aesc,
 	if (term == '\b') {
 		if (strchr("BDHLRSvxNhl", buf[inam]) != NULL &&
 		    strchr(" %&()*+-./0123456789:<=>", buf[iarg]) != NULL) {
+			err = MANDOCERR_ESC_DELIM;
 			if (rval != ESCAPE_EXPAND)
 				rval = ESCAPE_ERROR;
 			if (buf[inam] != 'D') {
@@ -291,6 +292,7 @@ roff_escape(const char *buf, const int ln, const int aesc,
 		case '[':
 			if (buf[++iarg] == ' ') {
 				iendarg = iend = iarg + 1;
+				err = MANDOCERR_ESC_ARG;
 				rval = ESCAPE_ERROR;
 				goto out;
 			}
@@ -368,13 +370,23 @@ roff_escape(const char *buf, const int ln, const int aesc,
 		case '2':
 		case '3':
 		case '4':
-			rval = argl == 1 ? ESCAPE_IGNORE : ESCAPE_ERROR;
+			if (argl == 1)
+				rval = ESCAPE_IGNORE;
+			else {
+				err = MANDOCERR_ESC_ARG;
+				rval = ESCAPE_ERROR;
+			}
 			break;
 		case '5':
-			rval = buf[iarg - 1] == '[' ? ESCAPE_UNSUPP :
-			    ESCAPE_ERROR;
+			if (buf[iarg - 1] == '[')
+				rval = ESCAPE_UNSUPP;
+			else {
+				err = MANDOCERR_ESC_ARG;
+				rval = ESCAPE_ERROR;
+			}
 			break;
 		default:
+			err = MANDOCERR_ESC_ARG;
 			rval = ESCAPE_ERROR;
 			break;
 		}
@@ -386,6 +398,8 @@ roff_escape(const char *buf, const int ln, const int aesc,
 	switch (rval) {
 	case ESCAPE_FONT:
 		rval = mandoc_font(buf + iarg, argl);
+		if (rval == ESCAPE_ERROR)
+			err = MANDOCERR_ESC_ARG;
 		break;
 
 	case ESCAPE_SPECIAL:
@@ -487,10 +501,6 @@ out:
 
 	*resc = iesc;
 	switch (rval) {
-	case ESCAPE_ERROR:
-		if (err == MANDOCERR_OK)
-			err = MANDOCERR_ESC_BAD;
-		break;
 	case ESCAPE_UNSUPP:
 		err = MANDOCERR_ESC_UNSUPP;
 		break;