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 does not
suffer from the pixelation of math rendered to GIFs.

Also, use scheme.sty and scheme.hsty from stex instead of
stale copies with ad-hoc changes.

Depends on dybvig/stex#7
  • Loading branch information
LiberalArtist committed Dec 1, 2023
1 parent a8c93ed commit 0e72026
Show file tree
Hide file tree
Showing 13 changed files with 108 additions and 192 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
16 changes: 14 additions & 2 deletions build.zuo
Original file line number Diff line number Diff line change
Expand Up @@ -239,14 +239,26 @@
(define name-sym (string->symbol name))
(define (run-make target)
(check-not-kernel-only)
;; Note: build.bat on Windows does not currently configure these
;; settings, so only evaluate (hash-ref config ...) when trying to
;; build a target, not while merely generating the list of targets.
(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)
Expand Down
2 changes: 2 additions & 0 deletions csug/csug.css
Original file line number Diff line number Diff line change
Expand Up @@ -33,3 +33,5 @@ h1, h2, h3, h4 {font-weight: bold}

table.indent {margin-left: 20px}

.schemedisplay { line-height: 1.0625; }
.schemedisplay .katex { font-size: 1em; }
2 changes: 1 addition & 1 deletion csug/csug.stex
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@

% Just don't care about small overflows, most of the time:
\iflatex
\hfuzz=16.0pt
\hfuzz=26.0pt
\fi

\iflatex
Expand Down
14 changes: 12 additions & 2 deletions csug/csug8.cls
Original file line number Diff line number Diff line change
Expand Up @@ -376,7 +376,11 @@
%%% index
\newenvironment{theindex}
{\if@openright\cleardoublepage\else\clearpage\fi
\begingroup\raggedright\schemeindexsize\footnotesize
\begingroup\raggedright\footnotesize
% tighten spacing for entries:
% may need to adjust this for future changes in stex
\def\scheme##1{\mbox{\fontsize{7}{8}\ttfamily\frenchspacing\spaceskip=0.5\fontdimen2\font plus \fontdimen3\font minus 0.5\fontdimen4\font##1}}
\def\var##1{{\footnotesize\textit{##1}}}
\columnseprule \z@
\columnsep 35\p@
\twocolumn[\plainchapterhead{\indexname}]%
Expand Down Expand Up @@ -457,6 +461,8 @@
\def\categorymodule{module}
\def\categoryftype{ftype}

%%% summary of forms
% see also summary.stex and summary.ss
\newwrite\forms
\openout\forms=\jobname.rfm
% \formsummary{sort key}{type}{form}{label}
Expand All @@ -471,7 +477,11 @@
\hbox to 5pc{#2\ \hfil}%
\hfil #3}}
\newenvironment{thesummary}
{\begingroup\schemesummarysize\small\bigskip
{\begingroup\small\bigskip%
% tighten spacing to fit entries on one line:
% may need to adjust this for future changes in stex
\def\scheme##1{\mbox{\fontsize{8}{9}\ttfamily\frenchspacing\spaceskip=0.5\fontdimen2\font plus \fontdimen3\font minus 0.5\fontdimen4\font##1}}%
\def\var##1{{\footnotesize\textit{##1}}}%
\sfentry{{\slshape Form}}{{\slshape Category}}{{\slshape Page}}
\kern3pt\hrule\kern3pt}
{\endgroup}
Expand Down
33 changes: 0 additions & 33 deletions csug/scheme.hsty

This file was deleted.

89 changes: 0 additions & 89 deletions csug/scheme.sty

This file was deleted.

52 changes: 38 additions & 14 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-relInstallReleaseNotes
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,14 +40,43 @@ 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\
libraries.stex syntax.stex system.stex smgmt.stex threads.stex\
compat.stex bibliography.stex summary.stex
texsrc = ${stexsrc:%.stex=%.tex}

moresrc = tspl4-prep.stex priminfo.ss docond.ss csug8.cls csug8.hcls csug810.clo scheme.sty csug.bib \
moresrc = tspl4-prep.stex priminfo.ss docond.ss csug8.cls csug8.hcls csug810.clo csug.bib \
setup.ss summary.ss tspl.bst

$(stexsrc) $(moresrc):
Expand Down Expand Up @@ -136,9 +155,14 @@ $(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
$(x).firstrun:

tspl.aux: ${TSPLdir}/tspl.aux
cat ${TSPLdir}/*.aux | grep '\\newlabel' | \
Expand Down
18 changes: 16 additions & 2 deletions 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 All @@ -25,7 +27,7 @@ bib =
include $(STEXLIB)/Mf-stex

srcs = $(x).stex releasenotes.cls releasenotes.hcls \
macros.stex releasenotes.css scheme.sty
macros.stex releasenotes.css

# define or override suffixes here

Expand All @@ -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
2 changes: 2 additions & 0 deletions release_notes/releasenotes.css
Original file line number Diff line number Diff line change
Expand Up @@ -55,3 +55,5 @@ table.indent {margin-left: 20px}
.tag{ color: navy; font-weight: bold; }
.entity{ color: purple; font-weight: bold; }
.errflag{ color: red; font-weight: bold; }
.schemedisplay { line-height: 1.0625; }
.schemedisplay .katex { font-size: 1em; }
Loading

0 comments on commit 0e72026

Please sign in to comment.