Improve docs on customizing `raw` (#6000)
Co-authored-by: Malo <57839069+MDLC01@users.noreply.github.com> Co-authored-by: Laurenz <laurmaedje@gmail.com>
This commit is contained in:
PgBiel
GitHub
parent
16758e7daa
commit
b08593bf26
|
|
@ -2975,7 +2975,7 @@ dependencies = [
|
|||
[[package]]
|
||||
name = "typst-dev-assets"
|
||||
version = "0.13.1"
|
||||
source = "git+https://github.com/typst/typst-dev-assets?rev=c6c2acf#c6c2acf6cdc31f99a23a478d3d614f8bf806a4f5"
|
||||
source = "git+https://github.com/typst/typst-dev-assets?rev=cb896b4#cb896b4ce786b8b33af15791da894327572fc488"
|
||||
|
||||
[[package]]
|
||||
name = "typst-docs"
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ typst-syntax = { path = "crates/typst-syntax", version = "0.13.1" }
|
|||
typst-timing = { path = "crates/typst-timing", version = "0.13.1" }
|
||||
typst-utils = { path = "crates/typst-utils", version = "0.13.1" }
|
||||
typst-assets = { git = "https://github.com/typst/typst-assets", rev = "fbf00f9" }
|
||||
typst-dev-assets = { git = "https://github.com/typst/typst-dev-assets", rev = "c6c2acf" }
|
||||
typst-dev-assets = { git = "https://github.com/typst/typst-dev-assets", rev = "cb896b4" }
|
||||
arrayvec = "0.7.4"
|
||||
az = "1.2"
|
||||
base64 = "0.22"
|
||||
|
|
|
|||
|
|
@ -32,6 +32,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
|
||||
|
|
@ -74,6 +80,49 @@ 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 (or if you want to override the built-in definition), you may
|
||||
/// provide a custom syntax specification file to the
|
||||
/// [`syntaxes`]($raw.syntaxes) field.
|
||||
///
|
||||
/// # Styling
|
||||
/// By default, the `raw` element uses the `DejaVu Sans Mono` font (included
|
||||
/// with 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")
|
||||
///
|
||||
/// // Reset raw blocks to the same size as normal text,
|
||||
/// // but keep inline raw at the reduced size.
|
||||
/// #show raw.where(block: true): set text(1em / 0.8)
|
||||
///
|
||||
/// 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.
|
||||
///
|
||||
/// Note that, in raw text, typesetting features like
|
||||
/// [hyphenation]($text.hyphenate), [overhang]($text.overhang),
|
||||
/// [CJK-Latin spacing]($text.cjk-latin-spacing) (and
|
||||
/// [justification]($par.justify) for [raw blocks]($raw.block)) will be
|
||||
/// disabled by default.
|
||||
#[elem(
|
||||
scope,
|
||||
title = "Raw Text / Code",
|
||||
|
|
|
|||
|
|
@ -76,21 +76,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`] |
|
||||
| Monospace (typewriter) | `\texttt{mono}` | `text` or `mono` functions | [`text`], [`mono`]($math.mono) |
|
||||
| Code | `lstlisting` environment | ``[`print(f"{x}")`]`` | [`raw`] |
|
||||
| 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`),
|
||||
|
|
@ -122,6 +124,18 @@ To get a [numbered list]($enum) (`enumerate`) instead, use a `+` instead of the
|
|||
hyphen. For a [term list]($terms) (`description`), write `[/ Term: Description]`
|
||||
instead.
|
||||
|
||||
Note that the [`raw` function]($raw) and syntax (e.g. ``[`raw`]``) only work for
|
||||
verbatim (unformatted) text. If you require formatting, you can use the
|
||||
[`text` function]($text) with a monospace font instead, like in the example
|
||||
below:
|
||||
|
||||
```example
|
||||
#text(
|
||||
font: "DejaVu Sans Mono",
|
||||
size: 0.8em,
|
||||
)[monospace *bold*]
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue