Document meta and data loading categories

4 files changed, 112 insertions, 10 deletions

diff --git a/library/src/meta/document.rs b/library/src/meta/document.rs
index e20821c5..c5d4e050 100644
--- a/library/src/meta/document.rs
+++ b/library/src/meta/document.rs
@@ -1,7 +1,14 @@
 use crate::layout::{LayoutRoot, PageNode};
 use crate::prelude::*;
 
-/// The root node that represents a full document.
+/// The root element of a document and its metadata.
+///
+/// All documents are automatically wrapped in a `document` element. The main
+/// use of this element is to use it in `set` rules to specify document
+/// metadata.
+///
+/// The metadata set with this function is not rendered within the document.
+/// Instead, it is embedded in the compiled PDF file.
 ///
 /// # Tags
 /// - meta
@@ -12,7 +19,8 @@ pub struct DocumentNode(pub StyleVec<PageNode>);
 
 #[node]
 impl DocumentNode {
-    /// The document's title.
+    /// The document's title. This is often rendered as the title of the
+    /// PDF viewer window.
     #[property(referenced)]
     pub const TITLE: Option<EcoString> = None;
 
diff --git a/library/src/meta/link.rs b/library/src/meta/link.rs
index 6a2f66df..3b816083 100644
--- a/library/src/meta/link.rs
+++ b/library/src/meta/link.rs
@@ -1,14 +1,47 @@
 use crate::prelude::*;
 use crate::text::TextNode;
 
-/// Link text and other elements to a destination.
+/// Link to a URL or another location in the document.
+///
+/// The link function makes its positional `body` argument clickable and links
+/// it to the destination specified by the `dest` argument.
+///
+/// # Example
+/// ```
+/// #show link: underline
+///
+/// #link("https://example.com") \
+/// #link("https://example.com")[
+///   See example.com
+/// ]
+/// ```
 ///
 /// # Parameters
 /// - dest: Destination (positional, required)
 ///   The destination the link points to.
+///   
+///   - To link to web pages, `dest` should be a valid URL string. If the URL is
+///     in the `mailto:` or `tel:` scheme and the `body` parameter is omitted,
+///     the email address or phone number will be the link's body, without the
+///     scheme.
+///
+///   - To link to another part of the document, `dest` must contain a
+///     dictionary with a `page` key of type `integer` and `x` and `y`
+///     coordinates of type `length`. Pages are counted from one, and the
+///     coordinates are relative to the page's top left corner.
+///
+///   # Example
+///   ```
+///   #link("mailto:hello@typst.app") \
+///   #link((page: 1, x: 0pt, y: 0pt))[
+///     Go to top
+///   ]
+///   ```
 ///
 /// - body: Content (positional)
-///   How the link is represented. Defaults to the destination if it is a link.
+///
+///   The content that should become a link. If `dest` is an URL string, the
+///   parameter can be omitted. In this case, the URL will be shown as the link.
 ///
 /// # Tags
 /// - meta
diff --git a/library/src/meta/outline.rs b/library/src/meta/outline.rs
index 6ea65391..47453526 100644
--- a/library/src/meta/outline.rs
+++ b/library/src/meta/outline.rs
@@ -3,7 +3,22 @@ use crate::layout::{BlockNode, HNode, HideNode, RepeatNode, Spacing};
 use crate::prelude::*;
 use crate::text::{LinebreakNode, SpaceNode, TextNode};
 
-/// A section outline (table of contents).
+/// Generate a section outline / table of contents.
+///
+/// This function generates a list of all headings in the
+/// document, up to a given depth. The [@heading] numbering will be reproduced
+/// within the outline.
+///
+/// # Example
+/// ```
+/// #outline()
+///
+/// = Introduction
+/// #lorem(5)
+///
+/// = Prior work
+/// #lorem(10)
+/// ```
 ///
 /// # Tags
 /// - meta
@@ -15,18 +30,52 @@ pub struct OutlineNode;
 #[node]
 impl OutlineNode {
     /// The title of the outline.
+    ///
+    /// - When set to `{auto}`, an appropriate title for the [@text] language will
+    ///   be used. This is the default.
+    /// - When set to `{none}`, the outline will not have a title.
+    /// - A custom title can be set by passing content.
     #[property(referenced)]
     pub const TITLE: Option<Smart<Content>> = Some(Smart::Auto);
 
-    /// The maximum depth up to which headings are included in the outline.
+    /// The maximum depth up to which headings are included in the outline. When
+    /// this arguement is `{none}`, all headings are included.
     pub const DEPTH: Option<NonZeroUsize> = None;
 
-    /// Whether to indent the subheadings to match their parents.
+    /// Whether to indent the subheadings to align the start of their numbering
+    /// with the title of their parents. This will only have an effect if a
+    /// [@heading] numbering is set.
+    ///
+    /// # Example
+    /// ```
+    /// #set heading(numbering: "1.a.")
+    ///
+    /// #outline(indent: true)
+    ///
+    /// = About ACME Corp.
+    ///
+    /// == History
+    /// #lorem(10)
+    ///
+    /// == Products
+    /// #lorem(10)
+    /// ```
     pub const INDENT: bool = false;
 
-    /// The fill symbol.
+    /// The symbol used to fill the space between the title and the page
+    /// number. Can be set to `none` to disable filling. The default is a
+    /// single dot.
+    ///
+    /// # Example
+    /// ```
+    /// #outline(
+    ///   fill: pad(x: -1.5pt)[―]
+    /// )
+    ///
+    /// = A New Beginning
+    /// ```
     #[property(referenced)]
-    pub const FILL: Option<EcoString> = Some('.'.into());
+    pub const FILL: Option<Content> = Some(TextNode::packed("."));
 
     fn construct(_: &Vm, _: &mut Args) -> SourceResult<Content> {
         Ok(Self.pack())
@@ -132,7 +181,7 @@ impl Show for OutlineNode {
             // Add filler symbols between the section name and page number.
             if let Some(filler) = styles.get(Self::FILL) {
                 seq.push(SpaceNode.pack());
-                seq.push(RepeatNode(TextNode::packed(filler.clone())).pack());
+                seq.push(RepeatNode(filler.clone()).pack());
                 seq.push(SpaceNode.pack());
             } else {
                 let amount = Spacing::Fractional(Fr::one());
diff --git a/library/src/meta/reference.rs b/library/src/meta/reference.rs
index c49ff970..1a4b22e4 100644
--- a/library/src/meta/reference.rs
+++ b/library/src/meta/reference.rs
@@ -3,6 +3,18 @@ use crate::text::TextNode;
 
 /// A reference to a label.
 ///
+/// *Note: This function is currently unimplemented.*
+///
+/// The reference function produces a textual reference to a label. For example,
+/// a reference to a heading will yield an appropriate string such as "Section
+/// 1" for a reference to the first heading's label. The references are also
+/// links to the respective labels.
+///
+/// # Syntax
+/// This function also has dedicated syntax: A reference to a label can be
+/// created by typing an `@` followed by the name of the label (e.g. `[=
+/// Introduction <intro>]` can be referenced by typing `[@intro]`).
+///
 /// # Parameters
 /// - target: Label (positional, required)
 ///   The label that should be referenced.