Merge 25ad4f7d419b5d2798645a565138c97c65c0eab6 into b1c79b50d4253e7acb839a93450311c1fca12ac8

Co-authored-by: Malo <57839069+MDLC01@users.noreply.github.com>

README.md

@@ -174,7 +174,10 @@ typst help watch
 ```
 
 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/text/raw.rs

@@ -31,6 +31,12 @@ use crate::World;
 /// Displays the text verbatim and in a monospace font. This is typically used
 /// to embed computer code into your document.
 ///
+/// Note that text given to this element cannot contain arbitrary formatting,
+/// such as `[*strong*]` or `[_emphasis_]`, as it is displayed verbatim. If
+/// you'd like to display any kind of content with a monospace font, instead of
+/// using [`raw`], you should change its font to a monospace font using the
+/// [`text`]($text) function.
+///
 /// # Example
 /// ````example
 /// Adding `rbx` to `rcx` gives
@@ -57,6 +63,38 @@ use crate::World;
 /// #raw("fn " + "main() {}", lang: "rust")
 /// ```
 ///
+/// # Styling
+/// By default, the `raw` element uses the `DejaVu Sans Mono` font, available
+/// by default in Typst, with a smaller font size of `0.8em` (that is, 80% of
+/// the global font size). This is because monospace fonts tend to be visually
+/// larger than non-monospace fonts.
+///
+/// You can customize these properties with show-set rules:
+///
+/// ````example
+/// // Switch to Cascadia Code for
+/// // both inline and block raw.
+/// #show raw: set text(font: "Cascadia Code")
+///
+/// // Make raw blocks 20% larger than their default size.
+/// // Keep inline raw at the same size.
+/// #show raw.where(block: true): set text(1.2em)
+///
+/// Now using the `Cascadia Code` font for raw text.
+/// Here's some Python code. It looks larger now:
+///
+/// ```py
+/// def python():
+///   return 5 + 5
+/// ```
+/// ````
+///
+/// In addition, you can customize the syntax highlighting colors by setting
+/// a custom theme through the [`theme`]($raw.theme) field.
+///
+/// For complete customization of the appearance of a raw block, a show rule
+/// on [`raw.line`]($raw.line) could be helpful, such as to add line numbers.
+///
 /// # Syntax
 /// This function also has dedicated syntax. You can enclose text in 1 or 3+
 /// backticks (`` ` ``) to make it raw. Two backticks produce empty raw text.
@@ -73,6 +111,10 @@ use crate::World;
 /// needed, start the text with a single space (which will be trimmed) or use
 /// the single backtick syntax. If your text should start or end with a
 /// backtick, put a space before or after it (it will be trimmed).
+///
+/// If no syntax highlighting is available by default for your specified
+/// language tag, you may provide a custom syntax specification file to the
+/// [`syntaxes`]($raw.syntaxes) field.
 #[elem(
     scope,
     title = "Raw Text / Code",

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)

docs/guides/guide-for-latex-users.md

@@ -75,21 +75,23 @@ Emphasis (usually rendered as italic text) is expressed by enclosing text in
 Here is a list of common markup commands used in LaTeX and their Typst
 equivalents. You can also check out the [full syntax cheat sheet]($syntax).
 
-| Element          | LaTeX                     | Typst                  | See        |
-|:-----------------|:--------------------------|:-----------------------|:-----------|
-| Strong emphasis  | `\textbf{strong}`         | `[*strong*]`           | [`strong`] |
-| Emphasis         | `\emph{emphasis}`         | `[_emphasis_]`         | [`emph`]   |
-| Monospace / code | `\texttt{print(1)}`       | ``[`print(1)`]``       | [`raw`]    |
-| Link             | `\url{https://typst.app}` | `[https://typst.app/]` | [`link`]   |
-| Label            | `\label{intro}`           | `[<intro>]`            | [`label`]  |
-| Reference        | `\ref{intro}`             | `[@intro]`             | [`ref`]    |
-| Citation         | `\cite{humphrey97}`       | `[@humphrey97]`        | [`cite`]   |
-| Bullet list      | `itemize` environment     | `[- List]`             | [`list`]   |
-| Numbered list    | `enumerate` environment   | `[+ List]`             | [`enum`]   |
-| Term list        | `description` environment | `[/ Term: List]`       | [`terms`]  |
-| Figure           | `figure` environment      | `figure` function      | [`figure`] |
-| Table            | `table` environment       | `table` function       | [`table`]  |
-| Equation         | `$x$`, `align` / `equation` environments | `[$x$]`, `[$ x = y $]` | [`equation`]($math.equation) |
+| Element                | LaTeX                     | Typst                  | See        |
+|:-----------------------|:--------------------------|:-----------------------|:-----------|
+| Strong emphasis        | `\textbf{strong}`         | `[*strong*]`           | [`strong`] |
+| Emphasis               | `\emph{emphasis}`         | `[_emphasis_]`         | [`emph`]   |
+| Link                   | `\url{https://typst.app}` | `[https://typst.app/]` | [`link`]   |
+| Label                  | `\label{intro}`           | `[<intro>]`            | [`label`]  |
+| Reference              | `\ref{intro}`             | `[@intro]`             | [`ref`]    |
+| Citation               | `\cite{humphrey97}`       | `[@humphrey97]`        | [`cite`]   |
+| Verbatim / code        | `\verb|print(f"{x}")|`, `verbatim` / `listing` environments | ``[`print(f"{x}")`]`` | [`raw`] |
+| Monospace / typewriter | `\texttt{mono}` | ``[`mono`]`` or `text` function | [`raw`], [`text`] |
+| Verbatim               | `verbatim` environment    | ``[`#typst-code()`]``  | [`raw`]    |
+| Bullet list            | `itemize` environment     | `[- List]`             | [`list`]   |
+| Numbered list          | `enumerate` environment   | `[+ List]`             | [`enum`]   |
+| Term list              | `description` environment | `[/ Term: List]`       | [`terms`]  |
+| Figure                 | `figure` environment      | `figure` function      | [`figure`] |
+| Table                  | `table` environment       | `table` function       | [`table`]  |
+| Equation               | `$x$`, `align` / `equation` environments | `[$x$]`, `[$ x = y $]` | [`equation`]($math.equation) |
 
 [Lists]($list) do not rely on environments in Typst. Instead, they have
 lightweight syntax like headings. To create an unordered list (`itemize`),
@@ -121,6 +123,16 @@ To get a [numbered list]($enum) (`enumerate`) instead, use a `+` instead of the
 hyphen. For a [term list]($terms) (`description`), write `[/ Term: Description]`
 instead.
 
+Regarding the usage of monospace fonts (also known as "typewriter" font style
+in LaTeX), it should be noted that using [`raw`] such as in
+``[`monospace`]`` (where you'd use `\texttt{monospace}` in LaTeX) works for
+most cases where you only have simple text. If you need to use formatting, such
+as in `\texttt{monospace \textbf{bold}}`, you will need to replicate its look by
+switch to changing the text font to a monospace font with
+`#text(font: "DejaVu Sans Mono", size: 0.8em)[monospace *bold*]`, for example,
+since `raw` only supports verbatim (unformatted) text. See its documentation
+for more details.
+
 ## How do I use a command? { #commands }
 LaTeX heavily relies on commands (prefixed by backslashes). It uses these
 _macros_ to affect the typesetting process and to insert and manipulate content.

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 {
-    docs.lines().next().unwrap_or_default()
+fn oneliner(docs: &str) -> EcoString {
+    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>,