Introduce a new mdoc(7) macro .Tg ("tag") to explicitly mark a place

as defining a term.  Please only use it when automatic tagging does
not work.  Manual page authors will not be required to add the new
macro; using it remains optional.  HTML output is still rudimentary
in this version and will be polished later.

Thanks to kn@ for reminding me that i have been considering since
BSDCan 2014 whether something like this might be useful.  Given
that possibilities of making automatic tagging better are running
out and there are still several situations where automatic tagging
cannot do the job, i think the time is now ripe.

Feedback and no objection from millert@; OK espie@ inoguchi@ kn@.

14 files changed, 93 insertions, 25 deletions

diff --git a/usr.bin/mandoc/html.c b/usr.bin/mandoc/html.c
index fd0093eb578..9c0e7a71cc6 100644
--- a/usr.bin/mandoc/html.c
+++ b/usr.bin/mandoc/html.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: html.c,v 1.132 2019/09/05 13:34:55 schwarze Exp $ */
+/*	$OpenBSD: html.c,v 1.133 2020/01/19 17:59:01 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2011-2015, 2017-2019 Ingo Schwarze <schwarze@openbsd.org>
@@ -86,6 +86,7 @@ static	const struct htmldata htmltags[TAG_MAX] = {
 	{"span",	HTML_INPHRASE | HTML_TOPHRASE},
 	{"var",		HTML_INPHRASE | HTML_TOPHRASE},
 	{"br",		HTML_INPHRASE | HTML_NOSTACK | HTML_NLALL},
+	{"mark",	HTML_INPHRASE | HTML_NOSTACK },
 	{"math",	HTML_INPHRASE | HTML_NLALL | HTML_INDENT},
 	{"mrow",	0},
 	{"mi",		0},
diff --git a/usr.bin/mandoc/html.h b/usr.bin/mandoc/html.h
index b928bb3a695..f0c9fe6d7a4 100644
--- a/usr.bin/mandoc/html.h
+++ b/usr.bin/mandoc/html.h
@@ -1,4 +1,4 @@
-/*	$OpenBSD: html.h,v 1.67 2019/09/01 15:12:03 schwarze Exp $ */
+/*	$OpenBSD: html.h,v 1.68 2020/01/19 17:59:01 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2017, 2018, 2019 Ingo Schwarze <schwarze@openbsd.org>
@@ -48,6 +48,7 @@ enum	htmltag {
 	TAG_SPAN,
 	TAG_VAR,
 	TAG_BR,
+	TAG_MARK,
 	TAG_MATH,
 	TAG_MROW,
 	TAG_MI,
diff --git a/usr.bin/mandoc/mandoc.h b/usr.bin/mandoc/mandoc.h
index 12fe018ecd9..4aac1c1464e 100644
--- a/usr.bin/mandoc/mandoc.h
+++ b/usr.bin/mandoc/mandoc.h
@@ -1,4 +1,4 @@
-/*	$OpenBSD: mandoc.h,v 1.207 2020/01/19 16:16:33 schwarze Exp $ */
+/*	$OpenBSD: mandoc.h,v 1.208 2020/01/19 17:59:01 schwarze Exp $ */
 /*
  * Copyright (c) 2010, 2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2012-2020 Ingo Schwarze <schwarze@openbsd.org>
@@ -223,6 +223,7 @@ enum	mandocerr {
 	MANDOCERR_SHIFT, /* excessive shift: ..., but max is ... */
 	MANDOCERR_SO_PATH, /* NOT IMPLEMENTED: .so with absolute path or ".." */
 	MANDOCERR_SO_FAIL, /* .so request failed */
+	MANDOCERR_TG_SPC, /* skipping tag containing whitespace: tag */
 	MANDOCERR_ARG_SKIP, /* skipping all arguments: macro args */
 	MANDOCERR_ARG_EXCESS, /* skipping excess arguments: macro ... args */
 	MANDOCERR_DIVZERO, /* divide by zero */
diff --git a/usr.bin/mandoc/mandoc_msg.c b/usr.bin/mandoc/mandoc_msg.c
index 769ed617dfb..3bb7a65ad0a 100644
--- a/usr.bin/mandoc/mandoc_msg.c
+++ b/usr.bin/mandoc/mandoc_msg.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: mandoc_msg.c,v 1.7 2020/01/19 16:16:33 schwarze Exp $ */
+/*	$OpenBSD: mandoc_msg.c,v 1.8 2020/01/19 17:59:01 schwarze Exp $ */
 /*
  * Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2014-2020 Ingo Schwarze <schwarze@openbsd.org>
@@ -221,6 +221,7 @@ static	const char *const type_message[MANDOCERR_MAX] = {
 	"excessive shift",
 	"NOT IMPLEMENTED: .so with absolute path or \"..\"",
 	".so request failed",
+	"skipping tag containing whitespace",
 	"skipping all arguments",
 	"skipping excess arguments",
 	"divide by zero",
diff --git a/usr.bin/mandoc/mdoc_html.c b/usr.bin/mandoc/mdoc_html.c
index 4c1b51e86b7..8a6275f4f5e 100644
--- a/usr.bin/mandoc/mdoc_html.c
+++ b/usr.bin/mandoc/mdoc_html.c
@@ -1,7 +1,7 @@
-/*	$OpenBSD: mdoc_html.c,v 1.207 2019/12/10 10:49:04 bentley Exp $ */
+/*	$OpenBSD: mdoc_html.c,v 1.208 2020/01/19 17:59:01 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
- * Copyright (c) 2014-2019 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2014-2020 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
@@ -113,6 +113,7 @@ static	int		  mdoc_ss_pre(MDOC_ARGS);
 static	int		  mdoc_st_pre(MDOC_ARGS);
 static	int		  mdoc_sx_pre(MDOC_ARGS);
 static	int		  mdoc_sy_pre(MDOC_ARGS);
+static	int		  mdoc_tg_pre(MDOC_ARGS);
 static	int		  mdoc_va_pre(MDOC_ARGS);
 static	int		  mdoc_vt_pre(MDOC_ARGS);
 static	int		  mdoc_xr_pre(MDOC_ARGS);
@@ -239,6 +240,7 @@ static const struct mdoc_html_act mdoc_html_acts[MDOC_MAX - MDOC_Dd] = {
 	{mdoc__x_pre, mdoc__x_post}, /* %Q */
 	{mdoc__x_pre, mdoc__x_post}, /* %U */
 	{NULL, NULL}, /* Ta */
+	{mdoc_tg_pre, NULL}, /* Tg */
 };
 
 
@@ -720,6 +722,16 @@ mdoc_xr_pre(MDOC_ARGS)
 }
 
 static int
+mdoc_tg_pre(MDOC_ARGS)
+{
+	char	*id;
+
+	if ((id = html_make_id(n, 1)) != NULL)
+		print_otag(h, TAG_MARK, "i", id);
+	return 0;
+}
+
+static int
 mdoc_ns_pre(MDOC_ARGS)
 {
 
diff --git a/usr.bin/mandoc/mdoc_macro.c b/usr.bin/mandoc/mdoc_macro.c
index b86e469162e..a8aa3c964ca 100644
--- a/usr.bin/mandoc/mdoc_macro.c
+++ b/usr.bin/mandoc/mdoc_macro.c
@@ -1,7 +1,7 @@
-/*	$OpenBSD: mdoc_macro.c,v 1.190 2020/01/19 16:16:33 schwarze Exp $ */
+/*	$OpenBSD: mdoc_macro.c,v 1.191 2020/01/19 17:59:01 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv>
- * Copyright (c) 2010, 2012-2019 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2010, 2012-2020 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
@@ -198,6 +198,7 @@ static const struct mdoc_macro mdoc_macros[MDOC_MAX - MDOC_Dd] = {
 	{ in_line_eoln, MDOC_JOIN }, /* %Q */
 	{ in_line_eoln, 0 }, /* %U */
 	{ phrase_ta, MDOC_CALLABLE | MDOC_PARSED | MDOC_JOIN }, /* Ta */
+	{ in_line_eoln, 0 }, /* Tg */
 };
 
 
diff --git a/usr.bin/mandoc/mdoc_man.c b/usr.bin/mandoc/mdoc_man.c
index 712f8f8aadb..5be33dc9aa8 100644
--- a/usr.bin/mandoc/mdoc_man.c
+++ b/usr.bin/mandoc/mdoc_man.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: mdoc_man.c,v 1.130 2019/01/04 03:17:38 schwarze Exp $ */
+/*	$OpenBSD: mdoc_man.c,v 1.131 2020/01/19 17:59:01 schwarze Exp $ */
 /*
  * Copyright (c) 2011-2019 Ingo Schwarze <schwarze@openbsd.org>
  *
@@ -260,6 +260,7 @@ static const struct mdoc_man_act mdoc_man_acts[MDOC_MAX - MDOC_Dd] = {
 	{ NULL, NULL, post_percent, NULL, NULL }, /* %Q */
 	{ NULL, NULL, post_percent, NULL, NULL }, /* %U */
 	{ NULL, NULL, NULL, NULL, NULL }, /* Ta */
+	{ NULL, NULL, NULL, NULL, NULL }, /* Tg */
 };
 static const struct mdoc_man_act *mdoc_man_act(enum roff_tok);
 
diff --git a/usr.bin/mandoc/mdoc_markdown.c b/usr.bin/mandoc/mdoc_markdown.c
index b35fcb7cd09..e43ed44f275 100644
--- a/usr.bin/mandoc/mdoc_markdown.c
+++ b/usr.bin/mandoc/mdoc_markdown.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: mdoc_markdown.c,v 1.31 2019/07/01 22:43:03 schwarze Exp $ */
+/*	$OpenBSD: mdoc_markdown.c,v 1.32 2020/01/19 17:59:01 schwarze Exp $ */
 /*
  * Copyright (c) 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
  *
@@ -226,6 +226,7 @@ static	const struct md_act md_acts[MDOC_MAX - MDOC_Dd] = {
 	{ NULL, NULL, md_post_pc, NULL, NULL }, /* %Q */
 	{ NULL, md_pre_Lk, md_post_pc, NULL, NULL }, /* %U */
 	{ NULL, NULL, NULL, NULL, NULL }, /* Ta */
+	{ NULL, NULL, NULL, NULL, NULL }, /* Tg */
 };
 static const struct md_act *md_act(enum roff_tok);
 
diff --git a/usr.bin/mandoc/mdoc_state.c b/usr.bin/mandoc/mdoc_state.c
index 55a466bac83..954f7099094 100644
--- a/usr.bin/mandoc/mdoc_state.c
+++ b/usr.bin/mandoc/mdoc_state.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: mdoc_state.c,v 1.15 2019/01/01 07:41:22 schwarze Exp $ */
+/*	$OpenBSD: mdoc_state.c,v 1.16 2020/01/19 17:59:01 schwarze Exp $ */
 /*
  * Copyright (c) 2014, 2015, 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
  *
@@ -157,6 +157,7 @@ static	const state_handler state_handlers[MDOC_MAX - MDOC_Dd] = {
 	NULL,		/* %Q */
 	NULL,		/* %U */
 	NULL,		/* Ta */
+	NULL,		/* Tg */
 };
 
 
diff --git a/usr.bin/mandoc/mdoc_term.c b/usr.bin/mandoc/mdoc_term.c
index 2b7bfcb917a..7e1161918b9 100644
--- a/usr.bin/mandoc/mdoc_term.c
+++ b/usr.bin/mandoc/mdoc_term.c
@@ -1,7 +1,7 @@
-/*	$OpenBSD: mdoc_term.c,v 1.273 2019/06/27 12:19:39 schwarze Exp $ */
+/*	$OpenBSD: mdoc_term.c,v 1.274 2020/01/19 17:59:01 schwarze Exp $ */
 /*
  * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
- * Copyright (c) 2010, 2012-2019 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2010, 2012-2020 Ingo Schwarze <schwarze@openbsd.org>
  * Copyright (c) 2013 Franco Fichtner <franco@lastsummer.de>
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -117,6 +117,7 @@ static	int	  termp_pp_pre(DECL_ARGS);
 static	int	  termp_ss_pre(DECL_ARGS);
 static	int	  termp_sy_pre(DECL_ARGS);
 static	int	  termp_tag_pre(DECL_ARGS);
+static	int	  termp_tg_pre(DECL_ARGS);
 static	int	  termp_under_pre(DECL_ARGS);
 static	int	  termp_vt_pre(DECL_ARGS);
 static	int	  termp_xr_pre(DECL_ARGS);
@@ -243,6 +244,7 @@ static const struct mdoc_term_act mdoc_term_acts[MDOC_MAX - MDOC_Dd] = {
 	{ NULL, termp____post }, /* %Q */
 	{ NULL, termp____post }, /* %U */
 	{ NULL, NULL }, /* Ta */
+	{ termp_tg_pre, NULL }, /* Tg */
 };
 
 static	int	 fn_prio;
@@ -2080,6 +2082,13 @@ termp_tag_pre(DECL_ARGS)
 }
 
 static int
+termp_tg_pre(DECL_ARGS)
+{
+	tag_put(n->child->string, -2, p->line);
+	return 0;
+}
+
+static int
 termp_abort_pre(DECL_ARGS)
 {
 	abort();
diff --git a/usr.bin/mandoc/mdoc_validate.c b/usr.bin/mandoc/mdoc_validate.c
index 243326aa3be..b7ae573a127 100644
--- a/usr.bin/mandoc/mdoc_validate.c
+++ b/usr.bin/mandoc/mdoc_validate.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: mdoc_validate.c,v 1.291 2020/01/19 16:16:33 schwarze Exp $ */
+/*	$OpenBSD: mdoc_validate.c,v 1.292 2020/01/19 17:59:01 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010-2020 Ingo Schwarze <schwarze@openbsd.org>
@@ -111,6 +111,7 @@ static	void	 post_sm(POST_ARGS);
 static	void	 post_st(POST_ARGS);
 static	void	 post_std(POST_ARGS);
 static	void	 post_sx(POST_ARGS);
+static	void	 post_tg(POST_ARGS);
 static	void	 post_useless(POST_ARGS);
 static	void	 post_xr(POST_ARGS);
 static	void	 post_xx(POST_ARGS);
@@ -236,6 +237,7 @@ static	const v_post mdoc_valids[MDOC_MAX - MDOC_Dd] = {
 	NULL,		/* %Q */
 	NULL,		/* %U */
 	NULL,		/* Ta */
+	post_tg,	/* Tg */
 };
 
 #define	RSORD_MAX 14 /* Number of `Rs' blocks. */
@@ -1075,6 +1077,41 @@ post_st(POST_ARGS)
 }
 
 static void
+post_tg(POST_ARGS)
+{
+	struct roff_node	*n, *nch;
+	size_t			len;
+
+	n = mdoc->last;
+	nch = n->child;
+	if (nch == NULL && n->next != NULL &&
+	    n->next->child->type == ROFFT_TEXT) {
+		mdoc->next = ROFF_NEXT_CHILD;
+		roff_word_alloc(mdoc, n->line, n->pos, n->next->child->string);
+		nch = mdoc->last;
+		nch->flags |= NODE_NOSRC;
+		mdoc->last = n;
+	}
+	if (nch == NULL || *nch->string == '\0') {
+		mandoc_msg(MANDOCERR_MACRO_EMPTY, n->line, n->pos, "Tg");
+		roff_node_delete(mdoc, n);
+		return;
+	}
+	len = strcspn(nch->string, " \t");
+	if (nch->string[len] != '\0')
+		mandoc_msg(MANDOCERR_TG_SPC, nch->line, nch->pos + len + 1,
+		    "Tg %s", nch->string);
+	if (nch->next != NULL) {
+		mandoc_msg(MANDOCERR_ARG_EXCESS, nch->next->line,
+		    nch->next->pos, "Tg ... %s", nch->next->string);
+		while (nch->next != NULL)
+			roff_node_delete(mdoc, nch->next);
+	}
+	if (nch->string[len] != '\0')
+		roff_node_delete(mdoc, n);
+}
+
+static void
 post_obsolete(POST_ARGS)
 {
 	struct roff_node *n;
@@ -1739,7 +1776,7 @@ post_bl(POST_ARGS)
 	while (nchild != NULL) {
 		nnext = nchild->next;
 		if (nchild->tok == MDOC_It ||
-		    (nchild->tok == MDOC_Sm &&
+		    ((nchild->tok == MDOC_Sm || nchild->tok == MDOC_Tg) &&
 		     nnext != NULL && nnext->tok == MDOC_It)) {
 			nchild = nnext;
 			continue;
diff --git a/usr.bin/mandoc/roff.c b/usr.bin/mandoc/roff.c
index 625d155fbce..35eec08824c 100644
--- a/usr.bin/mandoc/roff.c
+++ b/usr.bin/mandoc/roff.c
@@ -1,7 +1,7 @@
-/*	$OpenBSD: roff.c,v 1.240 2019/12/26 19:51:47 schwarze Exp $ */
+/*	$OpenBSD: roff.c,v 1.241 2020/01/19 17:59:01 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2012, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
- * Copyright (c) 2010-2015, 2017-2019 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2010-2015, 2017-2020 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
@@ -353,7 +353,7 @@ const char *__roff_name[MAN_MAX + 1] = {
 	"Lk",		"Mt",		"Brq",		"Bro",
 	"Brc",		"%C",		"Es",		"En",
 	"Dx",		"%Q",		"%U",		"Ta",
-	NULL,
+	"Tg",		NULL,
 	"TH",		"SH",		"SS",		"TP",
 	"TQ",
 	"LP",		"PP",		"P",		"IP",
diff --git a/usr.bin/mandoc/roff.h b/usr.bin/mandoc/roff.h
index 037759af400..1479a12688f 100644
--- a/usr.bin/mandoc/roff.h
+++ b/usr.bin/mandoc/roff.h
@@ -1,7 +1,7 @@
-/*	$OpenBSD: roff.h,v 1.51 2019/03/04 13:01:52 schwarze Exp $	*/
+/*	$OpenBSD: roff.h,v 1.52 2020/01/19 17:59:01 schwarze Exp $	*/
 /*
  * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
- * Copyright (c) 2013-2015, 2017-2019 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2013-2015, 2017-2020 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
@@ -437,6 +437,7 @@ enum	roff_tok {
 	MDOC__Q,
 	MDOC__U,
 	MDOC_Ta,
+	MDOC_Tg,
 	MDOC_MAX,
 	MAN_TH,
 	MAN_SH,
diff --git a/usr.bin/mandoc/tag.c b/usr.bin/mandoc/tag.c
index 31caad35c2e..394a08b1d5a 100644
--- a/usr.bin/mandoc/tag.c
+++ b/usr.bin/mandoc/tag.c
@@ -1,6 +1,6 @@
-/*	$OpenBSD: tag.c,v 1.25 2019/07/27 13:40:42 schwarze Exp $ */
+/*	$OpenBSD: tag.c,v 1.26 2020/01/19 17:59:01 schwarze Exp $ */
 /*
- * Copyright (c) 2015, 2016, 2018, 2019 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2015,2016,2018,2019,2020 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
@@ -194,12 +194,13 @@ tag_put(const char *s, int prio, size_t line)
 
 		/* A better entry is already present, ignore the new one. */
 
-		if (entry->prio > 0 && entry->prio < prio)
+		if (entry->prio != -1 && entry->prio < prio)
 			return;
 
 		/* The existing entry is worse, clear it. */
 
-		if (entry->prio < 1 || entry->prio > prio)
+		if (entry->prio == -1 || entry->prio == 0 ||
+		    entry->prio > prio)
 			entry->nlines = 0;
 	}
 
@@ -239,7 +240,7 @@ tag_write(void)
 	empty = 1;
 	entry = ohash_first(&tag_data, &slot);
 	while (entry != NULL) {
-		if (stream != NULL && entry->prio >= 0) {
+		if (stream != NULL && entry->prio != -1) {
 			for (i = 0; i < entry->nlines; i++) {
 				fprintf(stream, "%s %s %zu\n",
 				    entry->s, tag_files.ofn, entry->lines[i]);