From a536e5becaba193474a197e4e55ba061b5ddca75 Mon Sep 17 00:00:00 2001 From: "D. Ben Knoble" Date: Sat, 23 Nov 2024 08:49:32 -0500 Subject: [PATCH 1/3] docs: fix contract links Include more for-label requires and use the correct names for ->, listof, and image-element? (the latter of which comes from the cached return value, which invokes image; in the uncached case, a filepath is returned, which is not actually an image-element?). --- scribblings/scribble-math.scrbl | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/scribblings/scribble-math.scrbl b/scribblings/scribble-math.scrbl index cc324789a..2147cb3ba 100644 --- a/scribblings/scribble-math.scrbl +++ b/scribblings/scribble-math.scrbl @@ -1,7 +1,10 @@ #lang scribble/manual @require[@for-label[scribble-math racket/base - scribble/core] + racket/contract + scribble/core + scribble/base + scribble/manual] @for-syntax[racket/base syntax/parse] scribble-math] @@ -110,21 +113,21 @@ details see the documentation of @racket[with-html5]. (the @tech[#:doc '(lib "scribblings/scribble/scribble.scrbl")]{prefix file} contains the @tt{DOCTYPE} line).} -@defparam[$-html-handler handler (→ (listof? string?) element?) +@defparam[$-html-handler handler (-> (listof string?) element?) #:value $-katex]{ A parameter whose value is a function called by @racket[$], to transform the math code into HTML. The @racket[$] function uses this parameter only when rendering the document as HTML.} -@defparam[$$-html-handler handler (→ (listof? string?) element?) +@defparam[$$-html-handler handler (-> (listof string?) element?) #:value $$-katex]{ A parameter whose value is a function called by @racket[$$], to transform the math code into HTML. The @racket[$$] function uses this parameter only when rendering the document as HTML. } -@defproc[($-katex [math (listof? string?)]) element?]{ +@defproc[($-katex [math (listof string?)]) element?]{ Produces an @racket[element?] which contains the given @racket[math] code, so that it is rendered as @tech{inline mode} math using KaTeX. More precisely, the resulting @@ -136,7 +139,7 @@ details see the documentation of @racket[with-html5]. @racket[($-katex "x^2")] renders as @$-katex{x^2}.} -@defproc[($$-katex [math (listof? string?)]) element?]{ +@defproc[($$-katex [math (listof string?)]) element?]{ Produces an @racket[element?] which contains the given @racket[math] code, so that it is rendered as @tech{display mode} math (centered, alone on its line) using KaTeX. More @@ -152,7 +155,7 @@ details see the documentation of @racket[with-html5]. @$$-katex{\sum_{i=0}^n x_i^3}} -@defproc[($-mathjax [math (listof? string?)]) element?]{ +@defproc[($-mathjax [math (listof string?)]) element?]{ Produces an @racket[element?] which contains the given @racket[math] code, so that it is rendered as @tech{inline mode} math using MathJax. More precisely, the resulting @@ -164,7 +167,7 @@ details see the documentation of @racket[with-html5]. @racket[($-mathjax "x^2")] renders as @$-mathjax{x^2}.} -@defproc[($$-mathjax [math (listof? string?)]) element?]{ +@defproc[($$-mathjax [math (listof string?)]) element?]{ Produces an @racket[element?] which contains the given @racket[math] code, so that it is rendered as @tech{display mode} math (centered, alone on its line) using KaTeX. More @@ -181,7 +184,7 @@ details see the documentation of @racket[with-html5]. @$$-mathjax{\sum_{i=0}^n x_i^3}} -@defproc[($-tex2svg [math (listof? string?)]) element?]{ +@defproc[($-tex2svg [math (listof string?)]) element?]{ Produces an @racket[element?] which contains the given @racket[math] rendered as an HTML SVG literal. It is rendered in @tech{inline mode} math using @tt{tex2svg}. @@ -197,7 +200,7 @@ details see the documentation of @racket[with-html5]. This procedure requires Racket 6.12 or later.} -@defproc[($$-tex2svg [math (listof? string?)]) element?]{ +@defproc[($$-tex2svg [math (listof string?)]) element?]{ Produces an @racket[element?] which contains the given @racket[math] rendered as an HTML SVG literal. It is rendered in @tech{display mode} math using @tt{tex2svg}. @@ -340,7 +343,7 @@ text $\sum x^3$ is typeset as-is, like the rest of the text. @defmodule[scribble-math/asymptote] -@defproc[(asymptote [#:cache cache? any/c #t] [str string?] ...+) image?]{ +@defproc[(asymptote [#:cache cache? any/c #t] [str string?] ...+) image-element?]{ Renders the figure described by the given strings using Asymptote. If @racket[cache?] is @racket[#f], then the resulting images are generated into temporary PNG, SVG and From 81b2514edd6d8b56b6c218676daea611e8cb484a Mon Sep 17 00:00:00 2001 From: "D. Ben Knoble" Date: Sat, 23 Nov 2024 08:57:03 -0500 Subject: [PATCH 2/3] asymptote: simplify string construction Preserve the exact content of the string while using a simpler construction. I think ~a (display-style) might be redundant on strings, but without contracts the input might be non-strings, so keep it. Even simpler would be (apply ~a #:separator "\n" s strs), but that changes the hash because it misses the final newline. An uncommitted version used (string-join (map ~a (cons s strs)) "\n" #:after-last "\n") for a similar effect. --- asymptote.rkt | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/asymptote.rkt b/asymptote.rkt index be9409a5a..226c19a0d 100644 --- a/asymptote.rkt +++ b/asymptote.rkt @@ -8,9 +8,7 @@ (define (asymptote #:cache [cache? #t] s . strs) (define single-str - (with-output-to-string - (lambda () (for ([str (in-list `(,s . ,strs))]) - (displayln str))))) + (string-append (apply ~a #:separator "\n" s strs) "\n")) (if cache? ;; cache: (let* ([asymptote-dir "asymptote-images"] @@ -54,4 +52,4 @@ (λ () ;(with-output-to-string (system (format "asy -v -f png -o ~a" tmp-file)))) - tmp-file))) ; HTML png PDF pdf \ No newline at end of file + tmp-file))) ; HTML png PDF pdf From a48c878927318a60f8ae1c81268db2eaf3f60c09 Mon Sep 17 00:00:00 2001 From: "D. Ben Knoble" Date: Sat, 23 Nov 2024 09:02:43 -0500 Subject: [PATCH 3/3] asymptote: remove display side-effect When building the documentation, the call to asymptote outputs the pwd and the checksum; this interrupts the new progress bar mechanism in recent Racket versions. Silence it by removing the display entirely. (Perhaps we should provide a function to get the hash or document how it is computed? The function could also accept a side-channel to communicate the hash to, such as a box. Modifying it to return multiple values would be a breaking change.) --- asymptote.rkt | 2 -- 1 file changed, 2 deletions(-) diff --git a/asymptote.rkt b/asymptote.rkt index 226c19a0d..c50c6135d 100644 --- a/asymptote.rkt +++ b/asymptote.rkt @@ -23,8 +23,6 @@ [pdf-path (build-path asymptote-dir pdf-name)] [svg-name (string-append md ".svg")] [svg-path (build-path asymptote-dir svg-name)]) - (display (current-directory)) (display md) (newline) - ;; create dir if neccessary (unless (directory-exists? asymptote-dir) (make-directory asymptote-dir))