[book-dp1] Chapter 3 HTML/PDF comparison issues

[Chihiro2000GitHub]

Hi @mmcky @jstac

What follows are the differences I found between the PDF and HTML versions for Chapter 3.

For this chapter, I found relatively fewer issues to be resolved.
This might be because some of the issues we addressed in earlier chapters were not chapter-specific, so potential issues in Chapter 3 may have already been resolved as well.

I'd be grateful if you could review the following when you have a moment!

1. Listing numbering and caption-label mismatch

PDF: The listings in Chapter 3 are numbered from Listing 3.1 to Listing 3.5.
HTML: The corresponding listings are numbered as Listing 1 through Listing 5, so the chapter-based numbering appears to be missing.
Issue: The HTML numbering does not match the PDF numbering format. In addition, the HTML captions use Program rather than Listing, whereas the PDF uses Listing. This is connected to the issue noted in item 5 of the Chapter 1 issue: #26 (comment)

2. PDF-specific page references remain in the HTML

PDF: In the proof of Lemma 3.2.1, the text reads Applying the Neumann series lemma (p. 18) ....

HTML: The corresponding text reads Applying the Neumann series lemma (p. ) ....

Issue: My understanding is that page references such as (p. 18) are PDF-specific and should generally be removed entirely in the HTML version. In this case, the page reference still appears in the HTML, although the page number itself has been removed.

I searched for similar cases across the Volume I chapters I am responsible for, and found the following additional instances:

• Chapter 7, immediately after equation (7.2):
  we can use Du’s theorem to establish the next result (which generalizes Lemma 6.1.4 on page ).

• Chapter 9, proof of Proposition 9.2.3:
  By the Knaster–Tarski theorem (p. ), ...

These appear to be the same type of issue and should probably be removed as well.

Additional note

I also noticed that the font used for D(X) differs between the PDF and HTML versions. However, my understanding is that this kind of PDF/HTML font difference has been treated as an accepted limitation, as discussed here:
#24 (comment)

So I am not treating this as something that needs to be changed.

[jstac]

Thanks @Chihiro2000GitHub , super helpful!

@mmcky , I didn't even think of the \pageref entries. I can see that's a problem.

I could probably get rid of most of them --- it's a habit from the days when I expected people to be reading hardcopy...

What do you think?

[mmcky]

Thanks @Chihiro2000GitHub — really useful as always, and good catch on the page references. Status on both items, plus a reply to @jstac's question.

1. Listing numbering (Program N → Listing 3.x). You're right that the live site still shows the old behaviour — I checked it just now: the captions read Program 1…Program 5 and the in-text cross-references read Listing 1…Listing 5 with no chapter prefix. The fix is already staged: myst.yml now numbers code listings chapter-scoped and labels them Listing, and on the newer theme build it renders exactly as the PDF does (Listing 3.1–3.5, zero Program). It can't go live yet because our deploy is pinned to an older theme tag that doesn't honour code-listing numbering; the bump to the newer tag is waiting on an upstream theme fix for ordered lists (QuantEcon/mystmd#51). So this one is ready and ships with that bump — no further source change needed. It's the same item as Chapter 1 #5.

2. Page references (p. ). Confirmed — and there's a fourth instance beyond the three you listed: Chapter 4 (in the remark after the optimal-stopping exercises) has the same problem, rendering Figure 4.x on provides…. The pipeline already strips the standard page~\pageref{…} form everywhere, so ~154 of the 158 page references render cleanly; these four just use off-spec spellings — an abbreviated p., a stray double space, and one missing the word "page" — that slip past the stripper and leave the wrapper text behind. Two are genuine typos worth fixing in the source (they're slightly off in the PDF too), and the other two are the intentional (p. 18) abbreviation, which we'll keep in the PDF and strip from the HTML in the converter. The four spots and the exact TeX + config fixes are written up in our tracker: QuantEcon/book-dp1#357.

@jstac — on whether to get rid of the page references: you don't need to for the web. The conversion already strips every standard page~\pageref{…}, and most are redundant online anyway because the neighbouring \ref{} is already a clickable link (e.g. "Proposition 9.2.3 on page X" — the proposition number is the link, so "on page X" adds nothing). So feel free to thin them out in the PDF if you prefer the cleaner look, but there's no urgency and the HTML doesn't depend on it. For any you keep, just use the standard page~\pageref{…} form and the web build strips them automatically.

Font (D(X)). Agreed, and thanks for checking against #24 — accepted PDF/HTML limitation, nothing to change.

[mmcky]

Item 2 (\pageref remnants) is now fixed and live across the affected chapters on https://quantecon.github.io/book-dp1.

The off-spec \pageref spellings that leaked "(p. )" / "on " into the HTML are resolved two ways: a config strip rule now handles the abbreviated p.~\pageref form (Ch3 here, plus Ch9), and two source typos were normalized to the canonical on page~\pageref (Ch4 and Ch7) so they strip cleanly. I've verified on the live site that the stranded fragments are gone.

Item 1 (Listing/Program captions) is unchanged — that's the theme-renderer upgrade still tracked in book-dp1#355. Thanks again for catching these.

[Chihiro2000GitHub]

Thanks @mmcky for the update! (cc: @jstac)

I understand that the Listing/Program caption issue is still tracked separetely.

For the \pageref issue, I checked the three places I listed earlier on the live site, and they looked fixed to me.

I also wanted to check one point about the fourth instance you mentioned. Is this the reference in Remark 4.1.1, as shown below? In the HTML, it now reads simply Figure 3.5 provides ..., so the page-reference fragment seems to be removed there as well.

Remark 4.1.1 in the HTML:

One important note:
When checking this Remark 4.1.1 against the PDF, I noticed what may be a small typo in the PDF version. The PDF text reads:

Figure 3.5 on 100 provides ...

Should this be Figure 3.5 on p. 100 provides ..., as in the other page references?

@jstac, I am mentioning you as well since this may concern the PDF text.

Thanks!

[jstac]

Thanks @Chihiro2000GitHub , nice catch! I've fixed the missing "page" in the tex file and pushed the update to main 👍