Cross-references on unnumbered pages fail (PDF) or are mislabeled (HTML)

[matthew-brett]

Bug description

I have a book with a couple of prefaces : https://resampling-stats.github.io/resampling-with/python-book . I want the chapter numbers to start at the first chapter, so the preface pages are .unnumbered.

I want one preface to crossreference the other, but the links are mislabeled in HTML, and fail to resolve in PDF. Is there a way of doing these crossreferences?

See below for a minimal reproducer.

Steps to reproduce

git clone https://github.com/matthew-brett/test-quarto
cd test-quarto
quarto render .  --to html

In the HTML rendering you will see that the crossreferences to the unnumbered prefaces resolve correctly to the page, but get labeled with "Chapter 1" and "Chapter 2", although the contents give no number to the prefaces, and label the first (subsequent) chapter with 2.

For PDF rendering:

quarto render . --to pdf

I get:

WARNING (/Users/mb312/dev_trees/quarto-cli/src/resources/filters/./crossref/refs.lua:110) Unable to resolve crossref @sec-pre1
WARNING (/Users/mb312/dev_trees/quarto-cli/src/resources/filters/./crossref/refs.lua:110) Unable to resolve crossref @sec-pre2
WARNING (/Users/mb312/dev_trees/quarto-cli/src/resources/filters/./crossref/refs.lua:110) Unable to resolve crossref @sec-pre2
WARNING (/Users/mb312/dev_trees/quarto-cli/src/resources/filters/./crossref/refs.lua:110) Unable to resolve crossref @sec-pre1
WARNING (/Users/mb312/dev_trees/quarto-cli/src/resources/filters/./crossref/refs.lua:110) Unable to resolve crossref @sec-pre1

and indeed, the references to the preface unnumbered sections appear as e.g. ?@sec-pre1. etc.

Expected behavior

The cross-references should resolve to the correct location rather than failing, in the PDF build.

In both cases, the cross-reference label could be the unnumbered document title plus numbering or even section title, as in (in my reproducer) Preface 2; section 1 or even Preface 2; Preface 2 subsection.

Actual behavior

See above. Cross-reference to unnumbered sections fails with warning in PDF build. In HTML build, cross-references point to the correct document and location, but as mislabeled with e.g. "Chapter 1" or "Chapter 2" when the contents give other documents as being chapter 1 and chapter 2.

Your environment

Macos Ventura 12.4 Latest quarto-cli commit 1f3581304

Quarto check output

$ quarto check 

[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.2: OK
      Dart Sass version 1.55.0: OK
      Deno version 1.33.2: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 99.9.9
      Path: /Users/mb312/dev_trees/quarto-cli/package/dist/bin

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

[✓] Checking Python 3 installation....OK
      Version: 3.10.11
      Path: /Users/mb312/.virtualenvs/resampling-with/bin/python3
      Jupyter: 5.3.0
      Kernels: python3, ir

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

[✓] Checking R installation...........OK
      Version: 4.3.0
      Path: /opt/homebrew/Cellar/r/4.3.0_1/lib/R
      LibPaths:
        - /Users/mb312/Library/R/arm64/4.3/library
        - /opt/homebrew/lib/R/4.3/site-library
        - /opt/homebrew/Cellar/r/4.3.0_1/lib/R/library
      knitr: 1.42
      rmarkdown: 2.21

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

[cscheid]

I have a book with a couple of prefaces

Our crossref system is limited by what's available across formats, and specifically by the LaTeX support. Do multiple crossreferenceable prefaces work in plain LaTeX?

[matthew-brett]

I'm afraid I don't know LaTeX well enough to know whether you can do cross-links between unnumbered docs. I guess the remaining questions are what to do with the formats that do support that - such as HTML? At the moment, Quarto gives mislabeled links, which are actively confusing. Do you think it would be better to fix those links, or raise an error for cross-links to unnumbered documents, if it turns out that one of the formats (LaTeX) can't support it?

[cscheid]

References to unnumbered sections are currently badly supported in general, and yes, we definitely need to fix that. I was asking about LaTeX because that will inform what the fix ultimately should be.

[matthew-brett]

Well - but I guess you do have some features that are partially supported across backends - where you just degrade gracefully for the unsupported features? Or raise an error for building to that backend?

[stefanv]

Here's an example of how this could be handled in LaTeX:

\documentclass{article}
\usepackage{hyperref}

\title{My Document}
\author{Me}

\begin{document}

\section*{Preface}

\subsection*{Purpose}
\label{sec:purpose}
This document provides an overview of the purpose of the project.

\section{Introduction}
In this chapter, we will continue our discussion started in the
preface (see \nameref{sec:purpose}), with the aim ...
\end{document}

This gives valid links to the subsection, although exactly how the subsection name is displayed should probably be tweaked.

[cscheid]

I'll take a look at this in #4944

[tobydriscoll]

I'm having a similar problem (HTML only) with cross-referenced environments. In an unnumbered chapter, the cross-reference link text has the "Example #exm-tag" text rather than the correct "Example #.#".

git clone https://github.com/tobydriscoll/foo
cd foo
quarto render .  --to html

Numbered chapter:

Unnumbered chapter:

[cscheid]

@tobydriscoll, as you can see, the issue is still open is marked for v1.5.