Skip to content

Font Issue in matplotlib #22

Closed
Closed

Description

@HumphreyYang

In lectures where we have 'text.usetex': True, we need to add the following headers:

# Configure Matplotlib to use pdfLaTeX and CJKutf8
mpl.rcParams.update({
    'text.usetex': True,
    'text.latex.preamble': r'''
        \usepackage{{CJKutf8}}
        \usepackage{{amsmath}}
    '''
})
# Function to wrap Chinese text in CJK environment
def cjk(text):
    return rf'\begin{{CJK}}{{UTF8}}{{gbsn}}{text}\end{{CJK}}'

Then apply the cjk function to the Chinese character to the figure plotting matplotlib.

Example:
37c0d3c#diff-6d11baeb8df592b6a934e4de8f805cb9986d5b4524917a25c82e3dff8a670180L258-R270

Activity

  1. mmcky commented on Jul 19, 2026

    @mmcky
    Contributor

    Decision: move the zh edition off usetex rather than adopt the CJKutf8 + cjk() wrapper

    Revisiting this during the 2026-07-18/19 resync wave. The scope turned out to be tiny and precise: exactly two lectures in the whole edition use text.usetex=True — kalman_2 and two_auctions (verified by grepping the English source, since a resync only inherits usetex from upstream). So this issue affects those two files and nothing else.

    The wave gave us direct evidence of how fragile the usetex + cjk() approach is. On kalman_2 alone we hit three distinct failures: the resync dropped the def cjk() helper (→ NameError in every figure cell); once the helper was restored, the LaTeX preamble was missing amsfonts, so upstream's rewritten \mathbb{E}[...] titles raised "Undefined control sequence" and fig.tight_layout() crashed; and every one of these was invisible until a cold, uncached build — a cached green checkmark hid a broken lecture. two_auctions failed separately because the resync brought upstream's usetex=True but translated the labels to Chinese without wrapping them, so LaTeX errored on Unicode character 估 (U+4F30).

    The root cause is structural: usetex requires the cjk() def to be present, every Chinese label to be wrapped, the preamble to load every LaTeX package the labels' math uses, and a LaTeX toolchain in CI — and the resync engine drops these i18n adaptations on every run (the QuantEcon/action-translation#107 class), so each future sync re-breaks these lectures and needs careful manual repair.

    We weighed keeping usetex (this issue's original prescription) against dropping it and rendering via the font-manager + mathtext, which is what the other ~38 lectures already do. Dropping usetex wins on every axis that matters here: it removes the fragile machinery and the cache-masked failure mode, it makes the resync repair trivial (restore the one-line font block, same as everywhere else), it keeps these two lectures consistent with the rest of the edition, and it even makes the Chinese in plot labels use Source Han Serif (the edition's font) instead of the CJK LaTeX gbsn font. The only thing usetex bought us was marginally nicer LaTeX math in two lectures' plot labels — and the math involved is simple ($\mathbb{E}[y_t|y^{t-1}]$, $v_i$, $b_i$), all of which mathtext renders natively (mathtext supports \mathbb). That aesthetic edge is not worth a recurring, fragile maintenance burden on an edge case.

    Standard going forward: the zh edition renders Chinese via plt.rcParams['font.family'] = ['Source Han Serif SC'] and math via mathtext; avoid text.usetex in translated lectures. When a resync pulls in an upstream lecture that sets usetex, drop the usetex config rather than adding CJK machinery.

    Fixes landing this:

    Will close this once both are merged and verified green.

  2. mmcky commented on Jul 19, 2026

    @mmcky
    Contributor
  3. mmcky commented on Jul 19, 2026

    @mmcky
    Contributor

    Both usetex lectures are now converted and merged green, so this is resolved:

    The zh edition now renders Chinese via font.family (Source Han Serif) and math via mathtext across all lectures, with no lecture on the usetex path. Standard for future resyncs: when upstream sets text.usetex, drop it rather than adding CJK machinery.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions