Epic: Crossref Overhaul

[allenmanning]

ASAP

• [ ] https://github.com/quarto-dev/quarto-cli/issues/8848
• [ ] Customizable categories for Float and Block crossreferences
  • [x] #1655
  • [x] #3323
  • [ ] #3979
• Add crossreferences to
  • [x] floats (Tables, Figures, Listings, etc)
  • [ ] blocks
  • [x] Callouts
  • [ ] Theorem environments
  • [x] Proof environments
• [ ] Allow fine-grained control over crossref label formatting
  • [ ] #1095
  • [ ] #1196
  • [ ] #1771
  • [x] #2356
  • [ ] #2439
  • [x] #3440
  • [ ] #4364
  • [ ] #4532
  • [x] #5481
  • [ ] #5621
  • [ ] #5652
  • [ ] Improve treatment of compound crossreferences

  • 1706

  • 1707

• [ ] Glossary support
  • [ ] #1697
• [ ] Page number format control for page regions where collations (list of *) are put

  • 1889

• [ ] Crossref collations (list of figures, tables, equations, etc) in non-PDF formats

  • 2138

• [ ] Equation numbering, multiple refs in a single block, tags

  • 2275

  • 4136

• [ ] Short caption support for all Float crossrefs

  • 3498

  • [ ] #4776
• [ ] Niceties
  • [ ] #4938
• [ ] Crossref, TOC, knit_child interactions

  • 3178

• [ ] Book parts should be referenceable

  • 2571

  • 3234

• Add crossreferences to
  • [ ] inlines (Equations, arbitrary spans, anchors from headings, etc)

Later

• [ ] #4517

• [ ] fig-* support: layout interaction, non-crossreferenced images

  • 2251

  • 3370

• [ ] #8772

  Uncategorized

• [ ] -cap-location control for all Float crossreferences as well as subfloats and non-crossreferenceable figures (such as Pandoc.Figure)

  • [x] #1829
  • [ ] #1990
  • [x] #2154
  • [x] #2196
  • [x] #2221
  • [x] #3931
  • [ ] #7456
  • [x] #7455
  • [ ] #8938

• [ ] Allow computational cell code to be decorated (with filename, etc)

  • 2683

• [ ] Crossref filter and citeproc interaction

  • 1186

• [ ] https://github.com/quarto-dev/quarto-cli/discussions/2443

• [ ] https://github.com/quarto-dev/quarto-cli/discussions/4045

Outstanding Tasks

• [ ] Are we testing Epub crossrefs right now?
  • [ ] run output through epubcheck
• [ ] Check the crossref label
• [ ] Check the issues that refer to this
• [ ] Consistency of CSS class names: "fig" vs "figure", etc.

Wontfix

• We don't know enough DocX to make it work in all our usecases (subfloats, custom crossrefs, etc):
  • [ ] https://github.com/quarto-dev/quarto-cli/discussions/2464
  • [ ] https://github.com/quarto-dev/quarto-cli/discussions/2335
• [x] #1229

Needs project overhaul (so will be worked on after that epic)

• [ ] https://github.com/quarto-dev/quarto-cli/discussions/2900
• [ ] https://github.com/quarto-dev/quarto-cli/discussions/431

[cscheid]

I'm starting to check off issues that are resolved on the branch feature/float-crossref. For quarto users reading this, please don't take the checked-off boxes in here to mean that this work is ready to use. (feature/float-crossref is specifically not in a usable state right now.)

[mcanouil]

(edited by cscheid to move issue to main comment)

[mcanouil]

(edited by cscheid to move issue to main comment)

[bryanhanson]

I don't see it explicitly here, so for completeness make videos cross-referable, discussed here.

From my perspective, the format that would be consistent would be @vid-my-video or something similar.

[cscheid]

@bryanhanson You will implement the category yourself. It's under "Customizable categories for Float and Block crossreferences"

[bryanhanson]

@cscheid sorry I don't understand. Do you want me to add it there? I can't edit that task list. Or are you saying when completed I'll be able to define the particular type of cross-ref myself? Or something else?

[mcanouil]

@bryanhanson to rephrase:

• @cscheid is working on redesigning the whole cross-reference feature to work on possibly everything by allowing the user to define its own "structure".
• @cscheid only showed what's the future of Quarto holds, you can't use that example yourself now (it's going to be documented in the documentation when ready).
• this issue is to track that work. @cscheid mentioned it because if you want to know when the above feature will be usable in 1.4 pre-release, then you can "watch" this issue, i.e., closing this issue (or part of it) will tell you it's in the pre-release.
• currently what you want to do is not possible and the only thing you can do is to wait until the work is "ready".

[mcanouil]

(edited by cscheid to move issue to main comment)

[cscheid]

@bryanhanson As of the latest commit on main, what you're suggesting is possible. We still have to write (a lot of) documentation for the features, but see https://github.com/quarto-dev/quarto-cli/blob/main/tests/docs/crossrefs/v1.4/custom-categories/diagrams.qmd for a minimal example.

[cscheid]

Done in v1.4

• [x] ensure format options work across formats (or document where they can't)

  • 215

• [x] control numbering and formatting of anchor crossrefs

  • 644

  • 1145

  • 5614

• [x] Caption format control for float crossrefs

  • 645

• [x] Bookdown text references: in-body captions that can be "included" via references

  • 1959

• [x] Crossreferenceable callouts

  • 2241

  • 4863

• [x] Float crossrefs, subfloats, captions and lack thereof

  • 2492

  • 2551

  • 3603

  • 3711

• [x] Crossrefs in the content of computational outputs like tables

  • 3340

• [x] Be careful about redefining block crossref environments in Beamer and amsmath generally

  • 3650

• [x] Be careful about introducing nested LaTeX floats

  • 3736

• [x] allow arbitrary content as the payload of float crossrefs (e.g. if a third-party library tells us that something is a table, we go along with it) Allow listing captions/labels on executable code blocks and computational tables
  • [x] #1084
  • [x] #1556
  • [x] #1580
  • [x] #2297
  • [x] #3397
  • [x] #3600
  • [x] #3601
  • [x] #3770
  • [x] #4168
  • [x] #4171
  • [x] #4637
  • [x] #5101
  • [x] #5161
  • [x] #5383
• [x] https://github.com/quarto-dev/quarto-cli/discussions/1494
• [x] https://github.com/quarto-dev/quarto-cli/discussions/3181
• [x] https://github.com/quarto-dev/quarto-cli/discussions/3914
• [x] https://github.com/quarto-dev/quarto-cli/discussions/4343

[bcdavasconcelos]

Not sure whether/where to post this: The Typst output doesn't have any defined Amsthm cross-reference environments in version 1.4.537. (This causes rendering to fail). Hope this helps.

[mcanouil]

It does not really without a reproducible example.

Could you open a new issue with a reproducible example? Could you share a small self-contained "working" (reproducible) example to work with, i.e., a complete Quarto document or a Git repository? Thanks.

You can share a Quarto document using the following syntax, i.e., using more backticks than you have in your document (usually four ````).

````qmd
---
title: "Reproducible Quarto Document"
format: html
engine: knitr
---

This is a reproducible Quarto document using `format: html`.
It is written in Markdown and contains embedded R code.
When you run the code, it will produce a plot.

```{r}
plot(cars)

The end.

[bcdavasconcelos]

My pleasure, @mcanouil. See https://github.com/quarto-dev/quarto-cli/issues/8167.

[cscheid]

See https://github.com/quarto-dev/quarto-cli/discussions/10020

[acxz]

@cscheid I noticed from the OP that certain docx cross reference features are slated as won't fix.

Would it be possible to revisit this? Specifically creating lof and lot in docx similar to toc? (I realize this may need to be a pandoc issue instead see: https://github.com/jgm/pandoc/issues/8245) See: https://github.com/quarto-dev/quarto-cli/discussions/2464 for more conversation regarding this. Let me know if I should create a specific issue to track this or if the discussion is enough, considering it is already being tracked in the OP.

[cscheid]

Would it be possible to revisit this?

Not at the near future, sorry.