Conflict between code annotation and reference-able code listing

[mkdjr]

Bug description

Hi there! When adding a listing label and caption to an HTML code block that I have already annotated using code annotation, the code annotation functionality disappears (note: the numbered list of annotations are still present, but their formatting and corresponding icons in the code block are not). The listing functionality is, however, present. It seems as though they are mutually exclusive.

Steps to reproduce

```{.python filename="run_experiments.py" #lst-corpus-gen lst-cap="Corpus Loading/Generation Logic"}
line 1 # <1>
line 2 # <2>
```
1. annotation 1
2. annotation 2

Expected behavior

I am able to cross-reference a labelled HTML code block while still using code annotations.

Actual behavior

Either code annotation or code block labeling/captioning are functional independently. When combined, code annotation does not work as expected.

Your environment

• IDE: VSCode 1.89.1
• OS: Windows 19045.4291, using WSL 2

Quarto check output

[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.11: OK
      Dart Sass version 1.69.5: OK
      Deno version 1.37.2: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.4.550
      Path: /opt/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: (not installed)
      Chromium: (not installed)

[✓] Checking LaTeX....................OK
      Tex:  (not detected)

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.11.9
      Path: /home/mkdjr/.pyenv/versions/pytorch-env/bin/python3
      Jupyter: 5.7.2
      Kernels: python3, crs-data-kernel, global-kernel, pytorch-env-kernel

[✓] Checking Jupyter engine render....OK

[✓] Checking R installation...........(None)

      Unable to locate an installed version of R.
      Install R from https://cloud.r-project.org/

[cscheid]

(I went ahead and edited your post. For future reference, you can get code cells to display properly by using more backticks than whatever's inside them.)

[cderv]

@cscheid I think this happens because our process of code annotation expect the OrderedList to be the Block right after CodeBlock

and our normalize-combine-2 step is parsing FloatRefTarget which code listing is among, and it split the orderedList from the CodeBlock

Our trace shows this results after the step

blocks:
  - customAST: true
    type: "Listing"
    classes:
      - "python"
    t: "FloatRefTarget"
    attributes: []
    identifier: "lst-corpus-gen"
    scaffold:
      - t: "Div"
        attr: "('', [], ['__quarto_custom_scaffold,true'])"
        content:
          - t: "CodeBlock"
            attr: "('', [], [])"
            text: "line 1 # <1>\nline 2 # <2>"
      - t: "Div"
        attr: "('', [], ['__quarto_custom_scaffold,true'])"
        content:
          - t: "Plain"
            content: "Corpus Loading/Generation Logic"
  - t: "OrderedList"
    listAttributes:
      start: 1
      style: "Decimal"
      delimiter: "Period"
    content:
      - t: "Plain"
        content: "annotation 1"
      - t: "Plain"
        content: "annotation 2"

from this content before the parsing

blocks:
  - t: "CodeBlock"
    attr: "('lst-corpus-gen', ['python'], ['lst-cap,Corpus Loading/Generation Logic'])"
    text: "line 1 # <1>\nline 2 # <2>"
  - t: "OrderedList"
    listAttributes:
      start: 1
      style: "Decimal"
      delimiter: "Period"
    content:
      - t: "Plain"
        content: "annotation 1"
      - t: "Plain"
        content: "annotation 2"

Our code annotation processing does not account for Code Listing like this for now

quarto-cli/src/resources/filters/quarto-pre/code-annotation.lua

Lines 467 to 470 in 283ed3b

	-- There are pending annotations, which means this OL is immediately after
	-- a code cell with annotations. Use to emit a DL describing the code
	local items = pandoc.List()
	for i, v in ipairs(block.content) do

So this is a matter of teaching Code Annotation about FloatRefTarget lst- or keeping an OrderedList after a codeCell as part of the FloatRefTarget.

Maybe we need a AnnotatedCodeBlock like we have a DecoratedCodeBlock ?

Hope it helps

[cscheid]

The DecoratedCodeBlock node should be aware of annotations: annotations should be another form of decoration.

It's a tricky one to handle because of filter ordering. I've tried to fix this bug in the past but failed. I think there's a duplicate in our repo somewhere.

[cderv]

The DecoratedCodeBlock node should be aware of annotations: annotations should be another form of decoration.

Oh ok. Cool! I thought DecoratedCodeBlock was more targeting codeblocks with specific attributes tieds to feature. But ideally I agree is could be part of it. We need to handle specifities in DecoratedCodeBlock if we do so. Another type would make it very different.

It is indeed not easy here. I tried to find the other one but failed to find it. @mcanouil maybe you know ? 😉

[mcanouil]

Well, the real issue is that code-annotation is accumulating conflicts with other features:

• code-annotation

(I think they all have the label)

[cscheid]

This almost works:

::: {#lst-corpus-gen}

```{.python filename="run_experiments.py"}
line 1 # <1>
line 2 # <2>
```
1. annotation 1
2. annotation 2

Corpus Loading/Generation Logic
:::

[cscheid]

With the fix incoming in #9725, the workaround above will suffice.