Rename desc to terms

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
+/// # Numbered List
-/// An ordered list.
+/// A numbered list.
 ///
 /// Displays a sequence of items vertically and numbers them consecutively.
 ///

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
+/// # Bullet List
-/// An unordered list.
+/// An bullet list.
 ///
 /// Displays a sequence of items vertically, with each item introduced by a
 /// marker.

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::*;

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
+/// followed by a term, a colon and a description creates a term list item.
-/// 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
+///   When using the term list syntax, adjacents items are automatically
-///   collected into description lists, even through constructs like for loops.
+///   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
+///   If this is `{false}`, the items are spaced apart with [term list
-///   spacing](@desc/spacing). If it is `{true}`, they use normal
+///   spacing](@terms/spacing). If it is `{true}`, they use normal
-///   [leading](@par/leading) instead. This makes the description list more
+///   [leading](@par/leading) instead. This makes the term list more compact,
-///   compact, which can look better if the items are short.
+///   which can look better if the items are short.
 ///
 ///   ### Example
 ///   ```
-///   / Fact: If a description list has
+///   / Fact: If a term list has a lot
-///     a lot of text, and maybe other
+///     of text, and maybe other inline
-///     inline content, it should not be
+///     content, it should not be tight
-///     tight anymore.
+///     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)
+    /// #set terms(hanging-indent: 0pt)
-    /// / Term: This description list
+    /// / Term: This term list does not
-    ///   does not make use of hanging
+    ///   make use of hanging indents.
-    ///   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()) {

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.
+    /// An item of a term list.
-    Desc(DescItem),
+    Term(TermItem),
 }
 
 #[node]

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
+    /// Climate change is one of the most
-    /// most pressing issues of our
+    /// pressing issues of our time, with
-    /// time, with the potential to
+    /// the potential to devastate
-    /// devastate communities,
+    /// communities, ecosystems, and
-    /// ecosystems, and economies
+    /// economies around the world. It's
-    /// around the world. It's clear
+    /// clear that we need to take urgent
-    /// that we need to take urgent
     /// action to reduce our carbon
-    /// emissions and mitigate the
+    /// emissions and mitigate the impacts
-    /// impacts of a rapidly changing
+    /// of a rapidly changing climate.
-    /// climate.
     /// ```
     pub const COLUMNS: NonZeroUsize = NonZeroUsize::new(1).unwrap();
 
@@ -209,14 +207,12 @@ impl PageNode {
     ///
     /// # Example
     /// ```
-    /// #set page(
+    /// #set page(background: align(
-    ///  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(
+    /// #set page(foreground: align(
-    ///   foreground: align(
     ///   center + horizon,
-    ///    text(24pt)[🥸]
+    ///   text(24pt)[🥸],
-    ///   ),
+    /// ))
-    /// )
     ///
     /// Reviewer 2 has marked our paper
     /// "Weak Reject" because they did

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| {
+        term_item: |term, description| {
-            layout::ListItem::Desc(basics::DescItem { term, description }).pack()
+            layout::ListItem::Term(basics::TermItem { term, description }).pack()
         },
         math: |children, block| math::MathNode { children, block }.pack(),
         math_atom: |atom| math::AtomNode(atom).pack(),

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.

src/ide/complete.rs

@@ -712,25 +712,25 @@ impl<'a> CompletionContext<'a> {
         self.snippet_completion(
             "list item",
             "- ${item}",
-            "Inserts an item of an unordered list.",
+            "Inserts an item of a bullet list.",
         );
 
         self.snippet_completion(
             "enumeration item",
             "+ ${item}",
-            "Inserts an item of an ordered list.",
+            "Inserts an item of a numbered list.",
         );
 
         self.snippet_completion(
             "enumeration item (numbered)",
             "${number}. ${item}",
-            "Inserts an explicitly numbered item of an ordered list.",
+            "Inserts an explicitly numbered list item.",
         );
 
         self.snippet_completion(
-            "description list item",
+            "term list item",
             "/ ${term}: ${description}",
-            "Inserts an item of a description list.",
+            "Inserts an item of a term list.",
         );
 
         self.snippet_completion(

src/ide/highlight.rs

@@ -23,9 +23,9 @@ pub enum Category {
     Ref,
     /// A section heading.
     Heading,
-    /// A marker of a list, enumeration, or description list.
+    /// A marker of a list, enumeration, or term list.
     ListMarker,
-    /// A term in a description list.
+    /// A term in a term list.
     ListTerm,
     /// The delimiters of a math formula.
     MathDelimiter,
@@ -114,7 +114,7 @@ pub fn highlight(node: &LinkedNode) -> Option<Category> {
             _ => Category::Operator,
         }),
         SyntaxKind::Slash => Some(match node.parent_kind() {
-            Some(SyntaxKind::DescItem) => Category::ListMarker,
+            Some(SyntaxKind::TermItem) => Category::ListMarker,
             Some(SyntaxKind::Frac) => Category::MathOperator,
             _ => Category::Operator,
         }),
@@ -159,7 +159,7 @@ pub fn highlight(node: &LinkedNode) -> Option<Category> {
         SyntaxKind::From => Some(Category::Keyword),
 
         SyntaxKind::Markup { .. }
-            if node.parent_kind() == Some(&SyntaxKind::DescItem)
+            if node.parent_kind() == Some(&SyntaxKind::TermItem)
                 && node.next_sibling().as_ref().map(|v| v.kind())
                     == Some(&SyntaxKind::Colon) =>
         {
@@ -183,7 +183,7 @@ pub fn highlight(node: &LinkedNode) -> Option<Category> {
         SyntaxKind::ListItem => None,
         SyntaxKind::EnumItem => None,
         SyntaxKind::EnumNumbering(_) => Some(Category::ListMarker),
-        SyntaxKind::DescItem => None,
+        SyntaxKind::TermItem => None,
         SyntaxKind::Math => None,
         SyntaxKind::Atom(_) => None,
         SyntaxKind::Script => None,

src/model/eval.rs

@@ -274,7 +274,7 @@ impl Eval for ast::MarkupNode {
             Self::Heading(v) => v.eval(vm)?,
             Self::List(v) => v.eval(vm)?,
             Self::Enum(v) => v.eval(vm)?,
-            Self::Desc(v) => v.eval(vm)?,
+            Self::Term(v) => v.eval(vm)?,
             Self::Ref(v) => v.eval(vm)?,
             Self::Expr(_) => unimplemented!("handled above"),
         }
@@ -393,13 +393,13 @@ impl Eval for ast::EnumItem {
     }
 }
 
-impl Eval for ast::DescItem {
+impl Eval for ast::TermItem {
     type Output = Content;
 
     fn eval(&self, vm: &mut Vm) -> SourceResult<Self::Output> {
         let term = self.term().eval(vm)?;
         let description = self.description().eval(vm)?;
-        Ok((vm.items.desc_item)(term, description))
+        Ok((vm.items.term_item)(term, description))
     }
 }
 

src/model/library.rs

@@ -59,12 +59,12 @@ pub struct LangItems {
     pub ref_: fn(target: EcoString) -> Content,
     /// A section heading: `= Introduction`.
     pub heading: fn(level: NonZeroUsize, body: Content) -> Content,
-    /// An item in an unordered list: `- ...`.
+    /// An item in a bullet list: `- ...`.
     pub list_item: fn(body: Content) -> Content,
-    /// An item in an enumeration (ordered list): `+ ...` or `1. ...`.
+    /// An item in an enumeration (numbered list): `+ ...` or `1. ...`.
     pub enum_item: fn(number: Option<NonZeroUsize>, body: Content) -> Content,
-    /// An item in a description list: `/ Term: Details`.
+    /// An item in a term list: `/ Term: Details`.
-    pub desc_item: fn(term: Content, description: Content) -> Content,
+    pub term_item: fn(term: Content, description: Content) -> Content,
     /// A mathematical formula: `$x$`, `$ x^2 $`.
     pub math: fn(children: Vec<Content>, block: bool) -> Content,
     /// An atom in a formula: `x`, `+`, `12`.
@@ -102,7 +102,7 @@ impl Hash for LangItems {
         self.heading.hash(state);
         self.list_item.hash(state);
         self.enum_item.hash(state);
-        self.desc_item.hash(state);
+        self.term_item.hash(state);
         self.math.hash(state);
         self.math_atom.hash(state);
         self.math_script.hash(state);

src/syntax/ast.rs

@@ -101,12 +101,12 @@ pub enum MarkupNode {
     Ref(Ref),
     /// A section heading: `= Introduction`.
     Heading(Heading),
-    /// An item in an unordered list: `- ...`.
+    /// An item in a bullet list: `- ...`.
     List(ListItem),
-    /// An item in an enumeration (ordered list): `+ ...` or `1. ...`.
+    /// An item in an enumeration (numbered list): `+ ...` or `1. ...`.
     Enum(EnumItem),
-    /// An item in a description list: `/ Term: Details`.
+    /// An item in a term list: `/ Term: Details`.
-    Desc(DescItem),
+    Term(TermItem),
     /// An expression.
     Expr(Expr),
 }
@@ -129,7 +129,7 @@ impl AstNode for MarkupNode {
             SyntaxKind::Heading => node.cast().map(Self::Heading),
             SyntaxKind::ListItem => node.cast().map(Self::List),
             SyntaxKind::EnumItem => node.cast().map(Self::Enum),
-            SyntaxKind::DescItem => node.cast().map(Self::Desc),
+            SyntaxKind::TermItem => node.cast().map(Self::Term),
             _ => node.cast().map(Self::Expr),
         }
     }
@@ -151,7 +151,7 @@ impl AstNode for MarkupNode {
             Self::Heading(v) => v.as_untyped(),
             Self::List(v) => v.as_untyped(),
             Self::Enum(v) => v.as_untyped(),
-            Self::Desc(v) => v.as_untyped(),
+            Self::Term(v) => v.as_untyped(),
             Self::Expr(v) => v.as_untyped(),
         }
     }
@@ -362,7 +362,7 @@ impl Heading {
 }
 
 node! {
-    /// An item in an unordered list: `- ...`.
+    /// An item in a bullet list: `- ...`.
     ListItem
 }
 
@@ -374,7 +374,7 @@ impl ListItem {
 }
 
 node! {
-    /// An item in an enumeration (ordered list): `+ ...` or `1. ...`.
+    /// An item in an enumeration (numbered list): `+ ...` or `1. ...`.
     EnumItem
 }
 
@@ -394,23 +394,21 @@ impl EnumItem {
 }
 
 node! {
-    /// An item in a description list: `/ Term: Details`.
+    /// An item in a term list: `/ Term: Details`.
-    DescItem
+    TermItem
 }
 
-impl DescItem {
+impl TermItem {
     /// The term described by the item.
     pub fn term(&self) -> Markup {
-        self.0
+        self.0.cast_first_child().expect("term list item is missing term")
-            .cast_first_child()
-            .expect("description list item is missing term")
     }
 
     /// The description of the term.
     pub fn description(&self) -> Markup {
         self.0
             .cast_last_child()
-            .expect("description list item is missing description")
+            .expect("term list item is missing description")
     }
 }
 

src/syntax/kind.rs

@@ -39,8 +39,7 @@ pub enum SyntaxKind {
     /// A semicolon terminating an expression: `;`.
     Semicolon,
     /// A colon between name/key and value in a dictionary, argument or
-    /// parameter list, or between the term and body of a description list
+    /// parameter list, or between the term and body of a term list term: `:`.
-    /// term: `:`.
     Colon,
     /// The strong text toggle, multiplication operator, and wildcard import
     /// symbol: `*`.
@@ -54,8 +53,8 @@ pub enum SyntaxKind {
     /// The unary negation, binary subtraction operator, and start of list
     /// items: `-`.
     Minus,
-    /// The division operator, start of description list items, and fraction
+    /// The division operator, start of term list items, and fraction operator
-    /// operator in a formula: `/`.
+    /// in a formula: `/`.
     Slash,
     /// The superscript operator in a formula: `^`.
     Hat,
@@ -163,14 +162,14 @@ pub enum SyntaxKind {
     Ref(EcoString),
     /// A section heading: `= Introduction`.
     Heading,
-    /// An item in an unordered list: `- ...`.
+    /// An item in a bullet list: `- ...`.
     ListItem,
-    /// An item in an enumeration (ordered list): `+ ...` or `1. ...`.
+    /// An item in an enumeration (numbered list): `+ ...` or `1. ...`.
     EnumItem,
     /// An explicit enumeration numbering: `23.`.
     EnumNumbering(NonZeroUsize),
-    /// An item in a description list: `/ Term: Details`.
+    /// An item in a term list: `/ Term: Details`.
-    DescItem,
+    TermItem,
     /// A mathematical formula: `$x$`, `$ x^2 $`.
     Math,
     /// An atom in a formula: `x`, `+`, `12`.
@@ -405,7 +404,7 @@ impl SyntaxKind {
             Self::ListItem => "list item",
             Self::EnumItem => "enumeration item",
             Self::EnumNumbering(_) => "enumeration item numbering",
-            Self::DescItem => "description list item",
+            Self::TermItem => "term list item",
             Self::Math => "math formula",
             Self::Atom(s) => match s.as_str() {
                 "(" => "opening paren",
@@ -533,7 +532,7 @@ impl Hash for SyntaxKind {
             Self::ListItem => {}
             Self::EnumItem => {}
             Self::EnumNumbering(num) => num.hash(state),
-            Self::DescItem => {}
+            Self::TermItem => {}
             Self::Math => {}
             Self::Atom(c) => c.hash(state),
             Self::Script => {}

src/syntax/parsing.rs

@@ -247,7 +247,7 @@ fn markup_node(p: &mut Parser, at_start: &mut bool) {
         SyntaxKind::Minus => list_item(p, *at_start),
         SyntaxKind::Plus | SyntaxKind::EnumNumbering(_) => enum_item(p, *at_start),
         SyntaxKind::Slash => {
-            desc_item(p, *at_start).ok();
+            term_item(p, *at_start).ok();
         }
         SyntaxKind::Colon => {
             let marker = p.marker();
@@ -341,7 +341,7 @@ fn enum_item(p: &mut Parser, at_start: bool) {
     }
 }
 
-fn desc_item(p: &mut Parser, at_start: bool) -> ParseResult {
+fn term_item(p: &mut Parser, at_start: bool) -> ParseResult {
     let marker = p.marker();
     let text: EcoString = p.peek_src().into();
     p.eat();
@@ -351,7 +351,7 @@ fn desc_item(p: &mut Parser, at_start: bool) -> ParseResult {
         markup_line(p, |node| matches!(node, SyntaxKind::Colon));
         p.expect(SyntaxKind::Colon)?;
         markup_indented(p, min_indent);
-        marker.end(p, SyntaxKind::DescItem);
+        marker.end(p, SyntaxKind::TermItem);
     } else {
         marker.convert(p, SyntaxKind::Text(text));
     }

tests/typ/basics/enum.typ

@@ -32,9 +32,9 @@
 
 ---
 // Mix of different lists
-- List
+- Bullet List
-+ Enum
++ Numbered List
-/ Desc: List
+/ Term: List
 
 ---
 // Test numbering with closure.

tests/typ/basics/list.typ

@@ -1,4 +1,4 @@
-// Test unordered lists.
+// Test bullet lists.
 
 ---
 -

tests/typ/basics/terms.typ

@@ -1,4 +1,4 @@
-// Test description lists.
+// Test term list.
 
 ---
 /
@@ -7,7 +7,7 @@ No: list \
 
 ---
 // Test with constructor.
-#desc(
+#terms(
   ([One], [First]),
   ([Two], [Second]),
 )
@@ -32,12 +32,12 @@ No: list \
 #set text(8pt)
 / First list: #lorem(4)
 
-#set desc(hanging-indent: 30pt)
+#set terms(hanging-indent: 30pt)
 / Second list: #lorem(4)
 
 ---
 // Test grid like show rule.
-#show desc: it => table(
+#show terms: it => table(
   columns: 2,
   inset: 3pt,
   ..it.items.map(item => (emph(item(0)), item(1))).flatten(),