Re: [PATCH 1/3] Wrap manual header in the "<header>" tag

[Anna <cyber@sysrq.in>]

On 2022-07-05 17:16, Ingo Schwarze wrote:
> > Yes, there's no such requirement. I misinterpreted it. So wrapping the
> > form in <header> is fine.
> 
> Done.  In addition, i also committed another patch to move
> the <h1> site header typically contained in header.html
> into the <header>.
> 
> 
> Next, i drafted a patch to use <header> for the manual header line,
> but it does not work, and i feel a bit at a loss now.  The version
> of the patch appended below (also installed on man.bsd.lv for
> testing) is deliberately inconsistent to demonstrate two ways
> of writing the <header>.
> 
> For manuals in man(7) format, the patch implements the original idea,
> so for example, https://man.bsd.lv/cvs.1 contains:
> 
>   <header role="doc-pageheader" aria-label="manual header line">
>   <table class="head">
>     <tr>
>       <td class="head-ltitle">CVS(1)</td>
>       <td class="head-vol">General Commands Manual</td>
>       <td class="head-rtitle">CVS(1)</td>
>     </tr>
>   </table>
>   </header>
> 
> But that is invalid code, see
> 
>   https://validator.w3.org/nu/?doc=https%3A%2F%2Fman.bsd.lv%2Fcvs.1
> 
>   Error: Bad value doc-pageheader for attribute role on element header.
>   From line 171, column 1; to line 171, column 62
> 
> And indeed, https://www.w3.org/TR/html-aria/#docconformance says:
> 
>   HTML element: <header>
>   ARIA roles which MAY be used: group, none or presentation. 

Same with footer.

> So we must not use doc-pageheader on <header>.
> 
> My next attempt was to move the ARIA information from the <header>
> to the contained <table>.  For demonstration, i implemented that
> for manuals in mdoc(7) format.  For example, https://man.bsd.lv/true.1
> contains:
> 
>   <header role="group">
>   <table role="doc-pageheader" aria-label="manual header line">
>     <tr>
>       <td class="head-ltitle">TRUE(1)</td>
>       <td class="head-vol">General Commands Manual</td>
>       <td class="head-rtitle">TRUE(1)</td>
>     </tr>
>   </table>
>   </header>
> 
> But the validator complains anyway:
> 
>   https://validator.w3.org/nu/?doc=https%3A%2F%2Fman.bsd.lv%2Ftrue.1
> 
>   Error: Bad value doc-pageheader for attribute role on element table.
>   From line 172, column 1; to line 172, column 61
> 
> I have no idea why; https://www.w3.org/TR/html-aria/#docconformance says:
> 
>   HTML element: <table>
>   ARIA roles which MAY be used: Any role
> 
> The section https://www.w3.org/TR/html-aria/#allowed-descendants-of-aria-roles
> does not appear to restrict the content of an element of role="group";
> it allows any flow content.  I don't see anything
> in https://www.w3.org/TR/dpub-aria-1.1/#doc-pageheader either
> that might be violated.
> 
> Do you have an idea what might be wrong here, or how we could fix it?
> 
> If you have no idea either, i might just drop the <header> element
> around the manual header line, like this:
> 
>   [...]
>   </form>
>   </header>
>   <hr>
>   <table role="doc-pageheader" aria-label="manual header line">
>     <tr>
>       <td class="head-ltitle">TRUE(1)</td>
>       <td class="head-vol">General Commands Manual</td>
>       <td class="head-rtitle">TRUE(1)</td>
>     </tr>
>   </table>
>   <main class="manual-text">
>   <section class="Sh">
>   [...]
> 
> That looks syntactically and semantically correct to me,
> and the validator doesn't complain about it either.

Whatever works (but then we need to keep class="head" for styles).

While we're at this, can we use something other than tables for
pageheader/pagefooter layout?
https://git.sr.ht/~devinprater/fossability/tree/master/item/user%20interface%20and%20experience/web.md#html

> Yours,
>   Ingo
> 
> 
> Index: html.c
> ===================================================================
> RCS file: /cvs/src/usr.bin/mandoc/html.c,v
> retrieving revision 1.148
> diff -u -p -r1.148 html.c
> --- html.c	3 Jul 2022 14:28:26 -0000	1.148
> +++ html.c	5 Jul 2022 14:06:10 -0000
> @@ -1,7 +1,7 @@
>  /* $OpenBSD: html.c,v 1.148 2022/07/03 14:28:26 schwarze Exp $ */
>  /*
> + * Copyright (c) 2011-2015, 2017-2022 Ingo Schwarze <schwarze@openbsd.org>
>   * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
> - * Copyright (c) 2011-2015, 2017-2021 Ingo Schwarze <schwarze@openbsd.org>
>   * Copyright (c) 2022 Anna Vyalkova <cyber@sysrq.in>
>   *
>   * Permission to use, copy, modify, and distribute this software for any
> @@ -66,10 +66,12 @@ static	const struct htmldata htmltags[TA
>  	{"style",	HTML_NLALL | HTML_INDENT},
>  	{"title",	HTML_NLAROUND},
>  	{"body",	HTML_NLALL},
> +	{"header",	HTML_NLALL},
>  	{"main",	HTML_NLALL},
>  	{"div",		HTML_NLAROUND},
>  	{"section",	HTML_NLALL},
>  	{"nav",		HTML_NLALL},
> +	{"footer",	HTML_NLALL},
>  	{"table",	HTML_NLALL | HTML_INDENT},
>  	{"tr",		HTML_NLALL | HTML_INDENT},
>  	{"td",		HTML_NLAROUND},
> Index: html.h
> ===================================================================
> RCS file: /cvs/src/usr.bin/mandoc/html.h,v
> retrieving revision 1.73
> diff -u -p -r1.73 html.h
> --- html.h	3 Jul 2022 14:28:27 -0000	1.73
> +++ html.h	5 Jul 2022 14:06:10 -0000
> @@ -2,6 +2,7 @@
>  /*
>   * Copyright (c) 2017, 2018, 2019, 2020 Ingo Schwarze <schwarze@openbsd.org>
>   * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
> + * Copyright (c) 2022 Anna Vyalkova <cyber@sysrq.in>
>   *
>   * Permission to use, copy, modify, and distribute this software for any
>   * purpose with or without fee is hereby granted, provided that the above
> @@ -27,10 +28,12 @@ enum	htmltag {
>  	TAG_STYLE,
>  	TAG_TITLE,
>  	TAG_BODY,
> +	TAG_HEADER,
>  	TAG_MAIN,
>  	TAG_DIV,
>  	TAG_SECTION,
>  	TAG_NAV,
> +	TAG_FOOTER,
>  	TAG_TABLE,
>  	TAG_TR,
>  	TAG_TD,
> Index: man_html.c
> ===================================================================
> RCS file: /cvs/src/usr.bin/mandoc/man_html.c,v
> retrieving revision 1.134
> diff -u -p -r1.134 man_html.c
> --- man_html.c	4 Jul 2022 14:37:14 -0000	1.134
> +++ man_html.c	5 Jul 2022 14:06:10 -0000
> @@ -1,7 +1,8 @@
>  /* $OpenBSD: man_html.c,v 1.134 2022/07/04 14:37:14 schwarze Exp $ */
>  /*
> - * Copyright (c) 2013-2015, 2017-2020 Ingo Schwarze <schwarze@openbsd.org>
> + * Copyright (c) 2013-2015,2017-2020,2022 Ingo Schwarze <schwarze@openbsd.org>
>   * Copyright (c) 2008-2012, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
> + * Copyright (c) 2022 Anna Vyalkova <cyber@sysrq.in>
>   *
>   * Permission to use, copy, modify, and distribute this software for any
>   * purpose with or without fee is hereby granted, provided that the above
> @@ -268,7 +269,9 @@ man_root_pre(const struct roff_meta *man
>  	assert(man->msec);
>  	mandoc_asprintf(&title, "%s(%s)", man->title, man->msec);
>  
> -	t = print_otag(h, TAG_TABLE, "c", "head");
> +	t = print_otag(h, TAG_HEADER, "r?", "doc-pageheader",
> +		"aria-label", "manual header line");
> +	print_otag(h, TAG_TABLE, "c", "head");
>  	tt = print_otag(h, TAG_TR, "");
>  
>  	print_otag(h, TAG_TD, "c", "head-ltitle");
> @@ -291,7 +294,9 @@ man_root_post(const struct roff_meta *ma
>  {
>  	struct tag	*t, *tt;
>  
> -	t = print_otag(h, TAG_TABLE, "c", "foot");
> +	t = print_otag(h, TAG_FOOTER, "r?", "doc-pagefooter",
> +		"aria-label", "manual footer line");
> +	print_otag(h, TAG_TABLE, "c", "foot");
>  	tt = print_otag(h, TAG_TR, "");
>  
>  	print_otag(h, TAG_TD, "c", "foot-date");
> Index: mandoc.css
> ===================================================================
> RCS file: /cvs/src/usr.bin/mandoc/mandoc.css,v
> retrieving revision 1.37
> diff -u -p -r1.37 mandoc.css
> --- mandoc.css	3 Jul 2022 14:28:27 -0000	1.37
> +++ mandoc.css	5 Jul 2022 14:06:10 -0000
> @@ -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; }
> @@ -61,7 +62,8 @@ td.head-vol {	text-align: center; }
>  td.head-rtitle {
>  		text-align: right; }
>  
> -table.foot {	width: 100%;
> +footer > table {
> +		width: 100%;
>  		border-top: 1px dotted #808080;
>  		margin-top: 1em;
>  		font-size: smaller; }
> Index: mdoc_html.c
> ===================================================================
> RCS file: /cvs/src/usr.bin/mandoc/mdoc_html.c,v
> retrieving revision 1.221
> diff -u -p -r1.221 mdoc_html.c
> --- mdoc_html.c	4 Jul 2022 14:37:14 -0000	1.221
> +++ mdoc_html.c	5 Jul 2022 14:06:10 -0000
> @@ -453,7 +453,9 @@ mdoc_root_post(const struct roff_meta *m
>  {
>  	struct tag	*t, *tt;
>  
> -	t = print_otag(h, TAG_TABLE, "c", "foot");
> +	t = print_otag(h, TAG_FOOTER, "r", "group");
> +	print_otag(h, TAG_TABLE, "r?", "doc-pagefooter",
> +	    "aria-label", "manual footer line");
>  	tt = print_otag(h, TAG_TR, "");
>  
>  	print_otag(h, TAG_TD, "c", "foot-date");
> @@ -483,7 +485,9 @@ mdoc_root_pre(const struct roff_meta *me
>  		mandoc_asprintf(&title, "%s(%s)",
>  		    meta->title, meta->msec);
>  
> -	t = print_otag(h, TAG_TABLE, "c", "head");
> +	t = print_otag(h, TAG_HEADER, "r", "group");
> +	print_otag(h, TAG_TABLE, "r?", "doc-pageheader",
> +	    "aria-label", "manual header line");
>  	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