Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Optionally use KaTeX for csug and release_notes #761

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Optionally use KaTeX for csug and release_notes #761

wants to merge 1 commit into from

Conversation

LiberalArtist
Copy link
Contributor

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 dybvig/stex#7

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

ChezScheme/csug/smgmt.stex

Lines 167 to 171 in 0654a2d

Specifically, the target generation for any object in a collected
generation \var{g} is
$\mbox{min}(\mbox{max}(\mbox{\emph{g}}+1,\mbox{\emph{min-tg}}),\mbox{\emph{max-tg}})$, where
\scheme{static} is taken to have the value one greater
than the maximum nonstatic generation.

Before:

Screenshot 2023-11-19 at 18-17-10 Storage Management

After:

Screenshot 2023-11-19 at 18-19-41 Storage Management

@LiberalArtist LiberalArtist mentioned this pull request Nov 22, 2023
Open
@LiberalArtist
Copy link
Contributor Author

LiberalArtist commented Nov 22, 2023 •
edited
Loading

I've pushed some updates in response to @owaddell's dybvig/stex#7 (comment)

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 d46d53f. 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 --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 --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
Copy link
Contributor Author

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

@LiberalArtist
Copy link
Contributor Author

I've force-pushed a rebased commit that more completely addresses @owaddell's dybvig/stex#7 (comment) and the follow-up issues I described in #761 (comment). 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 dybvig/stex@c715b0b. It also turned out not to have been entirely successful at avoiding collisions, even before this PR, e.g.:

Screenshot of the Summary of Forms showing (compile-to-port objs op sfd wpoop covop mach hostop ext nortds?) colliding with procedure.

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:

Fixed screenshot of Summary of Forms showing that (compile-to-port objs op sfd wpoop covop mach hostop ext nortds?) no longer collides with procedure.

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 dybvig/stex#7 is merged (so the stex submodule can point to the merged, and ideally tagged, version).

@LiberalArtist
optionally use KaTeX for csug and release_notes
2aa6ce5 
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
@LiberalArtist
Copy link
Contributor Author

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 dybvig/stex#7 should be merged first so the submodule can point to the merged, and ideally tagged, commit.

@LiberalArtist LiberalArtist marked this pull request as ready for review February 25, 2024 18:22
@LiberalArtist LiberalArtist mentioned this pull request Jun 7, 2024
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@LiberalArtist