Re: [PATCH 2/8] mdoc_html: Add DPUB-ARIA roles to sections

[Ingo Schwarze <schwarze@usta.de>]

Hi Anna,

i agree with the findamental idea of your patch
titled "Add DPUB-ARIA roles to sections", but i have a few questions and
i think there are number of details that need to be resolved before it
becomes ready for commit.

Anna "CyberTailor" wrote on Tue, Jun 21, 2022 at 05:27:43PM +0500:

> diff --git a/html.h b/html.h
> index 5e2adc06..dc4febf2 100644
> --- a/html.h
> +++ b/html.h
> @@ -74,6 +74,32 @@ enum	htmltag {
>  	TAG_MAX
>  };
>  
> +static	const char * const dpubroles[SEC__MAX] = {
> +	NULL,			/* SEC_NONE */
> +	"doc-abstract",		/* SEC_NAME */

I'm not sure this is correct.  The doc-abstract role is defined as:

  A short summary of the principal ideas, concepts, and conclusions
  of the work, or of a section or excerpt within it.

But the NAME section merely contains a title and a subtitle for the
document as a whole, which is much less than an abstract.

Could we somehow mark the NAME section as containing nothing but
document titles?  Specifically, .Nm gives the main title
and .Nd feels like "doc-subtitle" to me.

> +	"doc-abstract",		/* SEC_LIBRARY */

This is clearly wrong.  The LIBRARY section does not contain an abstract.
While i consider the LIBRARY section ill-designed in the first place,
some operating systems use it, so you are right the we need to make it
clear what it contains.  It typically consists of a single line containing
only a few words, not even a complete sentence, for example any of the
following lines:

  Standard C Library (libc, -lc)
  Math Library (libm, -lm)
  Backtrace Information Library (libexecinfo, -lexecinfo)
  Netgraph User Library (libnetgraph, -lnetgraph)
  Begemot SNMP library (libbsnmp, -lbsnmp)
  System Utilities Library (libutil, -lutil)
  Video Graphics Library (libvgl, -lvgl)
  library "libcap_net"
  library "libcap_syslog"
  library "libcapsicum"
  library "libstats"

The jemalloc(3) page in FreeBSD is an aberration rather than the norm.

I'm not even convinced assigning a region or section class to
the LIBRARY section makes sense at all.  Maybe there is a better
alternative which does not mark it as a region or section?

Besically, its function is part of the function of the SYNOPSIS:
Explain the syntax needed to use the functions documented in this
manual page.  Admittedly not the syntax needed in the C source
code, but the syntax needed when calling ld(1).

> +	"doc-part",		/* SEC_SYNOPSIS */

This seems unfortunate, too.  The SYNOPSIS typically does not
contain any free-form text, but only a formalized syntax summary.
Is there a role that might apply to formal syntax descriptions
somewhere?  So far, i failed to find one.  If nobody comes up
with a better idea, maybe we might consider (ab)using "doc-abstract"
here?

> +	"doc-part",		/* SEC_DESCRIPTION */
> +	"doc-part",		/* SEC_CONTEXT */
> +	"doc-part",		/* SEC_IMPLEMENTATION */
> +	"doc-part",		/* SEC_RETURN_VALUES */
> +	"doc-part",		/* SEC_ENVIRONMENT */
> +	"doc-part",		/* SEC_FILES */
> +	"doc-part",		/* SEC_EXIT_STATUS */

I don't think doc-part is adequate for these.
DPUB-ARIA defines it as follows:

  A major structural division in a work that contains a set of related
  sections dealing with a particular subject, narrative arc, or similar
  encapsulated theme.

Things like SEC_CONTEXT, SEC_RETURN_VALUES, SEC_ENVIRONMENT, SEC_FILES,
and SEC_EXIT_STATUS certainly aren't "major structural divisions", and
even for SEC_DESCRIPTION, it's the exception rather than the rule for
it to contain "a set of related sections".

If i understand DPUB-ARIA correctly, doc-part is higher level than
doc-chapter, i.e. a part usually consists of multiple chapters.
So if we use DPUB-ARIA here at all, doc-chapter would seem more
appropriate.  But even that is decribed as:

  A major thematic section of content in a work.

That doesn't fit well for SEC_FILES and the like.

Is it maybe better to simply use the "region" role defined in the
WAI-ARIA standard itself?  It is described as:

  A perceivable section containing content that is relevant to a specific,
  author-specified purpose and sufficiently important that users will
  likely want to be able to navigate to the section easily and to have
  it listed in a summary of the page.

That seems to apply even to smaller sections like SEC_FILES.

If we want to use role="region", HTML-ARIA tells me that it's already
the default "if the <section> element has an accessible name.  Otherwise,
no corresponding role."
See: https://www.w3.org/TR/html-aria/

It would seem logical to me that, if the first child of the <section>
element is <h1> or <h2>, the "accessible name" would automatically be
taken from that header element.  But HTML-AAM-1.0 given me the
impression this is not the case:

  https://www.w3.org/TR/html-aam-1.0/#section-elements-and-grouping-content-elements-not-listed-elsewhere

  4.16.1 Section and Grouping Element Accessible Name Computation

    1. If the element has an aria-label or an aria-labelledby attribute
       the accessible name is to be calculated using the algorithm defined
       in Accessible Name and Description: Computation and API Mappings.
    2. Otherwise use the title attribute.
    3. If none of the above yield a usable text string there is no
       accessible name.

Does that really mean that we have to specify aria-labelledby="..."
on each and every <section> element?  Is there no way to get
accessible section names with less verbosity in the HTML code?

> +	"doc-example",		/* SEC_EXAMPLES */
[...]
> +	"doc-aknowledgments",	/* SEC_AUTHORS */

This is the bright side of this message: I agree with those two.

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv