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.2 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED,
	T_SCC_BODY_TEXT_LINE autolearn=no autolearn_force=no version=3.4.4
Received: (qmail 8361 invoked from network); 3 Jul 2022 18:49:55 -0000
Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12)
  by inbox.vuxu.org with ESMTPUTF8; 3 Jul 2022 18:49:55 -0000
Received: from fantadrom.bsd.lv (localhost [127.0.0.1])
	by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 512473b5
	for <ml@inbox.vuxu.org>;
	Sun, 3 Jul 2022 13:49:53 -0500 (EST)
Received: from sysrq.in (sysrq.in [37.79.202.136])
	by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 1565a894
	for <tech@mandoc.bsd.lv>;
	Sun, 3 Jul 2022 13:49:52 -0500 (EST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sysrq.in; s=sysrq.in;
	t=1656874188;
	h=from:from:reply-to:subject:subject:date:date:message-id:message-id:
	 to:to:cc:cc:mime-version:mime-version:content-type:content-type:
	 content-transfer-encoding:content-transfer-encoding:
	 in-reply-to:in-reply-to:references:references:autocrypt:autocrypt;
	bh=EUJlS/NaB9YRex/JsfijgjDa9mCrqblDGIDS5D3N90k=;
	b=tWvuZ+LzhfN/vV8EJWz0yfaX9jeIYKzKNe/30eEnbMcQKPcqXYkhcRaT/1Ue412zaiN7gF
	SBZQH712qAz6hPonytFO6XZak5Efu9DlV5rGwnEt621ORoqtk5hTVjPavii++KsNJ/bkwm
	mXXtENiUzc7aam8RoVOg2JdM/IE3PAzUpv10WDQ/kQQY+aiV+ppH2qZSSWqLebKZeJBiRl
	6fGw7MjgJByhseEzrsy5ITMyWuj7n7EUDqQEwhxu44gy41hbevzsAu913MeSYJLsKtZgAP
	8cvBHjf/Liar3WuPieoOAuwkAhhFWpcdkZo8uKPupR7xUqMlXaYIThnOKLMaaw==
Received: from sysrq.in (localhost [127.0.0.1])
	by sysrq.in (OpenSMTPD) with ESMTPSA id d96a8d6d (TLSv1.3:TLS_AES_256_GCM_SHA384:256:NO);
	Sun, 3 Jul 2022 18:49:48 +0000 (UTC)
Date: Sun, 3 Jul 2022 23:49:47 +0500
From: Anna Vyalkova <cyber@sysrq.in>
To: Ingo Schwarze <schwarze@usta.de>
Cc: tech@mandoc.bsd.lv
Subject: Re: [PATCH 1/3] Wrap manual header in the "<header>" tag
Message-ID: <YsHky81PH7PUI0YF@sysrq.in>
References: <20220628181844.15484-1-cyber@sysrq.in>
 <20220628181844.15484-2-cyber@sysrq.in>
 <YsHQwEk20FQARzFA@asta-kit.de>
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: <YsHQwEk20FQARzFA@asta-kit.de>
Autocrypt: addr=cyber@sysrq.in; prefer-encrypt=mutual; keydata=
	mDMEYIFqhRYJKwYBBAHaRw8BAQdAmXuImZ3E4FYSZevE6xmeyqwBedA5TL3F0mA4nM8Jv5C0J0F
	ubmEg4oCcQ3liZXJUYWlsb3LigJ0gPGN5YmVyQHN5c3JxLmluPoiQBBMWCAA4FiEERA3R5VXjf5
	x8ewz7f6gU36rhAzoFAmCBaoUCGwMFCwkIBwIGFQoJCAsCBBYCAwECHgECF4AACgkQf6gU36rhA
	zoeCwD/UbmIjoaPHgxAubn/yoHbqtix0p1W8BwVdZSBinqtoc8BAMX19adz5Zx71lYFinFG7Yav
	D4E0jClMEfnYJH2TeG4HuDgEYIFqhRIKKwYBBAGXVQEFAQEHQGL1LYMPZDabnCTPEuyg5QgIlnU
	bKBqoPjp5sNidRZJXAwEIB4h4BBgWCAAgFiEERA3R5VXjf5x8ewz7f6gU36rhAzoFAmCBaoUCGw
	wACgkQf6gU36rhAzpFxwD/Z0QQGqLgBcafYUcHmzYcYxuyazuKWIn3H6OkeFUYtTgBAJmK2E+Yo
	mSMc0Ds93+yNQU0KhN1Ipyp9PiLDSSm8Z4B
User-Agent: Mutt/2.2.6 (2022-06-05)

On 2022-07-03 19:24, Ingo Schwarze wrote:
> Hello Anna,
> 
> Anna Vyalkova wrote on Tue, Jun 28, 2022 at 11:18:42PM +0500:
> 
> [...]
> > diff --git a/mandoc.css b/mandoc.css
> > index 73f5c668..4cfb51e8 100644
> > --- a/mandoc.css
> > +++ b/mandoc.css
> > @@ -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; }
> > diff --git a/mdoc_html.c b/mdoc_html.c
> > index a0e29c72..cf771b75 100644
> > --- a/mdoc_html.c
> > +++ b/mdoc_html.c
> > @@ -470,7 +470,7 @@ mdoc_root_post(const struct roff_meta *meta, struct html *h)
> >  static int
> >  mdoc_root_pre(const struct roff_meta *meta, struct html *h)
> >  {
> > -	struct tag	*t, *tt;
> > +	struct tag	*th, *t, *tt;
> >  	char		*volume, *title;
> >  
> >  	if (NULL == meta->arch)
> > @@ -485,6 +485,7 @@ mdoc_root_pre(const struct roff_meta *meta, struct html *h)
> >  		mandoc_asprintf(&title, "%s(%s)",
> >  		    meta->title, meta->msec);
> >  
> > +	th = print_otag(h, TAG_HEADER, "");
> >  	t = print_otag(h, TAG_TABLE, "c", "head");
> >  	tt = print_otag(h, TAG_TR, "");
> >  
> > @@ -499,6 +500,7 @@ mdoc_root_pre(const struct roff_meta *meta, struct html *h)
> >  	print_otag(h, TAG_TD, "c", "head-rtitle");
> >  	print_text(h, title);
> >  	print_tagq(h, t);
> > +	print_tagq(h, th);
> >  
> >  	free(title);
> >  	free(volume);
> 
> I fully agree that the current <table class="head"> is insufficient
> because it has no ARIA effect.
> 
> I also agree that using <header> is not wrong because the HTML
> standard defines it very vaguely:
> 
>   https://html.spec.whatwg.org/multipage/sections.html#the-header-element
> 
>   The header element represents a group of introductory
>   or navigational aids.
> 
> However, according to the HTML-ARIA standard, the default role of <header>
> is "banner" if it is a child of <body>, and "banner" is the wrong role
> because WAI-ARIA defines it as follows:
> 
>   https://www.w3.org/TR/wai-aria-1.1/#banner
> 
>   A region that contains mostly site-oriented content, rather than
>   page-specific content.
> 
>   Site-oriented content typically includes things such as the logo or
>   identity of the site sponsor, and a site-specific search tool. A
>   banner usually appears at the top of the page and typically spans
>   the full width.
> 
> The table in question is clearly page-specific and definitely
> not the same for all documents on the site.  I really think we
> should better use the role "doc-pageheader" here and not "banner".

Yes, this is according to the standards (and to common sense, since
these sections are not worth assigning landmark roles). However only a
few screen readers support "doc-pageheader" and "doc-pagefooter" roles,
so an 'aria-label' tag may be needed in addition to avoid confusion:

  <header role="doc-pageheader" aria-label="Manual header line">

> We might of course consider using <header role="doc-pageheader">,
> but that would seem unfortunate to me because in the case of man.cgi(8)
> output, we really need the "banner" role (ideally getting it as the default
> from a header element) for the site name (e.g. "OpenBSD manual page server")
> and the search form ("Manual Page Search Parameters").  Using <header>
> for *that* would perfectly fit the definition of the "banner" role
> cited above.
> 
> As far as i can see, the HTML standard does not prohibit having two
> <header> elements in a row, for example like this:
> 
>   <body>
>     <header>
>       <h1><a href="https://www.openbsd.org/">OpenBSD</a>
>           manual page server</h1>

If it's only one H1, assigning it a banner role makes little sense as
it's already reflected in the document hierarchy.

>       <form action="/" method="get" autocomplete="off" autocapitalize="none">
>       ...
>       </form>

The search form needs to be top-level with role="search" to be
considered as a landmark:

  <body>
    <!-- custom site header -->
    <form action="/" method="get" autocomplete="off" autocapitalize="none" role="search">
    ...
    </form>

>     </header>
>     <hr>
>     <header role="doc-pageheader">
>       <table class="head">
>         <tr>
>           <td class="head-ltitle">PF.CONF(5)</td>
>           <td class="head-vol">File Formats Manual</td>
>           <td class="head-rtitle">PF.CONF(5)</td>
>         </tr>
>       </table>
>     </header>
>     <main>
> 
> But that would seem ugly to me.  Or do you think having two consecutive
> <header> elements here would be fine?

I think it's fine

1) in semantic sense (they are still headers and footers, just
   page-specific ones)
2) so we can write "header > table" in CSS
 
> https://stackoverflow.com/questions/21655804/html5-multiple-footers-headers-in-a-section (which is of course not authoritative) says
> 
>   There is no prohibition against having e.g. two header elements
>   (at the same level of nesting) in an article element. They would
>   then both contain “introductory content” for it. It is however
>   difficult to imagine situations where this would make sense, since
>   header elements normally precede other content, and the header
>   would thus be adjacent and could be combined into one.
>
> Here, they could not easily be combined into one because the search
> form is written by cgi.c whereas the <table class="head"> is written
> by html.c.  That's not just an implementation detail because both
> headers serve a significantly different purpose: the first one
> presents site-oriented content, the second one is specific to the
> manual page being shown.
> 
> Do you think having two consecutive headers right below <body> would
> be good here, or what should we do instead?

This won't happen with my proposal. Either this:

<form>
<header>

or this:

<form>
<nav> (with <table class="results">)
<header>

> If so, should we maybe explicitly set <header role="banner"> on the
> first header even though that is redundant, to make it more apparent
> why we have two headers?
> 
> For the footer, using <footer role="doc-pagefooter"> poses fewer
> problems because we only need one single footer.  But i'd like to
> solve the trickier case of the headers first before deciding how to
> mark up the footer.
> 
> Yours,
>   Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv