Re: [racket-users] Re: scribble: referencing two identifiers with the same name?

2021-05-03 Thread Robby Findler 
Oh! Thanks!

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

Robby


On Mon, May 3, 2021 at 10:37 AM Sam Caldwell  wrote:

> 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
>
> On Mon, May 3, 2021 at 11:24 AM Robby Findler 
> wrote:
>
>> On Mon, May 3, 2021 at 10:19 AM Sam Caldwell  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
>>
>> --
> 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/CALuKBHvJFmaJB9nf9%2BSDRAR6HUNa2pXeC0eaRfJ7VQ1quiC4_w%40mail.gmail.com
> 
> .
>

-- 
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/CAL3TdONURvPexFUbFeRPeNap8Y%2B4cRjRS-XBMWPK-hOPQFqVGQ%40mail.gmail.com.

Re: [racket-users] Re: scribble: referencing two identifiers with the same name?

2021-05-03 Thread 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

On Mon, May 3, 2021 at 11:24 AM Robby Findler 
wrote:

> On Mon, May 3, 2021 at 10:19 AM Sam Caldwell  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
>
>

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

Re: [racket-users] Re: scribble: referencing two identifiers with the same name?

2021-05-03 Thread Robby Findler 
On Mon, May 3, 2021 at 10:19 AM Sam Caldwell  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

-- 
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/CAL3TdOMVtxi6wjwRpPAPOB70pqAY36UjB2Cry0H0PpqoRcbE5Q%40mail.gmail.com.

Re: [racket-users] Re: scribble: referencing two identifiers with the same name?

2021-05-03 Thread 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

On Sat, May 1, 2021 at 2:00 PM Ryan Kramer  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
> 
> .
>

-- 
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.

[racket-users] Re: scribble: referencing two identifiers with the same name?

2021-05-01 Thread 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.

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.