Skip to content

Commit

Permalink
optionally use KaTeX for csug and release_notes
Browse files Browse the repository at this point in the history
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
  • Loading branch information
LiberalArtist committed Nov 19, 2023
1 parent 0654a2d commit 8e8f4c2
Show file tree
Hide file tree
Showing 6 changed files with 85 additions and 18 deletions.
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,10 @@
/xc-*/
/em-*/
*.*run
*.katex-css-link
/csug/math/
/csug/gifs/
/csug/katex/
/csug/Makefile
/csug/*.aux
/csug/*.html
Expand All @@ -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
Expand Down
20 changes: 19 additions & 1 deletion BUILDING
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand All @@ -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
Expand All @@ -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
Expand Down
14 changes: 11 additions & 3 deletions build.zuo
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
48 changes: 36 additions & 12 deletions makefiles/Makefile-csug.in
Original file line number Diff line number Diff line change
@@ -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`
Expand All @@ -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\
Expand All @@ -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\
Expand Down Expand Up @@ -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
Expand Down
16 changes: 15 additions & 1 deletion makefiles/Makefile-release_notes.in
Original file line number Diff line number Diff line change
@@ -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`
Expand Down Expand Up @@ -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

Expand Down

0 comments on commit 8e8f4c2

Please sign in to comment.