[book-dp1] Chapter 1 discrepancies between HTML and PDF

[Chihiro2000GitHub]

Hi @mmcky @jstac

I found a number of places in Chapter 1 that may need attention, so this issue has become quite long.

I would appreciate it if you could take a look when you have time.

Summary

While comparing Chapter 1 of the MyST/HTML version against the PDF, I noticed the following discrepancies and possible rendering issues.

1. Algorithm blocks are not rendered like the PDF

• PDF: The first two algorithm-style displays in Chapter 1 are not given algorithm numbers. Later, the “Value function iteration for job search” algorithm is numbered as “Algorithm 1.1”.
• HTML: The first two algorithm-style displays are numbered as “Algorithm 1.1” and “Algorithm 1.2”. As a result, the “Value function iteration for job search” algorithm is numbered as “Algorithm 1.3” instead of “Algorithm 1.1”.
• Issue: The algorithm numbering differs from the PDF, and this affects numbering parity.

Additional formatting differences:

• the PDF uses numbered algorithm lines, while the HTML uses bullet points;
• in the HTML, do is missing from some loop statements such as while ... do and for ... do;
• the HTML is missing the corresponding end lines;
• in the first algorithm-style block, the phrase “depends on the current state and action” is rendered as a separate bullet point, although it belongs to the preceding reward step.

2. Distribution symbol differs from the PDF throughout Chapter 1

• PDF: As shown above, the wage distribution symbol is rendered as \varphi in multiple places throughout Chapter 1.
• HTML: The corresponding symbol is rendered as \phi in multiple places.
• Issue: The HTML is internally consistent, but the symbol differs from the PDF across Chapter 1.

3. Figure 1.3 line color differs from the PDF

• PDF: In Figure 1.3, the line for w_1 + \beta w_1 is shown in a lighter blue. This makes the black dashed value-function line easier to distinguish where the two lines overlap after the kink.
• HTML: The corresponding line is rendered in a darker blue. As a result, the black dashed line becomes slightly less visible where it overlaps with the blue line.
• Issue: This is a minor visual difference, but it affects the readability of the figure relative to the PDF.

4. Possible issue with the value-function symbol throughout Chapter 1

• PDF: In the main text, the value-function symbol generally appears to be v. However, in Figure 1.3, the legend also looks closer to \upsilon_1 than to v_1.
• HTML: Throughout Chapter 1, the value-function symbols often look closer to \upsilon than to v, including in the main text, equations, and captions.
• Issue: This may simply be a font/rendering difference, but I wanted to flag it because the intended notation v is not always displayed clearly.

Minor note: In Figure 1.3, the value-function symbol appears similar in both the PDF and HTML versions, and in both cases it looks closer to \upsilon_1 than to v_1.

5. Listing references and captions differ from the PDF

• PDF: In Section 1.1.1.3, the text refers to “Listing 1.1” (“Parameters and functions underlying the figure are shown in Listing 1.1.”). The corresponding code block is also captioned as “Listing 1.1”.
• HTML: The corresponding text refers to “Listing 1” instead of “Listing 1.1”. The code block is captioned as “Program 1” rather than “Listing 1.1”.
• Issue: The numbering and object type differ from the PDF. This creates a mismatch between the PDF and HTML in both the cross-reference text and the code-block caption.

The same issue appears to occur for all listings in Chapter 1. In the PDF, they are numbered as “Listing 1.1” through “Listing 1.6”, while in the HTML the corresponding text references appear as “Listing 1” through “Listing 6” and the code-block captions appear as “Program 1” through “Program 6”.

6. Exercise numbering differs from the PDF throughout Chapter 1

• PDF: Exercises in Chapter 1 use a three-part numbering scheme, such as “Exercise 1.1.1”.
• HTML: The corresponding exercises use a shorter numbering scheme, such as “Exercise 1.1”.
• Issue: Exercise numbering differs systematically from the PDF throughout Chapter 1. This affects numbering parity and may also cause confusion when comparing the PDF and HTML versions.

7. Figure references are rendered as “Figure Figure ...”

• PDF: In-text references to figures are rendered normally, such as “Figure 1.1” and “Figure 1.2”.
• HTML: In Chapter 1, the in-text figure references appear to be rendered as “Figure Figure 1.1” and “Figure Figure 1.2”.
• Issue: The word “Figure” appears twice because the surrounding text already includes “Figure” and the cross-reference itself also renders with “Figure”. This seems to occur throughout Chapter 1 wherever figures are referenced in the main text.

8. Equation numbering no longer matches the PDF after equation (1.4)

• PDF: Equation numbering matches the HTML up to equation (1.4). After that, many displayed equations are left unnumbered in the PDF. The final numbered equation in Chapter 1 is (1.34).
• HTML: Equation numbering also matches the PDF up to equation (1.4), but from equation (1.5) onward, many displays that are unnumbered in the PDF receive equation numbers in the HTML. As a result, the final equation number in Chapter 1 is (1.61).
• Issue: Equation numbering diverges substantially between the PDF and HTML after equation (1.4). This affects numbering parity and may also break or confuse cross-references to equations in Chapter 1.

9. Notation for distribution sets differs from the PDF in multiple places

• PDF: In Assumption 1.1.1 and Section 1.2.4.3, the distribution-set notation appears as D(W) and D(X). In Assumption 1.1.1, the iid notation also appears in small caps, and the wage distribution symbol is rendered as \varphi.
• HTML: The corresponding D(W) and D(X) notation uses a visibly different font/style. In Assumption 1.1.1, the IID notation is also rendered differently, and the wage distribution symbol is rendered as \phi.
• Issue: As I noted in this issue: [book-dp1] Text and rendering discrepancies in Common Symbols table #24 (comment), the rendering of D(...) and the iid notation is not preserved exactly in the MyST/HTML version. This appears in multiple places in Chapter 1, including Assumption 1.1.1 and Section 1.2.4.3. In addition, Assumption 1.1.1 also shows the broader \varphi / \phi discrepancy noted above (2. Distribution symbol differs from the PDF throughout Chapter 1).

10. Appendix reference is rendered as “Appendix §Appendix A”

• PDF: In Section 1.2.1.1, the appendix reference is rendered as “Appendix §A”.
• HTML: The corresponding reference is rendered as “Appendix §Appendix A”.
• Issue: This appears similar to the “Figure Figure ...” issue noted above. The surrounding text already includes “Appendix”, while the cross-reference itself also renders with “Appendix A”. In addition, the position of the section symbol § differs from the PDF.

11. List of norm properties is rendered incorrectly in Section 1.2.1.2

• PDF: In Section 1.2.1.2, the four properties of a norm are listed as (a), (b), (c), and (d). The corresponding descriptions, such as “nonnegativity” and “positive definiteness,” appear aligned on the right-hand side of the same lines.
• HTML: The same content is rendered as a numbered list from 1 to 8. In addition, an isolated “2” appears before the list.
• Issue: The structure of the list is not preserved in the HTML version. The four mathematical properties and their corresponding descriptions are split into separate numbered items, which makes the list harder to read and changes the layout relative to the PDF.

See the attached screenshot for the HTML rendering.

12. Indicator function symbol differs from the PDF

• PDF: The indicator function is written with a double-struck 1.
• HTML: The corresponding indicator function is rendered with an ordinary 1.
• Issue: This appears to be related to the notation-rendering issue already noted here: [book-dp1] Text and rendering discrepancies in Common Symbols table #24 (comment). The intended double-struck indicator symbol is not preserved in the MyST/HTML version.

13. Matrix norm properties are numbered differently from the PDF

• PDF: In Section 1.2.1.4, the matrix norm properties are listed as (a), (b), (c), and (d).
• HTML: The corresponding properties are rendered as a numbered list from 1 to 4.
• Issue: The list numbering differs from the PDF. This appears related to the list-formatting issue for norm properties noted above.

14. Theorem titles are missing from some theorem blocks

• PDF: Some theorems include titles in parentheses. For example, Theorem 1.2.1 is displayed as “Theorem 1.2.1 (Neumann Series Lemma),” and Theorem 1.2.3 is displayed as “Theorem 1.2.3 (Banach’s contraction mapping theorem).”
• HTML: The corresponding theorem blocks are displayed only as “Theorem 1.2.1” and “Theorem 1.2.3”; the titles in parentheses are missing.
• Issue: The theorem numbers are preserved, but the theorem titles/names are not carried over to the HTML version.

15. Subitems inside exercises use different numbering from the PDF

• PDF: In some exercises, subitems are labeled with roman numerals, such as “(i)” and “(ii)”. This appears, for example, in Exercise 1.2.11 and Exercise 1.2.26.
• HTML: The corresponding subitems are rendered as ordinary numbered lists, such as “1.” and “2.”
• Issue: This is a minor formatting difference, but I wanted to flag it just in case. The exercise content appears to be the same, but the subitem numbering style differs from the PDF.

16. Labels are missing from Figure 1.9

• PDF: As shown above, Figure 1.9 labels the four points as u, v, u∨v, u∧v.
• HTML: The corresponding figure shows the four points, but the labels next to the points are missing.
• Issue: The figure number and caption appear to be the same, but part of the figure content is missing in the HTML version. This changes the information conveyed by the figure relative to the PDF.

17. Proof heading differs from the PDF

• PDF: In Section 1.3.1.2, the proof begins with “Proof of Proposition 1.3.1.” There is no separate heading such as “Proof 1.3.1”.
• HTML: The proof is displayed inside a block headed “Proof 1.3.1”, followed immediately by the text “Proof of Proposition 1.3.1.”
• Issue: The HTML introduces an additional proof heading that does not appear in the PDF. This makes the proof heading look duplicated. The PDF-style heading “Proof of Proposition 1.3.1” seems to be the relevant heading here.

[jstac]

Wow, these are super helpful! Thank you @Chihiro2000GitHub !!

Some of these are probably due to the fact that the preamble in the latex file is not being used to generate the html.

For example, in the file preamble.tex, roman numerals in lists are enforced by

\usepackage{enumitem}

% First-level enumerate uses lowercase roman numerals: (i), (ii), (iii)
\setlist[enumerate,1]{label={\upshape (\roman*)}}

This will be important to handle because the corresponding text refers to (i), (ii), etc.

Also, phi is mapped to varphi,

% Prettier Greek letters
\renewcommand{\phi}{\varphi}
\renewcommand{\epsilon}{\varepsilon}

[mmcky]

Wonderful - thanks so much @Chihiro2000GitHub. I'll dive into this tomorrow.

[mmcky]

Thank you so much @Chihiro2000GitHub — this is an exceptionally detailed and well-documented review. The side-by-side PDF/HTML comparisons, screenshots, and precise section references made every one of these easy to reproduce and triage. Genuinely appreciated.

I've worked through all 17 items and sorted them by where the fix belongs. Summary:

Conversion-tool bugs (claude-latex-to-myst) — these fix every affected spot at once and we pick them up via a regen:

• 1. Algorithms — uncaptioned algorithm blocks shouldn't be numbered; this is why "VFI for job search" shifted from PDF 1.1 to HTML 1.3. Also covers the missing do/end, bullets-vs-numbered lines, and the split "depends on the current state and action" step. → algorithm2e blocks mis-rendered: uncaptioned algorithms numbered; loops lose do/end; lines become bullets; wrapped line split claude-latex-to-myst#109
• 7 & 10. "Figure Figure" / "Appendix §Appendix A" — doubled noun where the cross-ref already renders the noun. → Doubled noun in cross-refs: "Figure Figure N" (numref) and "Appendix §Appendix A" (\S\ref) claude-latex-to-myst#110
• 11, 13, 15. Lists — multicols, the (a)(b)(c)(d) labels, and the (i)(ii) roman numerals (the enumitem setting @jstac pointed to) aren't carried over. → List structure lost: multicols, custom \item[(a)] labels, and enumitem roman-numeral style not carried to MyST claude-latex-to-myst#111
• 14 & 17. Theorem/proof titles — the (Neumann Series Lemma) titles are dropped, and the proof shows a duplicated "Proof 1.3.1" heading. → Theorem/proof optional [title] dropped (theorems) and duplicated (proofs) claude-latex-to-myst#112
• 8. Equation numbering — unnumbered (starred) displays are being numbered in HTML, which is exactly why the final number drifts from PDF (1.34) to HTML (1.61). → Unnumbered (starred) display equations get numbered in HTML — equation-numbering parity break (1.34→1.61) claude-latex-to-myst#113

book-dp1 configuration / assets (tracked in QuantEcon/book-dp1#353):

• 2. \phi→\varphi (and \epsilon→\varepsilon) — exactly as @jstac noted, the preamble \renewcommand isn't applied; we'll add it to the web math macros.
• 6. Exercise numbering (1.1 → 1.1.1) and 5. Listing "Program"/numbering — numbering-scope config (with one possible upstream piece for the code caption).
• 3. Figure 1.3 line color and 16. Figure 1.9 missing labels — figure-asset fixes (1.9's labels live in an xfig text overlay that the conversion currently drops).

Already tracked: 9 (D(...) font + iid small caps) and 12 (double-struck indicator 𝟙) are the same notation-rendering items you raised in book-dp-public#24 — tracked in QuantEcon/book-dp1#351 and QuantEcon/claude-latex-to-myst#107.

Cosmetic: 4 — there's no remapping of v in the source, so the value function really is v; the resemblance to \upsilon is a KaTeX font-rendering effect (you nicely noted the PDF legend looks similar too).

Full tiered breakdown with file/line references is in QuantEcon/book-dp1#353. We'll update here as the fixes land and the site is regenerated.

[mmcky]

thanks @jstac for thinking of the preamble updates -- big help.

[mmcky]

Status update: a converter release with fixes for most of the items here is now deployed to the live site. Here's the item-by-item state — validation of the ✅ rows would be super helpful, @Chihiro2000GitHub!

✅ Fixed — please re-check on the live site

#	Item	Now
1	Algorithm blocks	"VFI for job search" is Algorithm 1.1 again (uncaptioned algorithms no longer numbered); while…do / end restored; the wrapped line is one step
7	"Figure Figure 1.1"	reads "… {numref} 1.1" only — doubled noun gone book-wide
8	Equation numbering	Chapter 1 runs exactly (1.1)–(1.34), matching the PDF; starred equation*/align* are unnumbered
10	"Appendix §Appendix A"	reads "Appendix A"
11 (part)	stray "2" before the norm axioms	gone (multicols column count no longer leaks)
14	Theorem titles	"Theorem 1.2.1 (Neumann Series Lemma)" preserved

⚠️ Partially fixed / interim

• 17 (proof heading duplication): proof titles containing a cross-ref still render as a bold lead-in line under the auto "Proof" heading. Placing the ref in the directive title trips a renderer (mystmd) bug, so the full fix is tracked upstream of the converter.
• 11/13/15 (list labels): (a)…(d) and roman-numeral (i)(ii) markers remain plain 1. 2. — CommonMark has no custom ordered-list markers; left open as List structure lost: multicols, custom \item[(a)] labels, and enumitem roman-numeral style not carried to MyST claude-latex-to-myst#111.

🔜 Still queued (book-side config/assets, tracked in QuantEcon/book-dp1#353)

• 2 (\phi→\varphi, \epsilon→\varepsilon macros), 5 (Listing caption/numbering), 6 (exercise numbering 1.1.1)
• 3 (Fig 1.3 line colour), 16 (Fig 1.9 missing labels — xfig overlay)
• 9 & 12 (notation family: D(W) font, small-caps iid, indicator 𝟙 in the symbols table) — QuantEcon/book-dp1#351

No action planned for 4 (the v glyph is the KaTeX math-italic font, not a notation change).

Thanks again for the remarkably thorough audit — items 1/7/8/10/14 were all converter bugs that are now fixed for every book using this pipeline.

[mmcky]

Update: the remaining config + figure items from this audit are now live as well (QuantEcon/book-dp1#353 is closed — full disposition there). Newly deployed since my last comment:

• 2. \phi/\epsilon now render as φ (varphi) / ε (varepsilon), matching the print edition's preamble.
• 6. Exercises now number 1.1.1, 1.2.1, … (per-section, three-part) exactly like the PDF.
• 16. Figure 1.9 has its u, v, u∨v, u∧v labels back (the xfig text overlay is now rendered into the figure). The same silent label loss turned out to affect two more figures — the pointwise-order figure in Chapter 2 and the subgradient figure in Chapter 5 — both fixed.
• 3. Your Figure 1.3 colour observation was a real find, and bigger than it looked: the web and PDF shared a byte-identical figure file, but the site's PDF→PNG conversion was darkening colours (light steel-blue → dark navy — which is why the solid line vanished under the dashed one). All 73 figures are now served as vector SVGs with exact PDF colours, so this is fixed book-wide, not just for 1.3.
• 5. (Listing numbering) is config-ready but blocked on a renderer gap — tracked in numbering.code: scope ignored (no chapter prefix) and caption noun stays "Program" despite template "Listing %s" mystmd#47; references currently say "Listing N" while captions say "Program N".

Still open by design: 13/15 (the (a)/roman list markers — CommonMark limitation, claude-latex-to-myst#111) and the proof-title lead-in (17, renderer bug).

@Chihiro2000GitHub with this, everything actionable from all three of your reports is deployed — a re-check of items 2, 3, 6, 16 here (plus the figure colours generally, which improved on every page) would be super helpful. Thank you again; the Figure 1.3 catch alone improved every figure in the book.

[Chihiro2000GitHub]

Thank you for the detailed update, @mmcky!

I checked all the points you mentioned: items 2, 3, 6, and 16. They all look perfect to me now.

As for figure colours more generally, all the figures in Chapter 1 look good to me. I will continue checking them in later chapters as I work through the book chapter by chapter.

Thanks again, @mmcky, for working through such a long issue so carefully.
Also, @mmcky and @jstac, thank you for your warm comments. They really motivated me a lot!

I will create a new issue for Chapter 2, hopefully tomorrow night.

[mmcky]

thanks @Chihiro2000GitHub -- this is excellent work. Appreciate the detailed review. It is super helpful.