From 88e033f9985d9aec739c4497f51fb9348247d4db Mon Sep 17 00:00:00 2001
From: schwarze <schwarze@openbsd.org>
Date: Fri, 24 Jun 2022 11:15:19 +0000
Subject: [PATCH] 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.
---
 usr.bin/mandoc/html.c      | 6 +++++-
 usr.bin/mandoc/html.h      | 3 ++-
 usr.bin/mandoc/mdoc_html.c | 7 ++++---
 3 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/usr.bin/mandoc/html.c b/usr.bin/mandoc/html.c
index 1e996daf439..bff21059f53 100644
--- a/usr.bin/mandoc/html.c
+++ b/usr.bin/mandoc/html.c
@@ -1,4 +1,4 @@
-/* $OpenBSD: html.c,v 1.146 2021/09/09 14:45:18 schwarze Exp $ */
+/* $OpenBSD: html.c,v 1.147 2022/06/24 11:15:19 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2011-2015, 2017-2021 Ingo Schwarze <schwarze@openbsd.org>
@@ -67,6 +67,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},
@@ -706,6 +707,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/usr.bin/mandoc/html.h b/usr.bin/mandoc/html.h
index 06ba51e7d72..5ca0a38f280 100644
--- a/usr.bin/mandoc/html.h
+++ b/usr.bin/mandoc/html.h
@@ -1,4 +1,4 @@
-/* $OpenBSD: html.h,v 1.71 2021/09/09 14:45:18 schwarze Exp $ */
+/* $OpenBSD: html.h,v 1.72 2022/06/24 11:15:19 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/usr.bin/mandoc/mdoc_html.c b/usr.bin/mandoc/mdoc_html.c
index e6dbfbe4a83..8d34d5a1cec 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.217 2021/03/30 19:23:50 schwarze Exp $ */
+/* $OpenBSD: mdoc_html.c,v 1.218 2022/06/24 11:15:19 schwarze Exp $ */
 /*
  * Copyright (c) 2014-2021 Ingo Schwarze <schwarze@openbsd.org>
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
@@ -513,7 +513,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;
 
@@ -534,6 +534,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);
@@ -565,7 +566,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:
-- 
2.20.1