quarto-dev / quarto-cli

Open-source scientific and technical publishing system built on Pandoc.
https://quarto.org
Other
3.64k stars 298 forks source link

Conflict between code annotation and reference-able code listing #9703

Open MKDJr opened 2 months ago

MKDJr commented 2 months ago

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

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 commented 2 months ago

(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 commented 2 months ago

@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 https://github.com/quarto-dev/quarto-cli/blob/283ed3ba786e99f7892342972a3bcc1a9bf3c527/src/resources/filters/quarto-pre/code-annotation.lua#L467-L470

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 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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

(I think they all have the label)

cscheid commented 2 months ago

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 :::



<img width="906" alt="image" src="https://github.com/quarto-dev/quarto-cli/assets/285675/4506375b-9a15-415b-9f69-b37be1b00018">
cscheid commented 2 months ago

With the fix incoming in https://github.com/quarto-dev/quarto-cli/pull/9725/, the workaround above will suffice.