Skip to content

Commit 8e8f4c2

Browse files
LiberalArtistLiberalArtist
committed
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
1 parent 0654a2d commit 8e8f4c2

File tree

6 files changed

+85
-18
lines changed

6 files changed

+85
-18
lines changed

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,10 @@
2424
/xc-*/
2525
/em-*/
2626
*.*run
27+
*.katex-css-link
2728
/csug/math/
2829
/csug/gifs/
30+
/csug/katex/
2931
/csug/Makefile
3032
/csug/*.aux
3133
/csug/*.html
@@ -50,6 +52,7 @@
5052
/csug/primdata.ss
5153
/release_notes/math/
5254
/release_notes/gifs/
55+
/release_notes/katex/
5356
/release_notes/Makefile
5457
/release_notes/*.tex
5558
/release_notes/*.aux

‎BUILDING

+19-1
Original file line numberDiff line numberDiff line change
@@ -307,7 +307,7 @@ The makefile supports several targets:
307307
* `make docs`
308308

309309
Runs the build plus generates HTML and PDF versions of the Chez
310-
Scheme Users Guide and the release notes. Unlike the other build
310+
Scheme User's Guide and the release notes. Unlike the other build
311311
targets, the documentation is not built in the workarea, but rather
312312
in the "csug" and "release_notes" directories (where "configure" is
313313
run).
@@ -320,6 +320,14 @@ The makefile supports several targets:
320320

321321
* ppmtogif and pnmcrop (from Netpbm)
322322

323+
* Optionally, KaTeX (for better math in HTML)
324+
325+
To use KaTeX but not copy the supporting CSS and font files
326+
(e.g. because you wish to link to a copy already installed on your
327+
system), use `make docs KATEX_CSS=no`. See also the documentation
328+
in the "stex/doc" directory for further details and additional
329+
configuration options.
330+
323331
An X11 installation is not required, but ppmtogif does require an
324332
"rgb.txt" file, which it will automatically locate in the common
325333
X11 installation locations. If ppmtogif fails because it cannot
@@ -330,6 +338,16 @@ The makefile supports several targets:
330338
installation, then it might contain an "rgb.txt" in the directory
331339
identified by the `VIMRUNTIME` environment variable.
332340

341+
* `make csug` or `make release_notes`
342+
343+
Like `make docs`, but builds only the Chez Scheme User's Guide or
344+
the release notes, respectively.
345+
346+
* `sudo make install-docs` (or `install-csug` or `install-release_notes`)
347+
348+
Like `make docs` (or `make csug` or `make release_notes`, respectively),
349+
but also installs the built documentation.
350+
333351
* `make clean`
334352

335353
Removes all built elements from the workarea, and then removes

‎build.zuo

+11-3
Original file line numberDiff line numberDiff line change
@@ -233,20 +233,28 @@
233233
;; in parallel to doc-project-names
234234
'(InstallCSUG InstallReleaseNotes))
235235
(define (targets-for-doc name install-dir-key)
236-
(define doc-dir (at-dir ".." name)) ;; ".." goes out of the workarea
236+
(define doc-dir (at-dir ".." name)) ;; ".." goes out of the workarea FIXME not necessarily
237+
(define install-dir (hash-ref config install-dir-key))
237238
(define mf-in (at-source "makefiles" (~a "Makefile-" name ".in")))
238239
(define mf-out (build-path doc-dir "Makefile"))
239240
(define name-sym (string->symbol name))
241+
(define other-install-dir-key
242+
(car (remove install-dir-key doc-install-dir-keys)))
243+
(define other-install-dir
244+
(hash-ref config other-install-dir-key))
240245
(define (run-make target)
241246
(check-not-kernel-only)
242247
(define (->rel-shell pth)
243248
(string->shell (find-relative-path doc-dir pth)))
244249
(shell/wait "make"
245250
(~a "m=" m)
246251
(~a "srcdir=" (->rel-shell (at-source name)))
247-
(~a "installdir="
248-
(->rel-shell (hash-ref config install-dir-key)))
252+
(~a "installdir=" (->rel-shell install-dir))
249253
(~a "STEXLIB=" (->rel-shell stexlib))
254+
(~a other-install-dir-key "=" (->rel-shell other-install-dir))
255+
(~a "rel" other-install-dir-key "="
256+
(string->shell (find-relative-path install-dir
257+
other-install-dir)))
250258
target
251259
(hash 'dir doc-dir)))
252260
`([:target ,mf-out (,mf-in)

‎makefiles/Makefile-csug.in

+36-12
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
srcdir=oops-missing-srcdir
22
installdir=oops-missing-installdir
3+
InstallReleaseNotes=oops-missing-InstallReleaseNotes
4+
relInstallReleaseNotes=oops-missing-InstallReleaseNotes
35
m=oops-missing-m
46
STEXLIB=oops-missing-stexlib
57
# Zuo overrides the above variables when running `make`
@@ -17,18 +19,6 @@ DIR=$(shell basename `pwd`)
1719

1820
target: canned logcheck1 logcheck2 checklibs $(x).html $(x).pdf
1921

20-
install: target
21-
$(INSTALL) -m 2755 -d $(installdir)
22-
$(INSTALL) -m 0644 --ifdiff *.html *.css $(installdir)
23-
$(INSTALL) -m 0644 --ifdiff csug.pdf $(installdir)/csug9_9.pdf
24-
$(INSTALL) -m 2755 -d $(installdir)/canned
25-
$(INSTALL) -m 0644 --ifdiff canned/* $(installdir)/canned
26-
$(INSTALL) -m 2755 -d $(installdir)/gifs
27-
$(INSTALL) -m 0644 --ifdiff gifs/*.gif $(installdir)/gifs
28-
$(INSTALL) -m 2755 -d $(installdir)/$(mathdir)
29-
$(INSTALL) -m 0644 --ifdiff $(mathdir)/*.gif $(installdir)/$(mathdir)
30-
(cd $(installdir); ln -s -f $(x).html index.html)
31-
3222
# thrice is not enough when starting from scratch
3323
logcheck1: $(x).thirdrun
3424
@if [ -n "`grep 'Warning: Label(s) may have changed' $(x).log`" ] ; then\
@@ -50,6 +40,35 @@ logcheck2: $(x).thirdrun
5040

5141
include $(STEXLIB)/Mf-stex
5242

43+
install: target
44+
$(INSTALL) -m 2755 -d $(installdir)
45+
$(INSTALL) -m 0644 --ifdiff *.html *.css $(installdir)
46+
$(INSTALL) -m 0644 --ifdiff csug.pdf $(installdir)/csug9_9.pdf
47+
$(INSTALL) -m 2755 -d $(installdir)/canned
48+
$(INSTALL) -m 0644 --ifdiff canned/* $(installdir)/canned
49+
$(INSTALL) -m 2755 -d $(installdir)/gifs
50+
$(INSTALL) -m 0644 --ifdiff gifs/*.gif $(installdir)/gifs
51+
ifeq ($(strip $(KATEX)),)
52+
$(INSTALL) -m 2755 -d $(installdir)/$(mathdir)
53+
$(INSTALL) -m 0644 --ifdiff $(mathdir)/*.gif $(installdir)/$(mathdir)
54+
else ifneq ($(strip $(KATEX_CSS)),no)
55+
# if already installed release_notes, share katex.css and fonts
56+
(if $(if $(findstring Windows,$(OS)),[ ! "windows" ],[ -e $(InstallReleaseNotes)/katex/katex.css ] && [ ! -L $(InstallReleaseNotes)/katex ]) ; \
57+
then \
58+
(cd $(installdir); ln -s -f $(relInstallReleaseNotes)/katex katex) ; \
59+
else \
60+
$(INSTALL) -m 2755 -d $(installdir)/katex/fonts ; \
61+
$(INSTALL) -m 0644 --ifdiff katex/katex.css $(installdir)/katex/katex.css ; \
62+
$(INSTALL) -m 0644 --ifdiff katex/fonts/* $(installdir)/katex/fonts ; \
63+
fi)
64+
endif
65+
ifeq ($(OS),Windows_NT)
66+
cp $(installdir)/$(x).html $(installdir)/index.html
67+
else
68+
(cd $(installdir); ln -s -f $(x).html index.html)
69+
endif
70+
71+
5372
stexsrc = csug.stex title.stex copyright.stex contents.stex\
5473
preface.stex intro.stex use.stex expeditor.stex debug.stex foreign.stex\
5574
binding.stex control.stex objects.stex numeric.stex io.stex\
@@ -136,6 +155,11 @@ $(x).hprethirdrun: $(x).hsecondrun
136155
cat tspl.haux >> $x.haux
137156
touch $(x).hprethirdrun
138157

158+
$(x).hfourthrun: $(x).hprefourthrun
159+
$(x).hprefourthrun: $(x).hthirdrun
160+
cat tspl.haux >> $x.haux
161+
touch $(x).hprefourthrun
162+
139163
$(x).prefirstrun: $(texsrc) csug8.cls csug810.clo
140164

141165
$(x).firstrun: scheme.sty

‎makefiles/Makefile-release_notes.in

+15-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
srcdir=oops-missing-srcdir
22
installdir=oops-missing-installdir
3+
InstallCSUG=oops-missing-InstallCSUG
4+
relInstallCSUG=oops-missing-relInstallCSUG
35
m=oops-missing-m
46
STEXLIB=oops-missing-stexlib
57
# Zuo overrides the above variables when running `make`
@@ -42,10 +44,22 @@ install: $x.pdf $x.html
4244
fi)
4345
$(INSTALL) -m 2755 -d $(installdir)/gifs
4446
$(INSTALL) -m 0644 --ifdiff gifs/*.gif $(installdir)/gifs
45-
$(INSTALL) -m 2755 -d $(installdir)/math
4647
-rm -rf $(installdir)/$(mathdir)
48+
ifeq ($(strip $(KATEX)),)
49+
$(INSTALL) -m 2755 -d $(installdir)/math
4750
$(INSTALL) -m 2755 -d $(installdir)/$(mathdir)
4851
if [ -e $(mathdir)/0.gif ] ; then $(INSTALL) -m 0644 $(mathdir)/*.gif $(installdir)/$(mathdir) ; fi
52+
else ifneq ($(strip $(KATEX_CSS)),no)
53+
# if already installed csug, share katex.css and fonts
54+
(if $(if $(findstring Windows,$(OS)),[ ! "windows" ],[ -e $(InstallCSUG)/katex/katex.css ] && [ ! -L $(InstallCSUG)/katex ]) ; \
55+
then \
56+
(cd $(installdir); ln -s -f $(relInstallCSUG)/katex katex) ; \
57+
else \
58+
$(INSTALL) -m 2755 -d $(installdir)/katex/fonts ; \
59+
$(INSTALL) -m 0644 --ifdiff katex/katex.css $(installdir)/katex/katex.css ; \
60+
$(INSTALL) -m 0644 --ifdiff katex/fonts/* $(installdir)/katex/fonts ; \
61+
fi)
62+
endif
4963

5064
# define any dependencies here
5165

‎stex

0 commit comments

Comments
 (0)