Normative rule text doesn't handle latexmath properly

[james-ball-qualcomm]

In norm-rules.json, the image: portion is unusable and should be dropped, or left with the original latex math tag.

      "name": "signed_div_overflow",
      "def_filename": "normative_rule_defs/m-st-ext.yaml",
      "chapter_name": "M Extension",
      "tags": [
        {
          "name": "norm:signed_div_overflow",
          "text": "Signed division overflow occurs only when the most-negative integer is divided\nby image:../../build/images-out/stem-52c1acbf19a35be815dca1fd989d89e4.svg[width=15,height=8]. The quotient of a signed division with overflow is\nequal to the dividend, and the remainder is zero.",
          "tag_filename": "/build/riscv-unprivileged-norm-tags.json"
        }
      ]

This came from m-st-ext.adoc:

[#norm:signed_div_overflow]#Signed division overflow occurs only when the most-negative integer is divided
by latexmath:[$-1$]. The quotient of a signed division with overflow is
equal to the dividend, and the remainder is zero.#

[james-ball-qualcomm]

@Timmmm, FYI

[Timmmm]

Ah that's awkward. Maybe we can recover the original source and use that. I'll have a look.

[james-ball-qualcomm]

Thanks. Would the original text mean what comes after latexmath:?

[james-ball-qualcomm]

@kersten1, @aswaterman, @wmat - Adding you to this issue.

[Timmmm]

Would the original text mean what comes after latexmath:?

Probably including the latexmath: too, though I guess we can have a hacky filter for that maybe.

[Timmmm]

Interesting, when I edit tests/norm-rule/test.yaml to only consist of the source text you gave, and then run rm build/test-norm-tags.json; make build/test-norm-tags.json I get this JSON:

{
  "tags": {
    "norm:signed_div_overflow": "Signed division overflow occurs only when the most-negative integer is divided\nby �0�. The quotient of a signed division with overflow is\nequal to the dividend, and the remainder is zero."
  }, ...

The weird characters are U+0096 and U+0097 which are apparently "Start of Protected Area" and "End of Protected Area", and the content is always 0 irrespective of the Latex which is kind of bad!

[james-ball-qualcomm]

I can easily filter it too in my Ruby tool that consumes the tags JSON file. +james+

…

________________________________ From: Tim Hutt ***@***.***> Sent: Monday, November 17, 2025 1:19:28 PM To: riscv/docs-resources ***@***.***> Cc: James Ball (QUIC) ***@***.***>; Author ***@***.***> Subject: Re: [riscv/docs-resources] Normative rule text doesn't handle latexmath properly (Issue #126) WARNING: This email originated from outside of Qualcomm. Please be wary of any links or attachments, and do not enable macros. [https://avatars.githubusercontent.com/u/376842?s=20&v=4]Timmmm left a comment (riscv/docs-resources#126)<#126 (comment)> Interesting, when I edit tests/norm-rule/test.yaml to only consist of the source text you gave, and then run rm build/test-norm-tags.json; make build/test-norm-tags.json I get this JSON: { "tags": { "norm:signed_div_overflow": "Signed division overflow occurs only when the most-negative integer is divided\nby �0�. The quotient of a signed division with overflow is\nequal to the dividend, and the remainder is zero." }, ... The weird characters are U+0096 and U+0097 which are apparently "Start of Protected Area" and "End of Protected Area", and the content is always 0 irrespective of the Latex which is kind of bad! — Reply to this email directly, view it on GitHub<#126 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BBRBTGAYKX7ZY6GQJIQZVD335I3WBAVCNFSM6AAAAACMLLYLUKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTKNBTHA4DGOBYG4>. You are receiving this because you authored the thread.Message ID: ***@***.***>

[james-ball-qualcomm]

Tim, I've been wondering why I see images sometimes and others just omissions of the latexmath. I had examples of both in the email we've got going. Sounds like you've now seen a 3rd case with the special characters and then the content of the latexmath (0 in this case for div by zero). I don't know what influences which case you'll see in the tags JSON but am not sure I care too much. Your thoughts?

[wmat]

Just so I'm clear, is the problem with the generation of the json file from the adoc source where latexmath expressions exist? Currently, asciidoctor relies on asciidoctor-mathematical to render formulas as svg images in the PDF and HTML. Note that this isn't the case when using Antora, which uses MathJax instead as Antora is a Javascript toolchain vs. the Ruby based toolchain we're currently building with.

[james-ball-qualcomm]

Yes, the problem is adoc to json (containing normatively tagged text). Seems like many cases could just use regular ASCII characters or Unicode characters for special symbols (like infinity) and avoid a dependency on asciidoctor-mathematical or MathJax.

So, can I edit the normatively tagged text in the ISA manual that uses latexmath: to just ASCII/Unicode characters? I'd add more adoc macros so we can invoke these by name, not a 4-digit hex value.

[wmat]

So long as it doesn't break any of the more complex formulas, such as in the Vector chapter. I don't think it should though.

[jjscheel]

What I don't understand is the use case for having an image in "normative text". Is this really a requirement? If so, can you give me an example?