3

In writing Scribble docs for a function, I'd like to link to a built-in function that has the same name as a different function that's being documented in the same Scribble file. Normally @racketlink is usable for this purpose (together with something like prefix-in to differentiate the two functions in the document namespace), but this doesn't appear to work when the link needs to be within the arguments section of a @defproc form. For instance:

@defproc[(my-proc [f procedure? b:compose])
         any/c]{

 A procedure similar to @racketlink[b:compose]{compose}.

}

Note the two usages of b:compose above. The latter link to b:compose renders simply as compose (as expected) but if I try the same code in former instance (in the arguments block), it renders as (racketlink b:compose "compose"). How does one "escape" the literal treatment of the content within the defproc arguments block? Does this have anything to do with Scribble's notions of "content" and "pre-content" and the process of "decoding"?

mindthief
  • 12,755
  • 14
  • 57
  • 61

1 Answers1

4

Forms like @racket[_], @defproc[_], etc let you use #, (which reads as unsyntax) to escape from a code typesetting context. So you should be able to write your example as

@defproc[(my-proc [f procedure? #, @racketlink[b:compose]{compose})
         any/c]{ .... }

Note the space between the #, and the @, needed to prevent the reader from reading the whole sequence as unsyntax-splicing. You can also write the combination as @#, because of the way the @ reader interacts with reader abbreviations like #,.

The decoding step that turns pre-content (or pre-flow, etc) into content (or flow, etc) is unrelated. See the docs for scribble/decode.

Ryan Culpepper
  • 10,495
  • 4
  • 31
  • 30
  • This works well. Just one thing though, the rendered `compose` in this case is typeset as normal text (e.g. using serifed font) rather than as code. Anything we can do about that? – mindthief Jun 03 '20 at 19:06
  • Actually, it looks like this is normal behavior for `racketlink` and not particular to its usage here (it's just more obvious when surrounded by code as it is in this case). I got it to typeset as code by nesting a `racket` inside it: `#, @racketlink[b:compose]{@racket[compose]}` I had assumed that `@racketlink` was an alternative to `@racket`, intended so that we could link to a different source than it would do on its own, but I guess that's not the case, and the auto-linking happens independently of typesetting with the `@racket` tag. – mindthief Jun 03 '20 at 20:03