From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-0.0 required=5.0 tests=T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 20590 invoked from network); 26 Jun 2022 15:51:31 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 26 Jun 2022 15:51:31 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id c965d6c6 for ; Sun, 26 Jun 2022 10:51:27 -0500 (EST) Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 343ea9e9 for ; Sun, 26 Jun 2022 10:51:27 -0500 (EST) Received: from hekate.asta.kit.edu ([2a00:1398:5:f401::77]) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.3:ECDHE_SECP256R1__RSA_PSS_RSAE_SHA256__AES_256_GCM:256) (envelope-from ) id 1o5UXl-004hdn-GP; Sun, 26 Jun 2022 17:51:26 +0200 Received: from login-1.asta.kit.edu ([2a00:1398:5:f400::72]) by hekate.asta.kit.edu with esmtp (Exim 4.94.2) (envelope-from ) id 1o5UXj-00682k-AK; Sun, 26 Jun 2022 17:51:23 +0200 Received: from schwarze by login-1.asta.kit.edu with local (Exim 4.92) (envelope-from ) id 1o5UXj-0001wk-Mv; Sun, 26 Jun 2022 17:51:23 +0200 Date: Sun, 26 Jun 2022 17:51:23 +0200 From: Ingo Schwarze To: Anna Cc: tech@mandoc.bsd.lv Subject: Re: [PATCH 7/8] mdoc_html: Tell screen readers to skip the header Message-ID: References: <20220621122749.11417-1-cyber@sysrq.in> <20220621122749.11417-8-cyber@sysrq.in> X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit 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. document (structure) - use reading mode here no role can be assigned no role can be assigned

banner (landmark) - site-oriented, e.g. logo, site name, search tool

form (landmark) search (landmark) - special case of form, use for man.cgi in the future doc-pageheader

main (landmark) - main content of the document - use in the future instead of

? doc-subtitle - could maybe be used for .Nd doc-abstract - could maybe be used for the SYNOPSIS

navigation (landmark) - internal or external links doc-toc - used for -O toc

article (structure) - independent part doc-part doc-chapter

region (landmark) - could maybe be used for .Sh

-

heading (structure)
,
, list (structure)
listitem (structure) table (structure) , , rowgroup (structure) row (structure)
columnheader (structure)
rowheader (structure) , 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
contentinfo (landmark) - information about document, e.g. (c), privacy
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
and
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
with the standard
element. We could maybe keep the class="manual-text" attribute on the
element for backward compatibility. Then again, users of -T html are likely to have to adapt their CSS code to the change from
to
anyway, so i'd lean twoards deleting the custom class:
alone feels like fully expressing the intention, and when it comes to CSS, doing the same with less is more. 2. Instead of , say
. 3. Instead of
, say
. 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
if you think that is better than just . 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