Rewrite the CRAM Base Substitution (BS) code explanation

[jkbonfield]

Fixes #408

[jkbonfield]

@jmarshall This fails checks because latexdiff fails, and not because building the PDF from the main TeX fails.

The error details above show the command as:

make new/CRAMv3.pdf  && make -k OLD=$mergebase_sha NEW=HEAD diff/CRAMv3.pdf 

I'm wondering if we should replace it in pr-pds.yaml with

run: make ${{ env.pdfs }} && (make -k OLD=$mergebase_sha NEW=HEAD ${{ env.diffs }} || true)

so even when the diff fails, provided the primary document builds correctly then we're still OK.

What do you think? I wouldn't mind if it weren't for latexdiff being such a buggy mess. I've had numerous tables break with it sadly. Sometimes I've rewritten them until it works, but it feels a bit like tail wagging the dog. The preview is nice to have, but should never cause a CI failure IMO.

[jmarshall]

That's what make -k was supposed to be there for (to ignore the error if one of several diff PDFs spuriously fails), but of course it doesn't actually stop the exit status from being non-zero — d'oh. We could use what you've suggested or about equivalently make -i to really ignore errors, but I've long been vaguely dissatisfied by the && joining what are really separate commands, so I've made run.sh more fancy instead.

Rebase onto master again to get c044c04 and this should finally go away.

[github-actions]

Changed PDFs as of 4c631b4: CRAMv3.

[jkbonfield]

Thanks @jmarshall

[github-actions]

Changed PDFs as of 9eb4b32: CRAMv3.

[github-actions]

Changed PDFs as of 40beee1: CRAMv3.