scribble: referencing two identifiers with the same name?

[Sam Caldwell]

Is there an easy way to refer to two different identifiers with the same name when writing scribble documentation?

For example, let's say I have a language with a `let` binding that operates more or less the same as racket's `let`. I wanted to write something like this:

```
@(require (prefix-in racket: (for-label racket/base)))

@defform[(let ([id expr] ...) body ...){
The same behavior as @racket[racket:let].
}

```

This doesn't seem to work; the reference to racket's `let` ends up including the `racket:` prefix and doesn't seem to resolve to the appropriate link.

I looked at Typed Racket's docs to see how it manages this problem, and found the following pattern:

```
@(module def-racket racket/base
   (require (for-label racket/base) scribble/manual)
   (define let-id (racket let))
   (provide let-id))

@(require 'def-racket)

@defform[(let ([id expr] ...) body ...){
The same behavior as @|let-id|.
}
```

source: https://github.com/racket/typed-racket/blob/master/typed-racket-doc/typed-racket/scribblings/reference/special-forms.scrbl

So my question is, is there an easier/more direct way to accomplish this (perhaps since these typed racket docs were written)?

It also looks like this pattern could be captured by a macro---has someone written that already?

Thanks,
Sam Caldwell

[Ryan Kramer]

Using the prefix should still link correctly. When I run the following program, it links to section 3.9 of the Racket Reference where `let` is defined. Does your link go somewhere else?

```

#lang scribble/manual

@(require (prefix-in racket: (for-label racket/base)))

@defform[(let ([id expr] ...) body ...)]{

 The same behavior as @(racket racket:let).
}

```

If you really want to remove the prefix, I don't know of any easier way than what you've already found. However, as a reader of the documentation I don't mind seeing the prefix. In fact, I think I would prefer to see it because then I can make a very good guess that it is talking about Racket's `let` without hovering or clicking the link.

[Sam Caldwell]

When I first ran Ryan's example, the reference to `racket:let` did not resolve to the proper link. After further investigating, this appears to be due to scribble's default behavior of not loading extra cross-referencing information [1]. If instead of `raco scribble`, I run `raco scribble +m` the link does resolve to the proper location. It also appears that DrRacket uses the +m option by default.

So my current understanding is that there is no barrier to linking to other forms if you rename them `for-label`, but if I want the same name to link to different parts of the documentation I need to do something like the Typed Racket example.

-Sam Caldwell

[1] https://docs.racket-lang.org/scribble/running.html?q=scribble#%28part._xref-flags%29

--
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/334007f4-0632-4814-8d22-9ad56f650d21n%40googlegroups.com.

[Robby Findler]

On Mon, May 3, 2021 at 10:19 AM Sam Caldwell <sa...@ccs.neu.edu> wrote:

When I first ran Ryan's example, the reference to `racket:let` did not resolve to the proper link. After further investigating, this appears to be due to scribble's default behavior of not loading extra cross-referencing information [1]. If instead of `raco scribble`, I run `raco scribble +m` the link does resolve to the proper location. It also appears that DrRacket uses the +m option by default.

Just a minor point of clarification: DrRacket uses the documentation built by `raco setup`; it doesn't build the docs itself. This is the same build of the docs you see with `raco docs`.

Robby

[Sam Caldwell]

Ah, I meant what happens when I open up my scribble file in DrRacket and press the "Scribble HTML" button. Maybe it would be more accurate to describe that as a plugin than DrRacket itself?

-Sam Caldwell

[Robby Findler]

Oh! Thanks!

Perhaps DrRacket's button should include the +m flag.

Robby

--
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/CALuKBHvJFmaJB9nf9%2BSDRAR6HUNa2pXeC0eaRfJ7VQ1quiC4_w%40mail.gmail.com.