Re: [PATCH 6/8] mdoc_html: Add accessible description to crosslinks

[Ingo Schwarze <schwarze@usta.de>]

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 <cyber at sysrq dot in>,
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 <schwarze@openbsd.org>
+ * Copyright (c) 2014-2022 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
@@ -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 <schwarze@openbsd.org>
 Copyright (c) 2008-2012, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
-Copyright (c) 2010-2021 Ingo Schwarze <schwarze@openbsd.org>
 Copyright (c) 1999, 2004, 2017 Marc Espie <espie@openbsd.org>
 Copyright (c) 2009, 2010, 2011, 2012 Joerg Sonnenberger <joerg@netbsd.org>
 Copyright (c) 2013 Franco Fichtner <franco@lastsummer.de>
@@ -13,6 +13,7 @@ Copyright (c) 2014 Baptiste Daroussin <b
 Copyright (c) 2016 Ed Maste <emaste@freebsd.org>
 Copyright (c) 2017 Michael Stapelberg <stapelberg@debian.org>
 Copyright (c) 2017 Anthony Bentley <bentley@openbsd.org>
+Copyright (c) 2022 Anna Vyalkova <cyber@sysrq.in>
 Copyright (c) 1998, 2004, 2010, 2015 Todd C. Miller <Todd.Miller@courtesan.com>
 Copyright (c) 2008, 2017 Otto Moerbeek <otto@drijf.net>
 Copyright (c) 2004 Ted Unangst <tedu@openbsd.org>
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv