From: Ingo Schwarze <schwarze@usta.de>
To: Anna <cyber@sysrq.in>
Cc: tech@mandoc.bsd.lv
Subject: Re: [PATCH 7/8] mdoc_html: Tell screen readers to skip the header
Date: Sun, 26 Jun 2022 17:51:23 +0200 [thread overview]
Message-ID: <YriAe+aKV99log46@asta-kit.de> (raw)
In-Reply-To: <20220621122749.11417-8-cyber@sysrq.in>
Hello Anna,
i agree with your apparent goal to not force the listener to wait
for unnecessary chatter to finish. Then again, aria-hidden="true"
looks like quite a big hammer to me, and before wielding that one,
i'd like to look at the big picture of document structure first.
Unfortunately, that big picture of how HTML elements and ARIA roles
work together to convey the overall document structure appears to be
scattered around at least five lengthy documents: WAI-ARIA, ARIA-APG,
HTML-ARIA, HTML-AAM, and DPUB-ARIA. So i compiled the essentials of
these five documents into the following short tree structure.
Each line has four optional fields: HTML element, default ARIA role,
role category in parentheses, and a comment. I omitted elements
and roles that i deem unlikely to occur in manual pages.
<html> document (structure) - use reading mode here
<head> no role can be assigned
<body> no role can be assigned
<header> banner (landmark) - site-oriented, e.g. logo, site name, search tool
<form> form (landmark)
search (landmark) - special case of form, use for man.cgi in the future
doc-pageheader
<main> main (landmark) - main content of the document
- use in the future instead of <div class="manual-text">?
doc-subtitle - could maybe be used for .Nd
doc-abstract - could maybe be used for the SYNOPSIS
<nav> navigation (landmark) - internal or external links
doc-toc - used for -O toc
<article> article (structure) - independent part
doc-part
doc-chapter
<section> region (landmark) - could maybe be used for .Sh
<h1> - <h6> heading (structure)
<ul>, <ol>, <mewnu> list (structure)
<li> listitem (structure)
<table> table (structure)
<th> columnheader (structure)
<thead>, <tbody>, <tfoot> rowgroup (structure)
<tr> row (structure)
<th> rowheader (structure)
<td>, <th> cell (structure)
doc-example - use for EXAMPLES in the future
doc-bibliography - could maybe be used for .Rs in the future
doc-acknowledgments - use for AUTHORS in the furture
doc-pagefooter
<footer> contentinfo (landmark) - information about document, e.g. (c), privacy
<aside> complementary (landmark) - independent but related content
The two tables we are talking about here and in your next patch are
currently marked as class="head" and class="foot", which is good enough
to support the current mandoc.css but is unhelpful with respect to ARIA.
Let's consider which are the two places in the above tree
where these two tables occur.
The "head" table comes immediately after the search form and immediately
before the NAME section, i.e. shortly before the .Nd line. The only
node between "search" and "Nd" in the above tree is "doc-pageheader".
The "foot" table comes after AUTHORS. The <footer> and <aside> elements
and the contentinfo and complementary landmarks are inadequate for the
content of the "foot" table, which leaves us with doc-pagefooter
as the only option.
Conidering their DPUB-ARIA description, doc-pageheader and doc-pagefooter
maybe aren't perfect fits for these two tables, but i think close enough
to make their use acceptable.
What do you think about the following plan?
1. Replace the ideosyncratic <div class="manual-text">
with the standard <main> element.
We could maybe keep the class="manual-text" attribute
on the <main> element for backward compatibility.
Then again, users of -T html are likely to have to adapt
their CSS code to the change from <div> to <main> anyway,
so i'd lean twoards deleting the custom class: <main> alone
feels like fully expressing the intention, and when it comes
to CSS, doing the same with less is more.
2. Instead of <table class="head">, say <table role="doc-pageheader">.
3. Instead of <table class="foot">, say <table role="doc-pagefooter">.
It that enough to convince screen readers to refrain from pointless
chatter, or is the big hammer of aria-hidden="true" still needed?
I wouldn't be opposed to saying
<table role="doc-pageheader" aria-hidden="true">
if you think that is better than just <table role="doc-pageheader">.
I'm not sending a patch yet because i'd like to learn your opinion
on these ideas first.
Two minor remarks regarding your patch follow inline below.
Yours,
Ingo
Anna “CyberTailor” wrote on Tue, Jun 21, 2022 at 05:27:48PM +0500:
> diff --git a/html.c b/html.c
> index 3239a09b..c45e9ee0 100644
> --- a/html.c
> +++ b/html.c
> @@ -715,6 +715,9 @@ print_otag(struct html *h, enum htmltag tag, const char *fmt, ...)
> case 'r':
> attr = "role";
> break;
> + case 's':
> + attr = "aria-hidden";
> + break;
The format letter 's' cannot be used for this purpose because it is
already taken, see
https://mandoc.bsd.lv/man/mandoc_html.3.html#s
> case '?':
> attr = arg1;
> arg1 = va_arg(ap, char *);
> diff --git a/mdoc_html.c b/mdoc_html.c
> index cf2e8804..85aadc4e 100644
> --- a/mdoc_html.c
> +++ b/mdoc_html.c
> @@ -484,7 +484,8 @@ mdoc_root_pre(const struct roff_meta *meta, struct html *h)
> mandoc_asprintf(&title, "%s(%s)",
> meta->title, meta->msec);
>
> - t = print_otag(h, TAG_TABLE, "c", "head");
> + // Tell screen readers to skip the section
In OpenBSD C code, we *never* use // for comments, but always /* */.
> + t = print_otag(h, TAG_TABLE, "cs", "head", "true");
> 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-06-26 15:51 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-06-21 12:27 [PATCH 0/8] Make generated HTML more accessible Anna “CyberTailor”
2022-06-21 12:27 ` [PATCH 1/8] mdoc_html: Accessibility markup for ToC Anna “CyberTailor”
2022-06-21 12:27 ` [PATCH 2/8] mdoc_html: Add DPUB-ARIA roles to sections Anna “CyberTailor”
2022-06-24 13:58 ` Ingo Schwarze
2022-06-21 12:27 ` [PATCH 3/8] mdoc_html: Add DPUB-ARIA roles to subsections Anna “CyberTailor”
2022-06-21 12:27 ` [PATCH 4/8] man_html: Add DPUB-ARIA roles to (sub)sections Anna “CyberTailor”
2022-06-21 12:27 ` [PATCH 5/8] man.cgi: add ARIA roles and semantics Anna “CyberTailor”
2022-07-04 16:37 ` Ingo Schwarze
2022-06-21 12:27 ` [PATCH 6/8] mdoc_html: Add accessible description to crosslinks Anna “CyberTailor”
2022-06-25 12:58 ` Ingo Schwarze
2022-06-21 12:27 ` [PATCH 7/8] mdoc_html: Tell screen readers to skip the header Anna “CyberTailor”
2022-06-26 15:51 ` Ingo Schwarze [this message]
2022-06-28 16:33 ` Anna “CyberTailor”
2022-06-21 12:27 ` [PATCH 8/8] man_html: " Anna “CyberTailor”
2022-06-22 19:15 ` [PATCH 0/8] Make generated HTML more accessible Ingo Schwarze
2022-06-22 19:40 ` Anna “CyberTailor”
2022-06-23 13:34 ` Ingo Schwarze
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=YriAe+aKV99log46@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).