Add an option -T html -O toc to add a brief table of contents near

the top of HTML pages containing at least two non-standard sections.
Suggested by Adam Kalisz and discussed with kristaps@ during EuroBSDCon 2018.

7 files changed, 55 insertions, 13 deletions

diff --git a/usr.bin/mandoc/html.c b/usr.bin/mandoc/html.c
index 0268171bb44..6c92488d912 100644
--- a/usr.bin/mandoc/html.c
+++ b/usr.bin/mandoc/html.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: html.c,v 1.110 2018/10/02 12:32:55 schwarze Exp $ */
+/*	$OpenBSD: html.c,v 1.111 2018/10/02 14:56:36 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2011-2015, 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
@@ -134,6 +134,8 @@ html_alloc(const struct manoutput *outopts)
 	h->base_includes = outopts->includes;
 	if (outopts->fragment)
 		h->oflags |= HTML_FRAGMENT;
+	if (outopts->toc)
+		h->oflags |= HTML_TOC;
 
 	mandoc_ohash_init(&id_unique, 4, 0);
 
diff --git a/usr.bin/mandoc/html.h b/usr.bin/mandoc/html.h
index 700eca2bc18..daf646917d0 100644
--- a/usr.bin/mandoc/html.h
+++ b/usr.bin/mandoc/html.h
@@ -1,4 +1,4 @@
-/*	$OpenBSD: html.h,v 1.55 2018/10/02 12:32:55 schwarze Exp $ */
+/*	$OpenBSD: html.h,v 1.56 2018/10/02 14:56:36 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
@@ -93,6 +93,7 @@ struct	html {
 #define	HTML_SPLIT	 (1 << 8) /* break line before .An */
 #define	HTML_NONEWLINE	 (1 << 9) /* No line break in nofill mode. */
 #define	HTML_BUFFER	 (1 << 10) /* Collect a word to see if it fits. */
+#define	HTML_TOCDONE	 (1 << 11) /* The TOC was already written. */
 	size_t		  indent; /* current output indentation level */
 	int		  noindent; /* indent disabled by <pre> */
 	size_t		  col; /* current output byte position */
@@ -110,6 +111,7 @@ struct	html {
 	enum htmlfont	  metac; /* current font mode */
 	int		  oflags; /* output options */
 #define	HTML_FRAGMENT	 (1 << 0) /* don't emit HTML/HEAD/BODY */
+#define	HTML_TOC	 (1 << 1) /* emit a table of contents */
 };
 
 
diff --git a/usr.bin/mandoc/man.conf.5 b/usr.bin/mandoc/man.conf.5
index 60448e59ac1..ed4807f8fc7 100644
--- a/usr.bin/mandoc/man.conf.5
+++ b/usr.bin/mandoc/man.conf.5
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: man.conf.5,v 1.5 2017/08/22 18:17:47 schwarze Exp $
+.\"	$OpenBSD: man.conf.5,v 1.6 2018/10/02 14:56:36 schwarze Exp $
 .\"
-.\" Copyright (c) 2015 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2015, 2017 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
@@ -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: August 22 2017 $
+.Dd $Mdocdate: October 2 2018 $
 .Dt MAN.CONF 5
 .Os
 .Sh NAME
@@ -98,6 +98,7 @@ manual.
 .It Ic man      Ta string   Ta Cm html Ta path for \&Xr links
 .It Ic paper    Ta string   Ta Cm ps , pdf Ta paper size
 .It Ic style    Ta string   Ta Cm html Ta CSS file
+.It Ic toc      Ta none     Ta Cm html Ta print table of contents
 .It Ic width    Ta integer  Ta Cm ascii , utf8 Ta right margin
 .El
 .It Ic _whatdb Ar path Ns Cm /whatis.db
diff --git a/usr.bin/mandoc/manconf.h b/usr.bin/mandoc/manconf.h
index 2b3a2dde671..5c5026fb4af 100644
--- a/usr.bin/mandoc/manconf.h
+++ b/usr.bin/mandoc/manconf.h
@@ -1,4 +1,4 @@
-/*	$OpenBSD: manconf.h,v 1.5 2017/07/01 09:47:23 schwarze Exp $ */
+/*	$OpenBSD: manconf.h,v 1.6 2018/10/02 14:56:36 schwarze Exp $ */
 /*
  * Copyright (c) 2011, 2015, 2017 Ingo Schwarze <schwarze@openbsd.org>
  * Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
@@ -34,8 +34,9 @@ struct	manoutput {
 	size_t	  width;
 	int	  fragment;
 	int	  mdoc;
-	int	  synopsisonly;
 	int	  noval;
+	int	  synopsisonly;
+	int	  toc;
 };
 
 struct	manconf {
diff --git a/usr.bin/mandoc/mandoc.1 b/usr.bin/mandoc/mandoc.1
index 02d2a00dd6a..24d3f33fc29 100644
--- a/usr.bin/mandoc/mandoc.1
+++ b/usr.bin/mandoc/mandoc.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mandoc.1,v 1.153 2018/10/02 12:32:55 schwarze Exp $
+.\"	$OpenBSD: mandoc.1,v 1.154 2018/10/02 14:56:36 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2012, 2014-2018 Ingo Schwarze <schwarze@openbsd.org>
@@ -371,6 +371,9 @@ The file
 is used for an external style-sheet.
 This must be a valid absolute or
 relative URI.
+.It Cm toc
+If an input file contains at least two non-standard sections,
+print a table of contents near the beginning of the output.
 .El
 .Ss Locale Output
 By default,
diff --git a/usr.bin/mandoc/manpath.c b/usr.bin/mandoc/manpath.c
index 2c6e39b49f4..56370e73bef 100644
--- a/usr.bin/mandoc/manpath.c
+++ b/usr.bin/mandoc/manpath.c
@@ -1,6 +1,6 @@
-/*	$OpenBSD: manpath.c,v 1.22 2017/07/01 09:47:23 schwarze Exp $ */
+/*	$OpenBSD: manpath.c,v 1.23 2018/10/02 14:56:36 schwarze Exp $ */
 /*
- * Copyright (c) 2011, 2014, 2015, 2017 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2011,2014,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
@@ -233,7 +233,7 @@ manconf_output(struct manoutput *conf, const char *cp, int fromfile)
 {
 	const char *const toks[] = {
 	    "includes", "man", "paper", "style",
-	    "indent", "width", "fragment", "mdoc", "noval"
+	    "indent", "width", "fragment", "mdoc", "noval", "toc"
 	};
 
 	const char	*errstr;
@@ -320,6 +320,9 @@ manconf_output(struct manoutput *conf, const char *cp, int fromfile)
 	case 8:
 		conf->noval = 1;
 		return 0;
+	case 9:
+		conf->toc = 1;
+		return 0;
 	default:
 		if (fromfile)
 			warnx("-O %s: Bad argument", cp);
diff --git a/usr.bin/mandoc/mdoc_html.c b/usr.bin/mandoc/mdoc_html.c
index 7af29f7f2fa..e70db937294 100644
--- a/usr.bin/mandoc/mdoc_html.c
+++ b/usr.bin/mandoc/mdoc_html.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: mdoc_html.c,v 1.187 2018/10/02 12:32:55 schwarze Exp $ */
+/*	$OpenBSD: mdoc_html.c,v 1.188 2018/10/02 14:56:36 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2014,2015,2016,2017,2018 Ingo Schwarze <schwarze@openbsd.org>
@@ -505,9 +505,39 @@ cond_id(const struct roff_node *n)
 static int
 mdoc_sh_pre(MDOC_ARGS)
 {
-	char	*id;
+	struct roff_node	*sn;
+	struct tag		*t, *tt;
+	char			*id;
+	int			 sc;
 
 	switch (n->type) {
+	case ROFFT_BLOCK:
+		if ((h->oflags & HTML_TOC) == 0 ||
+		    h->flags & HTML_TOCDONE ||
+		    n->sec <= SEC_SYNOPSIS)
+			break;
+		h->flags |= HTML_TOCDONE;
+		sc = 0;
+		for (sn = n->next; sn != NULL; sn = sn->next)
+			if (sn->sec == SEC_CUSTOM)
+				if (++sc == 2)
+					break;
+		if (sc < 2)
+			break;
+		t = print_otag(h, TAG_H1, "c", "Sh");
+		print_text(h, "TABLE OF CONTENTS");
+		print_tagq(h, t);
+		t = print_otag(h, TAG_UL, "c", "Bl-compact");
+		for (sn = n->next; sn != NULL; sn = sn->next) {
+			id = html_make_id(sn->head, 0);
+			tt = print_otag(h, TAG_LI, "");
+			print_otag(h, TAG_A, "hR", id);
+			print_mdoc_nodelist(meta, sn->head->child, h);
+			print_tagq(h, tt);
+			free(id);
+		}
+		print_tagq(h, t);
+		break;
 	case ROFFT_HEAD:
 		id = html_make_id(n, 1);
 		print_otag(h, TAG_H1, "cTi", "Sh", id);