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
Date: Sun, 3 Jul 2022 23:49:47 +0500 [thread overview]
Message-ID: <YsHky81PH7PUI0YF@sysrq.in> (raw)
In-Reply-To: <YsHQwEk20FQARzFA@asta-kit.de>
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
next prev parent reply other threads:[~2022-07-03 18:49 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 [this message]
2022-07-03 20:12 ` Ingo Schwarze
2022-07-03 20:51 ` Anna “CyberTailor”
2022-07-05 15:16 ` Ingo Schwarze
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=YsHky81PH7PUI0YF@sysrq.in \
--to=cyber@sysrq.in \
--cc=schwarze@usta.de \
--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).