From a3c2489eb6e632367e1ac5d3f45f3aa3292be201 Mon Sep 17 00:00:00 2001 From: PgBiel <9021226+PgBiel@users.noreply.github.com> Date: Mon, 3 Mar 2025 21:12:20 -0300 Subject: [PATCH 1/4] improve raw docs --- crates/typst-library/src/text/raw.rs | 39 ++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/crates/typst-library/src/text/raw.rs b/crates/typst-library/src/text/raw.rs index 1ce8bfc61..de249e2ab 100644 --- a/crates/typst-library/src/text/raw.rs +++ b/crates/typst-library/src/text/raw.rs @@ -30,6 +30,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 @@ -56,6 +62,35 @@ 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). You can customize these properties with a show-set +/// rule: +/// +/// ````example +/// // Switch to Cascadia Code for both inline and block raw. +/// #show raw: set text(font: "Cascadia Code") +/// // Make raw blocks 20% larger than normal text, +/// // while keeping inline raw smaller than text. +/// #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. @@ -72,6 +107,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", From ec3c058220fca17779761e241209b4122b8c7290 Mon Sep 17 00:00:00 2001 From: PgBiel <9021226+PgBiel@users.noreply.github.com> Date: Tue, 4 Mar 2025 16:53:53 -0300 Subject: [PATCH 2/4] use markup highlighting Co-authored-by: Malo <57839069+MDLC01@users.noreply.github.com> --- crates/typst-library/src/text/raw.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/typst-library/src/text/raw.rs b/crates/typst-library/src/text/raw.rs index de249e2ab..3dbd1d2da 100644 --- a/crates/typst-library/src/text/raw.rs +++ b/crates/typst-library/src/text/raw.rs @@ -31,7 +31,7 @@ use crate::World; /// 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 +/// 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. From c4d7faf5271db65408a68a2da80b965a2de44363 Mon Sep 17 00:00:00 2001 From: PgBiel <9021226+PgBiel@users.noreply.github.com> Date: Tue, 4 Mar 2025 17:17:32 -0300 Subject: [PATCH 3/4] laurenz review adjustments --- crates/typst-library/src/text/raw.rs | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/crates/typst-library/src/text/raw.rs b/crates/typst-library/src/text/raw.rs index 3dbd1d2da..3cec14f2e 100644 --- a/crates/typst-library/src/text/raw.rs +++ b/crates/typst-library/src/text/raw.rs @@ -63,17 +63,20 @@ use crate::World; /// ``` /// /// # 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). You can customize these properties with a show-set -/// rule: +/// 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. +/// // Switch to Cascadia Code for +/// // both inline and block raw. /// #show raw: set text(font: "Cascadia Code") -/// // Make raw blocks 20% larger than normal text, -/// // while keeping inline raw smaller than text. +/// +/// // 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. From 25ad4f7d419b5d2798645a565138c97c65c0eab6 Mon Sep 17 00:00:00 2001 From: PgBiel <9021226+PgBiel@users.noreply.github.com> Date: Tue, 4 Mar 2025 17:58:59 -0300 Subject: [PATCH 4/4] mention typewriter font in LaTeX guide --- docs/guides/guide-for-latex-users.md | 42 ++++++++++++++++++---------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/docs/guides/guide-for-latex-users.md b/docs/guides/guide-for-latex-users.md index fffa6c521..4e2f5e9a4 100644 --- a/docs/guides/guide-for-latex-users.md +++ b/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}` | `[]` | [`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}` | `[]` | [`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.