Re: [PATCH 7/8] mdoc_html: Tell screen readers to skip the header

["Anna “CyberTailor”" <cyber@sysrq.in>]

On 2022-06-26 17:51, Ingo Schwarze wrote:
> 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.

Agree.

>  2. Instead of <table class="head">, say <table role="doc-pageheader">.

I'd better wrap it in a <header> tag. Using semantic HTML is better than
ARIA.

>  3. Instead of <table class="foot">, say <table role="doc-pagefooter">.

Same but with <footer>.

> 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'll test both variants later and send a patch with whatever works best.

> 
> 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");

Got it.
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv