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.0 required=5.0 tests=T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 10473 invoked from network); 24 Jun 2022 13:58:53 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 24 Jun 2022 13:58:53 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 3d42d229 for ; Fri, 24 Jun 2022 08:58:51 -0500 (EST) Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 1ed3ed5d for ; Fri, 24 Jun 2022 08:58:50 -0500 (EST) Received: from hekate.asta.kit.edu ([2a00:1398:5:f401::77]) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.3:ECDHE_SECP256R1__RSA_PSS_RSAE_SHA256__AES_256_GCM:256) (envelope-from ) id 1o4jpg-00HT0b-Ql; Fri, 24 Jun 2022 15:58:49 +0200 Received: from login-1.asta.kit.edu ([2a00:1398:5:f400::72]) by hekate.asta.kit.edu with esmtp (Exim 4.94.2) (envelope-from ) id 1o4jpf-0066Qm-AA; Fri, 24 Jun 2022 15:58:47 +0200 Received: from schwarze by login-1.asta.kit.edu with local (Exim 4.92) (envelope-from ) id 1o4jpf-0002Pt-Mn; Fri, 24 Jun 2022 15:58:47 +0200 Date: Fri, 24 Jun 2022 15:58:47 +0200 From: Ingo Schwarze To: Anna Cc: tech@mandoc.bsd.lv Subject: Re: [PATCH 2/8] mdoc_html: Add DPUB-ARIA roles to sections Message-ID: References: <20220621122749.11417-1-cyber@sysrq.in> <20220621122749.11417-3-cyber@sysrq.in> X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20220621122749.11417-3-cyber@sysrq.in> 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
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
element is

or

, 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
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