Improve accessibility of -T html -O toc output by using the <nav> element

in the DPUB-ARIA doc-toc role.
Patch from Anna Vyalkova <cyber at sysrq dot in> slightly tweaked by me.

This is hopefully the start of a collaboration to improve accessibility
of Unix manual pages using the WAI-ARIA, HTML-ARIA, and DPUB-ARIA standards.
Progress appears to be possible without changing *anything* with respect to
the way manual pages are written.  Instead, it seems sufficient to properly
translate semantic cues already implied by existing mdoc(7) markup into the
appropriate HTML elements and ARIA attributes.  Overall, the total length
of HTML output is likely to increase slightly, but not much.

diff --git a/html.c b/html.c
index 71c9c711e825851b2b52bec5a6d58d5904dcde11..4c12b7b64b3038aca915dfae14a6f888acbc2cbe 100644 (file)
--- a/html.c
+++ b/html.c
@@ -1,4 +1,4 @@
-/* $Id: html.c,v 1.275 2021/09/09 14:47:24 schwarze Exp $ */
+/* $Id: html.c,v 1.276 2022/06/24 11:15:53 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2011-2015, 2017-2021 Ingo Schwarze <schwarze@openbsd.org>
@@ -69,6 +69,7 @@ static        const struct htmldata htmltags[TAG_MAX] = {
        {"body",        HTML_NLALL},
        {"div",         HTML_NLAROUND},
        {"section",     HTML_NLALL},
+       {"nav",         HTML_NLALL},
        {"table",       HTML_NLALL | HTML_INDENT},
        {"tr",          HTML_NLALL | HTML_INDENT},
        {"td",          HTML_NLAROUND},
@@ -708,6 +709,9 @@ print_otag(struct html *h, enum htmltag tag, const char *fmt, ...)
                case 'i':
                        attr = "id";
                        break;
+               case 'r':
+                       attr = "role";
+                       break;
                case '?':
                        attr = arg1;
                        arg1 = va_arg(ap, char *);

diff --git a/html.h b/html.h
index 3d201403342d9f7188074ad23e63a117bacd0681..b19ee20cf4e5275332d1a6e8d0d41b35de37a9bf 100644 (file)
--- a/html.h
+++ b/html.h
@@ -1,4 +1,4 @@
-/* $Id: html.h,v 1.109 2021/09/09 14:47:24 schwarze Exp $ */
+/* $Id: html.h,v 1.110 2022/06/24 11:15:53 schwarze Exp $ */
 /*
  * Copyright (c) 2017, 2018, 2019, 2020 Ingo Schwarze <schwarze@openbsd.org>
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
@@ -29,6 +29,7 @@ enum  htmltag {
        TAG_BODY,
        TAG_DIV,
        TAG_SECTION,
+       TAG_NAV,
        TAG_TABLE,
        TAG_TR,
        TAG_TD,

diff --git a/mandoc_html.3 b/mandoc_html.3
index a77d0e04fce421646c41640009123799d3215eb2..a7c8d7960c4b4b676a61cec461f0634ede1425e0 100644 (file)
--- a/mandoc_html.3
+++ b/mandoc_html.3
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc_html.3,v 1.23 2020/04/24 13:13:06 schwarze Exp $
+.\"    $Id: mandoc_html.3,v 1.24 2022/06/24 11:15:53 schwarze Exp $
 .\"
 .\" Copyright (c) 2014, 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -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: April 24 2020 $
+.Dd $Mdocdate: June 24 2022 $
 .Dt MANDOC_HTML 3
 .Os
 .Sh NAME
@@ -221,6 +221,10 @@ option.
 Print an
 .Cm id
 attribute.
+.It Cm r
+Print an ARIA
+.Cm role
+attribute.
 .It Cm \&?
 Print an arbitrary attribute.
 This format letter requires two

diff --git a/mdoc_html.c b/mdoc_html.c
index c0a0a6a5697876c5197a357fc834be7f245cd0b7..85969a19d2aaac956a95d5ef5e6e3f59f2a423d5 100644 (file)
--- a/mdoc_html.c
+++ b/mdoc_html.c
@@ -1,4 +1,4 @@
-/* $Id: mdoc_html.c,v 1.342 2021/03/30 19:26:20 schwarze Exp $ */
+/* $Id: mdoc_html.c,v 1.343 2022/06/24 11:15:53 schwarze Exp $ */
 /*
  * Copyright (c) 2014-2021 Ingo Schwarze <schwarze@openbsd.org>
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
@@ -515,7 +515,7 @@ static int
 mdoc_sh_pre(MDOC_ARGS)
 {
        struct roff_node        *sn, *subn;
-       struct tag              *t, *tsec, *tsub;
+       struct tag              *t, *tnav, *tsec, *tsub;
        char                    *id;
        int                      sc;
 
@@ -536,6 +536,7 @@ mdoc_sh_pre(MDOC_ARGS)
                                        break;
                if (sc < 2)
                        break;
+               tnav = print_otag(h, TAG_NAV, "r", "doc-toc");
                t = print_otag(h, TAG_H1, "c", "Sh");
                print_text(h, "TABLE OF CONTENTS");
                print_tagq(h, t);
@@ -567,7 +568,7 @@ mdoc_sh_pre(MDOC_ARGS)
                        }
                        print_tagq(h, tsec);
                }
-               print_tagq(h, t);
+               print_tagq(h, tnav);
                print_otag(h, TAG_SECTION, "c", "Sh");
                break;
        case ROFFT_HEAD: