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.

diff --git a/TODO b/TODO
index 14289756a67584e531fc2ff3106e590cb5b1ec1f..a168133e2017340808e09f603c07c0a76749148e 100644 (file)
--- a/TODO
+++ b/TODO
@@ -1,6 +1,6 @@
 ************************************************************************
 * Official mandoc TODO.
-* $Id: TODO,v 1.272 2018/10/02 12:33:36 schwarze Exp $
+* $Id: TODO,v 1.273 2018/10/02 14:56:47 schwarze Exp $
 ************************************************************************
 
 Many issues are annotated for difficulty as follows:
@@ -390,11 +390,6 @@ are mere guesses, and some may be wrong.
 
 --- HTML issues --------------------------------------------------------
 
-- table of content at the top of HTML (and perhaps ps/pdf) pages
-  only if there are at least two (or three?) non-standard sections
-  only if the new option -O toc is given
-  suggested by Adam Kalisz during EuroBSDCon 2018
-
 - wrap Sh and Ss content into <div>
   Laura Morales <lauretas at mail dot com> 21 Apr 2018 18:10:48 +0200
   (Evaluate whether this is really useful and has no adverse

diff --git a/html.c b/html.c
index 5078864f4147879a8bf41272efb89a463070fab1..0d6687fb3ccdb3c7fa0ec7ceb37975bf202e6b1c 100644 (file)
--- a/html.c
+++ b/html.c
@@ -1,4 +1,4 @@
-/*     $Id: html.c,v 1.240 2018/10/02 12:33:37 schwarze Exp $ */
+/*     $Id: html.c,v 1.241 2018/10/02 14:56:47 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2011-2015, 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
@@ -136,6 +136,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/html.h b/html.h
index 606dd76de3d864849a1b814db01f30f56bc9856b..5f3c5ebe76f6a13526e193609cd51754b919cd2c 100644 (file)
--- a/html.h
+++ b/html.h
@@ -1,4 +1,4 @@
-/*     $Id: html.h,v 1.93 2018/10/02 12:33:37 schwarze Exp $ */
+/*     $Id: html.h,v 1.94 2018/10/02 14:56:47 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/man.conf.5 b/man.conf.5
index be0998087d171a74eba2b63b66a16d0c5fe050f3..0ffe868ad7641bf0f5a7676d1f054b72582997ff 100644 (file)
--- a/man.conf.5
+++ b/man.conf.5
@@ -1,6 +1,6 @@
-.\"    $Id: man.conf.5,v 1.5 2017/08/22 18:17:52 schwarze Exp $
+.\"    $Id: man.conf.5,v 1.6 2018/10/02 14:56:47 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/manconf.h b/manconf.h
index b4cd31646c913cf7886b322fc56c98bb77e5835f..babd463b46294119b0fc0c4311666e874ad21618 100644 (file)
--- a/manconf.h
+++ b/manconf.h
@@ -1,4 +1,4 @@
-/*     $Id: manconf.h,v 1.5 2017/07/01 09:47:30 schwarze Exp $ */
+/*     $Id: manconf.h,v 1.6 2018/10/02 14:56:47 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/mandoc.1 b/mandoc.1
index c35ef73aa33d8ca4e92d5fc09a624dd8df55d8e7..cd84be76287f029d1b954dd9131719193f1460c4 100644 (file)
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.1,v 1.229 2018/10/02 12:33:37 schwarze Exp $
+.\"    $Id: mandoc.1,v 1.230 2018/10/02 14:56:47 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/manpath.c b/manpath.c
index 54f7a6b110ade0ed84d2c7ed78ba0c6652536217..f6cf704f13b8e7bf39eb8bf210a2245df4c2f017 100644 (file)
--- a/manpath.c
+++ b/manpath.c
@@ -1,6 +1,6 @@
-/*     $Id: manpath.c,v 1.35 2017/07/01 09:47:30 schwarze Exp $ */
+/*     $Id: manpath.c,v 1.36 2018/10/02 14:56:47 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/mdoc_html.c b/mdoc_html.c
index fd181b60d910145230843090448c9d3999055b37..555046be2c55e9ff5b9d8412953cbf1c079670b0 100644 (file)
--- a/mdoc_html.c
+++ b/mdoc_html.c
@@ -1,4 +1,4 @@
-/*     $Id: mdoc_html.c,v 1.312 2018/10/02 12:33:37 schwarze Exp $ */
+/*     $Id: mdoc_html.c,v 1.313 2018/10/02 14:56:47 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2014,2015,2016,2017,2018 Ingo Schwarze <schwarze@openbsd.org>
@@ -507,9 +507,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);