From 7eebafa7837ec173a7b2064ae60fd45b5413d17c Mon Sep 17 00:00:00 2001 From: Laurenz Date: Thu, 23 Nov 2023 16:25:49 +0100 Subject: Merge `typst` and `typst-library` --- docs/reference/categories.yml | 178 ------------------------------------------ docs/reference/groups.yml | 82 +++++++++++++------ docs/reference/packages.md | 6 ++ 3 files changed, 63 insertions(+), 203 deletions(-) delete mode 100644 docs/reference/categories.yml create mode 100644 docs/reference/packages.md (limited to 'docs/reference') diff --git a/docs/reference/categories.yml b/docs/reference/categories.yml deleted file mode 100644 index 468c9f21..00000000 --- a/docs/reference/categories.yml +++ /dev/null @@ -1,178 +0,0 @@ -# Descriptions of the documentation categories. - -foundations: | - Foundational types and functions. - - Here, you'll find documentation for basic data types like [integers]($int) and - [strings]($str) as well as details about core computational functions. - -text: | - Text styling. - - The [text function]($text) is of particular interest. - -math: | - Typst has special [syntax]($syntax/#math) and library functions to typeset - mathematical formulas. Math formulas can be displayed inline with text or as - separate blocks. They will be typeset into their own block if they start and - end with at least one space (e.g. `[$ x^2 $]`). - - # Variables - In math, single letters are always displayed as is. Multiple letters, however, - are interpreted as variables and functions. To display multiple letters - verbatim, you can place them into quotes and to access single letter - variables, you can use the [hash syntax]($scripting/#expressions). - - ```example - $ A = pi r^2 $ - $ "area" = pi dot "radius"^2 $ - $ cal(A) := - { x in RR | x "is natural" } $ - #let x = 5 - $ #x < 17 $ - ``` - - # Symbols - Math mode makes a wide selection of [symbols]($category/symbols/sym) like - `pi`, `dot`, or `RR` available. Many mathematical symbols are available in - different variants. You can select between different variants by applying - [modifiers]($symbol) to the symbol. Typst further recognizes a number of - shorthand sequences like `=>` that approximate a symbol. When such a shorthand - exists, the symbol's documentation lists it. - - ```example - $ x < y => x gt.eq.not y $ - ``` - - # Line Breaks - Formulas can also contain line breaks. Each line can contain one or multiple - _alignment points_ (`&`) which are then aligned. - - ```example - $ sum_(k=0)^n k - &= 1 + ... + n \ - &= (n(n+1)) / 2 $ - ``` - - # Function calls - Math mode supports special function calls without the hash prefix. In these - "math calls", the argument list works a little differently than in code: - - - Within them, Typst is still in "math mode". Thus, you can write math - directly into them, but need to use hash syntax to pass code expressions - (except for strings, which are available in the math syntax). - - They support positional and named arguments, but don't support trailing - content blocks and argument spreading. - - They provide additional syntax for 2-dimensional argument lists. The - semicolon (`;`) merges preceding arguments separated by commas into an array - argument. - - ```example - $ frac(a^2, 2) $ - $ vec(1, 2, delim: "[") $ - $ mat(1, 2; 3, 4) $ - $ lim_x = - op("lim", limits: #true)_x $ - ``` - - To write a verbatim comma or semicolon in a math call, escape it with a - backslash. The colon on the other hand is only recognized in a special way if - directly preceded by an identifier, so to display it verbatim in those cases, - you can just insert a space before it. - - Functions calls preceded by a hash are normal code function calls and not - affected by these rules. - - # Alignment - When equations include multiple _alignment points_ (`&`), this creates blocks - of alternatingly right- and left-aligned columns. In the example below, the - expression `(3x + y) / 7` is right-aligned and `= 9` is left-aligned. The word - "given" is also left-aligned because `&&` creates two alignment points in a - row, alternating the alignment twice. `& &` and `&&` behave exactly the same - way. Meanwhile, "multiply by 7" is left-aligned because just one `&` precedes - it. Each alignment point simply alternates between right-aligned/left-aligned. - - ```example - $ (3x + y) / 7 &= 9 && "given" \ - 3x + y &= 63 & "multiply by 7" \ - 3x &= 63 - y && "subtract y" \ - x &= 21 - y/3 & "divide by 3" $ - ``` - - # Math fonts - You can set the math font by with a [show-set rule]($styling/#show-rules) as - demonstrated below. Note that only special OpenType math fonts are suitable - for typesetting maths. - - ```example - #show math.equation: set text(font: "Fira Math") - $ sum_(i in NN) 1 + i $ - ``` - - # Math module - All math functions are part of the `math` [module]($scripting/#modules), which - is available by default in equations. Outside of equations, they can be - accessed with the `math.` prefix. - -layout: | - Arranging elements on the page in different ways. - - By combining layout functions, you can create complex and automatic layouts. - -visualize: | - Drawing and data visualization. - - If you want to create more advanced drawings or plots, also have a look at the - [CetZ](https://github.com/johannes-wolf/cetz) package as well as more - specialized [packages]($packages) for your use case. - -meta: | - Document structuring, introspection, and metadata configuration. - - Here, you can find functions to structure your document and interact with that - structure. This includes section headings and figures, bibliography - management, cross-referencing and more. - - Moreover, this category is home to Typst's introspection capabilities: With - the `counter` function, you can access and manipulate page, section, figure, - and equation counters or create custom ones. And the `query` function lets you - search for elements in the document to construct things like a list of - figures or headers which show the current chapter title. - -symbols: | - These two modules give names to symbols and emoji to make them easy to insert - with a normal keyboard. Alternatively, you can also always directly enter - Unicode symbols into your text and formulas. In addition to the symbols listed - below, math mode defines `dif` and `Dif`. These are not normal symbol values - because they also affect spacing and font style. - -sym: | - Named general symbols. - - For example, `#sym.arrow` produces the → symbol. Within - [formulas]($category/math), these symbols can be used without the `#sym.` - prefix. - - The `d` in an integral's `dx` can be written as `[$dif x$]`. - Outside math formulas, `dif` can be accessed as `math.dif`. - -emoji: | - Named emoji. - - For example, `#emoji.face` produces the 😀 emoji. If you frequently use - certain emojis, you can also import them from the `emoji` module (`[#import - emoji: face]`) to use them without the `#emoji.` prefix. - -data-loading: | - Data loading from external files. - - These functions help you with loading and embedding data, for example from - the results of an experiment. - -packages: | - Typst [packages]($scripting/#packages) encapsulate reusable building blocks - and make them reusable across projects. Below is a list of Typst packages - created by the community. Due to the early and experimental nature of Typst's - package management, they all live in a `preview` namespace. Click on a - package's name to view its documentation and use the copy button on the right - to get a full import statement for it. diff --git a/docs/reference/groups.yml b/docs/reference/groups.yml index c6ec4533..fc2b845d 100644 --- a/docs/reference/groups.yml +++ b/docs/reference/groups.yml @@ -2,30 +2,33 @@ # together into one documentation page although they are not part of any scope. - name: variants - display: Variants + title: Variants category: math - functions: ["serif", "sans", "frak", "mono", "bb", "cal"] - description: | + path: ["math"] + filter: ["serif", "sans", "frak", "mono", "bb", "cal"] + details: | Alternate typefaces within formulas. These functions are distinct from the [`text`]($text) function because math fonts contain multiple variants of each letter. - name: styles - display: Styles + title: Styles category: math - functions: ["upright", "italic", "bold"] - description: | + path: ["math"] + filter: ["upright", "italic", "bold"] + details: | Alternate letterforms within formulas. These functions are distinct from the [`text`]($text) function because math fonts contain multiple variants of each letter. - name: sizes - display: Sizes + title: Sizes category: math - functions: ["display", "inline", "script", "sscript"] - description: | + path: ["math"] + filter: ["display", "inline", "script", "sscript"] + details: | Forced size styles for expressions within formulas. These functions allow manual configuration of the size of equation elements @@ -33,9 +36,10 @@ sub/superscripts. - name: underover - display: Under/Over + title: Under/Over category: math - functions: [ + path: ["math"] + filter: [ "underline", "overline", "underbrace", @@ -43,17 +47,18 @@ "underbracket", "overbracket", ] - description: | + details: | Delimiters above or below parts of an equation. The braces and brackets further allow you to add an optional annotation below or above themselves. - name: roots - display: Roots + title: Roots category: math - functions: ["root", "sqrt"] - description: | + path: ["math"] + filter: ["root", "sqrt"] + details: | Square and non-square roots. # Example @@ -63,10 +68,11 @@ ``` - name: attach - display: Attach + title: Attach category: math - functions: ["attach", "scripts", "limits"] - description: | + path: ["math"] + filter: ["attach", "scripts", "limits"] + details: | Subscript, superscripts, and limits. Attachments can be displayed either as sub/superscripts, or limits. Typst @@ -84,10 +90,11 @@ hat (`^`) to indicate a superscript i.e. top attachment. - name: lr - display: Left/Right + title: Left/Right category: math - functions: ["lr", "abs", "norm", "floor", "ceil", "round"] - description: | + path: ["math"] + filter: ["lr", "abs", "norm", "floor", "ceil", "round"] + details: | Delimiter matching. The `lr` function allows you to match two delimiters and scale them with the @@ -105,10 +112,10 @@ ``` - name: calc - display: Calculation + title: Calculation category: foundations path: ["calc"] - description: | + details: | Module for calculations and processing of numeric values. These definitions are part of the `calc` module and not imported by default. @@ -116,12 +123,37 @@ the constants `pi`, `tau`, `e`, `inf`, and `nan`. - name: sys - display: System + title: System category: foundations path: ["sys"] - description: | + details: | Module for system interactions. Currently, this module defines a single item: The `sys.version` constant (of type [`version`]($version)), that specifies the currently active Typst compiler version. + +- name: sym + title: General + category: symbols + path: ["sym"] + details: | + Named general symbols. + + For example, `#sym.arrow` produces the → symbol. Within + [formulas]($category/math), these symbols can be used without the `#sym.` + prefix. + + The `d` in an integral's `dx` can be written as `[$dif x$]`. + Outside math formulas, `dif` can be accessed as `math.dif`. + +- name: emoji + title: Emoji + category: symbols + path: ["emoji"] + details: | + Named emoji. + + For example, `#emoji.face` produces the 😀 emoji. If you frequently use + certain emojis, you can also import them from the `emoji` module (`[#import + emoji: face]`) to use them without the `#emoji.` prefix. diff --git a/docs/reference/packages.md b/docs/reference/packages.md new file mode 100644 index 00000000..bfd1ef58 --- /dev/null +++ b/docs/reference/packages.md @@ -0,0 +1,6 @@ +Typst [packages]($scripting/#packages) encapsulate reusable building blocks +and make them reusable across projects. Below is a list of Typst packages +created by the community. Due to the early and experimental nature of Typst's +package management, they all live in a `preview` namespace. Click on a package's +name to view its documentation and use the copy button on the right to get a +full import statement for it. -- cgit v1.2.3