►Rhombus Scribble
▼3 Core Scribble
On this page:
hyperlink
url
secref
Secref
seclink
docref
elemtag
elemref
9.0.0.6
  top  contents    up   

3.6 Hyperlinks🔗ℹ

function

fun hyperlink(

  url_str :: String,

  pre_content :: PreContent,

  ~underline: underline = #true,

  ~style: style :: maybe(Style || String || Symbol) = (if underline

                                                       | #false

                                                       | "plainlink")

) :: Element

 

function

fun url(dest :: String) :: Element

The hyperlink function creates an element that typesets as the given pre_content, but that is hyperlinked to url_str (if supported by the renderer). The underline argument is a shorthand way to select the default style argument.

The url function is a shorthand to providing the same string to hyperlink as both url_str and pre_content.

function

fun secref(

  tag :: String,

  ~doc: module_path :: maybe(ModulePath) = #false,

  ~tag_prefixes: prefixes :: maybe(List.of(String)) = #false,

  ~underline: underline = #true,

  ~ref_style: ref_style :: maybe(LinkRenderStyle) = #false

) :: Element

Inserts a reference to the section tagged with tag, including a hyperlink if supported by the renderer.

If a module path is provided via ~doc: module_path, the tag refers to a tag with a prefix determined by module_path. When raco setup renders documentation, it automatically adds a tag prefix to the document based on the source module. So, for example, to refer to a section of the Rhombus guide, module_path would be ModulePath'lib("rhombus/scribblings/rhombus.scrbl")'.

The ~tag_prefixes: prefixes argument similarly supports selecting a particular section as determined by a path of tag prefixes. When a ~doc argument is provided, then prefixes should trace a path of tag-prefixed subsections to reach the tag section. When ~doc is not provided, the prefixes path is relative to any enclosing section (i.e., the youngest ancestor that produces a match).

If ref_style is not #false, then it is attached as a style property and affects the rendering of the link. Alternatively, an enclosing part can have a LinkRenderStyle property that adjusts the rendering style for all links within the part. See LinkRenderStyle for more information about the rendering of section references.

If underline is #false, then a style is attached to the result so that the hyperlink is rendered in HTML without an underline.

In Racket and Rhombus documentation that is rendered to HTML, clicking on a section title normally shows a Rhombus secref or Racket secref call that is needed to link to the section—and the module path will need conversion to use it with a secref variant diferent from the one that is shown.

function

fun Secref(

  tag :: String,

  ~doc: module_path :: maybe(ModulePath) = #false,

  ~tag_prefixes: prefixes :: maybe(List.of(String)) = #false,

  ~underline: underline = #true,

  ~ref_style: ref_style :: maybe(LinkRenderStyle) = #false

) :: Element

Like secref, but if the rendered form of the reference starts with a word (e.g., “section”), then the word is capitalized.

function

fun seclink(

  tag :: String,

  pre_content :: PreContent = [],

  ~doc: module_path :: maybe(ModulePath) = #false,

  ~tag_prefixes: prefixes :: maybe(List.of(String)) = #false,

  ~underline: underline = #true,

  ~indirect: indirect = #false

) :: Element

Like secref, but the link is rendered as pre_content instead of the target section’s name.

In addition to secref’s arguments, seclink supports a indirect argument. When indirect is true, then the section hyperlink’s resolution in HTML is potentially delayed until the HTML is viewed, and it may link to a documentation server instead of requiring installed documentation.

function

fun docref(

  module_path :: ModulePath,

  ~underline: underline = #true,

  ~indirect: indirect :: maybe(Content) = #false

) :: Element

Like secref for a document’s implicit "top" tag.

If indirect is content, then the link’s resolution in HTML can be delayed, like seclink with ~indirect: #true. The indirect content is prefixed with “the” and suffixed with ““documentation” to generate the rendered text of the link. For example,

@docref(ModulePath'lib("parsack/parsack/parsack.scrbl")',

        ~indirect: "Parsec implementation in Racket")

renders as a hyperlink with the text

the Parsec implementation in Racket documentation

function

fun elemtag(

  t :: (Taglet || GeneratedTag),

  pre_content :: PreContent

) :: Element

 

function

fun elemref(

  t :: (Taglet || GeneratedTag),

  pre_content :: PreContent,

  ~underline: underline = #true

) :: Element

The elemtag function renders as pre_content, but establishes a target for hyperlinks using a tag build with t.

The elemref function renders as pre_content, but hyperlinked to the target established by elemtag with t.

  top  contents    up