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.
 ************************************************************************
 * 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:
 ************************************************************************
 
 Many issues are annotated for difficulty as follows:


@@ -390,11 +390,6 @@ are mere guesses, and some may be wrong.
 
 --- HTML issues --------------------------------------------------------
 
 
 --- 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
 - 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>
 /*
  * 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;
        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);
 
 
        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>
 /*
  * 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_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 */
        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 */
        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
 .\"
 .\" 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.
 .\"
 .\" 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
 .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 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
 .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>
 /*
  * 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;
        size_t    width;
        int       fragment;
        int       mdoc;

-       int       synopsisonly;

        int       noval;
        int       noval;

+       int       synopsisonly;
+       int       toc;

 };
 
 struct manconf {
 };
 
 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>
 .\"
 .\" 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.
 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,
 .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
  * 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",
 {
        const char *const toks[] = {
            "includes", "man", "paper", "style",

-           "indent", "width", "fragment", "mdoc", "noval"
+           "indent", "width", "fragment", "mdoc", "noval", "toc"

        };
 
        const char      *errstr;
        };
 
        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 8:
                conf->noval = 1;
                return 0;

+       case 9:
+               conf->toc = 1;
+               return 0;

        default:
                if (fromfile)
                        warnx("-O %s: Bad argument", cp);
        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>
 /*
  * 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)
 {
 static int
 mdoc_sh_pre(MDOC_ARGS)
 {

-       char    *id;
+       struct roff_node        *sn;
+       struct tag              *t, *tt;
+       char                    *id;
+       int                      sc;

 
        switch (n->type) {
 
        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);
        case ROFFT_HEAD:
                id = html_make_id(n, 1);
                print_otag(h, TAG_H1, "cTi", "Sh", id);