In -T locale (the default), -T ascii, and -T utf8 mode, provide a new

output option -O tag[=term] to move right to the definition of "term" when
opening the manual page in a pager, effectively porting the -T html
fragment name feature - https://man.openbsd.org/ksh#ulimit - to the
terminal.  Try:

$ man -O tag uvm_sysctl
$ man -O tag=ulimit ksh
$ man -O tag 3 compress

Feature development triggered by a question from kn@.  Klemens also
tested, provided feedback that resulted in improvements, and provided
an OK.

7 files changed, 60 insertions, 12 deletions

diff --git a/main.c b/main.c
index 8db0b585..ad85efd6 100644
--- a/main.c
+++ b/main.c
@@ -518,8 +518,13 @@ main(int argc, char *argv[])
 		fd = mparse_open(curp.mp, resp != NULL ? resp->file : *argv);
 		if (fd != -1) {
 			if (use_pager) {
-				tag_files = tag_init();
 				use_pager = 0;
+				tag_files = tag_init();
+				if (conf.output.tag != NULL &&
+				    tag_files->tagname == NULL)
+					tag_files->tagname =
+					    *conf.output.tag != '\0' ?
+					    conf.output.tag : *argv;
 			}
 
 			if (resp == NULL)
@@ -1180,7 +1185,7 @@ spawn_pager(struct tag_files *tag_files)
 	const char	*pager;
 	char		*cp;
 	size_t		 cmdlen;
-	int		 argc;
+	int		 argc, use_ofn;
 	pid_t		 pager_pid;
 
 	pager = getenv("MANPAGER");
@@ -1196,7 +1201,7 @@ spawn_pager(struct tag_files *tag_files)
 	 */
 
 	argc = 0;
-	while (argc + 4 < MAX_PAGER_ARGS) {
+	while (argc + 5 < MAX_PAGER_ARGS) {
 		argv[argc++] = cp;
 		cp = strchr(cp, ' ');
 		if (cp == NULL)
@@ -1210,14 +1215,21 @@ spawn_pager(struct tag_files *tag_files)
 
 	/* For less(1), use the tag file. */
 
+	use_ofn = 1;
 	if ((cmdlen = strlen(argv[0])) >= 4) {
 		cp = argv[0] + cmdlen - 4;
 		if (strcmp(cp, "less") == 0) {
 			argv[argc++] = mandoc_strdup("-T");
 			argv[argc++] = tag_files->tfn;
+			if (tag_files->tagname != NULL) {
+				argv[argc++] = mandoc_strdup("-t");
+				argv[argc++] = tag_files->tagname;
+				use_ofn = 0;
+			}
 		}
 	}
-	argv[argc++] = tag_files->ofn;
+	if (use_ofn)
+		argv[argc++] = tag_files->ofn;
 	argv[argc] = NULL;
 
 	switch (pager_pid = fork()) {
diff --git a/man.1 b/man.1
index c9bff9ab..8c7cec71 100644
--- a/man.1
+++ b/man.1
@@ -3,7 +3,7 @@
 .\" Copyright (c) 1989, 1990, 1993
 .\"	The Regents of the University of California.  All rights reserved.
 .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
-.\" Copyright (c) 2010, 2011, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2010, 2011, 2014-2018 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -266,6 +266,13 @@ and
 can be used to move to the next and to the previous place providing
 information about the term last searched for with
 .Ic :t .
+The
+.Fl O Cm tag Ns Op = Ns Ar term
+option documented in the
+.Xr mandoc 1
+manual opens a manual page at the definition of a specific
+.Ar term
+rather than at the beginning.
 .It Ev MANPATH
 The standard search path used by
 .Nm
diff --git a/manconf.h b/manconf.h
index 20973366..9d8d088a 100644
--- a/manconf.h
+++ b/manconf.h
@@ -1,6 +1,6 @@
 /*	$Id$ */
 /*
- * Copyright (c) 2011, 2015, 2017 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2011, 2015, 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
  * Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -30,6 +30,7 @@ struct	manoutput {
 	char	 *man;
 	char	 *paper;
 	char	 *style;
+	char	 *tag;
 	size_t	  indent;
 	size_t	  width;
 	int	  fragment;
diff --git a/mandoc.1 b/mandoc.1
index 466cbeb2..91b3003f 100644
--- a/mandoc.1
+++ b/mandoc.1
@@ -290,6 +290,18 @@ One useful application is for checking that
 output formats in the same way as the
 .Xr mdoc 7
 source it was generated from.
+.It Cm tag Ns Op = Ns Ar term
+If the formatted manual page is opened in a pager,
+go to the definition of the
+.Ar term
+rather than showing the manual page from the beginning.
+If no
+.Ar term
+is specified, reuse the first command line argument that is not a
+.Ar section
+number.
+This is useful when it is the name of a manual page,
+in particular the name of a library function.
 .It Cm width Ns = Ns Ar width
 The output width is set to
 .Ar width
diff --git a/manpath.c b/manpath.c
index 24f57598..6d67151b 100644
--- a/manpath.c
+++ b/manpath.c
@@ -232,8 +232,8 @@ int
 manconf_output(struct manoutput *conf, const char *cp, int fromfile)
 {
 	const char *const toks[] = {
-	    "includes", "man", "paper", "style",
-	    "indent", "width", "fragment", "mdoc", "noval", "toc"
+	    "includes", "man", "paper", "style", "indent", "width",
+	    "tag", "fragment", "mdoc", "noval", "toc"
 	};
 
 	const char	*errstr;
@@ -257,7 +257,7 @@ manconf_output(struct manoutput *conf, const char *cp, int fromfile)
 		warnx("-O %s=?: Missing argument value", toks[tok]);
 		return -1;
 	}
-	if ((tok == 6 || tok == 7) && *cp != '\0') {
+	if (tok > 6 && *cp != '\0') {
 		warnx("-O %s: Does not take a value: %s", toks[tok], cp);
 		return -1;
 	}
@@ -312,15 +312,22 @@ manconf_output(struct manoutput *conf, const char *cp, int fromfile)
 		warnx("-O width=%s is %s", cp, errstr);
 		return -1;
 	case 6:
-		conf->fragment = 1;
+		if (conf->tag != NULL) {
+			oldval = mandoc_strdup(conf->tag);
+			break;
+		}
+		conf->tag = mandoc_strdup(cp);
 		return 0;
 	case 7:
-		conf->mdoc = 1;
+		conf->fragment = 1;
 		return 0;
 	case 8:
-		conf->noval = 1;
+		conf->mdoc = 1;
 		return 0;
 	case 9:
+		conf->noval = 1;
+		return 0;
+	case 10:
 		conf->toc = 1;
 		return 0;
 	default:
diff --git a/tag.c b/tag.c
index 5d0119c5..bef94939 100644
--- a/tag.c
+++ b/tag.c
@@ -18,6 +18,9 @@
 
 #include <sys/types.h>
 
+#if HAVE_ERR
+#include <err.h>
+#endif
 #include <limits.h>
 #include <signal.h>
 #include <stddef.h>
@@ -216,6 +219,11 @@ tag_write(void)
 
 	if (tag_files.tfd <= 0)
 		return;
+	if (tag_files.tagname != NULL && ohash_find(&tag_data,
+            ohash_qlookup(&tag_data, tag_files.tagname)) == NULL) {
+		warnx("%s: no such tag", tag_files.tagname);
+		tag_files.tagname = NULL;
+	}
 	stream = fdopen(tag_files.tfd, "w");
 	entry = ohash_first(&tag_data, &slot);
 	while (entry != NULL) {
diff --git a/tag.h b/tag.h
index 216b801d..cbfe375f 100644
--- a/tag.h
+++ b/tag.h
@@ -18,6 +18,7 @@
 struct	tag_files {
 	char	 ofn[20];
 	char	 tfn[20];
+	char	*tagname;
 	int	 ofd;
 	int	 tfd;
 	pid_t	 tcpgid;