Merge 9e12b2c9f11bb2b6c4bb6fc00563a9e3d3c43dc3 into b790c6d59ceaf7a809cc24b60c1f1509807470e2

Note that `path` was left out because it may not be removed, but
replaced by a path type constructor right away.

README.md

@@ -173,8 +173,11 @@ typst help
 typst help watch
 ```
 
-If you prefer an integrated IDE-like experience with autocompletion and instant
+If you prefer an integrated IDE-like experience with autocompletion and instant 
-preview, you can also check out [Typst's free web app][app].
+preview, you can also check out our [free web app][app]. Alternatively, there is 
+a community-created language server called 
+[Tinymist](https://myriad-dreamin.github.io/tinymist/) which is integrated into 
+various editor extensions.
 
 ## Community
 The main places where the community gathers are our [Forum][forum] and our

crates/typst-library/src/diag.rs

@@ -234,18 +234,23 @@ impl From<SyntaxError> for SourceDiagnostic {
 
 /// Destination for a deprecation message when accessing a deprecated value.
 pub trait DeprecationSink {
-    /// Emits the given deprecation message into this sink.
+    /// Emits the given deprecation message into this sink alongside a version
-    fn emit(self, message: &str);
+    /// in which the deprecated item is planned to be removed.
+    fn emit(self, message: &str, until: Option<&str>);
 }
 
 impl DeprecationSink for () {
-    fn emit(self, _: &str) {}
+    fn emit(self, _: &str, _: Option<&str>) {}
 }
 
 impl DeprecationSink for (&mut Engine<'_>, Span) {
     /// Emits the deprecation message as a warning.
-    fn emit(self, message: &str) {
+    fn emit(self, message: &str, version: Option<&str>) {
-        self.0.sink.warn(SourceDiagnostic::warning(self.1, message));
+        self.0.sink.warn(
+            SourceDiagnostic::warning(self.1, message).with_hints(
+                version.map(|v| eco_format!("this will be removed in {}", v)),
+            ),
+        );
     }
 }
 

crates/typst-library/src/foundations/scope.rs

@@ -255,6 +255,10 @@ pub struct Binding {
     category: Option<Category>,
     /// A deprecation message for the definition.
     deprecation: Option<&'static str>,
+    /// A version in which the deprecated binding is planned to be removed.
+    ///
+    /// This is ignored if `deprecation` is `None`.
+    until: Option<&'static str>,
 }
 
 /// The different kinds of slots.
@@ -275,6 +279,7 @@ impl Binding {
             kind: BindingKind::Normal,
             category: None,
             deprecation: None,
+            until: None,
         }
     }
 
@@ -289,6 +294,14 @@ impl Binding {
         self
     }
 
+    /// Set the version in which the binding is planned to be removed.
+    ///
+    /// This is ignored if [`Binding::deprecated`] isn't also set.
+    pub fn until(&mut self, version: &'static str) -> &mut Self {
+        self.until = Some(version);
+        self
+    }
+
     /// Read the value.
     pub fn read(&self) -> &Value {
         &self.value
@@ -301,7 +314,7 @@ impl Binding {
     /// - pass `(&mut engine, span)` to emit a warning into the engine.
     pub fn read_checked(&self, sink: impl DeprecationSink) -> &Value {
         if let Some(message) = self.deprecation {
-            sink.emit(message);
+            sink.emit(message, self.until);
         }
         &self.value
     }

crates/typst-library/src/foundations/symbol.rs

@@ -151,7 +151,7 @@ impl Symbol {
                 modifiers.best_match_in(list.variants().map(|(m, _, d)| (m, d)))
             {
                 if let Some(message) = deprecation {
-                    sink.emit(message)
+                    sink.emit(message, None)
                 }
                 return Ok(self);
             }

crates/typst-library/src/loading/cbor.rs

@@ -33,7 +33,10 @@ pub fn cbor(
 impl cbor {
     /// Reads structured data from CBOR bytes.
     #[func(title = "Decode CBOR")]
-    #[deprecated = "`cbor.decode` is deprecated, directly pass bytes to `cbor` instead"]
+    #[deprecated(
+        message = "`cbor.decode` is deprecated, directly pass bytes to `cbor` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// CBOR data.

crates/typst-library/src/loading/csv.rs

@@ -95,7 +95,10 @@ pub fn csv(
 impl csv {
     /// Reads structured data from a CSV string/bytes.
     #[func(title = "Decode CSV")]
-    #[deprecated = "`csv.decode` is deprecated, directly pass bytes to `csv` instead"]
+    #[deprecated(
+        message = "`csv.decode` is deprecated, directly pass bytes to `csv` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// CSV data.

crates/typst-library/src/loading/json.rs

@@ -67,7 +67,10 @@ pub fn json(
 impl json {
     /// Reads structured data from a JSON string/bytes.
     #[func(title = "Decode JSON")]
-    #[deprecated = "`json.decode` is deprecated, directly pass bytes to `json` instead"]
+    #[deprecated(
+        message = "`json.decode` is deprecated, directly pass bytes to `json` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// JSON data.

crates/typst-library/src/loading/toml.rs

@@ -41,7 +41,10 @@ pub fn toml(
 impl toml {
     /// Reads structured data from a TOML string/bytes.
     #[func(title = "Decode TOML")]
-    #[deprecated = "`toml.decode` is deprecated, directly pass bytes to `toml` instead"]
+    #[deprecated(
+        message = "`toml.decode` is deprecated, directly pass bytes to `toml` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// TOML data.

crates/typst-library/src/loading/xml.rs

@@ -75,7 +75,10 @@ pub fn xml(
 impl xml {
     /// Reads structured data from an XML string/bytes.
     #[func(title = "Decode XML")]
-    #[deprecated = "`xml.decode` is deprecated, directly pass bytes to `xml` instead"]
+    #[deprecated(
+        message = "`xml.decode` is deprecated, directly pass bytes to `xml` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// XML data.

crates/typst-library/src/loading/yaml.rs

@@ -54,7 +54,10 @@ pub fn yaml(
 impl yaml {
     /// Reads structured data from a YAML string/bytes.
     #[func(title = "Decode YAML")]
-    #[deprecated = "`yaml.decode` is deprecated, directly pass bytes to `yaml` instead"]
+    #[deprecated(
+        message = "`yaml.decode` is deprecated, directly pass bytes to `yaml` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// YAML data.

crates/typst-library/src/visualize/color.rs

@@ -797,7 +797,9 @@ impl Color {
         components
     }
 
-    /// Returns the constructor function for this color's space:
+    /// Returns the constructor function for this color's space.
+    ///
+    /// Returns one of:
     /// - [`luma`]($color.luma)
     /// - [`oklab`]($color.oklab)
     /// - [`oklch`]($color.oklch)

crates/typst-library/src/visualize/image/mod.rs

@@ -169,7 +169,10 @@ pub struct ImageElem {
 impl ImageElem {
     /// Decode a raster or vector graphic from bytes or a string.
     #[func(title = "Decode Image")]
-    #[deprecated = "`image.decode` is deprecated, directly pass bytes to `image` instead"]
+    #[deprecated(
+        message = "`image.decode` is deprecated, directly pass bytes to `image` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         span: Span,
         /// The data to decode as an image. Can be a string for SVGs.

crates/typst-library/src/visualize/mod.rs

@@ -46,6 +46,7 @@ pub(super) fn define(global: &mut Scope) {
         .deprecated("the `path` function is deprecated, use `curve` instead");
     global
         .define("pattern", Type::of::<Tiling>())
-        .deprecated("the name `pattern` is deprecated, use `tiling` instead");
+        .deprecated("the name `pattern` is deprecated, use `tiling` instead")
+        .until("0.15.0");
     global.reset_category();
 }

crates/typst-macros/src/scope.rs

@@ -1,7 +1,8 @@
 use heck::ToKebabCase;
 use proc_macro2::TokenStream;
 use quote::quote;
-use syn::{parse_quote, Result};
+use syn::punctuated::Punctuated;
+use syn::{parse_quote, MetaNameValue, Result, Token};
 
 use crate::util::{foundations, BareType};
 
@@ -53,13 +54,31 @@ pub fn scope(_: TokenStream, item: syn::Item) -> Result<TokenStream> {
             _ => bail!(child, "unexpected item in scope"),
         };
 
-        if let Some(message) = attrs.iter().find_map(|attr| match &attr.meta {
+        if let Some(attr) = attrs.iter().find(|attr| attr.path().is_ident("deprecated")) {
-            syn::Meta::NameValue(pair) if pair.path.is_ident("deprecated") => {
+            match &attr.meta {
-                Some(&pair.value)
+                syn::Meta::NameValue(pair) if pair.path.is_ident("deprecated") => {
+                    let message = &pair.value;
+                    def = quote! { #def.deprecated(#message) }
+                }
+                syn::Meta::List(list) if list.path.is_ident("deprecated") => {
+                    let args = list.parse_args_with(
+                        Punctuated::<MetaNameValue, Token![,]>::parse_separated_nonempty,
+                    )?;
+
+                    if let Some(message) = args.iter().find_map(|pair| {
+                        pair.path.is_ident("message").then_some(&pair.value)
+                    }) {
+                        def = quote! { #def.deprecated(#message) }
+                    }
+
+                    if let Some(version) = args.iter().find_map(|pair| {
+                        pair.path.is_ident("until").then_some(&pair.value)
+                    }) {
+                        def = quote! { #def.until(#version) }
+                    }
+                }
+                _ => {}
             }
-            _ => None,
-        }) {
-            def = quote! { #def.deprecated(#message) }
         }
 
         definitions.push(def);

docs/src/lib.rs

@@ -242,7 +242,7 @@ fn category_page(resolver: &dyn Resolver, category: Category) -> PageModel {
             items.push(CategoryItem {
                 name: group.name.clone(),
                 route: subpage.route.clone(),
-                oneliner: oneliner(docs).into(),
+                oneliner: oneliner(docs),
                 code: true,
             });
             children.push(subpage);
@@ -296,7 +296,7 @@ fn category_page(resolver: &dyn Resolver, category: Category) -> PageModel {
                 items.push(CategoryItem {
                     name: name.into(),
                     route: subpage.route.clone(),
-                    oneliner: oneliner(func.docs().unwrap_or_default()).into(),
+                    oneliner: oneliner(func.docs().unwrap_or_default()),
                     code: true,
                 });
                 children.push(subpage);
@@ -306,7 +306,7 @@ fn category_page(resolver: &dyn Resolver, category: Category) -> PageModel {
                 items.push(CategoryItem {
                     name: ty.short_name().into(),
                     route: subpage.route.clone(),
-                    oneliner: oneliner(ty.docs()).into(),
+                    oneliner: oneliner(ty.docs()),
                     code: true,
                 });
                 children.push(subpage);
@@ -637,7 +637,7 @@ fn group_page(
     let item = CategoryItem {
         name: group.name.clone(),
         route: model.route.clone(),
-        oneliner: oneliner(&group.details).into(),
+        oneliner: oneliner(&group.details),
         code: false,
     };
 
@@ -772,8 +772,24 @@ pub fn urlify(title: &str) -> EcoString {
 }
 
 /// Extract the first line of documentation.
-fn oneliner(docs: &str) -> &str {
+fn oneliner(docs: &str) -> EcoString {
-    docs.lines().next().unwrap_or_default()
+    let paragraph = docs.split("\n\n").next().unwrap_or_default();
+    let mut depth = 0;
+    let mut period = false;
+    let mut end = paragraph.len();
+    for (i, c) in paragraph.char_indices() {
+        match c {
+            '(' | '[' | '{' => depth += 1,
+            ')' | ']' | '}' => depth -= 1,
+            '.' if depth == 0 => period = true,
+            c if period && c.is_whitespace() && !docs[..i].ends_with("e.g.") => {
+                end = i;
+                break;
+            }
+            _ => period = false,
+        }
+    }
+    EcoString::from(&docs[..end]).replace("\r\n", " ").replace("\n", " ")
 }
 
 /// The order of types in the documentation.

docs/src/model.rs

@@ -86,7 +86,7 @@ pub struct FuncModel {
     pub name: EcoString,
     pub title: &'static str,
     pub keywords: &'static [&'static str],
-    pub oneliner: &'static str,
+    pub oneliner: EcoString,
     pub element: bool,
     pub contextual: bool,
     pub deprecation: Option<&'static str>,
@@ -139,7 +139,7 @@ pub struct TypeModel {
     pub name: &'static str,
     pub title: &'static str,
     pub keywords: &'static [&'static str],
-    pub oneliner: &'static str,
+    pub oneliner: EcoString,
     pub details: Html,
     pub constructor: Option<FuncModel>,
     pub scope: Vec<FuncModel>,

flake.nix

@@ -127,6 +127,10 @@
           checks = self'.checks;
           inputsFrom = [ typst ];
 
+          buildInputs = with pkgs; [
+            rust-analyzer
+          ];
+
           packages = [
             # A script for quickly running tests.
             # See https://github.com/typst/typst/blob/main/tests/README.md#making-an-alias

tests/suite/loading/cbor.typ

@@ -1,3 +1,4 @@
 --- cbor-decode-deprecated ---
 // Warning: 15-21 `cbor.decode` is deprecated, directly pass bytes to `cbor` instead
+// Hint: 15-21 this will be removed in 0.15.0
 #let _ = cbor.decode

tests/suite/loading/csv.typ

@@ -32,4 +32,5 @@
 
 --- csv-decode-deprecated ---
 // Warning: 14-20 `csv.decode` is deprecated, directly pass bytes to `csv` instead
+// Hint: 14-20 this will be removed in 0.15.0
 #let _ = csv.decode

tests/suite/loading/json.typ

@@ -11,6 +11,7 @@
 
 --- json-decode-deprecated ---
 // Warning: 15-21 `json.decode` is deprecated, directly pass bytes to `json` instead
+// Hint: 15-21 this will be removed in 0.15.0
 #let _ = json.decode
 
 --- issue-3363-json-large-number ---

tests/suite/loading/toml.typ

@@ -42,4 +42,5 @@
 
 --- toml-decode-deprecated ---
 // Warning: 15-21 `toml.decode` is deprecated, directly pass bytes to `toml` instead
+// Hint: 15-21 this will be removed in 0.15.0
 #let _ = toml.decode

tests/suite/loading/xml.typ

@@ -29,4 +29,5 @@
 
 --- xml-decode-deprecated ---
 // Warning: 14-20 `xml.decode` is deprecated, directly pass bytes to `xml` instead
+// Hint: 14-20 this will be removed in 0.15.0
 #let _ = xml.decode

tests/suite/loading/yaml.typ

@@ -18,4 +18,5 @@
 
 --- yaml-decode-deprecated ---
 // Warning: 15-21 `yaml.decode` is deprecated, directly pass bytes to `yaml` instead
+// Hint: 15-21 this will be removed in 0.15.0
 #let _ = yaml.decode

tests/suite/visualize/image.typ

@@ -188,26 +188,31 @@ A #box(image("/assets/images/tiger.jpg", height: 1cm, width: 80%)) B
 --- image-decode-svg ---
 // Test parsing from svg data
 // Warning: 8-14 `image.decode` is deprecated, directly pass bytes to `image` instead
+// Hint: 8-14 this will be removed in 0.15.0
 #image.decode(`<svg xmlns="http://www.w3.org/2000/svg" height="140" width="500"><ellipse cx="200" cy="80" rx="100" ry="50" style="fill:yellow;stroke:purple;stroke-width:2" /></svg>`.text, format: "svg")
 
 --- image-decode-bad-svg ---
 // Error: 15-152 failed to parse SVG (missing root node at 1:1)
 // Warning: 8-14 `image.decode` is deprecated, directly pass bytes to `image` instead
+// Hint: 8-14 this will be removed in 0.15.0
 #image.decode(`<svg height="140" width="500"><ellipse cx="200" cy="80" rx="100" ry="50" style="fill:yellow;stroke:purple;stroke-width:2" /></svg>`.text, format: "svg")
 
 --- image-decode-detect-format ---
 // Test format auto detect
 // Warning: 8-14 `image.decode` is deprecated, directly pass bytes to `image` instead
+// Hint: 8-14 this will be removed in 0.15.0
 #image.decode(read("/assets/images/tiger.jpg", encoding: none), width: 80%)
 
 --- image-decode-specify-format ---
 // Test format manual
 // Warning: 8-14 `image.decode` is deprecated, directly pass bytes to `image` instead
+// Hint: 8-14 this will be removed in 0.15.0
 #image.decode(read("/assets/images/tiger.jpg", encoding: none), format: "jpg", width: 80%)
 
 --- image-decode-specify-wrong-format ---
 // Error: 2-91 failed to decode image (Format error decoding Png: Invalid PNG signature.)
 // Warning: 8-14 `image.decode` is deprecated, directly pass bytes to `image` instead
+// Hint: 8-14 this will be removed in 0.15.0
 #image.decode(read("/assets/images/tiger.jpg", encoding: none), format: "png", width: 80%)
 
 --- image-pixmap-empty ---

tests/suite/visualize/tiling.typ

@@ -161,5 +161,6 @@
 #set page(width: auto, height: auto, margin: 0pt)
 
 // Warning: 10-17 the name `pattern` is deprecated, use `tiling` instead
+// Hint: 10-17 this will be removed in 0.15.0
 #let t = pattern(size: (10pt, 10pt), line(stroke: 4pt, start: (0%, 0%), end: (100%, 100%)))
 #rect(width: 50pt, height: 50pt, fill: t)