Refactor raw blocks 💱

1 files changed, 81 insertions, 12 deletions

diff --git a/src/syntax/tree.rs b/src/syntax/tree.rs
index 5327bfa4..51a7937a 100644
--- a/src/syntax/tree.rs
+++ b/src/syntax/tree.rs
@@ -31,16 +31,93 @@ pub enum SyntaxNode {
     ToggleBolder,
     /// Plain text.
     Text(String),
+    /// An optionally syntax-highlighted raw block.
+    Raw(Raw),
     /// Section headings.
     Heading(Heading),
-    /// Lines of raw text.
-    Raw(Vec<String>),
-    /// An optionally highlighted (multi-line) code block.
-    Code(Code),
     /// A function call.
     Call(CallExpr),
 }
 
+/// A raw block, rendered in monospace with optional syntax highlighting.
+///
+/// Raw blocks start with an arbitrary number of backticks and end with the same
+/// number of backticks. If you want to include a sequence of backticks in a raw
+/// block, simply surround the block with more backticks.
+///
+/// When using at least two backticks, an optional language tag may follow
+/// directly after the backticks. This tag defines which language to
+/// syntax-highlight the text in. Apart from the language tag and some
+/// whitespace trimming discussed below, everything inside a raw block is
+/// rendered verbatim, in particular, there are no escape sequences.
+///
+/// # Examples
+/// - Raw text is surrounded by backticks.
+///   ```typst
+///   `raw`
+///   ```
+/// - An optional language tag may follow directly at the start when the block
+///   is surrounded by at least two backticks.
+///   ```typst
+///   ``rust println!("hello!")``;
+///   ```
+/// - Blocks can span multiple lines. Two backticks suffice to be able to
+///   specify the language tag, but three are fine, too.
+///   ```typst
+///   ``rust
+///   loop {
+///      find_yak().shave();
+///   }
+///   ``
+///   ```
+/// - Start with a space to omit the language tag (the space will be trimmed
+///   from the output) and use more backticks to allow backticks in the raw
+///   text.
+///   `````typst
+///   ```` This contains ```backticks``` and has no leading & trailing spaces. ````
+///   `````
+///
+///   # Trimming
+///   If we would always render the raw text between the backticks exactly as
+///   given, a few things would become problematic or even impossible:
+///   - Typical multiline code blocks (like in the example above) would have an
+///     additional newline before and after the code.
+///   - Raw text wrapped in more than one backtick could not exist without
+///     leading whitespace since the first word would be interpreted as a
+///     language tag.
+///   - A single backtick without surrounding spaces could not exist as raw text
+///     since it would be interpreted as belonging to the opening or closing
+///     backticks.
+///
+///   To fix these problems, we trim text in multi-backtick blocks as follows:
+///   - We trim a single space or a sequence of whitespace followed by a newline
+///     at the start.
+///   - We trim a single space or a newline followed by a sequence of whitespace
+///     at the end.
+///
+///   With these rules, a single raw backtick can be produced by the sequence
+///   ``` `` ` `` ```, ``` `` unhighlighted text `` ``` has no surrounding
+///   spaces and multiline code blocks don't have extra empty lines. Note that
+///   you can always force leading or trailing whitespace simply by adding more
+///   spaces.
+#[derive(Debug, Clone, PartialEq)]
+pub struct Raw {
+    /// An optional identifier specifying the language to syntax-highlight in.
+    pub lang: Option<Ident>,
+    /// The lines of raw text, determined as the raw string between the
+    /// backticks trimmed according to the above rules and split at newlines.
+    pub lines: Vec<String>,
+    /// Whether the element can be layouted inline.
+    ///
+    /// - When true, it will be layouted integrated within the surrounding
+    ///   paragraph.
+    /// - When false, it will be separated into its own paragraph.
+    ///
+    /// Single-backtick blocks are always inline-level. Multi-backtick blocks
+    /// are inline-level when they contain no newlines.
+    pub inline: bool,
+}
+
 /// A section heading.
 #[derive(Debug, Clone, PartialEq)]
 pub struct Heading {
@@ -49,14 +126,6 @@ pub struct Heading {
     pub tree: SyntaxTree,
 }
 
-/// A code block.
-#[derive(Debug, Clone, PartialEq)]
-pub struct Code {
-    pub lang: Option<Spanned<Ident>>,
-    pub lines: Vec<String>,
-    pub block: bool,
-}
-
 /// An expression.
 #[derive(Clone, PartialEq)]
 pub enum Expr {