Optionally use KaTeX for csug and release_notes

[LiberalArtist]

KaTeX renders LaTeX math ahead-of-time to MathML and/or HTML, as an alternative to rendering to GIF images. The most important benefit of using KaTeX is that its output is accessible to screenreaders and other assistive technologies, rather than appearing as <graphic>. The output also integrates with CSS, can be copied and pasted as text, can reflow across line breaks as needed, and doesn't suffer from pixelation.

Depends on https://github.com/dybvig/stex/pull/7

As an example, here is a comparison of the rendering of:

https://github.com/cisco/ChezScheme/blob/0654a2d8fee32bef7c2f1ff802437fbdc2c42f01/csug/smgmt.stex#L167-L171

Before:	
After:	

[LiberalArtist]

I've pushed some updates in response to @owaddell's https://github.com/dybvig/stex/pull/7#issuecomment-1820971301

In the process, I found that this repository contains the files:

• csug/scheme.sty
• csug/scheme.hsty
• release_notes/scheme.sty (n.b. no .hsty)

which are slightly different both from each other and from the versions in stex/inputs/, which they override.

Details (see follow-up comments for conclusions):

In the case of `csug/scheme.hsty`, it seemed mostly like an old version of the one from stex, so I've tried just deleting the file. For the others, the diffs (below) are more substantive and date back to the original open-source release https://github.com/cisco/ChezScheme/commit/d46d53ffe215083e1b27295e487edf047da987b2. However, from some quick grepping, it seems the macros like `schemesmall` aren't actually used anywhere. I'm inclined to try just deleting these, too, and consistently using the ones from stex, but I wanted to point it out in case someone knows the rationale behind e.g. the added `\baselineskip=11pt plus 1pt` in the definition of `\noskip` for the release notes. ```diff diff --git a/stex/inputs/scheme.sty b/csug/scheme.sty index 8e27c24c..db437b66 100644 --- a/stex/inputs/scheme.sty +++ b/csug/scheme.sty @@ -16,8 +16,41 @@ \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 =\ } @@ -29,7 +62,7 @@ \def\schunderscore{\char`\_} \def\schlbrace{\char`\{} \def\schrbrace{\char`\}} -\def\scheme#1{\mbox{\ttfamily\frenchspacing\spaceskip=\ttglue#1}} +\def\scheme#1{\mbox{\tt\frenchspacing\spaceskip=\ttglue#1}} \def\schemeblankline{\par\penalty-100\vskip .7\baselineskip} \def\schemelinestart{{\leavevmode\hbox{\hskip \schemeindent\relax}}} @@ -54,13 +87,3 @@ \def\beforeschemedisplay{\penalty-100\vskip\parskip\vskip5pt} \def\afterschemedisplay{\penalty-200\vskip5pt} -% From test/screenshotter/test.tex in the KaTeX source code, which says: -% > Based on LaTeX's definition of \LaTeX, with L changed to K and kerns -% > changed as in src/macros.js -\DeclareRobustCommand{\KaTeX}{\mbox{% -K\kern-.17em% -{\sbox0 T\vbox to\ht0{\hbox% - {\fontsize{.75em}{1em}\selectfont A}% -\vss}}% -\kern-.15em% -\TeX}} ``` ```diff diff --git a/stex/inputs/scheme.sty b/release_notes/scheme.sty index 8e27c24c..72e85ee8 100644 --- a/stex/inputs/scheme.sty +++ b/release_notes/scheme.sty @@ -2,21 +2,12 @@ \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}} \newskip\ttglue +\let\ninefivett=\tt % \font\ninefivett=cmtt9 at 9.5pt \ttglue=.5em plus .25em minus .15em \newskip\schemeindent \schemeindent=0pt @@ -29,9 +20,9 @@ \def\schunderscore{\char`\_} \def\schlbrace{\char`\{} \def\schrbrace{\char`\}} -\def\scheme#1{\mbox{\ttfamily\frenchspacing\spaceskip=\ttglue#1}} +\def\scheme#1{\mbox{\ttfamily\ninefivett\frenchspacing\spaceskip=\ttglue#1}} -\def\schemeblankline{\par\penalty-100\vskip .7\baselineskip} +\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 @@ -44,7 +35,7 @@ \def\is{\hbox to 2em{\hfil$\Rightarrow$\hfil}}% \def\si{\hbox to 2em{\hfil}}% \interlinepenalty=2000% - \tt\obeyspaces\frenchspacing} + \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} @@ -54,13 +45,3 @@ \def\beforeschemedisplay{\penalty-100\vskip\parskip\vskip5pt} \def\afterschemedisplay{\penalty-200\vskip5pt} -% From test/screenshotter/test.tex in the KaTeX source code, which says: -% > Based on LaTeX's definition of \LaTeX, with L changed to K and kerns -% > changed as in src/macros.js -\DeclareRobustCommand{\KaTeX}{\mbox{% -K\kern-.17em% -{\sbox0 T\vbox to\ht0{\hbox% - {\fontsize{.75em}{1em}\selectfont A}% -\vss}}% -\kern-.15em% -\TeX}} ```

[LiberalArtist]

Well, at least \schemesummarysize is used: I'll investigate further.

[LiberalArtist]

I've force-pushed a rebased commit that more completely addresses @owaddell's https://github.com/dybvig/stex/pull/7#issuecomment-1820971301 and the follow-up issues I described in https://github.com/cisco/ChezScheme/pull/761#issuecomment-1823340240. I've also pushed an un-squashed version of these changes to https://github.com/LiberalArtist/ChezScheme/tree/hist/katex-2.

It worked out to just remove csug/scheme.hsty and release_notes/scheme.sty and use the current versions from stex, but csug/scheme.sty (i.e. the PDF of the user's guide) needed a little more work. It had defined \schemesummarysize and \schemeindexsize to get tighter spacing for the summary of forms and the index, respectively, especially to make the entries in the summary of forms fit on a single line. The approach relied on implementation details: in particular, it assumed that redefining \tt would affect the expansion of \scheme{}, whereas the stex version of scheme.sty has instead used \ttfamily since its initial public release in https://github.com/dybvig/stex/commit/c715b0b70894476b4acdfafe39f29b8555458bb4. It also turned out not to have been entirely successful at avoiding collisions, even before this PR, e.g.:

I inlined the non-dead code from \schemesummarysize and \schemeindexsize into the definitions of theindex and thesummary in csug8.cls, allowing me to remove csug/scheme.sty and use the version from stex. I was able to fix the collisions by tightening \spaceskip and using a slightly smaller font size for the formal parameters:

After these fixes, the following overfull \hbox warnings remained and were treated as errors by the logcheck build step:

Overfull \hbox (17.36086pt too wide) in paragraph at lines 2925--2928
Overfull \hbox (16.00319pt too wide) in paragraph at lines 3679--3691
Overfull \hbox (25.58617pt too wide) in paragraph at lines 3861--3872
Overfull \hbox (16.2795pt too wide) in paragraph at lines 5227--5480
Overfull \hbox (19.06062pt too wide) in paragraph at lines 401--404
Overfull \hbox (16.2795pt too wide) in paragraph at lines 3083--3100

I have not managed to find the offending \hboxes, and I've just about exhausted my LaTeX debugging skills (which I don't feel are particularly strong). Instead, the latest commit increases \hfuzz (from 16.0pt to 26.0pt) to just ignore the problem.

At this point, I think this PR is ready to merge as soon as https://github.com/dybvig/stex/pull/7 is merged (so the stex submodule can point to the merged, and ideally tagged, version).

[LiberalArtist]

I've rebased this on the latest main. I'm marking this PR as "ready for review" to reflect the fact that I think it is complete, but I still think https://github.com/dybvig/stex/pull/7 should be merged first so the submodule can point to the merged, and ideally tagged, commit.