Comment spans render as body text in every format but docx

Đang mở
  • Có gì không ổn?
#15,335 4 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
48/100
Loại issue
Lỗi
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
html, javascript
Lĩnh vực
backend, documentation

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.

Ngôn ngữ chính
JavaScript
Star
6.2k
Fork
482
Merge trung bình
17 giờ 46 phút
Pull request đã merge (30 ngày)
135

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của quarto-dev/quarto-cli

Tất cả issue của quarto-dev/quarto-cli

Issue tương tự

Thêm issue về JavaScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.