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 "<graphic>"), and it also looks less
pixelated than math rendered to GIFs.

Depends on dybvig/stex#7

Author: LiberalArtist

.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

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

build.zuo

@@ -233,20 +233,28 @@
     ;; 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)) ;; ".." goes out of the workarea FIXME not necessarily
+    (define install-dir (hash-ref config install-dir-key))
     (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 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 (run-make target)
       (check-not-kernel-only)
       (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)

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

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