[patch] use mandatory arg for \Description in acmart

[dginev]

Fixes #2638

Took a closer look, it appears that this was a typo in the argument usage for \Description.

The previous PR #2591 already intended to use the mandatory argument (as visible from the comment in the binding sub), but that is #2 rather than #1.

Edit: This PR also ensures the HTML output contains simple markup that is hidden, using a dedicated <ltx:note role="nodisplay">

[dginev]

It is good to get a healthy Windows CI failure again (even if still spurious path separator differences). I have a commit simplifying the test again, but github has the update "pending" for an hour. Will check again in a day.

[dginev]

Ready for review, CI is happy.

[dginev]

One more update: the ltx:note use always creates a mark in HTML, which both has CSS implications (sometimes the mark remains visible) but also vocalization implications (we don't have any ARIA markup on the notes).

So, instead, I switched to ltx:inline-block which creates a simpler container without any complications.

[brucemiller]

I'm confused by the change from ltx:note to ltx:inline-block; what is the "mark" that you say is always created? There are marks involved with \note, but not generally with ltx:note. Clearly note is heavily overloaded with lots of magic, but it is semantically more sensible, and I'd hate to have the magic start creeping into ltx:inline-block as well. Probably we should address the mark, and keep inline-blocks as simple as possible.

[dginev]

With the ltx:note variant I see the following caption HTML code with the default transformation:

<figcaption class="ltx_caption">
  <span class="ltx_tag ltx_tag_figure">Figure 1. </span>caption text
  <span id="acmlabel1" class="ltx_note ltx_nodisplay">
    <sup class="ltx_note_mark">†</sup>
    <span class="ltx_note_outer">
      <span class="ltx_note_content">
        <sup class="ltx_note_mark">†</sup>
        <span class="ltx_note_type">: </span>Fly 1 and fly 2 comparison shows identical length,
 wingspan, and overall bodily structure.
      </span></span></span></figcaption>
</figure>

coming from the following XML from the core phase:

<ltx:caption>
  <ltx:tag close=". ">Figure 1</ltx:tag>caption text
  <ltx:note class="ltx_nodisplay" xml:id="acmlabel1">Fly 1 and fly 2 comparison shows identical 
length, wingspan, and overall bodily structure.
  </ltx:note>
</ltx:caption>

indentation and namespaces mine

[dginev]

I attempted adding a new role called "nodisplay", where <ltx:note> with that role gets mapped to very simple markup via XSLT with the additional ltx_nodisplay class that ensures it remains hidden.

Let me know if this is close to what you had in mind as a change that continues using ltx:note @brucemiller .

Also the commit history is a bit silly now, feel free to squash & merge.

[brucemiller]

It seems the interesting question (to me) is why we're adding an ltx_note_mark with a dagger at all? When does that form get invoked? I'd have expected no mark span wrapper at all when there wasn't a @mark.
And role=nodisplay is really not getting into the Semantic spirit of things.

[dginev]

I hear a request for a rename - done, the role is now called accessible-description. Feel free to suggest specific names.

What is much harder to do on my end is to opine on the structuring of the XSLT for note marks. I went on a quick fishing expedition and found the introduction of the note-mark rule, which is invoked on every note:

db157ca

If that commit is any guide, the <sup> boilerplate was always deposited, but the specific mark was conditional on the @mark attribute being set.

Luckily we have the author here to tell us if that was an oversight or if we are just now starting to grow out of the older design, which allows for a healthy refactor. I suggest refactoring in a separate place (and possibly time), as I expect the details can stay completely internal/under the hood of XSLT.

[brucemiller]

Cool; How about simply "description", since it's useful even in non-accessibilty situations?

Thanks for digging out the ancient code for note marks; that's likely from an era where notes were thought of purely as footnotes, so maybe a dagger fallback seemed right, but perhaps no longer is. Those daggers don't appear in any output I've got handy, but I wonder if they appear in arXiv in places where some mark really is needed (rather than distinctly unwanted :> ) Do you see any? If they do, I'd expect them to come from frontmatter mangles, but probably should have somehow gotten an explicit @mark if it were needed. I can propose a refactor of the XSLT if that would be more comfortable?

[dginev]

It gets cooler - now we get to argue semantics :>

It is not sufficiently clear to me that we can't have "note descriptions" that want to be visible margin notes. It is immediately clear to me that metadata aimed at accessibility is not meant to be visible. So the a11y mention is somewhat mandatory semantics here, in my mind.

I think I have seen mangled frontmatter notes in arXiv, yes. They're just not the focus of this PR, and I'd hate to get the wires crossing here. Sounds like an independent refactor to me.

[brucemiller]

I've seen nothing in any of the documentations that indicate that these descriptions are intended exclusively for accessibility, so I don't see the restriction as mandatory. And whether or not these or other descriptions might appear as margin notes seems to be an entirely separate issue.

My question was not whether there are mangled front matter in arXiv (obviously there is), but whether there were notes that got the dagger mark that should have some kind of mark. That we're getting unwanted marks apparently is part of the focus of this PR, so we should address it properly.

[dginev]

It is addressed properly for the use in-scope. Please generalize this elsewhere.

This PR adds the first use of ltx:note that is intended as invisible in the rendered HTML documents. As such it requires its own bit of implementation (leading to the ltx_nodisplay class). This is a requirement coming from their use as accessible notes, not from them being descriptions.