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 On Sat, May 1, 2021 at 2:00 PM Ryan Kramer <[email protected]> wrote: > 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. > > On Friday, April 30, 2021 at 11:01:20 AM UTC-5 [email protected] wrote: > >> 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 >> > -- > 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 [email protected]. > To view this discussion on the web visit > https://groups.google.com/d/msgid/racket-users/334007f4-0632-4814-8d22-9ad56f650d21n%40googlegroups.com > <https://groups.google.com/d/msgid/racket-users/334007f4-0632-4814-8d22-9ad56f650d21n%40googlegroups.com?utm_medium=email&utm_source=footer> > . > -- 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 [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/CALuKBHsNBmvrNYpTE_hSvp%3D6-gTxQCerhC-Gr4bkf5-gHGLp%3Dg%40mail.gmail.com.
