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 29605 invoked from network); 25 Jun 2022 12:59:03 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 25 Jun 2022 12:59:03 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id dedc6e3a for ; Sat, 25 Jun 2022 07:59:02 -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 347db43e for ; Sat, 25 Jun 2022 07:59:02 -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 1o55NM-002AxG-Lh; Sat, 25 Jun 2022 14:59:01 +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 1o55NL-00677f-1j; Sat, 25 Jun 2022 14:58:59 +0200 Received: from schwarze by login-1.asta.kit.edu with local (Exim 4.92) (envelope-from ) id 1o55NL-0002oW-EC; Sat, 25 Jun 2022 14:58:59 +0200 Date: Sat, 25 Jun 2022 14:58:59 +0200 From: Ingo Schwarze To: Anna Cc: tech@mandoc.bsd.lv Subject: Re: [PATCH 6/8] mdoc_html: Add accessible description to crosslinks Message-ID: References: <20220621122749.11417-1-cyber@sysrq.in> <20220621122749.11417-7-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-7-cyber@sysrq.in> Hello Anna, Anna "CyberTailor" wrote on Tue, Jun 21, 2022 at 05:27:47PM +0500: > Never hear "mdoc, left parenthesis, 7, right parenthesis" again. Indeed, as i noticed in the past when sitting next to people who were using screen readers, it is quite annoying when the screen reader reads out punctuation verbosely. It takes significant time, which is bad because using a screen reader is already slower than reading text using your eyes, and it also distracts from listening to the actual text. So even though the approach you propose results in a bit of verbosity in the HTML code, i don't think that can be avoided if we are serious about accessibility. > diff --git a/html.c b/html.c > index 4710bab7..3239a09b 100644 > --- a/html.c > +++ b/html.c > @@ -709,6 +709,9 @@ print_otag(struct html *h, enum htmltag tag, const char *fmt, ...) > case 'i': > attr = "id"; > break; > + case 'l': > + attr = "aria-label"; > + break; I expect that "aria-label" attributes will be needed for relatively few purposes in manual pages, so for now, i prefer using the generic "?" format letter. If it turns out i'm wrong and we need "aria-label" in more places than i expect, we can always add a dedicated "l" format letter later. > diff --git a/mdoc_html.c b/mdoc_html.c > index 076a6bac..cf2e8804 100644 > --- a/mdoc_html.c > +++ b/mdoc_html.c > @@ -667,26 +667,35 @@ mdoc_nm_pre(MDOC_ARGS) > static int > mdoc_xr_pre(MDOC_ARGS) > { > + char *name = NULL, *section = NULL, *label = NULL; > + I dislike assignments in declarations and usually avoid them, in particular when they are redundant (like, in this case, for the name variable). > if (NULL == n->child) > return 0; > > + name = n->child->string; > + label = name; > + if (NULL != n->child->next) > + section = n->child->next->string; > + > + if (NULL != section) > + mandoc_asprintf(&label, "%s, section %s", name, section); > + > if (h->base_man1) > - print_otag(h, TAG_A, "chM", "Xr", > - n->child->string, n->child->next == NULL ? > - NULL : n->child->next->string); > + print_otag(h, TAG_A, "clhM", "Xr", label, name, section); > else > - print_otag(h, TAG_A, "c", "Xr"); > + print_otag(h, TAG_A, "cl", "Xr", label); > > - n = n->child; > - print_text(h, n->string); > + free(label); There is quite a bad bug here. If no section is specified in the document, we have label == n->child->string at this point, so we would wrongly free a field of the syntax tree, resulting in a double free error when the whole tree is freed later on. > + > + print_text(h, name); > > - if (NULL == (n = n->next)) > + if (NULL == section) > return 0; > > h->flags |= HTML_NOSPACE; > print_text(h, "("); > h->flags |= HTML_NOSPACE; > - print_text(h, n->string); > + print_text(h, section); > h->flags |= HTML_NOSPACE; > print_text(h, ")"); > return 0; I committed the following variation of your patch. In case you find a problem with it, we can tweak it in the tree. Yours, Ingo Log Message: ----------- If an .Xr macro contains a section argument, write an aria-label attribute such that users of screen readers aren't forced to listen to lengthy and distracting readings like "mdoc, left parenthesis, 7, right parenthesis". Based on a patch from Anna Vyalkova , significantly tweaked by me. Modified Files: -------------- mandoc: LICENSE mdoc_html.c Revision Data ------------- Index: mdoc_html.c =================================================================== RCS file: /home/cvs/mandoc/mandoc/mdoc_html.c,v retrieving revision 1.343 retrieving revision 1.344 diff -Lmdoc_html.c -Lmdoc_html.c -u -p -r1.343 -r1.344 --- mdoc_html.c +++ mdoc_html.c @@ -1,7 +1,8 @@ /* $Id$ */ /* - * Copyright (c) 2014-2021 Ingo Schwarze + * Copyright (c) 2014-2022 Ingo Schwarze * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons + * Copyright (c) 2022 Anna Vyalkova * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -665,26 +666,34 @@ mdoc_nm_pre(MDOC_ARGS) static int mdoc_xr_pre(MDOC_ARGS) { - if (NULL == n->child) + char *name, *section, *label; + + if (n->child == NULL) return 0; + name = n->child->string; + if (n->child->next != NULL) { + section = n->child->next->string; + mandoc_asprintf(&label, "%s, section %s", name, section); + } else + section = label = NULL; + if (h->base_man1) - print_otag(h, TAG_A, "chM", "Xr", - n->child->string, n->child->next == NULL ? - NULL : n->child->next->string); + print_otag(h, TAG_A, "chM?", "Xr", + name, section, "aria-label", label); else - print_otag(h, TAG_A, "c", "Xr"); + print_otag(h, TAG_A, "c?", "Xr", "aria-label", label); - n = n->child; - print_text(h, n->string); + free(label); + print_text(h, name); - if (NULL == (n = n->next)) + if (section == NULL) return 0; h->flags |= HTML_NOSPACE; print_text(h, "("); h->flags |= HTML_NOSPACE; - print_text(h, n->string); + print_text(h, section); h->flags |= HTML_NOSPACE; print_text(h, ")"); return 0; Index: LICENSE =================================================================== RCS file: /home/cvs/mandoc/mandoc/LICENSE,v retrieving revision 1.22 retrieving revision 1.23 diff -LLICENSE -LLICENSE -u -p -r1.22 -r1.23 --- LICENSE +++ LICENSE @@ -4,8 +4,8 @@ With the exceptions noted below, all non in the mandoc toolkit are protected by the Copyright of the following developers: +Copyright (c) 2010-2022 Ingo Schwarze Copyright (c) 2008-2012, 2014 Kristaps Dzonsons -Copyright (c) 2010-2021 Ingo Schwarze Copyright (c) 1999, 2004, 2017 Marc Espie Copyright (c) 2009, 2010, 2011, 2012 Joerg Sonnenberger Copyright (c) 2013 Franco Fichtner @@ -13,6 +13,7 @@ Copyright (c) 2014 Baptiste Daroussin Copyright (c) 2017 Michael Stapelberg Copyright (c) 2017 Anthony Bentley +Copyright (c) 2022 Anna Vyalkova Copyright (c) 1998, 2004, 2010, 2015 Todd C. Miller Copyright (c) 2008, 2017 Otto Moerbeek Copyright (c) 2004 Ted Unangst -- To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv