From 4c70777099e17546098233d66c9f9a5ffff02d8d Mon Sep 17 00:00:00 2001 From: oli Date: Thu, 8 Oct 2026 08:48:57 +0100 Subject: [PATCH 1/3] Fix maths markup so the book builds as PDF via LaTeX The notes were written against MathJax, which accepts plain-TeX and MathJax-only idioms that real LaTeX rejects. The HTML build never complained, so these accumulated silently and `--builder pdflatex` failed with 163 hard errors. LaTeX halts at the first error, so each build only exposed the next one. Seven root causes (the rest were cascades): * \lt and \gt are MathJax-only -> \providecommand in the preamble * \ce{} / \pu{} had no LaTeX package -> \usepackage{mhchem} * \newcommand{\ee} repeated in-document -> moved to config, both outputs * \eqalignno{} / \eqalign{} are plain TeX -> aligned * \cr inside align -> \\ * & placed inside \ce{} -> moved outside * _\ce{AB} and ^\ddagger unbraced -> braced \pu has no LaTeX equivalent (mhchem v4.10 does not define it), so its one use is now written in plain math. mathjax3_config also needs 'configmacros' in tex.packages: that list is a replacement, not an addition, and without it MathJax silently ignores the macros block and \ee renders as "Undefined control sequence". makefile: `make pdf` now uses the LaTeX builder (needs MacTeX/TeX Live). The old pdfhtml route is kept as `make pdfhtml` but is broken -- pyppeteer calls websockets.client.connect, which websockets >= 10 no longer exposes as a bare attribute. Verified: PDF builds to 464 pages with 0 LaTeX errors, structurally validated with ghostscript. HTML output diffed against a pristine baseline across all 66 pages -- no rendering differences, 0 MathJax errors, and equation numbering unchanged. Co-Authored-By: Claude Opus 5 (1M context) --- book/02_environments/l4/l4.md | 1 - book/02_environments/l5/l5.md | 1 - book/02_environments/l7/l7.md | 12 +++++------ book/03_detection/l4/l4.md | 40 +++++++++++++++++------------------ book/03_detection/l5/l5.md | 12 +++++------ book/03_detection/l6/l6.md | 20 +++++++++--------- book/03_detection/l7/l7.md | 8 +++---- book/_config.yml | 9 +++++++- makefile | 18 ++++++++++++---- 9 files changed, 68 insertions(+), 53 deletions(-) diff --git a/book/02_environments/l4/l4.md b/book/02_environments/l4/l4.md index 76fea080..b97a04be 100644 --- a/book/02_environments/l4/l4.md +++ b/book/02_environments/l4/l4.md @@ -44,7 +44,6 @@ describe the end-member behaviour of the mantle. Within an **elastic solid**, stress and strain are related by **Hooke's law** which we write as ```{math} -\newcommand{\ee}{\mathrm{e}}\newcommand{\ii}{\mathrm{i}}\newcommand{\ddns}{\,\mathrm{d}} \sigma = \mu \epsilon, ``` with $\mu$ an elastic modulus. Here we see that the diff --git a/book/02_environments/l5/l5.md b/book/02_environments/l5/l5.md index d92569a8..23d89ef8 100644 --- a/book/02_environments/l5/l5.md +++ b/book/02_environments/l5/l5.md @@ -113,7 +113,6 @@ the lithosphere is dominantly through conduction. We also showed last time that the time-scale for conductive cooling over a length-scale $l$ is given by ```{math} -\newcommand{\ee}{\mathrm{e}}\newcommand{\ii}{\mathrm{i}}\newcommand{\ddns}{\,\mathrm{d}} t \sim \frac{l^{2}}{\kappa}, ``` with $\kappa$ the thermal diffusivity. diff --git a/book/02_environments/l7/l7.md b/book/02_environments/l7/l7.md index f06795fe..efa83d24 100755 --- a/book/02_environments/l7/l7.md +++ b/book/02_environments/l7/l7.md @@ -72,12 +72,12 @@ Volcanoes produce ash, gases and aerosols which may contain soluble metal salts Thick ash fall can lead to plant death if the plant’s ability to take up minerals and photosynthesis is impaired. Over longer timescales (100s years) however, volcanic ash weathers and absorbs organic carbon, making fertile soils. The weathering process draws down atmospheric CO2 through the reactions: ```{math} -\begin{align} -\ce{CO2 + H2O &\rightarrow H2CO3}\\ -\ce{&\rightarrow HCO3- + H+}\\ -\ce{CaSiO3 + 2H+ &\rightarrow Ca2+ + H2O + SiO2}\\ -\ce{Ca2+ + HCO3- &\rightarrow CaCO3 + H2O + CO2} -\end{align} +\begin{aligned} +\ce{CO2 + H2O} &\ce{-> H2CO3}\\ +&\ce{-> HCO3- + H+}\\ +\ce{CaSiO3 + 2H+} &\ce{-> Ca2+ + H2O + SiO2}\\ +\ce{Ca2+ + HCO3-} &\ce{-> CaCO3 + H2O + CO2} +\end{aligned} ``` It has been recognised that sometimes lava flows or ash fall into the sea can lead to phytoplankton blooms, by disrupting water flow and/or introducing Fe and other elements. A good example is the phytoplankton bloom that was recently observed offshore Hawaii during the 2018 East Rift zone eruption of Kilauea, where lava flowed into the sea, causing upwelling of deep, nutrient-rich water. diff --git a/book/03_detection/l4/l4.md b/book/03_detection/l4/l4.md index 2ca37520..3865ffc9 100755 --- a/book/03_detection/l4/l4.md +++ b/book/03_detection/l4/l4.md @@ -28,7 +28,7 @@ $$\ce{A + BC <=> AB + C}$$ Once an equilibrium has been reached, the extent of this reaction is be determined by its equilibrium constant -$$K=\frac{a_\ce{AB} a_\ce{C}}{a_\ce{A} a_\ce{BC}} = -RT \ln \Delta_r G^\ominus$$ +$$K=\frac{a_{\ce{AB}} a_{\ce{C}}}{a_{\ce{A}} a_{\ce{BC}}} = \exp{-\Delta_r G^\ominus/(RT)}$$ NB the Gibbs free energy of each of the individual substances is temperature dependent, so $\Delta_r G^\ominus$ will also be temperature dependent. The various factors which determine $\Delta_r G^\ominus$ can be calculated from statistical thermodynamics from the molecular energy levels (through the partition function), and so for simple molecules, can in principle be determined computationally. In the simple case of a gas-phase molecule, these energy levels are governed by the rotations and vibrations of the molecule and can be accurately measured by microwave and infrared spectroscopy. @@ -36,7 +36,7 @@ The various factors which determine $\Delta_r G^\ominus$ can be calculated from In the literature, you may find a common approximation replacing the activities of a substance in solution by its concentration. This is not strictly dimensionally correct, and instead we may write $a_X \approx \frac{[X]}{c^0}$ -where $c^0$ is a standard concentration (e.g. $\pu{1 mol dm-3}$). This approximation is good in the low concentration limit, and we will make use of it throughout this lecture. +where $c^0$ is a standard concentration (e.g. $\mathrm{1\ mol\ dm^{-3}}$). This approximation is good in the low concentration limit, and we will make use of it throughout this lecture. In general, however, a system is not as a whole at equilibrium, so it is helpful to also look at the time dependence of chemical reactions, a field called chemical kinetics. If the timescale of a reaction is fast compared to our observations, and the reaction reaches equilibrium, we say it is 'thermodynamically controlled'. If, however, the reaction is slow compared to observation, and we do not readily reach equilibrium, it is 'kinetically controlled'. @@ -55,10 +55,10 @@ $$\ce{2NO + O2 -> 2NO2}$$ can be split into two elementary steps -$$\eqalignno{ -\ce{2NO &->[k_1] N2O2} &[1]\cr -\ce{N2O2 + O2 &->[k_2] 2NO2} &[2] -}$$ +$$\begin{aligned} +\ce{2NO} &\ce{->[k_1] N2O2} &[1]\\ +\ce{N2O2 + O2} &\ce{->[k_2] 2NO2} &[2] +\end{aligned}$$ The rate law for an elementary step relates the rate of that reaction to the concentration of the reactants @@ -71,7 +71,7 @@ Here we shall look at the factors which control the rates of the individual elem ## Reaction Pathways -To understand what occurs during a chemical reaction we can look at the energy of the combined system of reactants as a function of the positions of the atoms. Even in our three-atom, two molecule system, that is far too many degrees of freedom to plot, so we will consider the simple case of one dimension, where A, B, and C are collinear, with distances, $r_\ce{AB}$ and $r_\ce{BC}$. +To understand what occurs during a chemical reaction we can look at the energy of the combined system of reactants as a function of the positions of the atoms. Even in our three-atom, two molecule system, that is far too many degrees of freedom to plot, so we will consider the simple case of one dimension, where A, B, and C are collinear, with distances, $r_{\ce{AB}}$ and $r_{\ce{BC}}$. ```{figure} figures/ABC.png --- @@ -88,10 +88,10 @@ It is possible to plot the 'energy' of the system as a function of these two coo name: fig:PES3D width: 70% --- -A 3-dimensional plot of a Potential energy surface with coordinates $r_\ce{AB}$ and $r_\ce{BC}$ is too difficult to draw. +A 3-dimensional plot of a Potential energy surface with coordinates $r_{\ce{AB}}$ and $r_{\ce{BC}}$ is too difficult to draw. ``` -The reactants, if they are stable, will sit in a local minimum of the PES with a large $r_\ce{AB}$ and short $r_\ce{BC}$. (Because the molecules are themselves quantum mechanical, they don't just sit at the minimum of this well. Their (nuclear) wavefunction is spread over the minimum of the PES.). +The reactants, if they are stable, will sit in a local minimum of the PES with a large $r_{\ce{AB}}$ and short $r_{\ce{BC}}$. (Because the molecules are themselves quantum mechanical, they don't just sit at the minimum of this well. Their (nuclear) wavefunction is spread over the minimum of the PES.). Similarly the products will sit in a different local minimum with a (probably) different energy. ```{figure} figures/PES2D_1.png @@ -99,7 +99,7 @@ Similarly the products will sit in a different local minimum with a (probably) d name: fig:PES2D_1 width: 70% --- -A 2-dimensional plot of the reaction space with coordinates $r_\ce{AB}$ and $r_\ce{BC}$, showing the position of reactants and products. +A 2-dimensional plot of the reaction space with coordinates $r_{\ce{AB}}$ and $r_{\ce{BC}}$, showing the position of reactants and products. ``` ```{figure} figures/PES2D_2.png @@ -107,7 +107,7 @@ A 2-dimensional plot of the reaction space with coordinates $r_\ce{AB}$ and $r_\ name: fig:PES2D_2 width: 70% --- -A 2-dimensional contour plot of the energy in the reaction space with coordinates $r_\ce{AB}$ and $r_\ce{BC}$, showing the reactants and products as local minima. +A 2-dimensional contour plot of the energy in the reaction space with coordinates $r_{\ce{AB}}$ and $r_{\ce{BC}}$, showing the reactants and products as local minima. ``` We describe a chemical reaction by a pathway on the PES joining the reactants minimum with the products minimum. @@ -117,7 +117,7 @@ We describe a chemical reaction by a pathway on the PES joining the reactants mi name: fig:PES2D_3 width: 70% --- -A 2-dimensional contour plot of the energy in the reaction space with coordinates $r_\ce{AB}$ and $r_\ce{BC}$, showing the reactants and products as local minima joined by their reaction pathway containing the transition state $\ce{ABC^\ddagger}.$ +A 2-dimensional contour plot of the energy in the reaction space with coordinates $r_{\ce{AB}}$ and $r_{\ce{BC}}$, showing the reactants and products as local minima joined by their reaction pathway containing the transition state $\ce{ABC^{\ddagger}}.$ ``` @@ -139,21 +139,21 @@ Many reactions approximately fit this, though the equation it is not directly ba Instead we can use an approach called "Eyring Transition State Theory". We assume that the reaction proceeds through the transition state labelled $\ce{ABC}^\ddagger$. Since the transition state is significantly higher in energy than the reactants, relatively few collisions of $\ce{A + BC}$ reach the transition state, and so we can statistically model the few that do. This is done by assuming that the reactants and transition state are in equilibrium, with equilibrium constant $K^*$. -$$\ce{A + BC <=> ABC^\ddagger -> AB + C}$$ +$$\ce{A + BC <=> ABC^{\ddagger} -> AB + C}$$ Further, we assume that once a system has reached the transition state, it has a fixed rate of descending the PES to the reactants, $k_\text{1st}$. Overall therefore the rate of reaction is -$$\text{rate} = \frac{d[\ce{AB}]}{dt} = k_1[\ce{ABC^\ddagger}].$$ +$$\text{rate} = \frac{d[\ce{AB}]}{dt} = k_1[\ce{ABC^{\ddagger}}].$$ From the equilibrium, -$$K^* = \frac{[\ce{ABC^\ddagger}]/c^0 }{ \left([\ce{A}]/c^0\right) \left([\ce{B}]/c^0\right)} = c^0 \frac{[\ce{ABC^\ddagger}]}{ [\ce{A}][\ce{B}]}$$ +$$K^* = \frac{[\ce{ABC^{\ddagger}}]/c^0 }{ \left([\ce{A}]/c^0\right) \left([\ce{B}]/c^0\right)} = c^0 \frac{[\ce{ABC^{\ddagger}}]}{ [\ce{A}][\ce{B}]}$$ so -$$[\ce{ABC^\ddagger}] = \frac{K^*}{c^0}[\ce{A}][\ce{B}]$$ +$$[\ce{ABC^{\ddagger}}] = \frac{K^*}{c^0}[\ce{A}][\ce{B}]$$ and therefore @@ -193,10 +193,10 @@ We also see that the pre-exponential factor is both temperature dependent, and h Not all chemical reactions occur from molecules in their ground state, owing to often large activation energy barriers. One way of overcoming this is to first excite a molecule to a higher energy electronic state, usually by the absorption of a photon. This may then react or decompose. -$$\eqalign{ -\ce{X + h\nu &-> X^*}\cr -\ce{X^* &-> A + B} -}$$ +$$\begin{aligned} +\ce{X + h\nu} &\ce{-> X^*}\\ +\ce{X^*} &\ce{-> A + B} +\end{aligned}$$ This process involves two PESes: the ground state of $\ce{X}$ which may have a high barrier to producing $\ce{A+B}$, and its excited state, $\ce{X^*}$, where it's possible that making the products is even exothermic. diff --git a/book/03_detection/l5/l5.md b/book/03_detection/l5/l5.md index 99e54584..099358e6 100755 --- a/book/03_detection/l5/l5.md +++ b/book/03_detection/l5/l5.md @@ -111,10 +111,10 @@ and is separated out of the average (**why is this a fair thing to do? How would In the case of an ion-neutral collision with an ion and a polarizable molecule, we can see that the polarized molecule experiences an attractive force as a function of intermolecular distance, $r$ (m), of $F = P \cdot \big(dE/dr\big)$, where $P = \alpha_N E$ (C m) is the dipole moment, and $\alpha_N$ (C m$^2$/V) is the polarizability, and $E$ (V/m) is the electric field. Given a Coulomb field, $E = kq/r^2$ where the charge here is typically equal to the charge of a single electron, $q = 1.6 \times 10^{-19}$ C, and $k = 8.99 \times 10^9$ N m$^2$ C$^{-2}$; we can then solve for the force: ```{math} :label: eqn:L9-coulomb-force -\begin{align} +\begin{aligned} F &= P \Bigg(\frac{dE}{dr}\Bigg)\\ &= \frac{-2 \alpha_N k^2 q^2}{r^5}. -\end{align} +\end{aligned} ``` Given that $F = -dU/dr$, we can represent the potential energy of the polarized molecular species in the Coulomb field as: ```{math} @@ -183,11 +183,11 @@ Once H$_2$ is formed, a path is now opened to more complex chemistry, including Let's look at a simple sequence of reactions: ```{math} :label: eqn:L9-sequence-of-reactions -\begin{align} +\begin{aligned} {\rm H_2 + GCR} &\rightarrow {\rm H_2^+} + e^- \\ {\rm H_2^+ + H_2} &\rightarrow {\rm H_3^+ + H} \\ {\rm H_3^+ + CO} &\rightarrow {\rm HCO^+ + H_2} -\end{align} +\end{aligned} ``` Other reactions with H$_3^+$ and atomic carbon can lead to rich interstellar chemistry, see Larsson et al. (2012). This chemistry depends on the concentration of H$_3^+$, and the steady-state concentration can be calculated from the rate equations based on the simple series of reactions above. @@ -199,11 +199,11 @@ The very first molecular species in our universe formed before there were dust g ```{math} :label: eqn:L9-first-molecules -\begin{align} +\begin{aligned} {\rm H + He^+} &\rightarrow {\rm HeH^+} + h\nu \\ {\rm HeH^+ + H} &\rightarrow {\rm H_2^+ + He} \\ {\rm H_2^+ + H} &\rightarrow {\rm H_2 + H^+} -\end{align} +\end{aligned} ``` HeH$^+$ (or possibly He$_2^+$) was the first chemical species in our universe. The radiative association reactions shown here with ion-neutral species are still very slow ($\sim 10^{-20}$ cm$^3$ s$^{-1}$, see Roberge & Dalgarno 1982), but not nearly as slow as H + H radiative association, or most neutral atomic radiative association reactions. This is not fast enough to explain how all H$_2$ in a dense cloud would have been formed, but it is enough to predict that there would have been significant abundances of various molecular species in the early Universe, before dust grains were formed. diff --git a/book/03_detection/l6/l6.md b/book/03_detection/l6/l6.md index 54e68f05..dfab0a73 100755 --- a/book/03_detection/l6/l6.md +++ b/book/03_detection/l6/l6.md @@ -99,11 +99,11 @@ $$ where A is our initial reactant, B an **intermediate** product and C the final product of the reaction. Following the same procedure as above we can write: $$ -\begin{align} +\begin{aligned} \frac{d[{\rm A}]}{dt} &= -k_1 [{\rm A}] \\ \frac{d[{\rm B}]}{dt} &= k_1 [{\rm A}] - k_2 [{\rm B}] \\ \frac{d[{\rm C}]}{dt} &= k_2 [{\rm B}] -\end{align} +\end{aligned} $$ Solutions for these equations are shown in Figures {numref}`AA-F3` and {numref}`AA-F4`. @@ -135,10 +135,10 @@ where the subscript $ss$ is used to note that we are considering the **intermedi Following this through, we can re-write the remaining equations which describe our complex reaction (making the substitution $[{\rm B}]_{ss}=k_1 [{\rm A}]/k_2$): $$ -\begin{align} +\begin{aligned} \frac{d[{\rm A}]}{dt} &= -k_1 [{\rm A}] \\ \frac{d[{\rm C}]}{dt} &= k_2 \times \frac{k_1 [{\rm A}]}{k_2} \simeq k_1 [{\rm A}] -\end{align} +\end{aligned} $$ In doing so we have greatly reduced the complexity of this reaction system. @@ -158,12 +158,12 @@ Schematic showing possible connections between an A and B molecule with A underg We can appeal to steady state and write out steady state solutions for [A] and [B] $$ -\begin{align} +\begin{aligned} \frac{d[{\rm A}]}{dt} &= F_A - k_1 [{\rm A}] - k_2[{\rm A}] \\ [{\rm A}]_{ss} &= \frac{F_A}{k'} = F_A \times \tau_A \\ \frac{d[{\rm B}]}{dt} &= k_1 [{\rm A}] - k_2[{\rm B}] \\ [{\rm B}]_{ss} &= \frac{k_1[{\rm A}]}{k_1} -\end{align} +\end{aligned} $$ And we can then write an expression for the ratio of $[{\rm B}]_{ss}/[{\rm A}]_{ss}$ @@ -197,10 +197,10 @@ $$ With rate constants: $$ -\begin{align} +\begin{aligned} {\rm A} &\xrightarrow{k_1} {\rm B} \\ {\rm B} &\xrightarrow{k_{-1}} {\rm A} -\end{align} +\end{aligned} $$ the system approaches equilibrium with a time constant of $(k_1 + k_{-1})^{-1}$ (s). So, only need $k_1$ **or** $k_{-1}$ to be large for $\tau$ to be small, and to then allow us to apply steady-state. @@ -269,11 +269,11 @@ $$ We can also use studies on the kinetics of chemical reactions to tell us about their mechanisms. By mechanism we mean the elementary series of steps (or step) involved in a molecular encounter. An example is the oxidation of the aromatic compound, benzene. The main sink for benzene is the reaction with OH. OH can either add to the aromatic ring on benzene or abstract (pull off) a hydrogen atom. $$ -\begin{align} +\begin{aligned} {\rm OH + C_6H_6} &\xrightarrow{k_1} {\rm H_2O + C_6H_5} \\ {\rm OH + C_6H_6} &\xrightarrow{k_2} {\rm HOC_6H_6} \\ k_{{\rm obs},T} &= k_1 + k_2 -\end{align} +\end{aligned} $$ ```{figure} ./figures/C3_Archibald_Figure7.jpg diff --git a/book/03_detection/l7/l7.md b/book/03_detection/l7/l7.md index 72bdc297..e9f67ad6 100755 --- a/book/03_detection/l7/l7.md +++ b/book/03_detection/l7/l7.md @@ -133,13 +133,13 @@ Reactions in an atmosphere occur through either collisions or absorption of phot When two species collide there are a limited number of outcomes. Let’s consider an example of an A molecule colliding with a BC molecule. $$ -\begin{align} +\begin{aligned} \mathrm{\mathbf{Addition:}}&\\ {\rm A + BC} &\rightarrow {\rm ABC}\\ \mathrm{\mathbf{Abstraction:}}&\\ {\rm A + BC} &\rightarrow {\rm AB + C}\\ {\rm A + BC} &\rightarrow {\rm AC + B} -\end{align} +\end{aligned} $$ As our molecules get more complex (include more atoms) then the number of possible products increases considerably. @@ -147,7 +147,7 @@ As our molecules get more complex (include more atoms) then the number of possib For absorption of photons we can consider photolysis (breaking of bonds), excitation (increasing energy levels) or rearrangement. Let’s consider another example of a molecule ABC. $$ -\begin{align} +\begin{aligned} \mathrm{\mathbf{Photolysis:}}&\\ {\rm ABC} + h\nu &\rightarrow {\rm A + BC}\\ {\rm ABC} + h\nu &\rightarrow {\rm AB + C}\\ @@ -158,7 +158,7 @@ $$ {\rm ABC} + h\nu &\rightarrow {\rm ACB}\\ {\rm ABC} + h\nu &\rightarrow {\rm BCA}\\ {\rm ABC} + h\nu &\rightarrow {\rm BAC} -\end{align} +\end{aligned} $$ We won’t dwell on ionisation reactions in these lectures but note that they add considerable further complexity. Generally speaking these reactions are only of importance in the upper atmosphere of a planet. diff --git a/book/_config.yml b/book/_config.yml index 7d5afd2e..8f40d120 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -46,9 +46,16 @@ sphinx: loader: load: ['[tex]/physics', '[tex]/ams', '[tex]/mhchem', '[tex]/color', '[tex]/newcommand', '[tex]/textcomp'] tex: - packages: ['base', 'physics', 'ams', 'amsmath', 'mhchem', 'color', 'newcommand', 'textcomp'] + packages: ['base', 'physics', 'ams', 'amsmath', 'mhchem', 'color', 'newcommand', 'textcomp', 'configmacros'] # configmacros is what makes `macros:` below take effect + macros: + ee: '\mathrm{e}' # mirrors the LaTeX preamble definition + ii: '\mathrm{i}' # mirrors the LaTeX preamble definition + ddns: '\,\mathrm{d}' # mirrors the LaTeX preamble definition latex_elements: preamble: | + \usepackage{mhchem} % replaces MathJax [tex]/mhchem: \ce (no \pu in LaTeX mhchem) + \providecommand{\lt}{<} % MathJax-only macro, undefined in LaTeX + \providecommand{\gt}{>} % MathJax-only macro, undefined in LaTeX \newcommand{\dv}[2]{\frac{\mathrm{d}#1}{\mathrm{d}#2}} % replaces physics.sty \dv \newcommand{\dd}{\mathrm{d}} % replaces physics.sty \dd \newcommand{\pdv}[2]{\frac{\partial #1}{\partial #2}} % partial derivative diff --git a/makefile b/makefile index 5df308a3..e415578b 100644 --- a/makefile +++ b/makefile @@ -1,10 +1,20 @@ -.PHONY: html pdf pdflatex +.PHONY: html pdf pdflatex pdfhtml html: jupyter-book build book/ -pdf: - jupyter-book build book/ --builder pdfhtml +# PDF via LaTeX. This is the working route, but it needs a TeX distribution +# (MacTeX or TeX Live) providing xelatex and latexmk on your PATH. +pdf: pdflatex pdflatex: - jupyter-book build book/ --builder pdflatex \ No newline at end of file + jupyter-book build book/ --builder pdflatex + +# PDF via headless Chromium. BROKEN: pyppeteer does a bare `import websockets` +# and then calls websockets.client.connect, but websockets >= 10 lazy-loads its +# submodules, so the attribute does not resolve and the HTML -> PDF step dies with +# AttributeError: module 'websockets' has no attribute 'client' +# The HTML stage succeeds first, which makes the failure look like a book problem. +# Use `make pdf` instead. +pdfhtml: + jupyter-book build book/ --builder pdfhtml From c87db58a269559cacf93ec0ab9c788a53e519186 Mon Sep 17 00:00:00 2001 From: oli Date: Thu, 8 Oct 2026 08:54:26 +0100 Subject: [PATCH 2/3] Document the PDF build route and drop the unused pyppeteer dependency pyppeteer was only ever needed by the pdfhtml builder, which is broken, so remove it from both requirements files. The makefile comment on the pdfhtml target is updated to say the target will now fail at import. Add a "Building a PDF" section to the README covering the TeX prerequisite (xelatex and latexmk, via MacTeX or TeX Live), which is not obvious from the Python dependencies alone, and the expected output. Also record the maths constructs that render under MathJax but break the LaTeX build. These fail silently in the HTML build, which is how they accumulated in the first place. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 49 +++++++++++++++++++++++++++++++++++++++++++ book/requirements.txt | 1 - makefile | 3 ++- requirements.txt | 1 - 4 files changed, 51 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index bf1c82ab..3252f208 100644 --- a/README.md +++ b/README.md @@ -49,3 +49,52 @@ jupyter-book build book/ ``` The compiled HTML files can then be viewed by opening `Core-course-notes/book/_build/html/index.html` in your browser. + +## Building a PDF + +The PDF is produced by rendering the book through LaTeX, so as well as the +Python dependencies above you need a TeX distribution providing `xelatex` and +`latexmk`: + +- **macOS** -- [MacTeX](https://www.tug.org/mactex/) +- **Linux** -- TeX Live, e.g. `sudo apt install texlive-xetex texlive-latex-extra latexmk` + +Then, from the `/Core-course-notes` directory, either use the `makefile`: + +```bash +make pdf +``` + +or call `jupyter-book` directly: + +```bash +jupyter-book build book/ --builder pdflatex +``` + +The result is written to `Core-course-notes/book/_build/latex/book.pdf` +(currently 464 pages, around 150 MB). + +`make pdfhtml` selects a different route, which drives a headless Chromium via +`pyppeteer`. It is currently broken and `pyppeteer` is no longer installed by +the requirements files, so use `make pdf` instead. + +### Maths that builds as HTML but breaks the PDF + +MathJax, which renders the maths on the website, accepts a number of plain-TeX +and MathJax-only constructs that LaTeX rejects. These build cleanly as HTML and +fail only when making the PDF, so please avoid: + +| Avoid | Use instead | +| --- | --- | +| `\eqalign{}`, `\eqalignno{}` | `\begin{aligned}` ... `\end{aligned}` | +| `\cr` | `\\` | +| `\begin{align}` nested inside `$$ ... $$` or a `{math}` directive | `\begin{aligned}` | +| `\lt`, `\gt` | `<`, `>` | +| `\pu{1 mol dm-3}` | plain maths, e.g. `\mathrm{1\ mol\ dm^{-3}}` | +| `&` inside `\ce{}` | put it outside: `\ce{A} &\ce{-> B}` | +| `a_\ce{AB}`, `\ce{ABC^\ddagger}` | brace them: `a_{\ce{AB}}`, `\ce{ABC^{\ddagger}}` | +| `\newcommand` inside a maths block | define it once in `book/_config.yml`, in both `mathjax3_config` and the LaTeX preamble | + +Macros added to `mathjax3_config` only take effect if `configmacros` is listed +in `tex.packages` -- that list replaces MathJax's defaults rather than adding to +them, and without it the macro is silently ignored. diff --git a/book/requirements.txt b/book/requirements.txt index 45412892..1d421f70 100644 --- a/book/requirements.txt +++ b/book/requirements.txt @@ -1,4 +1,3 @@ jupyter-book==1.0.4 matplotlib numpy -pyppeteer \ No newline at end of file diff --git a/makefile b/makefile index e415578b..c73c36a8 100644 --- a/makefile +++ b/makefile @@ -15,6 +15,7 @@ pdflatex: # submodules, so the attribute does not resolve and the HTML -> PDF step dies with # AttributeError: module 'websockets' has no attribute 'client' # The HTML stage succeeds first, which makes the failure look like a book problem. -# Use `make pdf` instead. +# pyppeteer is no longer in the requirements files, so this target will now +# fail at import. Use `make pdf` instead. pdfhtml: jupyter-book build book/ --builder pdfhtml diff --git a/requirements.txt b/requirements.txt index 23376de1..7e821e45 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,3 @@ jupyter-book matplotlib numpy -pyppeteer \ No newline at end of file From 007a35fbd59a313b39e41e0720daa579ae399717 Mon Sep 17 00:00:00 2001 From: oli Date: Thu, 8 Oct 2026 08:58:44 +0100 Subject: [PATCH 3/3] Build the book on pull requests without deploying The workflow only ran on push to main, so there was no way to check that a branch builds before it went live. Add a pull_request trigger covering the same build steps. The deploy step is guarded on the event being a push to main. Without that guard the new trigger would publish a pull request's branch straight to gh-pages, which is the opposite of the intent. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/book.yml | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/.github/workflows/book.yml b/.github/workflows/book.yml index b60ab5e5..54e4dcaa 100644 --- a/.github/workflows/book.yml +++ b/.github/workflows/book.yml @@ -1,10 +1,14 @@ name: deploy-book -# Only run this when the master branch changes +# Deploy when main changes; on pull requests, build only (see the guard on the +# deploy step below) so a PR is checked without touching the live site. on: push: branches: - main + pull_request: + branches: + - main # This job installs dependencies, build the book, and pushes it to `gh-pages` jobs: @@ -30,8 +34,11 @@ jobs: - name: Build the book run: | jupyter-book build book/ - # Push the book's HTML to github-pages + # Push the book's HTML to github-pages. + # Guarded: without this, opening a pull request would publish that branch + # to the live site. - name: Push to github-pages + if: github.event_name == 'push' && github.ref == 'refs/heads/main' # v3.6.1 uses: peaceiris/actions-gh-pages@v3 with: