From 0651eca7d8c725fc572893da977b6389d9eaa225 Mon Sep 17 00:00:00 2001 From: Philip McGrath Date: Sun, 19 Nov 2023 15:50:46 -0500 Subject: [PATCH] optionally use KaTeX for csug and release_notes KaTeX renders LaTeX math ahead-of-time to MathML and/or HTML. Its output is accessible to screen readers and other tools (instead of appearing as ""), and it also does not suffer from the pixelation of math rendered to GIFs. Depends on https://github.com/dybvig/stex/pull/7 --- .gitignore | 3 ++ BUILDING | 20 +++++++++++- build.zuo | 15 +++++++-- makefiles/Makefile-csug.in | 48 +++++++++++++++++++++-------- makefiles/Makefile-release_notes.in | 16 +++++++++- stex | 2 +- 6 files changed, 86 insertions(+), 18 deletions(-) diff --git a/.gitignore b/.gitignore index 3c58b1275..0d262fc41 100644 --- a/.gitignore +++ b/.gitignore @@ -24,8 +24,10 @@ /xc-*/ /em-*/ *.*run +*.katex-css-link /csug/math/ /csug/gifs/ +/csug/katex/ /csug/Makefile /csug/*.aux /csug/*.html @@ -50,6 +52,7 @@ /csug/primdata.ss /release_notes/math/ /release_notes/gifs/ +/release_notes/katex/ /release_notes/Makefile /release_notes/*.tex /release_notes/*.aux diff --git a/BUILDING b/BUILDING index c36527d32..cd04a5d46 100644 --- a/BUILDING +++ b/BUILDING @@ -307,7 +307,7 @@ The makefile supports several targets: * `make docs` Runs the build plus generates HTML and PDF versions of the Chez - Scheme Users Guide and the release notes. Unlike the other build + Scheme User's Guide and the release notes. Unlike the other build targets, the documentation is not built in the workarea, but rather in the "csug" and "release_notes" directories (where "configure" is run). @@ -320,6 +320,14 @@ The makefile supports several targets: * ppmtogif and pnmcrop (from Netpbm) + * Optionally, KaTeX (for better math in HTML) + + To use KaTeX but not copy the supporting CSS and font files + (e.g. because you wish to link to a copy already installed on your + system), use `make docs KATEX_CSS=no`. See also the documentation + in the "stex/doc" directory for further details and additional + configuration options. + An X11 installation is not required, but ppmtogif does require an "rgb.txt" file, which it will automatically locate in the common X11 installation locations. If ppmtogif fails because it cannot @@ -330,6 +338,16 @@ The makefile supports several targets: installation, then it might contain an "rgb.txt" in the directory identified by the `VIMRUNTIME` environment variable. + * `make csug` or `make release_notes` + + Like `make docs`, but builds only the Chez Scheme User's Guide or + the release notes, respectively. + + * `sudo make install-docs` (or `install-csug` or `install-release_notes`) + + Like `make docs` (or `make csug` or `make release_notes`, respectively), + but also installs the built documentation. + * `make clean` Removes all built elements from the workarea, and then removes diff --git a/build.zuo b/build.zuo index a211632a8..0e1aa92cc 100644 --- a/build.zuo +++ b/build.zuo @@ -233,20 +233,29 @@ ;; in parallel to doc-project-names '(InstallCSUG InstallReleaseNotes)) (define (targets-for-doc name install-dir-key) - (define doc-dir (at-dir ".." name)) ;; ".." goes out of the workarea + (define doc-dir (at-dir ".." name)) (define mf-in (at-source "makefiles" (~a "Makefile-" name ".in"))) (define mf-out (build-path doc-dir "Makefile")) (define name-sym (string->symbol name)) (define (run-make target) (check-not-kernel-only) + (define install-dir + (hash-ref config install-dir-key)) + (define other-install-dir-key + (car (remove install-dir-key doc-install-dir-keys))) + (define other-install-dir + (hash-ref config other-install-dir-key)) (define (->rel-shell pth) (string->shell (find-relative-path doc-dir pth))) (shell/wait "make" (~a "m=" m) (~a "srcdir=" (->rel-shell (at-source name))) - (~a "installdir=" - (->rel-shell (hash-ref config install-dir-key))) + (~a "installdir=" (->rel-shell install-dir)) (~a "STEXLIB=" (->rel-shell stexlib)) + (~a other-install-dir-key "=" (->rel-shell other-install-dir)) + (~a "rel" other-install-dir-key "=" + (string->shell (find-relative-path install-dir + other-install-dir))) target (hash 'dir doc-dir))) `([:target ,mf-out (,mf-in) diff --git a/makefiles/Makefile-csug.in b/makefiles/Makefile-csug.in index 52da6af88..8a1abb23d 100644 --- a/makefiles/Makefile-csug.in +++ b/makefiles/Makefile-csug.in @@ -1,5 +1,7 @@ srcdir=oops-missing-srcdir installdir=oops-missing-installdir +InstallReleaseNotes=oops-missing-InstallReleaseNotes +relInstallReleaseNotes=oops-missing-InstallReleaseNotes m=oops-missing-m STEXLIB=oops-missing-stexlib # Zuo overrides the above variables when running `make` @@ -17,18 +19,6 @@ DIR=$(shell basename `pwd`) target: canned logcheck1 logcheck2 checklibs $(x).html $(x).pdf -install: target - $(INSTALL) -m 2755 -d $(installdir) - $(INSTALL) -m 0644 --ifdiff *.html *.css $(installdir) - $(INSTALL) -m 0644 --ifdiff csug.pdf $(installdir)/csug9_9.pdf - $(INSTALL) -m 2755 -d $(installdir)/canned - $(INSTALL) -m 0644 --ifdiff canned/* $(installdir)/canned - $(INSTALL) -m 2755 -d $(installdir)/gifs - $(INSTALL) -m 0644 --ifdiff gifs/*.gif $(installdir)/gifs - $(INSTALL) -m 2755 -d $(installdir)/$(mathdir) - $(INSTALL) -m 0644 --ifdiff $(mathdir)/*.gif $(installdir)/$(mathdir) - (cd $(installdir); ln -s -f $(x).html index.html) - # thrice is not enough when starting from scratch logcheck1: $(x).thirdrun @if [ -n "`grep 'Warning: Label(s) may have changed' $(x).log`" ] ; then\ @@ -50,6 +40,35 @@ logcheck2: $(x).thirdrun include $(STEXLIB)/Mf-stex +install: target + $(INSTALL) -m 2755 -d $(installdir) + $(INSTALL) -m 0644 --ifdiff *.html *.css $(installdir) + $(INSTALL) -m 0644 --ifdiff csug.pdf $(installdir)/csug9_9.pdf + $(INSTALL) -m 2755 -d $(installdir)/canned + $(INSTALL) -m 0644 --ifdiff canned/* $(installdir)/canned + $(INSTALL) -m 2755 -d $(installdir)/gifs + $(INSTALL) -m 0644 --ifdiff gifs/*.gif $(installdir)/gifs +ifeq ($(strip $(KATEX)),) + $(INSTALL) -m 2755 -d $(installdir)/$(mathdir) + $(INSTALL) -m 0644 --ifdiff $(mathdir)/*.gif $(installdir)/$(mathdir) +else ifneq ($(strip $(KATEX_CSS)),no) +# if already installed release_notes, share katex.css and fonts + (if $(if $(findstring Windows,$(OS)),[ ! "windows" ],[ -e $(InstallReleaseNotes)/katex/katex.css ] && [ ! -L $(InstallReleaseNotes)/katex ]) ; \ + then \ + (cd $(installdir); ln -s -f $(relInstallReleaseNotes)/katex katex) ; \ + else \ + $(INSTALL) -m 2755 -d $(installdir)/katex/fonts ; \ + $(INSTALL) -m 0644 --ifdiff katex/katex.css $(installdir)/katex/katex.css ; \ + $(INSTALL) -m 0644 --ifdiff katex/fonts/* $(installdir)/katex/fonts ; \ + fi) +endif +ifeq ($(OS),Windows_NT) + cp $(installdir)/$(x).html $(installdir)/index.html +else + (cd $(installdir); ln -s -f $(x).html index.html) +endif + + stexsrc = csug.stex title.stex copyright.stex contents.stex\ preface.stex intro.stex use.stex expeditor.stex debug.stex foreign.stex\ binding.stex control.stex objects.stex numeric.stex io.stex\ @@ -136,6 +155,11 @@ $(x).hprethirdrun: $(x).hsecondrun cat tspl.haux >> $x.haux touch $(x).hprethirdrun +$(x).hfourthrun: $(x).hprefourthrun +$(x).hprefourthrun: $(x).hthirdrun + cat tspl.haux >> $x.haux + touch $(x).hprefourthrun + $(x).prefirstrun: $(texsrc) csug8.cls csug810.clo $(x).firstrun: scheme.sty diff --git a/makefiles/Makefile-release_notes.in b/makefiles/Makefile-release_notes.in index 4abe8eb8d..ccb324ee7 100644 --- a/makefiles/Makefile-release_notes.in +++ b/makefiles/Makefile-release_notes.in @@ -1,5 +1,7 @@ srcdir=oops-missing-srcdir installdir=oops-missing-installdir +InstallCSUG=oops-missing-InstallCSUG +relInstallCSUG=oops-missing-relInstallCSUG m=oops-missing-m STEXLIB=oops-missing-stexlib # Zuo overrides the above variables when running `make` @@ -42,10 +44,22 @@ install: $x.pdf $x.html fi) $(INSTALL) -m 2755 -d $(installdir)/gifs $(INSTALL) -m 0644 --ifdiff gifs/*.gif $(installdir)/gifs - $(INSTALL) -m 2755 -d $(installdir)/math -rm -rf $(installdir)/$(mathdir) +ifeq ($(strip $(KATEX)),) + $(INSTALL) -m 2755 -d $(installdir)/math $(INSTALL) -m 2755 -d $(installdir)/$(mathdir) if [ -e $(mathdir)/0.gif ] ; then $(INSTALL) -m 0644 $(mathdir)/*.gif $(installdir)/$(mathdir) ; fi +else ifneq ($(strip $(KATEX_CSS)),no) +# if already installed csug, share katex.css and fonts + (if $(if $(findstring Windows,$(OS)),[ ! "windows" ],[ -e $(InstallCSUG)/katex/katex.css ] && [ ! -L $(InstallCSUG)/katex ]) ; \ + then \ + (cd $(installdir); ln -s -f $(relInstallCSUG)/katex katex) ; \ + else \ + $(INSTALL) -m 2755 -d $(installdir)/katex/fonts ; \ + $(INSTALL) -m 0644 --ifdiff katex/katex.css $(installdir)/katex/katex.css ; \ + $(INSTALL) -m 0644 --ifdiff katex/fonts/* $(installdir)/katex/fonts ; \ + fi) +endif # define any dependencies here diff --git a/stex b/stex index 5e4f0ca67..5d73fbfae 160000 --- a/stex +++ b/stex @@ -1 +1 @@ -Subproject commit 5e4f0ca67bac448e19a24c09f12fc16d24cd6b6d +Subproject commit 5d73fbfaeb0a1970bb5ac40c7f548e8c7aae7d33