local variables are hyperlinked in scribble/manual

[Jos Koot]

Hi,

I have:

 

#lang scribble/manual

@(require (for-label racket) scribble/eval)

@interaction[

(let ((set 1)) (add1 set))]

 

I prepare a HTML document with DrRacket (in Windows 10).

Works, but local variable set is hyperlinked to procedure set in the documents (racket/set). I would like this variable to be typeset as any other local variable. How can I do that without loosing the hyperlink where I do mean the procedure from racket/set ?

 

Thanks, Jos

[Ryan Kramer]

My favorite way to avoid this problem is simply to choose another name, or use `except-in` to avoid importing `set` for-label. But if you must use the name `set` and you want it linking to racket/set most of the time (but not this time), here is a technique I've used in the past:

#lang scribble/manual

@(require (for-label racket) scribble/eval

          (for-syntax racket
                      syntax/parse))

@(define-for-syntax (replace-helper stx orig-sym new-sym)
   (let ([content (syntax-e stx)])
     (cond
       [(list? content)
        (datum->syntax stx
                       (map (λ (child) (replace-helper child orig-sym new-sym))
                            content)
                       stx stx)]
       [(equal? orig-sym content)
        (datum->syntax #f new-sym stx #f)]
       [else
        stx])))

@(define-syntax (replace stx)
   (syntax-parse stx
     [(_ [orig:id new:id] body:expr)
      (replace-helper #'body (syntax-e #'orig) (syntax-e #'new))]))

@(replace
  [SET set]
  @interaction[
 (let ((SET 1)) (add1 SET))])

[Ryan Culpepper]

You can also use make-element-id-transformer, like this:

    (define-syntax SET
      (make-element-id-transformer
       (lambda _ #'(racketvarfont "set"))))

Then Scribble will automatically replace SET within rendered code with the element expression above.

Another trick is to break the for-label binding by introducing a local binding that shadows it. For example, if you write

    (let ([set #f])
      (racket set))

then the occurrence of `set` within the `racket` form isn't linked to `set` from racket/set. This trick relies on being able to put a let around the occurrences you don't want linked but not the ones that you do want linked, so it might not work in all cases.

Ryan

--
You received this message because you are subscribed to the Google Groups "Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to racket-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/ffd4f155-ee18-409d-b92f-9450d976220f%40googlegroups.com.

[Jos Koot]

Thank you Ryan and Ryan.

 

I think make-element-id-transformer is the easiest solution.

(let ([set #f])   (racket set)) is nice too because it can be used just where needed.

I’ll try if that works around an interaction too.

 

An expression containing ‘set’ both as local and as imported variable remains a problem, I think,

but never mind, that can and probably must be avoided.

 

Thanks again, Jos

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/CANy33qk3Q3F6uLx9_Y%2BRNUb4j-z4DEuH3_%2BEgSc4evnNHpoXgg%40mail.gmail.com.

 

[Simon Schlee]

I struggled with a similar case, in my case the easiest/simplest solution was to use:

@var[identifier] instead of @racket[identifier]

(this works well for function arguments, but might not work for your case)

https://docs.racket-lang.org/scribble/scribble_manual_code.html?q=var#%28form._%28%28lib._scribble%2Fmanual..rkt%29._var%29%29

Writing this mainly for others who have overlooked var like I did.

Simon

[Jos Koot]

default...@gmail.com gave me a clear and usable answer.

His email follows below.

Best wishes, Jos

 

 

 

From Ryan Kramer

[Ryan Kramer]

That was actually Ryan Culpepper. Sorry for the noise, but I can't implicitly take credit for something that I didn't do.

By the way, thank you Ryan C for both of those techniques. I've already happily used `make-element-id-transformer`

On Saturday, June 13, 2020 at 4:07:06 PM UTC-5, jos.koot wrote:

defaul...@gmail.com gave me a clear and usable answer.

[Jos Koot]

Well, thanks to both Ryan C and Ryan K.

Sorry for my confusion.

Best wishes, Jos Koot

 

From: Ryan Kramer
Sent: 14 June 2020 02:20
To: Racket Users
Subject: Re: [racket-users] Re: local variables arehyperlinkedinscribble/manual

 

That was actually Ryan Culpepper. Sorry for the noise, but I can't implicitly take credit for something that I didn't do.

--

You received this message because you are subscribed to the Google Groups "Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to racket-users...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/f7162464-1d7b-4113-8883-03f022f0cf5fo%40googlegroups.com.