Scribble Enhanced🔗 i

1.1Easy rendering of quotes and syntax reader abbreviations🔗 i

The six common reader abbreviations are rendered as expected, using a heuristic on source locations (so that #‘ renders as #‘ and not quasisyntax when the source location span is exactly two characters, for example).

(defform#:kind"example"

(example-1a

#'(barg…)

#`(carg…)

#,(darg…)

'd

`e

,f

(syntax (earg…))

(quasisyntax (farg…))

(unsyntax (garg…))

(quote d)

(quasiquote e)

(unquote f)))

The above example renders as (with reader abbreviations for the first six, but not for the last six):

example

( example-1a

#'(barg…)

#`(carg…)

#,(darg…)

'd

`e

,f

(syntax (aarg…))

(quasisyntax (barg…))

(unsyntax (carg…))

(quote d)

(quasiquote e)

(unquote f))

1.2#:result for defform🔗 i

(defform#:kind"example"

(example-2a#'([bc]... ))

#:resultvoid?

#:contracts([aport? ]

[bnumber? ]

[cstring? ])

"Example description")

The code above renders as follows:

example

( example-2a#'([bc]...))

→ void?

a : port?

b : number?

c : string?

Example description

1.3Arbitrary rewriting of code in racketblock and similar🔗 i

This could be useful to typeset code using the xlist package, which rewrites identifiers ending with a superscript to mean repetition, so that (define-typethree-ints(xListInteger³)) is equivalent to (define-typethree-ints(ListIntegerIntegerInteger)).

;Correctly display xyz⃰, xyzⁿ, xyz⁰, xyz¹, … xyz⁹

(begin-for-syntax

(mutable-match-lambda-add-overriding-clause!

mutable-match-element-id-transformer

#:match-lambda

[(?identifier?

whole-id

(app(compose symbol->string syntax-e )

(pregexp #px"^(.*?)(⃰|ⁿ|[⁰¹²³⁴⁵⁶⁷⁸⁹]+)$"

(list wholebasepower))))

(define/with-syntaxbase-id(format-idwhole-id"~a"base))

(define/with-syntaxpower-characters

(string-join

(map (match-lambda["⃰""*"]

["ⁿ""n"]

["⁰""0"]["¹""1"]["²""2"]["³""3"]["⁴""4"]

["⁵""5"]["⁶""6"]["⁷""7"]["⁸""8"]["⁹""9"])

(map string (string->list power)))))

#'(elem(list (racketbase-id)

(superscriptpower-characters)))]))

Another use case would be a hack to correctly colour syntax classes from syntax-parse, when used as attr:stxclass. Here is how it would be defined:

(begin-for-syntax

(mutable-match-lambda-add-overriding-clause!

mutable-match-element-id-transformer

#:match-lambda

[(?identifier?

whole-id

(app(compose symbol->string syntax-e )

(pregexp #px"^([^:]*):([^:]*)$"

(list wholeattrcls))))

(define/with-syntaxattr-id(format-idwhole-id"~a"attr))

(define/with-syntaxcls-id(format-idwhole-id"~a"cls))

#'(elem(list (racketattr-id)

(elem#:style'tt":")

(racketcls-id)))]))

The code for these two examles would be inserted directly inside the document, before any racketblock, chunk or similar.

This feature is experimental, and may be changed in future versions.

Added in version 0.2 of package scribble-enhanced.
Changed in version 0.3: Deprecated in favour of scribble-render-as.

NOTE: This syntax property is deprecated; use scribble-render-as, instead. Deprecated as of scribble-enhanced version 0.3, because 'scribble-render only supports single-line replacements. The new 'scribble-render-as property is more flexible.

procedure

( scribble-render-as-proc self

id

typeset-expr

uncode-id

d->s-expr

stx-prop-expr) → stx-list?

self:syntax?

id:identifier?

typeset-expr:syntax?

uncode-id:identifier?

d->s-expr:syntax?

stx-prop-expr:syntax?

The first argument, self, is the whole syntax object bearing the 'scribble-render-as property. The other arguments are the (quoted syntax form of) the arguments passed to the define-code macro which generated the form currently rendering the code. The most useful argument is uncode, indicating which identifier should be used in place of unsyntax to escape the current form, which will be racketblock, RACKETBLOCK or another similar form.

The function must return a syntax object which will be spliced in place of the original when rendering. Note that the returned syntax object will be spliced, i.e. the outer pair of parentheses removed. If the original syntax object must be replaced by foo, then #'foo must be returned. The splicing operation allows several tokens to be rendered. For example, in (racketblockabc), if b has the 'scribble-render-as property, and the function returns #'(xyz), then the whole form will be rendered like (racketblockaxyzc).

As an example, here is the 'scribble-render-as procedure used by aful, to render the lambda shorthand notation "#λ(+ % 1)":

(define (aful-scribble-renderselfidcodetypeset-codeuncoded->sstx-prop)

(syntax-case self()

;#λ(body) reads as:

;(lambda args

; (define-syntax % (make-rename-transformer #'%1))

; body)

[(_ _ _ body)

(with-syntax ([uncode(datum->syntax uncode(syntax-e uncode)self)])

(syntax/top-locself

((uncode(seclink"_lang_aful"

#:doc'(lib"aful/docs/aful.scrbl")

(tt"#λ")))

body)))]))

This feature is experimental, and may be changed in future versions.

Added in version 0.3 of package scribble-enhanced.