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.

4 files changed, 12 insertions, 2 deletions

diff --git a/html.c b/html.c
index 65c31b64..0199edb0 100644
--- a/html.c
+++ b/html.c
@@ -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 dda19b8a..32742461 100644
--- a/html.h
+++ b/html.h
@@ -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 fc9751ad..f6e038fa 100644
--- a/mandoc_html.3
+++ b/mandoc_html.3
@@ -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 2dde0531..dc01f88c 100644
--- a/mdoc_html.c
+++ b/mdoc_html.c
@@ -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: