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.

diff --git a/LICENSE b/LICENSE
index 0a0fc1acd2ac8ef87d10c0634ff742594ea09fce..8b464f4e6aecd8702a0bbc0facf77a79da2ae229 100644 (file)
--- a/LICENSE
+++ b/LICENSE
@@ -1,11 +1,11 @@
-$Id: LICENSE,v 1.22 2021/09/19 11:02:09 schwarze Exp $
+$Id: LICENSE,v 1.23 2022/06/25 12:44:25 schwarze Exp $
 
 With the exceptions noted below, all non-trivial files contained
 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 <bapt@freebsd.org>
 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>

diff --git a/mdoc_html.c b/mdoc_html.c
index 85969a19d2aaac956a95d5ef5e6e3f59f2a423d5..63c98aaba21b05b62ec77da03d8f0e74a5fb429b 100644 (file)
--- a/mdoc_html.c
+++ b/mdoc_html.c
@@ -1,7 +1,8 @@
-/* $Id: mdoc_html.c,v 1.343 2022/06/24 11:15:53 schwarze Exp $ */
+/* $Id: mdoc_html.c,v 1.344 2022/06/25 12:44:25 schwarze Exp $ */
 /*
- * 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;