Tag backend produces unusable JSON tag file for unordered lists or description lists

[james-ball-qualcomm]

I'd like to tag and entire unordered list or description list but it won't work.

Here's an example of what I'd like to tag:

[[norm:fruit-color]]
Bananas::
Generally yellow in color
Apples::
Generally red in color

[#norm:Zca_misa_c]#MISA.C is set if the following extensions are selected:#

[[norm:Zca_misa_c_list]]
* Zca and not F
* Zca, Zcf and F (but not D) is specified (RV32 only)
* Zca, Zcf and Zcd if D is specified (RV32 only)
** this configuration excludes Zcmp, Zcmt
* Zca, Zcd if D is specified (RV64 only)
** this configuration excludes Zcmp, Zcmt

Unfortunately I get this in the tags JSON file for these tags:

    "norm:fruit-color": [
      [
        [
          "#<Asciidoctor::ListItem@73700 {list_context: :dlist, text: \"Bananas\", blocks: 0}>"
        ],
        "#<Asciidoctor::ListItem@73720 {list_context: :dlist, text: \"Generally yellow in color\", blocks: 0}>"
      ],
      [
        [
          "#<Asciidoctor::ListItem@73740 {list_context: :dlist, text: \"Apples\", blocks: 0}>"
        ],
        "#<Asciidoctor::ListItem@73760 {list_context: :dlist, text: \"Generally red in color\", blocks: 0}>"
      ]
    ],
    "norm:Zca_misa_c": "MISA.C is set if the following extensions are selected:",
    "norm:Zca_misa_c_list": [
      "#<Asciidoctor::ListItem@73780 {list_context: :ulist, text: \"Zca and not F\", blocks: 0}>",
      "#<Asciidoctor::ListItem@73800 {list_context: :ulist, text: \"Zca, Zcf and F (but not D) is specified (RV32 only)\", blocks: 0}>",
      "#<Asciidoctor::ListItem@73820 {list_context: :ulist, text: \"Zca, Zcf and Zcd if D is specified (RV32 only)\", blocks: 1}>",
      "#<Asciidoctor::ListItem@73840 {list_context: :ulist, text: \"Zca, Zcd if D is specified (RV64 only)\", blocks: 1}>"
    ],

This isn't usable in this form and is also missing the text in the nested unordered list (lines starting with **).

@Timmmm, can you enhance the tags backend to instead provide adoc-formatted text instead of an array of objects? So, instead have the tags look like:

    "norm:fruit-color": "Bananas::\nGenerally yellow in color\nApples::\nGenerally red in color",
    "norm:Zca_misa_c": "MISA.C is set if the following extensions are selected:",
    "norm:Zca_misa_c_list": "* Zca and not F\n* Zca, Zcf and F (but not D) is specified (RV32 only)\n* Zca, Zcf and Zcd if D is specified (RV32 only)\n** this configuration excludes Zcmp, Zcmt\nZca, Zcd if D is specified (RV64 only)\n** this configuration excludes Zcmp, Zcmt"

OR at the very least (but not particularly desirable) to create an error message an cause asciidoctor to exit with a non-zero status if it detects these cases?

[Timmmm]

Yeah it shouldn't do that! One of the huge downsides of Ruby's lack of static type checking (at least as far as I could see there isn't really a usable system). I will add a runtime check that it is a string at least.

It's definitely not obvious from inspection why this is happening. The code that gets these is:

  # `node` is an `AbstractNode`.
  def convert(node, transform = node.node_name, opts = nil)
...
      # Recursively get the text content of this node.
      content = if node.inline? then node.text else node.content end
...
          @tag_map[node.id] = content

Surely node.text is a string, and node.content is supposed to recurse, presumably until it gets to inline nodes. Might have to ask some Asciidoctor people.

[Timmmm]

Ok according to ChatGPT .content is only recursive for certain types of node... and we need to explicitly handle :dlist nodes and possibly others cough static types.

This contradicts the documentation and example here, but given that it's not working I'm guessing the documentation is just wrong.

Ah actually I found the sneaky caveat:

The converter is not called to handle nodes with the :list_item or :table_cell contexts. Instead, it’s up to the converter to access these nodes from the parent node and convert them directly.

Great. Except there is no :list_item or :table_cell :-/ Guess I will have to read the Asciidoctor source code...

[james-ball-qualcomm]

In Ruby, just do this:
raise "nice error message" unless content.is_a?(String)

[james-ball-qualcomm]

We've now got normative text that needs to be tagged in a list item that we can't tag so this is a problem.

Here's the adoc from the Zc chapter:

MISA.C is set if the following extensions are selected:

* Zca and not F
* Zca, Zcf and F (but not D) is specified (RV32 only)
* Zca, Zcf and Zcd if D is specified (RV32 only)
** this configuration excludes Zcmp, Zcmt
* Zca, Zcd if D is specified (RV64 only)
** this configuration excludes Zcmp, Zcmt

[Timmmm]

This might fix it (not tested yet): main...Timmmm:docs-resources:user/timh/fix_tables_and_lists

I also think tables are handled weirdly so if you tag an entire table it also might do weird stuff. Haven't managed to figure out how they work yet though.

[james-ball-qualcomm]

Thanks Tim. Maybe you could use or enhance the test in docs-resources I'm working on getting merged in that PR you reviewed? +james+

…

________________________________ From: Tim Hutt ***@***.***> Sent: Wednesday, September 17, 2025 6:42:39 AM To: riscv/docs-resources ***@***.***> Cc: James Ball (QUIC) ***@***.***>; Author ***@***.***> Subject: Re: [riscv/docs-resources] Tag backend produces unusable JSON tag file for unordered lists or description lists (Issue #72) 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#72)<#72 (comment)> This might fix it (not tested yet): main...Timmmm:docs-resources:user/timh/fix_tables_and_lists<main...Timmmm:docs-resources:user/timh/fix_tables_and_lists> I also think tables are handled weirdly so if you tag an entire table it also might do weird stuff. Haven't managed to figure out how they work yet though. — Reply to this email directly, view it on GitHub<#72 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BBRBTGD26WMAAKAQWHG64DL3TFQM7AVCNFSM6AAAAACGIOPSS2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTGMBTGA3TGNZTHE>. You are receiving this because you authored the thread.Message ID: ***@***.***>