CODEWITHSUNDEEP
racketdocumentationscribble
mindthief
mindthief

Reputation: 13383

How to Link to an Alias in Scribble Documentation for a Procedure?

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"?

Upvotes: 3

Views: 80

Answers (1)

Ryan Culpepper
Ryan Culpepper

Reputation: 10643

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.

Upvotes: 4

Related Questions