Implement the \N'number' (numbered character) roff escape sequence.

Don't use it in new manuals, it is inherently non-portable, but we
need it for backward-compatibility with existing manuals, for example
in Xenocara driver pages.
ok kristaps@ matthieu@ jmc@

11 files changed, 154 insertions, 11 deletions

diff --git a/regress/usr.bin/mandoc/char/Makefile b/regress/usr.bin/mandoc/char/Makefile
index bffdc8d2a1b..20ec64a8756 100644
--- a/regress/usr.bin/mandoc/char/Makefile
+++ b/regress/usr.bin/mandoc/char/Makefile
@@ -1,6 +1,6 @@
-# $OpenBSD: Makefile,v 1.1 2009/12/23 23:40:58 schwarze Exp $
+# $OpenBSD: Makefile,v 1.2 2011/01/30 16:05:29 schwarze Exp $
 
-SUBDIR+= space
+SUBDIR+= space N
 
 groff groff-clean: _SUBDIRUSE
 
diff --git a/regress/usr.bin/mandoc/char/N/Makefile b/regress/usr.bin/mandoc/char/N/Makefile
new file mode 100644
index 00000000000..81ff3c399bd
--- /dev/null
+++ b/regress/usr.bin/mandoc/char/N/Makefile
@@ -0,0 +1,6 @@
+# $OpenBSD: Makefile,v 1.1 2011/01/30 16:05:29 schwarze Exp $
+
+REGRESS_TARGETS=basic
+GROFF_TARGETS=basic
+
+.include <bsd.regress.mk>
diff --git a/regress/usr.bin/mandoc/char/N/basic.in b/regress/usr.bin/mandoc/char/N/basic.in
new file mode 100644
index 00000000000..1d7aa4b11fd
--- /dev/null
+++ b/regress/usr.bin/mandoc/char/N/basic.in
@@ -0,0 +1,23 @@
+.TH N-BASIC 1 "January 29, 2011"
+.SH NAME
+N-basic \- basic handling of character number escapes
+.SH DESCRIPTION
+basic usage: x\N'65'x
+.br
+too large: x\N'259'x
+.br
+much too large: x\N'2259'x
+.br
+null: x\N'0'x
+.br
+non-numerical content: x\N'XX'x
+.br
+mixed content: x\N'65XX'x
+.br
+empty: x\N''x
+.br
+no quoting: x\N65x
+.br
+non-matching quoting characters: x\NX65Yx
+.br
+end of test document
diff --git a/regress/usr.bin/mandoc/char/N/basic.out_ascii b/regress/usr.bin/mandoc/char/N/basic.out_ascii
new file mode 100644
index 00000000000..c4a07a8abe1
--- /dev/null
+++ b/regress/usr.bin/mandoc/char/N/basic.out_ascii
diff --git a/share/man/man7/mandoc_char.7 b/share/man/man7/mandoc_char.7
index 3199c14e5b8..b3e8b5c4e6c 100644
--- a/share/man/man7/mandoc_char.7
+++ b/share/man/man7/mandoc_char.7
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mandoc_char.7,v 1.6 2010/10/28 18:13:52 jmc Exp $
+.\"	$OpenBSD: mandoc_char.7,v 1.7 2011/01/30 16:05:29 schwarze Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,7 +14,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: October 28 2010 $
+.Dd $Mdocdate: January 30 2011 $
 .Dt MANDOC_CHAR 7
 .Os
 .Sh NAME
@@ -513,6 +513,21 @@ implementations:
 .It \e*(aa   Ta \*(aa       Ta acute
 .It \e*(ga   Ta \*(ga       Ta grave
 .El
+.Sh NUMBERED CHARACTERS
+For backward compatibility with existing manuals,
+.Xr mandoc 1
+also supports the
+.Pp
+.Dl \eN\(aq Ns Ar number Ns \(aq
+.Pp
+escape sequence, inserting the character
+.Ar number
+from the current character set into the output.
+Of course, this is inherently non-portable and is already marked
+as deprecated in the Heirloom roff manual.
+For example, do not use \eN'34', use \e(dq, or even the plain
+.Sq \(dq
+character where possible.
 .Sh COMPATIBILITY
 This section documents compatibility of
 .Nm
diff --git a/usr.bin/mandoc/chars.c b/usr.bin/mandoc/chars.c
index e3b192e6d70..0c5a33d8b1b 100644
--- a/usr.bin/mandoc/chars.c
+++ b/usr.bin/mandoc/chars.c
@@ -1,6 +1,7 @@
-/*	$Id: chars.c,v 1.15 2011/01/04 22:28:17 schwarze Exp $ */
+/*	$Id: chars.c,v 1.16 2011/01/30 16:05:29 schwarze Exp $ */
 /*
  * Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
+ * Copyright (c) 2011 Ingo Schwarze <schwarze@openbsd.org>
  *
  * Permission to use, copy, modify, and distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
@@ -148,6 +149,27 @@ chars_res2cp(void *arg, const char *p, size_t sz)
 }
 
 
+/*
+ * Numbered character to literal character,
+ * represented as a null-terminated string for additional safety.
+ */
+const char *
+chars_num2char(const char *p, size_t sz)
+{
+	int		  i;
+	static char	  c[2];
+
+	if (sz > 3)
+		return(NULL);
+	i = atoi(p);
+	if (i < 0 || i > 255)
+		return(NULL);
+	c[0] = (char)i;
+	c[1] = '\0';
+	return(c);
+}
+
+
 /* 
  * Special character to string array.
  */
diff --git a/usr.bin/mandoc/chars.h b/usr.bin/mandoc/chars.h
index b050994b65c..43ec349332e 100644
--- a/usr.bin/mandoc/chars.h
+++ b/usr.bin/mandoc/chars.h
@@ -1,6 +1,7 @@
-/*	$Id: chars.h,v 1.5 2010/07/25 18:05:54 schwarze Exp $ */
+/*	$Id: chars.h,v 1.6 2011/01/30 16:05:29 schwarze Exp $ */
 /*
  * Copyright (c) 2008, 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
+ * Copyright (c) 2011 Ingo Schwarze <schwarze@openbsd.org>
  *
  * Permission to use, copy, modify, and distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
@@ -25,6 +26,7 @@ enum	chars {
 };
 
 void		 *chars_init(enum chars);
+const char	 *chars_num2char(const char *, size_t);
 const char	 *chars_spec2str(void *, const char *, size_t, size_t *);
 int		  chars_spec2cp(void *, const char *, size_t);
 const char	 *chars_res2str(void *, const char *, size_t, size_t *);
diff --git a/usr.bin/mandoc/html.c b/usr.bin/mandoc/html.c
index ae78c352b02..b0261514a8f 100644
--- a/usr.bin/mandoc/html.c
+++ b/usr.bin/mandoc/html.c
@@ -1,6 +1,7 @@
-/*	$Id: html.c,v 1.22 2011/01/16 19:41:16 schwarze Exp $ */
+/*	$Id: html.c,v 1.23 2011/01/30 16:05:29 schwarze Exp $ */
 /*
  * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
+ * Copyright (c) 2011 Ingo Schwarze <schwarze@openbsd.org>
  *
  * Permission to use, copy, modify, and distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
@@ -89,6 +90,7 @@ static	const char	*const htmlattrs[ATTR_MAX] = {
 	"colspan", /* ATTR_COLSPAN */
 };
 
+static	void		  print_num(struct html *, const char *, size_t);
 static	void		  print_spec(struct html *, enum roffdeco,
 				const char *, size_t);
 static	void		  print_res(struct html *, const char *, size_t);
@@ -210,6 +212,17 @@ print_gen_head(struct html *h)
 
 
 static void
+print_num(struct html *h, const char *p, size_t len)
+{
+	const char	*rhs;
+
+	rhs = chars_num2char(p, len);
+	if (rhs)
+		putchar((int)*rhs);
+}
+
+
+static void
 print_spec(struct html *h, enum roffdeco d, const char *p, size_t len)
 {
 	int		 cp;
@@ -329,6 +342,9 @@ print_encode(struct html *h, const char *p, int norecurse)
 		len = a2roffdeco(&deco, &seq, &sz);
 
 		switch (deco) {
+		case (DECO_NUMBERED):
+			print_num(h, seq, sz);
+			break;
 		case (DECO_RESERVED):
 			print_res(h, seq, sz);
 			break;
diff --git a/usr.bin/mandoc/out.c b/usr.bin/mandoc/out.c
index 24f215792ff..7f2344adf1a 100644
--- a/usr.bin/mandoc/out.c
+++ b/usr.bin/mandoc/out.c
@@ -1,6 +1,7 @@
-/*	$Id: out.c,v 1.11 2011/01/25 12:07:26 schwarze Exp $ */
+/*	$Id: out.c,v 1.12 2011/01/30 16:05:29 schwarze Exp $ */
 /*
  * Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
+ * Copyright (c) 2011 Ingo Schwarze <schwarze@openbsd.org>
  *
  * Permission to use, copy, modify, and distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
@@ -247,6 +248,49 @@ a2roffdeco(enum roffdeco *d, const char **word, size_t *sz)
 			break;
 		}
 		break;
+
+	case ('N'):
+
+		/*
+		 * Sequence of characters:  backslash,  'N' (i = 0),
+		 * starting delimiter (i = 1), character number (i = 2).
+		 */
+
+		*word = wp + 2;
+		*sz = 0;
+
+		/*
+		 * Cannot use a digit as a starting delimiter;
+		 * but skip the digit anyway.
+		 */
+
+		if (isdigit((int)wp[1]))
+			return(2);
+
+		/*
+		 * Any non-digit terminates the character number.
+		 * That is, the terminating delimiter need not
+		 * match the starting delimiter.
+		 */
+
+		for (i = 2; isdigit((int)wp[i]); i++)
+			(*sz)++;
+
+		/*
+		 * This is only a numbered character
+		 * if the character number has at least one digit.
+		 */
+
+		if (*sz)
+			*d = DECO_NUMBERED;
+
+		/*
+		 * Skip the terminating delimiter, even if it does not
+		 * match, and even if there is no character number.
+		 */
+
+		return(++i);
+
 	case ('h'):
 		/* FALLTHROUGH */
 	case ('v'):
diff --git a/usr.bin/mandoc/out.h b/usr.bin/mandoc/out.h
index bdf04e69fe9..de7021c7f37 100644
--- a/usr.bin/mandoc/out.h
+++ b/usr.bin/mandoc/out.h
@@ -1,4 +1,4 @@
-/*	$Id: out.h,v 1.7 2011/01/09 14:30:48 schwarze Exp $ */
+/*	$Id: out.h,v 1.8 2011/01/30 16:05:29 schwarze Exp $ */
 /*
  * Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  *
@@ -52,6 +52,7 @@ enum	roffscale {
 
 enum	roffdeco {
 	DECO_NONE,
+	DECO_NUMBERED, /* numbered character */
 	DECO_SPECIAL, /* special character */
 	DECO_SSPECIAL, /* single-char special */
 	DECO_RESERVED, /* reserved word */
diff --git a/usr.bin/mandoc/term.c b/usr.bin/mandoc/term.c
index e2d136a1cca..3544fd4d603 100644
--- a/usr.bin/mandoc/term.c
+++ b/usr.bin/mandoc/term.c
@@ -1,7 +1,7 @@
-/*	$Id: term.c,v 1.55 2011/01/04 22:28:17 schwarze Exp $ */
+/*	$Id: term.c,v 1.56 2011/01/30 16:05:29 schwarze Exp $ */
 /*
  * Copyright (c) 2008, 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
- * Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
  *
  * Permission to use, copy, modify, and distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
@@ -349,6 +349,17 @@ term_vspace(struct termp *p)
 
 
 static void
+numbered(struct termp *p, const char *word, size_t len)
+{
+	const char	*rhs;
+
+	rhs = chars_num2char(word, len);
+	if (rhs) 
+		encode(p, rhs, 1);
+}
+
+
+static void
 spec(struct termp *p, enum roffdeco d, const char *word, size_t len)
 {
 	const char	*rhs;
@@ -507,6 +518,9 @@ term_word(struct termp *p, const char *word)
 		word += a2roffdeco(&deco, &seq, &ssz);
 
 		switch (deco) {
+		case (DECO_NUMBERED):
+			numbered(p, seq, ssz);
+			break;
 		case (DECO_RESERVED):
 			res(p, seq, ssz);
 			break;