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 <default.kra...@gmail.com> 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 sa...@ccs.neu.edu 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 racket-users+unsubscr...@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 > <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 racket-users+unsubscr...@googlegroups.com. 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.
