[add] native cross-ref syntax (#34)

docs/template.typ

@@ -88,7 +88,7 @@
   body
 }
 
-#let ref-fn(name) = link(label("tidy" + name), raw(name))
+#let ref-fn(name) = link(label("tidy-" + name), raw(name))
 
 #let file-code(filename, code) = pad(x: 4%, block(
   width: 100%, 

docs/tidy-guide.typ

@@ -139,7 +139,7 @@ We can now parse the module and pass the module `wiggly` through the `scope` par
   read("wiggly.typ"), 
   name: "wiggly",
   scope: (wiggly: wiggly),
-  preamble: "import wiggly: *;"
+  preamble: "#import wiggly: *\n"
 )
 ```
 
@@ -152,7 +152,7 @@ In the output, the preview of the code examples is shown next to it.
     read("/examples/wiggly.typ"), 
     name: "wiggly",
     scope: (wiggly: wiggly),
-    preamble: "import wiggly: draw-sine;", 
+    preamble: "#import wiggly: *\n", 
     old-parser: false
   )
   tidy-output-figure(tidy.show-module(module, show-outline: false))
@@ -255,7 +255,7 @@ Currently, the two predefined styles `tidy.styles.default` and `tidy-styles.mini
     read("/examples/wiggly.typ"), 
     name: "wiggly",
     scope: (wiggly: wiggly),
-    preamble: "import wiggly: *;",
+    preamble: "#import wiggly: *\n",
     old-parser: false
   )
   tidy-output-figure(tidy.show-module(module, show-outline: false, style: tidy.styles.minimal))

examples/wiggly.typ

@@ -1,7 +1,10 @@
 /// Draw a sine function with $n$ periods into a rectangle of given size.
 ///
 /// *Example:*
-/// #example(`draw-sine(1cm, 0.5cm, 2)`)
+/// 
+/// ```example
+/// #draw-sine(1cm, 0.5cm, 2)
+/// ```
 ///
 /// -> content
 #let draw-sine(
@@ -13,8 +16,11 @@
   height, 
 
   /// Number of periods to draw. 
-  ///      Example with many periods: 
-  ///      #example(`draw-sine(4cm, 1.3cm, 10)`)
+  /// 
+  /// Example with many periods: 
+  /// ```example
+  /// #draw-sine(4cm, 1.3cm, 10)
+  /// ```
   /// -> int | float
   periods
 ) = box(width: width, height: height, {

src/helping.typ

@@ -20,7 +20,7 @@
   if type(entry) != array {
     entry = (entry,)
   }
-  parse-module(entry.map(x => x()).join("\n"), old-parser: old-parser)
+  parse-module(entry.map(x => x()).join("\n"), old-parser: old-parser, label-prefix: "help-")
 }
 
 #let search-docs(search, searching, namespace, style, old-parser: false) = {
@@ -55,7 +55,7 @@
   module.variables = variables
   return help-box({ 
     show search: highlight.with(fill: rgb("#FF28")) 
-    show-module(module, style: style)
+    show-module(module, style: style, enable-cross-references: false)
   })
 }
 
@@ -173,7 +173,7 @@
       style: style,
       enable-cross-references: false,
       enable-tests: false,
-      show-outline: false
+      show-outline: false,
     )
   }
   return result

src/parse-module.typ

@@ -100,7 +100,7 @@
 /// - `types` (optional): A list of accepted argument types. 
 /// - `default` (optional): Default value for this argument.
 /// 
-/// See @@show-module() for outputting the results of this function.
+/// See @show-module for outputting the results of this function.
 #let parse-module(
 
   /// Content of `.typ` file to analyze for docstrings. 
@@ -137,7 +137,7 @@
   /// -> boolean
   old-parser: true
 ) = {
-  if label-prefix == auto { label-prefix = name }
+  if label-prefix == auto { label-prefix = name + "-" }
 
   let docs = (
     name: name,

src/show-example.typ

@@ -33,6 +33,10 @@
   col-spacing: 5pt,
   ..options
 ) = {
+  let content = code.text
+  let displayed-code = code.text.split("\n").filter(x => not x.starts-with(">>>")).join("\n")
+  let executed-code = code.text.split("\n").map(x => x.trim(">>>", at: start)).join("\n")
+
   let lang = if code.has("lang") { code.lang } else { "typc" }
   if mode == auto {
     if lang == "typ" { mode = "markup" }
@@ -41,11 +45,12 @@
   if mode == "markup" and not code.has("lang") { 
     lang = "typ" 
   }
+  code = raw(displayed-code, lang: lang, block: true)
   if code.has("block") and code.block == false {
-    code = raw(code.text, lang: lang, block: true)
+    // code = raw(code.text, lang: lang, block: true)
   }
 
-  let preview = [#eval(preamble + code.text, mode: mode, scope: scope + inherited-scope)]
+  let preview = [#eval(preamble + executed-code, mode: mode, scope: scope + inherited-scope)]
 
   let preview-outer-padding = 5pt
   let preview-inner-padding = 5pt
@@ -118,4 +123,16 @@
       else { measure(arrangement(width: size.width)).height }
     arrangement(height: height)
   })
+}
+
+#let render-examples(body) = {
+  show raw.where(lang: "example"): it => {
+    set text(4em / 3)
+
+    show-example(
+      raw(it.text, block: true, lang: "typ"), 
+      mode: "markup"
+      )
+  }
+  body
 }

src/show-module.typ

@@ -3,14 +3,16 @@
 #import "testing.typ"
 
 
+#let def-state = state("tidy-definitions", (:))
+
 
 /// Show given module in the given style.
 /// This displays all (documented) functions in the module.
 ///
 /// -> content
 #let show-module(
 
-  /// Module documentation information as returned by @@parse-module(). 
+  /// Module documentation information as returned by @parse-module. 
   /// -> dictionary
   module-doc, 
 
@@ -27,7 +29,7 @@
   /// -> int
   first-heading-level: 2,
 
-  /// Whether to output the name of the module at the top.  
+  /// Whether to output the name of the module at the top. 
   /// -> boolean
   show-module-name: true,
 
@@ -126,6 +128,32 @@
 
   style-args.scope = eval-scope
 
+  def-state.update(x => {
+    x + module-doc.functions.map(x => (x.name, 1)).to-dict() + module-doc.variables.map(x => (x.name, 0)).to-dict()
+  })
+
+  show ref: it => {
+    let target = str(it.target)
+    if target.starts-with(label-prefix){ return it }
+    if not enable-cross-references {
+      return raw(target)
+    }
+    let defs = def-state.final()
+    if defs.at(target, default: none) == 1 {
+      target += "()"
+    }
+    (eval-scope.tidy.show-reference)(label(label-prefix + target), target)
+  }
+
+  show raw.where(lang: "example"): it => {
+    set text(4em / 3)
+
+    (eval-scope.example)(
+      raw(it.text, block: true, lang: "typ"), 
+      mode: "markup"
+      )
+  }
+
 
   // Show the docs
 

src/styles/default.typ

@@ -119,14 +119,15 @@
 
 // Create a parameter description block, containing name, type, description and optionally the default value. 
 #let show-parameter-block(
-  name, types, content, style-args,
+  function-name: none, name, types, content, style-args,
   show-default: false, 
   default: none, 
 ) = block(
   inset: 10pt, fill: rgb("ddd3"), width: 100%,
   breakable: style-args.break-param-descriptions,
   [
     #box(heading(level: style-args.first-heading-level + 3, name))
+    #if function-name != none and style-args.enable-cross-references { label(function-name + "." + name) }
     #h(1.2em) 
     #types.map(x => (style-args.style.show-type)(x, style-args: style-args)).join([ #text("or",size:.6em) ])
 
@@ -142,11 +143,11 @@
 
   if style-args.colors == auto { style-args.colors = colors }
 
-  if style-args.enable-cross-references [
-    #heading(fn.name, level: style-args.first-heading-level + 1)
-    #label(style-args.label-prefix + fn.name + "()")
-  ] else [
+  [
     #heading(fn.name, level: style-args.first-heading-level + 1)
+    #if style-args.enable-cross-references {
+      label(style-args.label-prefix + fn.name + "()")
+    }
   ]
 
   eval-docstring(fn.description, style-args)
@@ -168,6 +169,7 @@
       style-args,
       show-default: "default" in info, 
       default: info.at("default", default: none),
+      function-name: style-args.label-prefix + fn.name
     )
   }
   v(4.8em, weak: true)

src/styles/help.typ

@@ -13,7 +13,8 @@
   let prefix = module-doc.label-prefix
   let items = ()
   for fn in module-doc.functions {
-    items.push(link(label(prefix + fn.name + "()"), fn.name + "()"))
+    items.push(fn.name + "()")
+    // items.push(link(label(prefix + fn.name + "()"), fn.name + "()"))
   }
   list(..items)
 }

src/styles/minimal.typ

@@ -68,13 +68,15 @@
   name, types, content, style-args,
   show-default: false, 
   default: none, 
+  function-name: none
 ) = block(
   inset: 0pt, width: 100%,
   breakable: style-args.break-param-descriptions,
   [ 
     #[
       #set text(fill: fn-color)
       #raw(name, lang: none) 
+      #if function-name != none and style-args.enable-cross-references { label(function-name + "." + name) }
     ]
     (#h(-.2em)
     #types.map(x => (style-args.style.show-type)(x)).join([ #text("or",size:.6em) ])
@@ -91,14 +93,12 @@
 ) = {
   set par(justify: false, hanging-indent: 1em, first-line-indent: 0em)
 
-  block(breakable: style-args.break-param-descriptions, 
-    if style-args.enable-cross-references [
-      #(style-args.style.show-parameter-list)(fn, style-args)
-      #label(style-args.label-prefix + fn.name + "()")
-    ] else [
-      #(style-args.style.show-parameter-list)(fn, style-args)
-    ]
-  )
+  block(breakable: style-args.break-param-descriptions)[
+    #(style-args.style.show-parameter-list)(fn, style-args)
+    #if style-args.enable-cross-references {
+      label(style-args.label-prefix + fn.name + "()")
+    }
+  ]
   pad(x: 0em, eval-docstring(fn.description, style-args))
 
   let parameter-block
@@ -115,6 +115,7 @@
       style-args,
       show-default: "default" in info, 
       default: info.at("default", default: none),
+      function-name: style-args.label-prefix + fn.name
     )
   }
 

src/tidy.typ

@@ -5,7 +5,7 @@
 #import "old-parser.typ" as tidy-parse
 #import "utilities.typ"
 #import "testing.typ"
-#import "show-example.typ"
+#import "show-example.typ" as show-example: render-examples
 #import "parse-module.typ": parse-module
 #import "show-module.typ": show-module
 #import "helping.typ" as helping: generate-help