From: Ingo Schwarze <schwarze@usta.de>
To: Anna <cyber@sysrq.in>
Cc: tech@mandoc.bsd.lv
Subject: Re: [PATCH 1/3] Wrap manual header in the "<header>" tag
Date: Tue, 5 Jul 2022 17:16:47 +0200 [thread overview]
Message-ID: <YsRV3yNbBmJwDxo0@asta-kit.de> (raw)
In-Reply-To: <YsIBNfFtEggNHnRk@sysrq.in>
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
next prev parent reply other threads:[~2022-07-05 15:16 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-06-28 18:18 [PATCH 0/3] Add HTML landmarks Anna Vyalkova
2022-06-28 18:18 ` [PATCH 1/3] Wrap manual header in the "<header>" tag Anna Vyalkova
2022-07-03 17:24 ` Ingo Schwarze
2022-07-03 18:49 ` Anna Vyalkova
2022-07-03 20:12 ` Ingo Schwarze
2022-07-03 20:51 ` Anna “CyberTailor”
2022-07-05 15:16 ` Ingo Schwarze [this message]
2022-07-05 16:15 ` Anna
2022-07-05 18:45 ` Ingo Schwarze
2022-07-05 19:03 ` Anna
2022-07-05 21:39 ` Ingo Schwarze
2022-06-28 18:18 ` [PATCH 2/3] Wrap manual text in the "<main>" tag Anna Vyalkova
2022-07-03 14:41 ` Ingo Schwarze
2022-06-28 18:18 ` [PATCH 3/3] Wrap manual footer in the "<footer>" tag Anna Vyalkova
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=YsRV3yNbBmJwDxo0@asta-kit.de \
--to=schwarze@usta.de \
--cc=cyber@sysrq.in \
--cc=tech@mandoc.bsd.lv \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).