Merge 25ad4f7d419b5d2798645a565138c97c65c0eab6 into 78355421ad73fdcbe93b4acca890b439c4b6f98d

crates/typst-library/src/text/raw.rs

@@ -31,6 +31,12 @@ use crate::visualize::Color;
 /// 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::visualize::Color;
 /// #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::visualize::Color;
 /// 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",

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

@@ -76,14 +76,16 @@ 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`]   |
+| 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`]  |
@@ -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.