Rename `desc` to `terms`

8 files changed, 70 insertions, 73 deletions

diff --git a/library/src/basics/enum.rs b/library/src/basics/enum.rs
index f0ca217a..81a36b61 100644
--- a/library/src/basics/enum.rs
+++ b/library/src/basics/enum.rs
@@ -5,8 +5,8 @@ use crate::layout::{BlockNode, GridNode, ParNode, Spacing, TrackSizing};
 use crate::prelude::*;
 use crate::text::TextNode;
 
-/// # Enumeration
-/// An ordered list.
+/// # Numbered List
+/// A numbered list.
 ///
 /// Displays a sequence of items vertically and numbers them consecutively.
 ///
diff --git a/library/src/basics/list.rs b/library/src/basics/list.rs
index eaba6594..24c7b21c 100644
--- a/library/src/basics/list.rs
+++ b/library/src/basics/list.rs
@@ -2,8 +2,8 @@ use crate::layout::{BlockNode, GridNode, ParNode, Spacing, TrackSizing};
 use crate::prelude::*;
 use crate::text::TextNode;
 
-/// # List
-/// An unordered list.
+/// # Bullet List
+/// An bullet list.
 ///
 /// Displays a sequence of items vertically, with each item introduced by a
 /// marker.
diff --git a/library/src/basics/mod.rs b/library/src/basics/mod.rs
index 431cb004..7520c42d 100644
--- a/library/src/basics/mod.rs
+++ b/library/src/basics/mod.rs
@@ -1,14 +1,14 @@
 //! Common document elements.
 
-mod desc;
 #[path = "enum.rs"]
 mod enum_;
 mod heading;
 mod list;
 mod table;
+mod terms;
 
-pub use self::desc::*;
 pub use self::enum_::*;
 pub use self::heading::*;
 pub use self::list::*;
 pub use self::table::*;
+pub use self::terms::*;
diff --git a/library/src/basics/desc.rs b/library/src/basics/terms.rs
index 2c764c59..1570d177 100644
--- a/library/src/basics/desc.rs
+++ b/library/src/basics/terms.rs
@@ -2,7 +2,7 @@ use crate::layout::{BlockNode, GridNode, HNode, ParNode, Spacing, TrackSizing};
 use crate::prelude::*;
 use crate::text::{SpaceNode, TextNode};
 
-/// # Description List
+/// # Term List
 /// A list of terms and their descriptions.
 ///
 /// Displays a sequence of terms and their descriptions vertically. When the
@@ -11,8 +11,7 @@ use crate::text::{SpaceNode, TextNode};
 ///
 /// ## Syntax
 /// This function also has dedicated syntax: Starting a line with a slash,
-/// followed by a term, a colon and a description creates a description list
-/// item.
+/// followed by a term, a colon and a description creates a term list item.
 ///
 /// ## Example
 /// ```
@@ -23,10 +22,10 @@ use crate::text::{SpaceNode, TextNode};
 ///
 /// ## Parameters
 /// - items: Content (positional, variadic)
-///   The descrition list's children.
+///   The term list's children.
 ///
-///   When using the description list syntax, adjacents items are automatically
-///   collected into description lists, even through constructs like for loops.
+///   When using the term list syntax, adjacents items are automatically
+///   collected into term lists, even through constructs like for loops.
 ///
 ///   ### Example
 ///   ```
@@ -38,17 +37,17 @@ use crate::text::{SpaceNode, TextNode};
 ///   ```
 ///
 /// - tight: bool (named)
-///   If this is `{false}`, the items are spaced apart with [description list
-///   spacing](@desc/spacing). If it is `{true}`, they use normal
-///   [leading](@par/leading) instead. This makes the description list more
-///   compact, which can look better if the items are short.
+///   If this is `{false}`, the items are spaced apart with [term list
+///   spacing](@terms/spacing). If it is `{true}`, they use normal
+///   [leading](@par/leading) instead. This makes the term list more compact,
+///   which can look better if the items are short.
 ///
 ///   ### Example
 ///   ```
-///   / Fact: If a description list has
-///     a lot of text, and maybe other
-///     inline content, it should not be
-///     tight anymore.
+///   / Fact: If a term list has a lot
+///     of text, and maybe other inline
+///     content, it should not be tight
+///     anymore.
 ///
 ///   / Tip: To make it wide, simply
 ///     insert a blank line between the
@@ -60,15 +59,15 @@ use crate::text::{SpaceNode, TextNode};
 #[func]
 #[capable(Layout)]
 #[derive(Debug, Hash)]
-pub struct DescNode {
+pub struct TermsNode {
     /// If true, the items are separated by leading instead of list spacing.
     pub tight: bool,
     /// The individual bulleted or numbered items.
-    pub items: StyleVec<DescItem>,
+    pub items: StyleVec<TermItem>,
 }
 
 #[node]
-impl DescNode {
+impl TermsNode {
     /// The indentation of each item's term.
     #[property(resolve)]
     pub const INDENT: Length = Length::zero();
@@ -77,15 +76,14 @@ impl DescNode {
     ///
     /// # Example
     /// ```
-    /// #set desc(hanging-indent: 0pt)
-    /// / Term: This description list
-    ///   does not make use of hanging
-    ///   indents.
+    /// #set terms(hanging-indent: 0pt)
+    /// / Term: This term list does not
+    ///   make use of hanging indents.
     /// ```
     #[property(resolve)]
     pub const HANGING_INDENT: Length = Em::new(1.0).into();
 
-    /// The spacing between the items of a wide (non-tight) description list.
+    /// The spacing between the items of a wide (non-tight) term list.
     ///
     /// If set to `{auto}` uses the spacing [below blocks](@block/below).
     pub const SPACING: Smart<Spacing> = Smart::Auto;
@@ -109,7 +107,7 @@ impl DescNode {
     }
 }
 
-impl Layout for DescNode {
+impl Layout for TermsNode {
     fn layout(
         &self,
         vt: &mut Vt,
@@ -151,16 +149,16 @@ impl Layout for DescNode {
     }
 }
 
-/// A description list item.
+/// A term list item.
 #[derive(Debug, Clone, Hash)]
-pub struct DescItem {
+pub struct TermItem {
     /// The term described by the list item.
     pub term: Content,
     /// The description of the term.
     pub description: Content,
 }
 
-impl DescItem {
+impl TermItem {
     /// Encode the item into a value.
     fn encode(&self) -> Value {
         Value::Array(array![
@@ -171,7 +169,7 @@ impl DescItem {
 }
 
 castable! {
-    DescItem,
+    TermItem,
     array: Array => {
         let mut iter = array.into_iter();
         let (term, description) = match (iter.next(), iter.next(), iter.next()) {
diff --git a/library/src/layout/mod.rs b/library/src/layout/mod.rs
index bd4b0430..67b53e1b 100644
--- a/library/src/layout/mod.rs
+++ b/library/src/layout/mod.rs
@@ -40,7 +40,7 @@ use typst::model::{
     StyleVecBuilder, StyledNode,
 };
 
-use crate::basics::{DescItem, DescNode, EnumNode, ListNode};
+use crate::basics::{EnumNode, ListNode, TermItem, TermsNode};
 use crate::meta::DocumentNode;
 use crate::prelude::*;
 use crate::shared::BehavedBuilder;
@@ -418,7 +418,7 @@ impl<'a, 'v, 't> Builder<'a, 'v, 't> {
             self.interrupt_par()?;
         } else if map.interruption::<ListNode>().is_some()
             || map.interruption::<EnumNode>().is_some()
-            || map.interruption::<DescNode>().is_some()
+            || map.interruption::<TermsNode>().is_some()
         {
             self.interrupt_list()?;
         }
@@ -519,7 +519,7 @@ impl<'a> FlowBuilder<'a> {
                 node.tight
             } else if let Some(node) = content.to::<EnumNode>() {
                 node.tight
-            } else if let Some(node) = content.to::<DescNode>() {
+            } else if let Some(node) = content.to::<TermsNode>() {
                 node.tight
             } else {
                 false
@@ -621,10 +621,10 @@ impl<'a> ListBuilder<'a> {
                 }),
             }
             .pack(),
-            ListItem::Desc(_) => DescNode {
+            ListItem::Term(_) => TermsNode {
                 tight: self.tight,
                 items: items.map(|item| match item {
-                    ListItem::Desc(item) => item.clone(),
+                    ListItem::Term(item) => item.clone(),
                     _ => panic!("wrong list item"),
                 }),
             }
@@ -648,12 +648,12 @@ impl Default for ListBuilder<'_> {
 #[capable]
 #[derive(Debug, Clone, Hash)]
 pub enum ListItem {
-    /// An item of an unordered list.
+    /// An item of a bullet list.
     List(Content),
-    /// An item of an ordered list.
+    /// An item of a numbered list.
     Enum(Option<NonZeroUsize>, Content),
-    /// An item of a description list.
-    Desc(DescItem),
+    /// An item of a term list.
+    Term(TermItem),
 }
 
 #[node]
diff --git a/library/src/layout/page.rs b/library/src/layout/page.rs
index c1ac6118..beedf4c5 100644
--- a/library/src/layout/page.rs
+++ b/library/src/layout/page.rs
@@ -125,17 +125,15 @@ impl PageNode {
     /// # Example
     /// ```
     /// #set page(columns: 2, height: 4.8cm)
-    /// Climate change is one of the
-    /// most pressing issues of our
-    /// time, with the potential to
-    /// devastate communities,
-    /// ecosystems, and economies
-    /// around the world. It's clear
-    /// that we need to take urgent
+    /// Climate change is one of the most
+    /// pressing issues of our time, with
+    /// the potential to devastate
+    /// communities, ecosystems, and
+    /// economies around the world. It's
+    /// clear that we need to take urgent
     /// action to reduce our carbon
-    /// emissions and mitigate the
-    /// impacts of a rapidly changing
-    /// climate.
+    /// emissions and mitigate the impacts
+    /// of a rapidly changing climate.
     /// ```
     pub const COLUMNS: NonZeroUsize = NonZeroUsize::new(1).unwrap();
 
@@ -191,13 +189,13 @@ impl PageNode {
     /// ```
     /// #set par(justify: true)
     /// #set page(
-    ///     margin: (x: 24pt, y: 32pt),
-    ///     footer: i => align(horizon + right,
-    ///       text(8pt, numbering("I", i))
-    ///     )
+    ///   margin: (x: 24pt, y: 32pt),
+    ///   footer: i => align(horizon + right,
+    ///     text(8pt, numbering("I", i))
     ///   )
+    /// )
     ///
-    ///   #lorem(18)
+    /// #lorem(18)
     /// ```
     #[property(referenced)]
     pub const FOOTER: Marginal = Marginal::None;
@@ -209,14 +207,12 @@ impl PageNode {
     ///
     /// # Example
     /// ```
-    /// #set page(
-    ///  background: align(
-    ///    center + horizon,
-    ///    rotate(24deg,
-    ///      text(18pt, fill: rgb("FFCBC4"))[*CONFIDENTIAL*]
-    ///    )
+    /// #set page(background: align(
+    ///   center + horizon,
+    ///   rotate(24deg,
+    ///     text(18pt, fill: rgb("FFCBC4"))[*CONFIDENTIAL*]
     ///   ),
-    /// )
+    /// ))
     ///
     /// = Typst's secret plans
     ///
@@ -232,12 +228,10 @@ impl PageNode {
     ///
     /// # Example
     /// ```
-    /// #set page(
-    ///   foreground: align(
-    ///    center + horizon,
-    ///    text(24pt)[🥸]
-    ///   ),
-    /// )
+    /// #set page(foreground: align(
+    ///   center + horizon,
+    ///   text(24pt)[🥸],
+    /// ))
     ///
     /// Reviewer 2 has marked our paper
     /// "Weak Reject" because they did
diff --git a/library/src/lib.rs b/library/src/lib.rs
index 26727711..a4c6fc30 100644
--- a/library/src/lib.rs
+++ b/library/src/lib.rs
@@ -28,7 +28,7 @@ fn scope() -> Scope {
     std.def_func::<basics::HeadingNode>("heading");
     std.def_func::<basics::ListNode>("list");
     std.def_func::<basics::EnumNode>("enum");
-    std.def_func::<basics::DescNode>("desc");
+    std.def_func::<basics::TermsNode>("terms");
     std.def_func::<basics::TableNode>("table");
 
     // Text.
@@ -200,8 +200,8 @@ fn items() -> LangItems {
         heading: |level, body| basics::HeadingNode { level, title: body }.pack(),
         list_item: |body| layout::ListItem::List(body).pack(),
         enum_item: |number, body| layout::ListItem::Enum(number, body).pack(),
-        desc_item: |term, description| {
-            layout::ListItem::Desc(basics::DescItem { term, description }).pack()
+        term_item: |term, description| {
+            layout::ListItem::Term(basics::TermItem { term, description }).pack()
         },
         math: |children, block| math::MathNode { children, block }.pack(),
         math_atom: |atom| math::AtomNode(atom).pack(),
diff --git a/library/src/meta/link.rs b/library/src/meta/link.rs
index 60d57a5f..ebb7a7e9 100644
--- a/library/src/meta/link.rs
+++ b/library/src/meta/link.rs
@@ -13,12 +13,17 @@ use crate::text::TextNode;
 /// ```
 /// #show link: underline
 ///
+/// https://example.com \
 /// #link("https://example.com") \
 /// #link("https://example.com")[
 ///   See example.com
 /// ]
 /// ```
 ///
+/// ## Syntax
+/// This function also has dedicated syntax: Text that starts with `http://` or
+/// `https://` is automatically turned into a link.
+///
 /// ## Parameters
 /// - dest: Destination (positional, required)
 ///   The destination the link points to.