From 0e72026451bb5f0bba76c0126a33cb04796bf679 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. Also, use scheme.sty and scheme.hsty from stex instead of stale copies with ad-hoc changes. Depends on https://github.com/dybvig/stex/pull/7 --- .gitignore | 3 + BUILDING | 20 ++++++- build.zuo | 16 +++++- csug/csug.css | 2 + csug/csug.stex | 2 +- csug/csug8.cls | 14 ++++- csug/scheme.hsty | 33 ----------- csug/scheme.sty | 89 ----------------------------- makefiles/Makefile-csug.in | 52 ++++++++++++----- makefiles/Makefile-release_notes.in | 18 +++++- release_notes/releasenotes.css | 2 + release_notes/scheme.sty | 47 --------------- stex | 2 +- 13 files changed, 108 insertions(+), 192 deletions(-) delete mode 100644 csug/scheme.hsty delete mode 100644 csug/scheme.sty delete mode 100644 release_notes/scheme.sty 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 2f36a892b..3fe4dced0 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..146c0a9a0 100644 --- a/build.zuo +++ b/build.zuo @@ -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) diff --git a/csug/csug.css b/csug/csug.css index 083ce260b..b0bca9e86 100644 --- a/csug/csug.css +++ b/csug/csug.css @@ -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; } diff --git a/csug/csug.stex b/csug/csug.stex index 697f5e056..4d6efdcc4 100644 --- a/csug/csug.stex +++ b/csug/csug.stex @@ -53,7 +53,7 @@ % Just don't care about small overflows, most of the time: \iflatex -\hfuzz=16.0pt +\hfuzz=26.0pt \fi \iflatex diff --git a/csug/csug8.cls b/csug/csug8.cls index 0fdd1aaea..37ea2823a 100644 --- a/csug/csug8.cls +++ b/csug/csug8.cls @@ -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}]% @@ -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} @@ -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} diff --git a/csug/scheme.hsty b/csug/scheme.hsty deleted file mode 100644 index c8281c851..000000000 --- a/csug/scheme.hsty +++ /dev/null @@ -1,33 +0,0 @@ -\def\transerr#1{\raw{}} -\def\transin#1{\raw{}} -\def\transout#1{\raw{}} -\def\endtranserr#1{\raw{}} -\def\endtransin#1{\raw{}} -\def\endtransout#1{\raw{}} - -\def\schemeblankline{{\\\\}} -\def\schemelinestart{} -%%% handle numbered lines in scheme.sty and scheme.hsty -%%% ---have scheme-prep produce only \schemelinestart -% following is probably broken until we have tables, I suspect. -% Actually, the right way to fix this may be to use CSS -\def\schemelinestartnumbered#1{\raw{
}#1\raw{
}} - -\def\scheme#1{{\tt #1}} -\def\longcode\schemedisplay{\schemedisplay} -\def\noskip\schemedisplay{\schemedisplay} -\def\schemedisplay{\par\begingroup\tt\hardspaces} -\def\endschemedisplay{\endgroup\par} -\def\schemeindent{} -\def\schatsign{\raw{@}} -\def\schbackslash{\raw{\}} -\def\schcarat{\raw{^}} -\def\schdot{\raw{.}} -\def\schlbrace{\raw{&##123;}} -\def\schrbrace{\raw{&##125;}} -\def\schtilde{\raw{~}} -\def\schunderscore{\raw{_}} -\def\becomes{$\rightarrow$} -\def\is{$\Rightarrow$} -\def\si{\raw{}} -\def\var#1{\emph{#1}} diff --git a/csug/scheme.sty b/csug/scheme.sty deleted file mode 100644 index db437b665..000000000 --- a/csug/scheme.sty +++ /dev/null @@ -1,89 +0,0 @@ -\usepackage{color} -\def\transerr#1{\begingroup\slshape} -\def\transin#1{\begingroup\color{red}} -\def\transout#1{\begingroup\color{blue}} -\def\traceout#1{\begingroup\color{blue}} -\def\endtranserr#1{\endgroup} -\def\endtransin#1{\endgroup} -\def\endtransout#1{\endgroup} -\def\endtraceout#1{\endgroup} - -% this didn't work --- screwed up indentation: -\long\def\showinteraction#1#2{\begin{minipage}[t]{4.375in}#1\end{minipage}\hfill\fbox{\begin{minipage}[t]{2in}#2\end{minipage}}} -% so I resorted to this: -\def\startrepl{\begin{minipage}[t]{4.3in}} % was 4.375 and 2 when interactionwindow = 28 -\def\endrepl{\end{minipage}} -\def\startinteraction{\begin{minipage}[t]{2.2in}\vrule\begin{minipage}[t]{2.2in}\hrule\schemeindent=2pt} -\def\endinteraction{\hrule\end{minipage}\vrule\end{minipage}} - -\font\ninefivett=cmtt9 at 9.5pt -\newskip\ttglue -\ttglue=.5em plus .25em minus .15em -\font\tinyvar=cmti7 -\font\smallvar=cmti9 -\font\summarysizevar=cmti9 -\font\indexsizevar=cmti8 -\font\normalvar=cmti10 at 11pt -\def\schemelarge{% - \def\schemelarger{\fontsize{14}{16}}% - \def\schemesmaller{\fontsize{10}{12}}% - \def\tt{\fontsize{12}{14}\ttfamily}% - \def\var##1{{\normalvar##1\/}}} -\def\schemenormal{% - \def\schemelarger{\fontsize{12}{14}}% - \def\schemesmaller{\fontsize{8}{9}}% - \def\tt{\fontsize{10pt}{11pt}\ttfamily\ninefivett}% - \def\var##1{{\smallvar##1\/}}} -\def\schemesmall{% - \def\schemelarger{\fontsize{10}{12}}% - \def\schemesmaller{\fontsize{6}{7}}% - \def\tt{\fontsize{8}{9}\ttfamily}% - \def\var##1{{\smallvar##1\/}}} -\def\schemesummarysize{% - \def\schemelarger{\fontsize{10}{12}}% - \def\schemesmaller{\fontsize{6}{7}}% - \def\tt{\fontsize{8}{9}\ttfamily}% - \def\var##1{{\summarysizevar##1\/}}} -\def\schemeindexsize{% - \def\schemelarger{\fontsize{10}{12}}% - \def\schemesmaller{\fontsize{6}{7}}% - \def\tt{\fontsize{7}{8}\ttfamily}% - \def\var##1{{\indexsizevar##1\/}}} -\schemenormal - -\newskip\schemeindent -\schemeindent=0pt -{\obeyspaces\global\let =\ } -\def\schtilde{\raisebox{-.5ex}{\hbox{\char`\~}}} -\def\schdot{.} -\def\schcarat{\char`\^} -\def\schbackslash{\char`\\} -\def\schatsign{\char`\@} -\def\schunderscore{\char`\_} -\def\schlbrace{\char`\{} -\def\schrbrace{\char`\}} -\def\scheme#1{\mbox{\tt\frenchspacing\spaceskip=\ttglue#1}} - -\def\schemeblankline{\par\penalty-100\vskip .7\baselineskip} -\def\schemelinestart{{\leavevmode\hbox{\hskip \schemeindent\relax}}} -%%% handle numbered lines in scheme.sty and scheme.hsty -%%% ---have scheme-prep produce only \schemelinestart -\def\schemelinestartnumbered#1{{\leavevmode\hbox{\hbox to 1em {\hfil{\rm #1}} \hskip .5\schemeindent\relax}}} - -\def\noskip\schemedisplay{\begingroup% - \parindent=0pt% - \parskip=0pt% - \def\becomes{\hbox to 2em{\hfil$\rightarrow$\hfil}}% - \def\is{\hbox to 2em{\hfil$\Rightarrow$\hfil}}% - \def\si{\hbox to 2em{\hfil}}% - \interlinepenalty=2000% - \tt\obeyspaces\frenchspacing} -\def\schemedisplay{\beforeschemedisplay\noskip\schemedisplay} -\def\longcode\schemedisplay{\penalty-200\vskip 8pt plus 4pt% - \kern3pt\hrule\kern5pt\nobreak\noskip\schemedisplay} -\def\endschemedisplay{\par\endgroup\afterschemedisplay} -\def\var#1{{\normalsize\textrm{\textit{#1}}}} -\def\raw#1{#1} -\def\beforeschemedisplay{\penalty-100\vskip\parskip\vskip5pt} -\def\afterschemedisplay{\penalty-200\vskip5pt} - diff --git a/makefiles/Makefile-csug.in b/makefiles/Makefile-csug.in index 52da6af88..81e5fb27f 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-relInstallReleaseNotes 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\ @@ -57,7 +76,7 @@ stexsrc = csug.stex title.stex copyright.stex contents.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): @@ -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' | \ diff --git a/makefiles/Makefile-release_notes.in b/makefiles/Makefile-release_notes.in index 4abe8eb8d..59c0c9ef6 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` @@ -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 @@ -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/release_notes/releasenotes.css b/release_notes/releasenotes.css index ef7507d2c..a3958eeb8 100644 --- a/release_notes/releasenotes.css +++ b/release_notes/releasenotes.css @@ -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; } diff --git a/release_notes/scheme.sty b/release_notes/scheme.sty deleted file mode 100644 index 72e85ee84..000000000 --- a/release_notes/scheme.sty +++ /dev/null @@ -1,47 +0,0 @@ -\usepackage{color} -\def\transerr#1{\begingroup\slshape} -\def\transin#1{\begingroup\color{red}} -\def\transout#1{\begingroup\color{blue}} -\def\endtranserr#1{\endgroup} -\def\endtransin#1{\endgroup} -\def\endtransout#1{\endgroup} - -\newskip\ttglue -\let\ninefivett=\tt % \font\ninefivett=cmtt9 at 9.5pt -\ttglue=.5em plus .25em minus .15em -\newskip\schemeindent -\schemeindent=0pt -{\obeyspaces\global\let =\ } -\def\schtilde{\raisebox{-.5ex}{\hbox{\char`\~}}} -\def\schdot{.} -\def\schcarat{\char`\^} -\def\schbackslash{\char`\\} -\def\schatsign{\char`\@} -\def\schunderscore{\char`\_} -\def\schlbrace{\char`\{} -\def\schrbrace{\char`\}} -\def\scheme#1{\mbox{\ttfamily\ninefivett\frenchspacing\spaceskip=\ttglue#1}} - -\def\schemeblankline{\par\beforeschemedisplay} -\def\schemelinestart{{\leavevmode\hbox{\hskip \schemeindent\relax}}} -%%% handle numbered lines in scheme.sty and scheme.hsty -%%% ---have scheme-prep produce only \schemelinestart -\def\schemelinestartnumbered#1{{\leavevmode\hbox{\hbox to 1em {\hfil{\rm #1}} \hskip .5\schemeindent\relax}}} - -\def\noskip\schemedisplay{\begingroup% - \parindent=0pt% - \parskip=0pt% - \def\becomes{\hbox to 2em{\hfil$\rightarrow$\hfil}}% - \def\is{\hbox to 2em{\hfil$\Rightarrow$\hfil}}% - \def\si{\hbox to 2em{\hfil}}% - \interlinepenalty=2000% - \baselineskip=11pt plus 1pt\ninefivett\obeyspaces\frenchspacing} -\def\schemedisplay{\beforeschemedisplay\noskip\schemedisplay} -\def\longcode\schemedisplay{\penalty-200\vskip 8pt plus 4pt% - \kern3pt\hrule\kern5pt\nobreak\noskip\schemedisplay} -\def\endschemedisplay{\par\endgroup\afterschemedisplay} -\def\var#1{{\normalsize\textrm{\textit{#1}}}} -\def\raw#1{#1} -\def\beforeschemedisplay{\penalty-100\vskip\parskip\vskip5pt} -\def\afterschemedisplay{\penalty-200\vskip5pt} - diff --git a/stex b/stex index 5e4f0ca67..188d0ea67 160000 --- a/stex +++ b/stex @@ -1 +1 @@ -Subproject commit 5e4f0ca67bac448e19a24c09f12fc16d24cd6b6d +Subproject commit 188d0ea6789dc512f1925bae8d25ecbfcee75c8a