From: Ingo Schwarze <schwarze@usta.de>
To: Anna <cyber@sysrq.in>
Cc: tech@mandoc.bsd.lv
Subject: Re: [PATCH 1/3] Wrap manual header in the "<header>" tag
Date: Sun, 3 Jul 2022 19:24:16 +0200 [thread overview]
Message-ID: <YsHQwEk20FQARzFA@asta-kit.de> (raw)
In-Reply-To: <20220628181844.15484-2-cyber@sysrq.in>
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".
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>
<form action="/" method="get" autocomplete="off" autocapitalize="none">
...
</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?
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?
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 17:24 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 [this message]
2022-07-03 18:49 ` Anna Vyalkova
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=YsHQwEk20FQARzFA@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).