Comment spans render as body text in every format but docx

Abierto
  • ¿Algo no está bien?
#15,335 4 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
48/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
html, javascript
Área
backend, documentation

Línea de trabajo

The report identifies Pandoc’s writers as the source of inlining and duplicate identifiers, and points to Quarto’s HTML theming, Typst template, and filters for possible handling. First compare the plain Pandoc output with Quarto rendering, then trace the relevant Quarto filters and templates. Done means comment text is not emitted as prose in non-docx output, with annotations or safe omission handled for the affected formats.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

bug pandoc upstream
What happens

Pandoc represents a Word comment as a pair of spans: .comment-start,
whose content is the note, and .comment-end, with a shared id. This
is pandoc's own vocabulary rather than something a user invented — its
docx reader produces exactly this from a commented .docx
(--track-changes=all), and its docx writer consumes it, so comments
round-trip through markdown.

Rendering the same document to any other format puts the note into the
document as ordinary prose.

Reproduction

comment.qmd:

---
title: "Comment probe"
---

The exposure window was [CONFIRM: that this is the window the
pharmacology supports.]{.comment-start id="0" author="Reviewer"}days 1
to 14[]{.comment-end id="0"}.

quarto render comment.qmd --to docx
quarto render comment.qmd --to html
quarto render comment.qmd --to typst
  • docx — correct. A real Word comment from "Reviewer", anchored to
    "days 1 to 14". Confirmed by reading word/comments.xml and
    independently in LibreOffice, which shows three of three as ranged
    annotations in a longer document.
  • html — the note is visible body text:
    <span id="0" class="comment-start" data-author="Reviewer">CONFIRM: …</span>days 1 to 14<span id="0" class="comment-end"></span>
  • typst — the class is gone and the note is body text:
    The exposure window was CONFIRM: …<0>days 1 to 14<0>.
  • pdf, through typst — pdftotext finds the note set in the middle
    of the sentence, which is what a reader sees.
Why this is worth changing

The failure is silent. A plan rendered for Word carries reviewer notes
in the margin, and the same source rendered to HTML or PDF asserts them
as things the document says. "CONFIRM: that this is the window the
pharmacology supports" reads, in the PDF, as part of the methods.

For a regulatory document that is the difference between a note to a
reviewer and a statement to an agency, so the current behaviour is one
a user cannot safely leave to chance: it has to be worked around by not
emitting comments for those formats at all, which is what we now do.

What would be better, cheapest first

  1. Do not inline the note. In a format with nowhere to put an
    annotation, dropping the .comment-start span's content and keeping
    the text it was attached to is strictly better than printing it. A
    dropped note is a known limitation; a printed one is a defect in the
    document.

  2. Render a real annotation where the format has one. HTML needs no
    pandoc change at all: the class and data-author/data-date already
    reach the output, so Quarto could present it as a margin note or an
    aside, in the same places .column-margin content goes, or at least
    style it as an annotation rather than prose. Typst has no comment, but
    a margin note is idiomatic there too.

  3. The shared id becomes a duplicate identifier. Both spans of a
    pair must carry the same id for the docx writer, and pandoc treats
    an id attribute as the element's identifier. So HTML gets two
    elements with id="0", which is invalid, and typst gets the label
    <0> twice, which makes a label ambiguous. This is worth fixing even
    if the annotation feature is not taken up.

Which part is pandoc's

Running plain pandoc -f markdown -t html and -t typst on the same
input gives the same output, so the inlining and the duplicate
identifier come from pandoc's writers rather than from Quarto's
filters. Items 1 and 3 may well belong upstream.

Item 2 is Quarto's either way, since the HTML theming and the typst
template are Quarto's — and a Quarto filter could cover all three for
Quarto's formats without waiting on pandoc, which is why this is filed
here.

Versions

Quarto 1.9.37, bundled pandoc 3.8.3, Windows 11. Also reproduced with
standalone pandoc 3.9.

Lenguaje dominante
JavaScript
Estrellas
6.2k
Forks
482
Merge medio
17 h 46 min
PR fusionados (30 d)
135

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de quarto-dev/quarto-cli

Todos los issues de quarto-dev/quarto-cli

Issues similares

Más issues de JavaScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.