Merge 25ad4f7d419b5d2798645a565138c97c65c0eab6 into 9a6268050fb769e18c4889fa5f59d4150e8878d6

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

crates/typst-html/src/convert.rs

@@ -109,10 +109,7 @@ fn handle(
             styles.chain(&style),
             Region::new(Size::splat(Abs::inf()), Axes::splat(false)),
         )?;
-        output.push(HtmlNode::Frame(HtmlFrame {
-            inner: frame,
-            text_size: styles.resolve(TextElem::size),
-        }));
+        output.push(HtmlNode::Frame(HtmlFrame::new(frame, styles)));
     } else {
         engine.sink.warn(warning!(
             child.span(),

crates/typst-html/src/dom.rs

@@ -2,10 +2,11 @@ use std::fmt::{self, Debug, Display, Formatter};
 
 use ecow::{EcoString, EcoVec};
 use typst_library::diag::{bail, HintedStrResult, StrResult};
-use typst_library::foundations::{cast, Dict, Repr, Str};
+use typst_library::foundations::{cast, Dict, Repr, Str, StyleChain};
 use typst_library::introspection::{Introspector, Tag};
 use typst_library::layout::{Abs, Frame};
 use typst_library::model::DocumentInfo;
+use typst_library::text::TextElem;
 use typst_syntax::Span;
 use typst_utils::{PicoStr, ResolvedPicoStr};
 
@@ -279,3 +280,10 @@ pub struct HtmlFrame {
     /// consistently.
     pub text_size: Abs,
 }
+
+impl HtmlFrame {
+    /// Wraps a laid-out frame.
+    pub fn new(inner: Frame, styles: StyleChain) -> Self {
+        Self { inner, text_size: styles.resolve(TextElem::size) }
+    }
+}

crates/typst-html/src/encode.rs

@@ -121,6 +121,7 @@ fn write_children(w: &mut Writer, element: &HtmlElement) -> SourceResult<()> {
     let pretty_inside = allows_pretty_inside(element.tag)
         && element.children.iter().any(|node| match node {
             HtmlNode::Element(child) => wants_pretty_around(child.tag),
+            HtmlNode::Frame(_) => true,
             _ => false,
         });
 
@@ -305,14 +306,6 @@ fn write_escape(w: &mut Writer, c: char) -> StrResult<()> {
 
 /// Encode a laid out frame into the writer.
 fn write_frame(w: &mut Writer, frame: &HtmlFrame) {
-    // FIXME: This string replacement is obviously a hack.
-    let svg = typst_svg::svg_frame(&frame.inner).replace(
-        "<svg class",
-        &format!(
-            "<svg style=\"overflow: visible; width: {}em; height: {}em;\" class",
-            frame.inner.width() / frame.text_size,
-            frame.inner.height() / frame.text_size,
-        ),
-    );
+    let svg = typst_svg::svg_html_frame(&frame.inner, frame.text_size);
     w.buf.push_str(&svg);
 }

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-svg/src/lib.rs

@@ -45,6 +45,30 @@ pub fn svg_frame(frame: &Frame) -> String {
     renderer.finalize()
 }
 
+/// Export a frame into an SVG suitable for embedding into HTML.
+#[typst_macros::time(name = "svg html frame")]
+pub fn svg_html_frame(frame: &Frame, text_size: Abs) -> String {
+    let mut renderer = SVGRenderer::with_options(xmlwriter::Options {
+        indent: xmlwriter::Indent::None,
+        ..Default::default()
+    });
+    renderer.write_header_with_custom_attrs(frame.size(), |xml| {
+        xml.write_attribute("class", "typst-frame");
+        xml.write_attribute_fmt(
+            "style",
+            format_args!(
+                "overflow: visible; width: {}em; height: {}em;",
+                frame.width() / text_size,
+                frame.height() / text_size,
+            ),
+        );
+    });
+
+    let state = State::new(frame.size(), Transform::identity());
+    renderer.render_frame(state, Transform::identity(), frame);
+    renderer.finalize()
+}
+
 /// Export a document with potentially multiple pages into a single SVG file.
 ///
 /// The padding will be added around and between the individual frames.
@@ -158,8 +182,13 @@ impl State {
 impl SVGRenderer {
     /// Create a new SVG renderer with empty glyph and clip path.
     fn new() -> Self {
+        Self::with_options(Default::default())
+    }
+
+    /// Create a new SVG renderer with the given configuration.
+    fn with_options(options: xmlwriter::Options) -> Self {
         SVGRenderer {
-            xml: XmlWriter::new(xmlwriter::Options::default()),
+            xml: XmlWriter::new(options),
             glyphs: Deduplicator::new('g'),
             clip_paths: Deduplicator::new('c'),
             gradient_refs: Deduplicator::new('g'),
@@ -170,11 +199,22 @@ impl SVGRenderer {
         }
     }
 
-    /// Write the SVG header, including the `viewBox` and `width` and `height`
-    /// attributes.
+    /// Write the default SVG header, including a `typst-doc` class, the
+    /// `viewBox` and `width` and `height` attributes.
     fn write_header(&mut self, size: Size) {
+        self.write_header_with_custom_attrs(size, |xml| {
+            xml.write_attribute("class", "typst-doc");
+        });
+    }
+
+    /// Write the SVG header with additional attributes and standard attributes.
+    fn write_header_with_custom_attrs(
+        &mut self,
+        size: Size,
+        write_custom_attrs: impl FnOnce(&mut XmlWriter),
+    ) {
         self.xml.start_element("svg");
-        self.xml.write_attribute("class", "typst-doc");
+        write_custom_attrs(&mut self.xml);
         self.xml.write_attribute_fmt(
             "viewBox",
             format_args!("0 0 {} {}", size.x.to_pt(), size.y.to_pt()),

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.

tests/ref/html/html-frame.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+  </head>
+  <body>
+    <p>A rectangle:</p>
+    <svg class="typst-frame" style="overflow: visible; width: 4.5em; height: 3em;" viewBox="0 0 45 30" width="45pt" height="30pt" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:h5="http://www.w3.org/1999/xhtml"><g><g transform="translate(-0 -0)"><path class="typst-shape" fill="none" stroke="#000000" stroke-width="1" stroke-linecap="butt" stroke-linejoin="miter" stroke-miterlimit="4" d="M 0 0 L 0 30 L 45 30 L 45 0 Z "/></g></g></svg>
+  </body>
+</html>

tests/suite/html/frame.typ

@@ -1,5 +1,6 @@
-// No proper HTML tests here yet because we don't want to test SVG export just
-// yet. We'll definitely add tests at some point.
+--- html-frame html ---
+A rectangle:
+#html.frame(rect())
 
 --- html-frame-in-layout ---
 // Ensure that HTML frames are transparent in layout. This is less important for