Re: [PATCH 1/3] Wrap manual header in the "<header>" tag

[Ingo Schwarze <schwarze@usta.de>]

Hello Anna,

Anna wrote on Mon, Jul 04, 2022 at 01:51:01AM +0500:

> There are incomplete lists:
> https://a11ysupport.io/
> https://www.powermapper.com/tests/screen-readers/aria/

Thanks, i linked those from https://mandoc.bsd.lv/links.html
to not forget them.

> On 2022-07-03 22:12, Ingo Schwarze wrote:

[...]
>> What difference does it make for a screen reader whether
>> the aria-label is present or absent?

> It will say the line before entering the element.

>> Why would a user ever want the words "Manual header line"
>> read out at them?

> To know what to expect (and decide whether to skip or not).

Fair enough, so we'll add such aria-label attributes where appropriate.

[...]
> Yes, there's no such requirement. I misinterpreted it. So wrapping the
> form in <header> is fine.

Done.  In addition, i also committed another patch to move
the <h1> site header typically contained in header.html
into the <header>.


Next, i drafted a patch to use <header> for the manual header line,
but it does not work, and i feel a bit at a loss now.  The version
of the patch appended below (also installed on man.bsd.lv for
testing) is deliberately inconsistent to demonstrate two ways
of writing the <header>.

For manuals in man(7) format, the patch implements the original idea,
so for example, https://man.bsd.lv/cvs.1 contains:

  <header role="doc-pageheader" aria-label="manual header line">
  <table class="head">
    <tr>
      <td class="head-ltitle">CVS(1)</td>
      <td class="head-vol">General Commands Manual</td>
      <td class="head-rtitle">CVS(1)</td>
    </tr>
  </table>
  </header>

But that is invalid code, see

  https://validator.w3.org/nu/?doc=https%3A%2F%2Fman.bsd.lv%2Fcvs.1

  Error: Bad value doc-pageheader for attribute role on element header.
  From line 171, column 1; to line 171, column 62

And indeed, https://www.w3.org/TR/html-aria/#docconformance says:

  HTML element: <header>
  ARIA roles which MAY be used: group, none or presentation. 

So we must not use doc-pageheader on <header>.

My next attempt was to move the ARIA information from the <header>
to the contained <table>.  For demonstration, i implemented that
for manuals in mdoc(7) format.  For example, https://man.bsd.lv/true.1
contains:

  <header role="group">
  <table role="doc-pageheader" aria-label="manual header line">
    <tr>
      <td class="head-ltitle">TRUE(1)</td>
      <td class="head-vol">General Commands Manual</td>
      <td class="head-rtitle">TRUE(1)</td>
    </tr>
  </table>
  </header>

But the validator complains anyway:

  https://validator.w3.org/nu/?doc=https%3A%2F%2Fman.bsd.lv%2Ftrue.1

  Error: Bad value doc-pageheader for attribute role on element table.
  From line 172, column 1; to line 172, column 61

I have no idea why; https://www.w3.org/TR/html-aria/#docconformance says:

  HTML element: <table>
  ARIA roles which MAY be used: Any role

The section https://www.w3.org/TR/html-aria/#allowed-descendants-of-aria-roles
does not appear to restrict the content of an element of role="group";
it allows any flow content.  I don't see anything
in https://www.w3.org/TR/dpub-aria-1.1/#doc-pageheader either
that might be violated.

Do you have an idea what might be wrong here, or how we could fix it?

If you have no idea either, i might just drop the <header> element
around the manual header line, like this:

  [...]
  </form>
  </header>
  <hr>
  <table role="doc-pageheader" aria-label="manual header line">
    <tr>
      <td class="head-ltitle">TRUE(1)</td>
      <td class="head-vol">General Commands Manual</td>
      <td class="head-rtitle">TRUE(1)</td>
    </tr>
  </table>
  <main class="manual-text">
  <section class="Sh">
  [...]

That looks syntactically and semantically correct to me,
and the validator doesn't complain about it either.

Yours,
  Ingo


Index: html.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/html.c,v
retrieving revision 1.148
diff -u -p -r1.148 html.c
--- html.c	3 Jul 2022 14:28:26 -0000	1.148
+++ html.c	5 Jul 2022 14:06:10 -0000
@@ -1,7 +1,7 @@
 /* $OpenBSD: html.c,v 1.148 2022/07/03 14:28:26 schwarze Exp $ */
 /*
+ * Copyright (c) 2011-2015, 2017-2022 Ingo Schwarze <schwarze@openbsd.org>
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
- * Copyright (c) 2011-2015, 2017-2021 Ingo Schwarze <schwarze@openbsd.org>
  * Copyright (c) 2022 Anna Vyalkova <cyber@sysrq.in>
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -66,10 +66,12 @@ static	const struct htmldata htmltags[TA
 	{"style",	HTML_NLALL | HTML_INDENT},
 	{"title",	HTML_NLAROUND},
 	{"body",	HTML_NLALL},
+	{"header",	HTML_NLALL},
 	{"main",	HTML_NLALL},
 	{"div",		HTML_NLAROUND},
 	{"section",	HTML_NLALL},
 	{"nav",		HTML_NLALL},
+	{"footer",	HTML_NLALL},
 	{"table",	HTML_NLALL | HTML_INDENT},
 	{"tr",		HTML_NLALL | HTML_INDENT},
 	{"td",		HTML_NLAROUND},
Index: html.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/html.h,v
retrieving revision 1.73
diff -u -p -r1.73 html.h
--- html.h	3 Jul 2022 14:28:27 -0000	1.73
+++ html.h	5 Jul 2022 14:06:10 -0000
@@ -2,6 +2,7 @@
 /*
  * Copyright (c) 2017, 2018, 2019, 2020 Ingo Schwarze <schwarze@openbsd.org>
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
+ * Copyright (c) 2022 Anna Vyalkova <cyber@sysrq.in>
  *
  * Permission to use, copy, modify, and distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
@@ -27,10 +28,12 @@ enum	htmltag {
 	TAG_STYLE,
 	TAG_TITLE,
 	TAG_BODY,
+	TAG_HEADER,
 	TAG_MAIN,
 	TAG_DIV,
 	TAG_SECTION,
 	TAG_NAV,
+	TAG_FOOTER,
 	TAG_TABLE,
 	TAG_TR,
 	TAG_TD,
Index: man_html.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/man_html.c,v
retrieving revision 1.134
diff -u -p -r1.134 man_html.c
--- man_html.c	4 Jul 2022 14:37:14 -0000	1.134
+++ man_html.c	5 Jul 2022 14:06:10 -0000
@@ -1,7 +1,8 @@
 /* $OpenBSD: man_html.c,v 1.134 2022/07/04 14:37:14 schwarze Exp $ */
 /*
- * Copyright (c) 2013-2015, 2017-2020 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2013-2015,2017-2020,2022 Ingo Schwarze <schwarze@openbsd.org>
  * Copyright (c) 2008-2012, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
+ * Copyright (c) 2022 Anna Vyalkova <cyber@sysrq.in>
  *
  * Permission to use, copy, modify, and distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
@@ -268,7 +269,9 @@ man_root_pre(const struct roff_meta *man
 	assert(man->msec);
 	mandoc_asprintf(&title, "%s(%s)", man->title, man->msec);
 
-	t = print_otag(h, TAG_TABLE, "c", "head");
+	t = print_otag(h, TAG_HEADER, "r?", "doc-pageheader",
+		"aria-label", "manual header line");
+	print_otag(h, TAG_TABLE, "c", "head");
 	tt = print_otag(h, TAG_TR, "");
 
 	print_otag(h, TAG_TD, "c", "head-ltitle");
@@ -291,7 +294,9 @@ man_root_post(const struct roff_meta *ma
 {
 	struct tag	*t, *tt;
 
-	t = print_otag(h, TAG_TABLE, "c", "foot");
+	t = print_otag(h, TAG_FOOTER, "r?", "doc-pagefooter",
+		"aria-label", "manual footer line");
+	print_otag(h, TAG_TABLE, "c", "foot");
 	tt = print_otag(h, TAG_TR, "");
 
 	print_otag(h, TAG_TD, "c", "foot-date");
Index: mandoc.css
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.css,v
retrieving revision 1.37
diff -u -p -r1.37 mandoc.css
--- mandoc.css	3 Jul 2022 14:28:27 -0000	1.37
+++ mandoc.css	5 Jul 2022 14:06:10 -0000
@@ -53,7 +53,8 @@ table.results {	margin-top: 1em;
 
 /* Header and footer lines. */
 
-table.head {	width: 100%;
+header > table {
+		width: 100%;
 		border-bottom: 1px dotted #808080;
 		margin-bottom: 1em;
 		font-size: smaller; }
@@ -61,7 +62,8 @@ td.head-vol {	text-align: center; }
 td.head-rtitle {
 		text-align: right; }
 
-table.foot {	width: 100%;
+footer > table {
+		width: 100%;
 		border-top: 1px dotted #808080;
 		margin-top: 1em;
 		font-size: smaller; }
Index: mdoc_html.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc_html.c,v
retrieving revision 1.221
diff -u -p -r1.221 mdoc_html.c
--- mdoc_html.c	4 Jul 2022 14:37:14 -0000	1.221
+++ mdoc_html.c	5 Jul 2022 14:06:10 -0000
@@ -453,7 +453,9 @@ mdoc_root_post(const struct roff_meta *m
 {
 	struct tag	*t, *tt;
 
-	t = print_otag(h, TAG_TABLE, "c", "foot");
+	t = print_otag(h, TAG_FOOTER, "r", "group");
+	print_otag(h, TAG_TABLE, "r?", "doc-pagefooter",
+	    "aria-label", "manual footer line");
 	tt = print_otag(h, TAG_TR, "");
 
 	print_otag(h, TAG_TD, "c", "foot-date");
@@ -483,7 +485,9 @@ mdoc_root_pre(const struct roff_meta *me
 		mandoc_asprintf(&title, "%s(%s)",
 		    meta->title, meta->msec);
 
-	t = print_otag(h, TAG_TABLE, "c", "head");
+	t = print_otag(h, TAG_HEADER, "r", "group");
+	print_otag(h, TAG_TABLE, "r?", "doc-pageheader",
+	    "aria-label", "manual header line");
 	tt = print_otag(h, TAG_TR, "");
 
 	print_otag(h, TAG_TD, "c", "head-ltitle");
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv