From ebfdb1dafa430786db10dad2ef7d5467c1bdbed1 Mon Sep 17 00:00:00 2001 From: Laurenz Date: Sun, 2 Jul 2023 19:59:52 +0200 Subject: Move everything into `crates/` directory --- docs/Cargo.toml | 27 - docs/changelog.md | 726 ++++++++++++++++++ docs/community.md | 72 ++ docs/dev/architecture.md | 171 +++++ docs/guides/guide-for-latex-users.md | 602 +++++++++++++++ docs/guides/welcome.md | 11 + docs/overview.md | 15 + docs/reference/details.yml | 174 +++++ docs/reference/groups.yml | 76 ++ docs/reference/scripting.md | 345 +++++++++ docs/reference/styling.md | 145 ++++ docs/reference/syntax.md | 138 ++++ docs/reference/types.md | 1190 ++++++++++++++++++++++++++++++ docs/reference/welcome.md | 29 + docs/src/contribs.rs | 86 --- docs/src/general/changelog.md | 726 ------------------ docs/src/general/community.md | 72 -- docs/src/general/overview.md | 15 - docs/src/guides/guide-for-latex-users.md | 602 --------------- docs/src/guides/welcome.md | 11 - docs/src/html.rs | 513 ------------- docs/src/lib.rs | 1002 ------------------------- docs/src/reference/details.yml | 174 ----- docs/src/reference/groups.yml | 76 -- docs/src/reference/scripting.md | 345 --------- docs/src/reference/styling.md | 145 ---- docs/src/reference/syntax.md | 138 ---- docs/src/reference/types.md | 1190 ------------------------------ docs/src/reference/welcome.md | 29 - docs/src/tutorial/1-writing.md | 308 -------- docs/src/tutorial/2-formatting.md | 283 ------- docs/src/tutorial/3-advanced.md | 509 ------------- docs/src/tutorial/4-template.md | 380 ---------- docs/src/tutorial/welcome.md | 44 -- docs/tutorial/1-writing.md | 308 ++++++++ docs/tutorial/2-formatting.md | 283 +++++++ docs/tutorial/3-advanced.md | 509 +++++++++++++ docs/tutorial/4-template.md | 380 ++++++++++ docs/tutorial/welcome.md | 44 ++ 39 files changed, 5218 insertions(+), 6675 deletions(-) delete mode 100644 docs/Cargo.toml create mode 100644 docs/changelog.md create mode 100644 docs/community.md create mode 100644 docs/dev/architecture.md create mode 100644 docs/guides/guide-for-latex-users.md create mode 100644 docs/guides/welcome.md create mode 100644 docs/overview.md create mode 100644 docs/reference/details.yml create mode 100644 docs/reference/groups.yml create mode 100644 docs/reference/scripting.md create mode 100644 docs/reference/styling.md create mode 100644 docs/reference/syntax.md create mode 100644 docs/reference/types.md create mode 100644 docs/reference/welcome.md delete mode 100644 docs/src/contribs.rs delete mode 100644 docs/src/general/changelog.md delete mode 100644 docs/src/general/community.md delete mode 100644 docs/src/general/overview.md delete mode 100644 docs/src/guides/guide-for-latex-users.md delete mode 100644 docs/src/guides/welcome.md delete mode 100644 docs/src/html.rs delete mode 100644 docs/src/lib.rs delete mode 100644 docs/src/reference/details.yml delete mode 100644 docs/src/reference/groups.yml delete mode 100644 docs/src/reference/scripting.md delete mode 100644 docs/src/reference/styling.md delete mode 100644 docs/src/reference/syntax.md delete mode 100644 docs/src/reference/types.md delete mode 100644 docs/src/reference/welcome.md delete mode 100644 docs/src/tutorial/1-writing.md delete mode 100644 docs/src/tutorial/2-formatting.md delete mode 100644 docs/src/tutorial/3-advanced.md delete mode 100644 docs/src/tutorial/4-template.md delete mode 100644 docs/src/tutorial/welcome.md create mode 100644 docs/tutorial/1-writing.md create mode 100644 docs/tutorial/2-formatting.md create mode 100644 docs/tutorial/3-advanced.md create mode 100644 docs/tutorial/4-template.md create mode 100644 docs/tutorial/welcome.md (limited to 'docs') diff --git a/docs/Cargo.toml b/docs/Cargo.toml deleted file mode 100644 index b6015d01..00000000 --- a/docs/Cargo.toml +++ /dev/null @@ -1,27 +0,0 @@ -[package] -name = "typst-docs" -version.workspace = true -rust-version.workspace = true -authors.workspace = true -edition.workspace = true -publish = false - -[lib] -doctest = false -bench = false - -[dependencies] -typst = { path = ".." } -typst-library = { path = "../library" } -comemo = "0.3" -heck = "0.4" -include_dir = "0.7" -once_cell = "1" -pulldown-cmark = "0.9" -serde = { version = "1", features = ["derive"] } -serde_yaml = "0.8" -syntect = { version = "5", default-features = false, features = ["parsing", "html", "regex-fancy"] } -typed-arena = "2" -unicode_names2 = "0.6.0" -unscanny = "0.1" -yaml-front-matter = "0.1" diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 00000000..95808fab --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,726 @@ +--- +description: | + Learn what has changed in the latest Typst releases and move your documents + forward. +--- + +# Changelog +## Version 0.6.0 (June 30, 2023) { #v0.6.0 } +- Package Management + - Typst now has built-in [package management]($scripting/#packages) + - You can import [published]($packages) community packages or create and use + [system-local](https://github.com/typst/packages#local-packages) ones + - Published packages are also supported in the web app + +- Math + - Added support for optical size variants of glyphs in math mode + - Added argument to enable [`limits`]($func/math.limits) conditionally + depending on whether the equation is set in [`display`]($func/math.display) + or [`inline`]($func/math.inline) style + - Added `gt.eq.slant` and `lt.eq.slant` symbols + - Increased precedence of factorials in math mode (`[$1/n!$]` works correctly + now) + - Improved [underlines]($func/math.underline) and + [overlines]($func/math.overline) in math mode + - Fixed usage of [`limits`]($func/math.limits) function in show rules + - Fixed bugs with line breaks in equations + +- Text and Layout + - Added support for alternating page [margins]($func/page.margin) with the + `inside` and `outside` keys + - Added support for specifying the page [`binding`]($func/page.binding) + - Added [`to`]($func/pagebreak.to) argument to pagebreak function to skip to + the next even or odd page + - Added basic i18n for a few more languages (TR, SQ, TL) + - Fixed bug with missing table row at page break + - Fixed bug with [underlines]($func/underline) + - Fixed bug superfluous table lines + - Fixed smart quotes after line breaks + - Fixed a crash related to text layout + +- Command line interface + - **Breaking change:** Added requirement for `--root`/`TYPST_ROOT` directory + to contain the input file because it designates the _project_ root. Existing + setups that use `TYPST_ROOT` to emulate package management should switch to + [local packages](https://github.com/typst/packages#local-packages) + - **Breaking change:** Now denies file access outside of the project root + - Added support for local packages and on-demand package download + - Now watches all relevant files, within the root and all packages + - Now displays compilation time + +- Miscellaneous Improvements + - Added [`outline.entry`]($func/outline.entry) to customize outline entries + with show rules + - Added some hints for error messages + - Added some missing syntaxes for [`raw`]($func/raw) highlighting + - Improved rendering of rotated images in PNG export and web app + - Made [footnotes]($func/footnote) reusable and referenceable + - Fixed bug with citations and bibliographies in [`locate`]($func/locate) + - Fixed inconsistent tense in documentation + +- Development + - Added [contribution guide](https://github.com/typst/typst/blob/main/CONTRIBUTING.md) + - Reworked `World` interface to accommodate for package management and make + it a bit simpler to implement _(Breaking change for implementors)_ + + + +## Version 0.5.0 (June 9, 2023) { #v0.5.0 } +- Text and Layout + - Added [`raw`]($func/raw) syntax highlighting for many more languages + - Added support for Korean [numbering]($func/numbering) + - Added basic i18n for a few more languages (NL, SV, DA) + - Improved linebreaking for East Asian languages + - Expanded functionality of outline [`indent`]($func/outline.indent) property + - Fixed footnotes in columns + - Fixed page breaking bugs with [footnotes]($func/footnote) + - Fixed bug with handling of footnotes in lists, tables, and figures + - Fixed a bug with CJK punctuation adjustment + - Fixed a crash with rounded rectangles + - Fixed alignment of [`line`]($func/line) elements + +- Math + - **Breaking change:** The syntax rules for mathematical + [attachments]($func/math.attach) were improved: `[$f^abs(3)$]` now parses as + `[$f^(abs(3))$]` instead of `[$(f^abs)(3)$]`. To disambiguate, add a space: + `[$f^zeta (3)$]`. + - Added [forced size]($category/math/sizes) commands for math + (e.g., [`display`]($func/math.display)) + - Added [`supplement`]($func/math.equation.supplement) parameter to + [`equation`]($func/math.equation), used by [references]($func/ref) + - New [symbols]($category/symbols/sym): `bullet`, `xor`, `slash.big`, + `sigma.alt`, `tack.r.not`, `tack.r.short`, `tack.r.double.not` + - Fixed a bug with symbols in matrices + - Fixed a crash in the [`attach`]($func/math.attach) function + +- Scripting + - Added new [`datetime`]($type/datetime) type and + [`datetime.today()`]($func/datetime.today) to retrieve the current date + - Added [`str.from-unicode`]($func/str.from-unicode) and + [`str.to-unicode`]($func/str.to-unicode) functions + - Added [`fields`]($type/content.fields) method on content + - Added `base` parameter to [`str`]($func/str) function + - Added [`calc.exp`]($func/calc.exp) and [`calc.ln`]($func/calc.ln) + - Improved accuracy of [`calc.pow`]($func/calc.pow) and + [`calc.log`]($func/calc.log) for specific bases + - Fixed [removal]($type/dictionary.remove) order for dictionary + - Fixed `.at(default: ..)` for [strings]($type/string.at) and + [content]($type/content.at) + - Fixed field access on styled elements + - Removed deprecated `calc.mod` function + +- Command line interface + - Added PNG export via `typst compile source.typ output-{n}.png`. The output + path must contain `[{n}]` if the document has multiple pages. + - Added `--diagnostic-format=short` for Unix-style short diagnostics + - Doesn't emit color codes anymore if stderr isn't a TTY + - Now sets the correct exit when invoked with a non-existent file + - Now ignores UTF-8 BOM in Typst files + +- Miscellaneous Improvements + - Improved errors for mismatched delimiters + - Improved error message for failed length comparisons + - Fixed a bug with images not showing up in Apple Preview + - Fixed multiple bugs with the PDF outline + - Fixed citations and other searchable elements in [`hide`]($func/hide) + - Fixed bugs with [reference supplements]($func/ref.supplement) + - Fixed Nix flake + + + +## Version 0.4.0 (May 20, 2023) { #v0.4.0 } +- Footnotes + - Implemented support for footnotes + - The [`footnote`]($func/footnote) function inserts a footnote + - The [`footnote.entry`]($func/footnote.entry) function can be used to + customize the footnote listing + - The `{"chicago-notes"}` [citation style]($func/cite.style) is now available + +- Documentation + - Added a [Guide for LaTeX users]($guides/guide-for-latex-users) + - Now shows default values for optional arguments + - Added richer outlines in "On this Page" + - Added initial support for search keywords: "Table of Contents" will now find + the [outline]($func/outline) function. Suggestions for more keywords are + welcome! + - Fixed issue with search result ranking + - Fixed many more small issues + +- Math + - **Breaking change**: Alignment points (`&`) in equations now alternate + between left and right alignment + - Added support for writing roots with Unicode: + For example, `[$root(x+y)$]` can now also be written as `[$√(x+y)$]` + - Fixed uneven vertical [`attachment`]($func/math.attach) alignment + - Fixed spacing on decorated elements + (e.g., spacing around a [canceled]($func/math.cancel) operator) + - Fixed styling for stretchable symbols + - Added `tack.r.double`, `tack.l.double`, `dotless.i` and `dotless.j` + [symbols]($category/symbols/sym) + - Fixed show rules on symbols (e.g. `{show sym.tack: set text(blue)}`) + - Fixed missing rename from `ast.op` to `ast` that should have been in the + previous release + +- Scripting + - Added function scopes: A function can now hold related definitions in its + own scope, similar to a module. The new [`assert.eq`]($func/assert.eq) + function, for instance, is part of the [`assert`]($func/assert) function's + scope. Note that function scopes are currently only available for built-in + functions. + - Added [`assert.eq`]($func/assert.eq) and [`assert.ne`]($func/assert.ne) + functions for simpler equality and inequality assertions with more helpful + error messages + - Exposed [list]($func/list.item), [enum]($func/enum.item), and + [term list]($func/terms.item) items in their respective functions' scope + - The `at` methods on [strings]($type/string.at), [arrays]($type/array.at), + [dictionaries]($type/dictionary.at), and [content]($type/content.at) now support + specifying a default value + - Added support for passing a function to [`replace`]($type/string.replace) + that is called with each match. + - Fixed [replacement]($type/string.replace) strings: They are now inserted + completely verbatim instead of supporting the previous (unintended) magic + dollar syntax for capture groups + - Fixed bug with trailing placeholders in destructuring patterns + - Fixed bug with underscore in parameter destructuring + - Fixed crash with nested patterns and when hovering over an invalid pattern + - Better error messages when casting to an [integer]($func/int) or + [float]($func/float) fails + +- Text and Layout + - Implemented sophisticated CJK punctuation adjustment + - Disabled [overhang]($func/text.overhang) for CJK punctuation + - Added basic translations for Traditional Chinese + - Fixed [alignment]($func/raw.align) of text inside raw blocks (centering a + raw block, e.g. through a figure, will now keep the text itself + left-aligned) + - Added support for passing a array instead of a function to configure table + cell [alignment]($func/table.align) and [fill]($func/table.fill) per column + - Fixed automatic figure [`kind`]($func/figure.kind) detection + - Made alignment of [enum numbers]($func/enum.number-align) configurable, + defaulting to `end` + - Figures can now be made breakable with a show-set rule for blocks in figure + - Initial fix for smart quotes in RTL languages + +- Export + - Fixed ligatures in PDF export: They are now copyable and searchable + - Exported PDFs now embed ICC profiles for images that have them + - Fixed export of strokes with zero thickness + +- Web app + - Projects can now contain folders + - Added upload by drag-and-drop into the file panel + - Files from the file panel can now be dragged into the editor to insert them + into a Typst file + - You can now copy-paste images and other files from your computer directly + into the editor + - Added a button to resend confirmation email + - Added an option to invert preview colors in dark mode + - Added tips to the loading screen and the Help menu. Feel free to propose + more! + - Added syntax highlighting for YAML files + - Allowed middle mouse button click on many buttons to navigate into a new tab + - Allowed more project names + - Fixed overridden Vim mode keybindings + - Fixed many bugs regarding file upload and more + +- Miscellaneous Improvements + - Improved performance of counters, state, and queries + - Improved incremental parsing for more efficient recompilations + - Added support for `.yaml` extension in addition to `.yml` for bibliographies + - The CLI now emits escape codes only if the output is a TTY + - For users of the `typst` crate: The `Document` is now `Sync` again and + the `World` doesn't have to be `'static` anymore + + + +## Version 0.3.0 (April 26, 2023) { #v0.3.0 } +- **Breaking changes:** + - Renamed a few symbols: What was previous `dot.op` is now just `dot` and the + basic dot is `dot.basic`. The same applies to `ast` and `tilde`. + - Renamed `mod` to [`rem`]($func/calc.rem) to more accurately reflect + the behaviour. It will remain available as `mod` until the next update as a + grace period. + - A lone underscore is not a valid identifier anymore, it can now only be used + in patterns + - Removed `before` and `after` arguments from [`query`]($func/query). This is + now handled through flexible [selectors]($type/selector) combinator methods + - Added support for [attachments]($func/math.attach) (sub-, superscripts) that + precede the base symbol. The `top` and `bottom` arguments have been renamed + to `t` and `b`. + +- New features + - Added support for more complex [strokes]($func/line.stroke) + (configurable caps, joins, and dash patterns) + - Added [`cancel`]($func/math.cancel) function for equations + - Added support for [destructuring]($scripting/#bindings) in argument lists + and assignments + - Added [`alt`]($func/image.alt) text argument to image function + - Added [`toml`]($func/toml) function for loading data from a TOML file + - Added [`zip`]($type/array.zip), [`sum`]($type/array.sum), and + [`product`]($type/array.product) methods for arrays + - Added `fact`, `perm`, `binom`, `gcd`, `lcm`, `atan2`, `quo`, `trunc`, and + `fract` [calculation]($category/calculate) + +- Improvements + - Text in SVGs now displays properly + - Typst now generates a PDF heading outline + - [References]($func/ref) now provides the referenced element as a field in + show rules + - Refined linebreak algorithm for better Chinese justification + - Locations are now a valid kind of selector + - Added a few symbols for algebra + - Added Spanish smart quote support + - Added [`selector`]($func/selector) function to turn a selector-like value + into a selector on which combinator methods can be called + - Improved some error messages + - The outline and bibliography headings can now be styled with show-set rules + - Operations on numbers now produce an error instead of overflowing + +- Bug fixes + - Fixed wrong linebreak before punctuation that follows inline equations, + citations, and other elements + - Fixed a bug with [argument sinks]($type/arguments) + - Fixed strokes with thickness zero + - Fixed hiding and show rules in math + - Fixed alignment in matrices + - Fixed some alignment bugs in equations + - Fixed grid cell alignment + - Fixed alignment of list marker and enum markers in presence of global + alignment settings + - Fixed [path]($func/path) closing + - Fixed compiler crash with figure references + - A single trailing line breaks is now ignored in math, just like in text + +- Command line interface + - Font path and compilation root can now be set with the environment + variables `TYPST_FONT_PATHS` and `TYPST_ROOT` + - The output of `typst fonts` now includes the embedded fonts + +- Development + - Added instrumentation for debugging and optimization + - Added `--update` flag and `UPDATE_EXPECT` environment variable to update + reference images for tests + - You can now run a specific subtest with `--subtest` + - Tests now run on multiple threads + + + +## Version 0.2.0 (April 11, 2023) { #v0.2.0 } +- **Breaking changes:** + - Removed support for iterating over index and value in + [for loops]($scripting/#loops). This is now handled via unpacking and + enumerating. Same goes for the [`map()`]($type/array.map) method. + - [Dictionaries]($type/dictionary) now iterate in insertion order instead of + alphabetical order. + +- New features + - Added [unpacking syntax]($scripting/#bindings) for let bindings, which + allows things like `{let (1, 2) = array}` + - Added [`enumerate()`]($type/array.enumerate) method + - Added [`path`]($func/path) function for drawing Bézier paths + - Added [`layout`]($func/layout) function to access the size of the + surrounding page or container + - Added `key` parameter to [`sorted()`]($type/array.sorted) method + +- Command line interface + - Fixed `--open` flag blocking the program + - New Computer Modern font is now embedded into the binary + - Shell completions and man pages can now be generated by setting the + `GEN_ARTIFACTS` environment variable to a target directory and then building + Typst + +- Miscellaneous improvements + - Fixed page numbering in outline + - Added basic i18n for a few more languages + (AR, NB, CS, NN, PL, SL, ES, UA, VI) + - Added a few numbering patterns (Ihora, Chinese) + - Added `sinc` [operator]($func/math.op) + - Fixed bug where math could not be hidden with [`hide`]($func/hide) + - Fixed sizing issues with box, block, and shapes + - Fixed some translations + - Fixed inversion of "R" in [`cal`]($func/math.cal) and + [`frak`]($func/math.frak) styles + - Fixed some styling issues in math + - Fixed supplements of references to headings + - Fixed syntax highlighting of identifiers in certain scenarios + - [Ratios]($type/ratio) can now be multiplied with more types and be converted + to [floats]($type/float) with the [`float`]($func/float) function + + + +## Version 0.1.0 (April 04, 2023) { #v0.1.0 } +- **Breaking changes:** + - When using the CLI, you now have to use subcommands: + - `typst compile file.typ` or `typst c file.typ` to create a PDF + - `typst watch file.typ` or `typst w file.typ` to compile and watch + - `typst fonts` to list all fonts + - Manual counters now start at zero. Read the "How to step" section + [here]($func/counter) for more details + - The [bibliography styles]($func/bibliography.style) + `{"author-date"}` and `{"author-title"}` were renamed to + `{"chicago-author-date"}` and `{"chicago-author-title"}` + +- Figure improvements + - Figures now automatically detect their content and adapt their + behaviour. Figures containing tables, for instance, are automatically + prefixed with "Table X" and have a separate counter + - The figure's supplement (e.g. "Figure" or "Table") can now be customized + - In addition, figures can now be completely customized because the show rule + gives access to the automatically resolved kind, supplement, and counter + +- Bibliography improvements + - The [`bibliography`]($func/bibliography) now also accepts multiple + bibliography paths (as an array) + - Parsing of BibLaTeX files is now more permissive (accepts non-numeric + edition, pages, volumes, dates, and Jabref-style comments; fixed + abbreviation parsing) + - Labels and references can now include `:` and `.` except at the end + - Fixed APA bibliography ordering + +- Drawing additions + - Added [`polygon`]($func/polygon) function for drawing polygons + - Added support for clipping in [boxes]($func/box.clip) and + [blocks]($func/block.clip) + +- Command line interface + - Now returns with non-zero status code if there is an error + - Now watches the root directory instead of the current one + - Now puts the PDF file next to input file by default + - Now accepts more kinds of input files (e.g. `/dev/stdin`) + - Added `--open` flag to directly open the PDF + +- Miscellaneous improvements + - Added [`yaml`]($func/yaml) function to load data from YAML files + - Added basic i18n for a few more languages (IT, RU, ZH, FR, PT) + - Added numbering support for Hebrew + - Added support for [integers]($type/integer) with base 2, 8, and 16 + - Added symbols for double bracket and laplace operator + - The [`link`]($func/link) function now accepts [labels]($func/label) + - The link syntax now allows more characters + - Improved justification of Japanese and Chinese text + - Calculation functions behave more consistently w.r.t to non-real results + - Replaced deprecated angle brackets + - Reduced maximum function call depth from 256 to 64 + - Fixed [`first-line-indent`]($func/par.first-line-indent) being not applied + when a paragraph starts with styled text + - Fixed extraneous spacing in unary operators in equations + - Fixed block spacing, e.g. in `{block(above: 1cm, below: 1cm, ..)}` + - Fixed styling of text operators in math + - Fixed invalid parsing of language tag in raw block with a single backtick + - Fixed bugs with displaying counters and state + - Fixed crash related to page counter + - Fixed crash when [`symbol`]($func/symbol) function was called without + arguments + - Fixed crash in bibliography generation + - Fixed access to label of certain content elements + - Fixed line number in error message for CSV parsing + - Fixed invalid autocompletion after certain markup elements + + + +## March 28, 2023 +- **Breaking changes:** + - Enumerations now require a space after their marker, that is, `[1.ok]` must + now be written as `[1. ok]` + - Changed default style for [term lists]($func/terms): Does not include a + colon anymore and has a bit more indent + +- Command line interface + - Added `--font-path` argument for CLI + - Embedded default fonts in CLI binary + - Fixed build of CLI if `git` is not installed + +- Miscellaneous improvements + - Added support for disabling [matrix]($func/math.mat) and + [vector]($func/math.vec) delimiters. Generally with + `[#set math.mat(delim: none)]` or one-off with + `[$mat(delim: #none, 1, 2; 3, 4)$]`. + - Added [`separator`]($func/terms.separator) argument to term lists + - Added [`round`]($func/math.round) function for equations + - Numberings now allow zeros. To reset a counter, you can write + `[#counter(..).update(0)]` + - Added documentation for `{page()}` and `{position()}` methods on + [`location`]($func/locate) type + - Added symbols for double, triple, and quadruple dot accent + - Added smart quotes for Norwegian Bokmål + - Added Nix flake + - Fixed bibliography ordering in IEEE style + - Fixed parsing of decimals in math: `[$1.2/3.4$]` + - Fixed parsing of unbalanced delimiters in fractions: `[$1/(2 (x)$]` + - Fixed unexpected parsing of numbers as enumerations, e.g. in `[1.2]` + - Fixed combination of page fill and header + - Fixed compiler crash if [`repeat`]($func/repeat) is used in page with + automatic width + - Fixed [matrices]($func/math.mat) with explicit delimiter + - Fixed [`indent`]($func/terms.indent) property of term lists + - Numerous documentation fixes + - Links in bibliographies are now affected by link styling + - Fixed hovering over comments in web app + + + +## March 21, 2023 +- Reference and bibliography management + - [Bibliographies]($func/bibliography) and [citations]($func/cite) (currently + supported styles are APA, Chicago Author Date, IEEE, and MLA) + - You can now [reference]($func/ref) sections, figures, formulas, and works + from the bibliography with `[@label]` + - You can make an element referenceable with a label: + - `[= Introduction ]` + - `[$ A = pi r^2 $ ]` + +- Introspection system for interactions between different parts of the document + - [`counter`]($func/counter) function + - Access and modify counters for pages, headings, figures, and equations + - Define and use your own custom counters + - Time travel: Find out what the counter value was or will be at some other + point in the document (e.g. when you're building a list of figures, you + can determine the value of the figure counter at any given figure). + - Counters count in layout order and not in code order + - [`state`]($func/state) function + - Manage arbitrary state across your document + - Time travel: Find out the value of your state at any position in the + document + - State is modified in layout order and not in code order + - [`query`]($func/query) function + - Find all occurrences of an element or a label, either in the whole document + or before/after some location + - Link to elements, find out their position on the pages and access their + fields + - Example use cases: Custom list of figures or page header with current + chapter title + - [`locate`]($func/locate) function + - Determines the location of itself in the final layout + - Can be accessed to get the `page` and `x`, `y` coordinates + - Can be used with counters and state to find out their values at that + location + - Can be used with queries to find elements before or after its location + +- New [`measure`]($func/measure) function + - Measure the layouted size of elements + - To be used in combination with the new [`style`]($func/style) function that + lets you generate different content based on the style context something is + inserted into (because that affects the measured size of content) + +- Exposed content representation + - Content is not opaque anymore + - Content can be compared for equality + - The tree of content elements can be traversed with code + - Can be observed in hover tooltips or with [`repr`]($func/repr) + - New [methods]($type/content) on content: `func`, `has`, `at`, and `location` + - All optional fields on elements are now settable + - More uniform field names (`heading.title` becomes `heading.body`, + `list.items` becomes `list.children`, and a few more changes) + +- Further improvements + - Added [`figure`]($func/figure) function + - Added [`numbering`]($func/math.equation.numbering) parameter on equation function + - Added [`numbering`]($func/page.numbering) and + [`number-align`]($func/page.number-align) parameters on page function + - The page function's [`header`]($func/page.header) and + [`footer`]($func/page.footer) parameters do not take functions anymore. If + you want to customize them based on the page number, use the new + [`numbering`]($func/page.numbering) parameter or [`counter`]($func/counter) + function instead. + - Added [`footer-descent`]($func/page.footer-descent) and + [`header-ascent`]($func/page.header-ascent) parameters + - Better default alignment in header and footer + - Fixed Arabic vowel placement + - Fixed PDF font embedding issues + - Renamed `math.formula` to [`math.equation`]($func/math.equation) + - Font family must be a named argument now: `[#set text(font: "..")]` + - Added support for [hanging indent]($func/par.hanging-indent) + - Renamed paragraph `indent` to + [`first-line-indent`]($func/par.first-line-indent) + - More accurate [logarithm]($func/calc.log) when base is `2` or `10` + - Improved some error messages + - Fixed layout of [`terms`]($func/terms) list + +- Web app improvements + - Added template gallery + - Added buttons to insert headings, equations, raw blocks, and references + - Jump to the source of something by clicking on it in the preview panel + (works for text, equations, images, and more) + - You can now upload your own fonts and use them in your project + - Hover debugging and autocompletion now takes multiple files into account and + works in show rules + - Hover tooltips now automatically collapse multiple consecutive equal values + - The preview now automatically scrolls to the right place when you type + - Links are now clickable in the preview area + - Toolbar, preview, and editor can now all be hidden + - Added autocompletion for raw block language tags + - Added autocompletion in SVG files + - New back button instead of four-dots button + - Lots of bug fixes + +## February 25, 2023 +- Font changes + - New default font: Linux Libertine + - New default font for raw blocks: DejaVu Sans Mono + - New default font for math: Book weight of New Computer Modern Math + - Lots of new math fonts available + - Removed Latin Modern fonts in favor of New Computer Modern family + - Removed unnecessary smallcaps fonts which are already accessible through + the corresponding main font and the [`smallcaps`]($func/smallcaps) function +- Improved default spacing for headings +- Added [`panic`]($func/panic) function +- Added [`clusters`]($type/string.clusters) and + [`codepoints`]($type/string.codepoints) + methods for strings +- Support for multiple authors in [`set document`]($func/document.author) +- Fixed crash when string is accessed at a position that is not a char boundary +- Fixed semicolon parsing in `[#var ;]` +- Fixed incremental parsing when inserting backslash at end of `[#"abc"]` +- Fixed names of a few font families + (including Noto Sans Symbols and New Computer Modern families) +- Fixed autocompletion for font families +- Improved incremental compilation for user-defined functions + +## February 15, 2023 +- [Box]($func/box) and [block]($func/block) have gained `fill`, `stroke`, + `radius`, and `inset` properties +- Blocks may now be explicitly sized, fixed-height blocks can still break + across pages +- Blocks can now be configured to be [`breakable`]($func/block.breakable) or not +- [Numbering style]($func/enum.numbering) can now be configured for nested enums +- [Markers]($func/list.marker) can now be configured for nested lists +- The [`eval`]($func/eval) function now expects code instead of markup and + returns an arbitrary value. Markup can still be evaluated by surrounding the + string with brackets. +- PDFs generated by Typst now contain XMP metadata +- Link boxes are now disabled in PDF output +- Tables don't produce small empty cells before a pagebreak anymore +- Fixed raw block highlighting bug + +## February 12, 2023 +- Shapes, images, and transformations (move/rotate/scale/repeat) are now + block-level. To integrate them into a paragraph, use a [`box`]($func/box) as + with other elements. +- A colon is now required in an "everything" show rule: Write `{show: it => ..}` + instead of `{show it => ..}`. This prevents intermediate states that ruin + your whole document. +- Non-math content like a shape or table in a math formula is now centered + vertically +- Support for widow and orphan prevention within containers +- Support for [RTL]($func/text.dir) in lists, grids, and tables +- Support for explicit `{auto}` sizing for boxes and shapes +- Support for fractional (i.e. `{1fr}`) widths for boxes +- Fixed bug where columns jump to next page +- Fixed bug where list items have no leading +- Fixed relative sizing in lists, squares and grid auto columns +- Fixed relative displacement in [`place`]($func/place) function +- Fixed that lines don't have a size +- Fixed bug where `{set document(..)}` complains about being after content +- Fixed parsing of `{not in}` operation +- Fixed hover tooltips in math +- Fixed bug where a heading show rule may not contain a pagebreak when an + outline is present +- Added [`baseline`]($func/box.baseline) property on [`box`]($func/box) +- Added [`tg`]($func/math.op) and [`ctg`]($func/math.op) operators in math +- Added delimiter setting for [`cases`]($func/math.cases) function +- Parentheses are now included when accepting a function autocompletion + +## February 2, 2023 +- Merged text and math symbols, renamed a few symbols + (including `infty` to `infinity` with the alias `oo`) +- Fixed missing italic mappings +- Math italics correction is now applied properly +- Parentheses now scale in `[$zeta(x/2)$]` +- Fixed placement of large root index +- Fixed spacing in `[$abs(-x)$]` +- Fixed inconsistency between text and identifiers in math +- Accents are now ignored when positioning superscripts +- Fixed vertical alignment in matrices +- Fixed `text` set rule in `raw` show rule +- Heading and list markers now parse consistently +- Allow arbitrary math directly in content + +## January 30, 2023 +[Go to the announcement blog post.](https://typst.app/blog/2023/january-update) +- New expression syntax in markup/math + - Blocks cannot be directly embedded in markup anymore + - Like other expressions, they now require a leading hashtag + - More expressions available with hashtag, including literals + (`[#"string"]`) as well as field access and method call + without space: `[#emoji.face]` +- New import syntax + - `[#import "module.typ"]` creates binding named `module` + - `[#import "module.typ": a, b]` or `[#import "module.typ": *]` to import items + - `[#import emoji: face, turtle]` to import from already bound module +- New symbol handling + - Removed symbol notation + - Symbols are now in modules: `{sym}`, `{emoji}`, and `{math}` + - Math module also reexports all of `{sym}` + - Modified through field access, still order-independent + - Unknown modifiers are not allowed anymore + - Support for custom symbol definitions with `symbol` function + - Symbols now listed in documentation +- New `{math}` module + - Contains all math-related functions + - Variables and function calls directly in math (without hashtag) access this + module instead of the global scope, but can also access local variables + - Can be explicitly used in code, e.g. `[#set math.vec(delim: "[")]` +- Delimiter matching in math + - Any opening delimiters matches any closing one + - When matched, they automatically scale + - To prevent scaling, escape them + - To forcibly match two delimiters, use `lr` function + - Line breaks may occur between matched delimiters + - Delimiters may also be unbalanced + - You can also use the `lr` function to scale the brackets + (or just one bracket) to a specific size manually +- Multi-line math with alignment + - The `\` character inserts a line break + - The `&` character defines an alignment point + - Alignment points also work for underbraces, vectors, cases, and matrices + - Multiple alignment points are supported +- More capable math function calls + - Function calls directly in math can now take code expressions with hashtag + - They can now also take named arguments + - Within math function calls, semicolons turn preceding arguments to arrays to + support matrices: `[$mat(1, 2; 3, 4)$]` +- Arbitrary content in math + - Text, images, and other arbitrary content can now be embedded in math + - Math now also supports font fallback to support e.g. CJK and emoji +- More math features + - New text operators: `op` function, `lim`, `max`, etc. + - New matrix function: `mat` + - New n-ary roots with `root` function: `[$root(3, x)$]` + - New under- and overbraces, -brackets, and -lines + - New `abs` and `norm` functions + - New shorthands: `[|`, `|]`, and `||` + - New `attach` function, overridable attachments with `script` and `limit` + - Manual spacing in math, with `h`, `thin`, `med`, `thick` and `quad` + - Symbols and other content may now be used like a function, e.g. `[$zeta(x)$]` + - Added Fira Math font, removed Noto Sans Math font + - Support for alternative math fonts through + `[#show math.formula: set text("Fira Math")]` +- More library improvements + - New `calc` module, `abs`, `min`, `max`, `even`, `odd` and `mod` moved there + - New `message` argument on `{assert}` function + - The `pairs` method on dictionaries now returns an array of length-2 arrays + instead of taking a closure + - The method call `{dict.at("key")}` now always fails if `"key"` doesn't exist + Previously, it was allowed in assignments. Alternatives are `{dict.key = x}` + and `{dict.insert("key", x)}`. +- Smarter editor functionality + - Autocompletion for local variables + - Autocompletion for methods available on a value + - Autocompletion for symbols and modules + - Autocompletion for imports + - Hover over an identifier to see its value(s) +- Further editor improvements + - New Font menu with previews + - Single projects may now be shared with share links + - New dashboard experience if projects are shared with you + - Keyboard Shortcuts are now listed in the menus and there are more of them + - New Offline indicator + - Tooltips for all buttons + - Improved account protection + - Moved Status indicator into the error list button +- Further fixes + - Multiple bug fixes for incremental parser + - Fixed closure parameter capturing + - Fixed tons of math bugs + - Bugfixes for performance, file management, editing reliability + - Added redirection to the page originally navigated to after signin diff --git a/docs/community.md b/docs/community.md new file mode 100644 index 00000000..32d2d185 --- /dev/null +++ b/docs/community.md @@ -0,0 +1,72 @@ +--- +description: | + Join the Typst community, get help from other users and have a say in the + future of Typst. +--- + +# Community +Hey and welcome to the Community page! We're so glad you're here. Typst is +developed by an early-stage startup and is still in its infancy, but it +would be pointless without people like you who are interested in it. + +We would love to not only hear from you but to also provide spaces where you can +discuss any topic around Typst, typesetting, writing, the sciences, and +typography with other likeminded people. + +For the time being, **we would like to invite you to our [Discord +server](https://discord.gg/2uDybryKPe).** The server is open for everyone, even +if you do not have preview access to Typst yet. Of course, you are also very +welcome to connect with us on social media +([Twitter](https://twitter.com/typstapp/), +[Instagram](https://instagram.com/typstapp/), +[LinkedIn](https://linkedin.com/company/typst), and +[GitHub](https://github.com/typst)). + +## What to share? { #want-to-share } +For our community, we want to foster versatility and inclusivity. +You are welcome to post about any topic that you think would interest other +community members, but if you need a little inspiration, here are a few ideas: + +- Share and discuss your thoughts and ideas for new features or improvements + you'd like to see in Typst +- Showcase documents you've created with Typst, or share any unique or creative + ways you've used the platform +- Share importable files or templates that you use to style your documents +- Alert us of bugs you encounter while using Typst + +## Beta test { #beta-test } +We are starting a public beta test of our product on March 21st, 2023. +The Typst compiler is still under active development and breaking changes can +occur at any point. The compiler is developed in the open on +[GitHub](https://github.com/typst/typst). + +We will update the members of our Discord server and our social media followers +when new features become available in the preview. We'll also update you on the +development progress of large features. A development tracker will become +available on the documentation pages soon. + +## How to support Typst { #support-typst } +If you want to support Typst, there are multiple ways to do that! You can +[contribute to the code](https://github.com/typst/typst) or +[translate the strings in Typst](https://github.com/search?q=repo%3Atypst%2Ftypst+impl+LocalName+for&type=code) +to your native language if it's not supported yet. You can also help us by +[sponsoring us!](https://github.com/sponsors/typst) Multiple recurring +sponsorship tiers are available and all of them come with a set of goodies. +No matter how you contribute, thank you for your support! + +## Community Rules { #rules } +We want to make our community a safe and inclusive space for everyone. +Therefore, we will not tolerate any sexual harassment, sexism, political +attacks, derogatory language or personal insults, racism, doxing, and other +inappropriate behavior. We pledge to remove members that are in violation of +these rules. [Contact us](https://typst.app/contact/) if you think another +community member acted inappropriately towards you. All complaints will be +reviewed and investigated promptly and fairly. + +In addition, our [privacy policy](https://typst.app/privacy/) applies on all +community spaces operated by us, such as the Discord server. Please also note +that the terms of service and privacy policies of the respective services apply. + +## See you soon! { #see-you } +Thanks again for learning more about Typst. We would be delighted to meet you on +our [Discord server](https://discord.gg/2uDybryKPe)! diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md new file mode 100644 index 00000000..af48401d --- /dev/null +++ b/docs/dev/architecture.md @@ -0,0 +1,171 @@ +# Typst Compiler Architecture +Wondering how to contribute or just curious how Typst works? This document +covers the general architecture of Typst's compiler, so you get an understanding +of what's where and how everything fits together. + +The source-to-PDF compilation process of a Typst file proceeds in four phases. + +1. **Parsing:** Turns a source string into a syntax tree. +2. **Evaluation:** Turns a syntax tree and its dependencies into content. +4. **Layout:** Layouts content into frames. +5. **Export:** Turns frames into an output format like PDF or a raster graphic. + +The Typst compiler is _incremental:_ Recompiling a document that was compiled +previously is much faster than compiling from scratch. Most of the hard work is +done by [`comemo`], an incremental compilation framework we have written for +Typst. However, the compiler is still carefully written with incrementality in +mind. Below we discuss the four phases and how incrementality affects each of +them. + + +## Parsing +The syntax tree and parser are located in `src/syntax`. Parsing is a pure +function `&str -> SyntaxNode` without any further dependencies. The result is a +concrete syntax tree reflecting the whole file structure, including whitespace +and comments. Parsing cannot fail. If there are syntactic errors, the returned +syntax tree contains error nodes instead. It's important that the parser deals +well with broken code because it is also used for syntax highlighting and IDE +functionality. + +**Typedness:** +The syntax tree is untyped, any node can have any `SyntaxKind`. This makes it +very easy to (a) attach spans to each node (see below), (b) traverse the tree +when doing highlighting or IDE analyses (no extra complications like a visitor +pattern). The `typst::syntax::ast` module provides a typed API on top of +the raw tree. This API resembles a more classical AST and is used by the +interpreter. + +**Spans:** +After parsing, the syntax tree is numbered with _span numbers._ These numbers +are unique identifiers for syntax nodes that are used to trace back errors in +later compilation phases to a piece of syntax. The span numbers are ordered so +that the node corresponding to a number can be found quickly. + +**Incremental:** +Typst has an incremental parser that can reparse a segment of markup or a +code/content block. After incremental parsing, span numbers are reassigned +locally. This way, span numbers further away from an edit stay mostly stable. +This is important because they are used pervasively throughout the compiler, +also as input to memoized functions. The less they change, the better for +incremental compilation. + + +## Evaluation +The evaluation phase lives in `src/eval`. It takes a parsed `Source` file and +evaluates it to a `Module`. A module consists of the `Content` that was written +in it and a `Scope` with the bindings that were defined within it. + +A source file may depend on other files (imported sources, images, data files), +which need to be resolved. Since Typst is deployed in different environments +(CLI, web app, etc.) these system dependencies are resolved through a general +interface called a `World`. Apart from files, the world also provides +configuration and fonts. + +**Interpreter:** +Typst implements a tree-walking interpreter. To evaluate a piece of source, you +first create a `Vm` with a scope stack. Then, the AST is recursively evaluated +through trait impls of the form `fn eval(&self, vm: &mut Vm) -> Result`. +An interesting detail is how closures are dealt with: When the interpreter sees +a closure / function definition, it walks the body of the closure and finds all +accesses to variables that aren't defined within the closure. It then clones the +values of all these variables (it _captures_ them) and stores them alongside the +closure's syntactical definition in a closure value. When the closure is called, +a fresh `Vm` is created and its scope stack is initialized with the captured +variables. + +**Incremental:** +In this phase, incremental compilation happens at the granularity of the module +and the closure. Typst memoizes the result of evaluating a source file across +compilations. Furthermore, it memoizes the result of calling a closure with a +certain set of parameters. This is possible because Typst ensures that all +functions are pure. The result of a closure call can be recycled if the closure +has the same syntax and captures, even if the closure values stems from a +different module evaluation (i.e. if a module is reevaluated, previous calls to +closures defined in the module can still be reused). + + +## Layout +The layout phase takes `Content` and produces one `Frame` per page for it. To +layout `Content`, we first have to _realize_ it by applying all relevant show +rules to the content. Since show rules may be defined as Typst closures, +realization can trigger closure evaluation, which in turn produces content that +is recursively realized. Realization is a shallow process: While collecting list +items into a list that we want to layout, we don't realize the content within +the list items just yet. This only happens lazily once the list items are +layouted. + +When we a have realized the content into a layoutable element, we can then +layout it into _regions,_ which describe the space into which the content shall +be layouted. Within these, an element is free to layout itself as it sees fit, +returning one `Frame` per region it wants to occupy. + +**Introspection:** +How content layouts (and realizes) may depend on how _it itself_ is layouted +(e.g., through page numbers in the table of contents, counters, state, etc.). +Typst resolves these inherently cyclical dependencies through the _introspection +loop:_ The layout phase runs in a loop until the results stabilize. Most +introspections stabilize after one or two iterations. However, some may never +stabilize, so we give up after five attempts. + +**Incremental:** +Layout caching happens at the granularity of the element. This is important +because overall layout is the most expensive compilation phase, so we want to +reuse as much as possible. + + +## Export +Exporters live in `src/export`. They turn layouted frames into an output file +format. + +- The PDF exporter takes layouted frames and turns them into a PDF file. +- The built-in renderer takes a frame and turns it into a pixel buffer. +- HTML export does not exist yet, but will in the future. However, this requires + some complex compiler work because the export will start with `Content` + instead of `Frames` (layout is the browser's job). + + +## IDE +The `src/ide` module implements IDE functionality for Typst. It builds heavily +on the other modules (most importantly, `syntax` and `eval`). + +**Syntactic:** +Basic IDE functionality is based on a file's syntax. However, the standard +syntax node is a bit too limited for writing IDE tooling. It doesn't provide +access to its parents or neighbours. This is a fine for an evaluation-like +recursive traversal, but impractical for IDE use cases. For this reason, there +is an additional abstraction on top of a syntax node called a `LinkedNode`, +which is used pervasively across the `ide` module. + +**Semantic:** +More advanced functionality like autocompletion requires semantic analysis of +the source. To gain semantic information for things like hover tooltips, we +directly use other parts of the compiler. For instance, to find out the type of +a variable, we evaluate and realize the full document equipped with a `Tracer` +that emits the variable's value whenever it is visited. From the set of +resulting values, we can then compute the set of types a value takes on. Thanks +to incremental compilation, we can recycle large parts of the compilation that +we had to do anyway to typeset the document. + +**Incremental:** +Syntactic IDE stuff is relatively cheap for now, so there are no special +incrementality concerns. Semantic analysis with a tracer is relatively +expensive. However, large parts of a traced analysis compilation can reuse +memoized results from a previous normal compilation. Only the module evaluation +of the active file and layout code that somewhere within evaluates source code +in the active file needs to re-run. This is all handled automatically by +`comemo` because the tracer is wrapped in a `comemo::TrackedMut` container. + + +## Tests +Typst has an extensive suite of integration tests. A test file consists of +multiple tests that are separated by `---`. For each test file, we store a +reference image defining what the compiler _should_ output. To manage the +reference images, you can use the VS code extension in `tools/test-helper`. + +The integration tests cover parsing, evaluation, realization, layout and +rendering. PDF output is sadly untested, but most bugs are in earlier phases of +the compiler; the PDF output itself is relatively straight-forward. IDE +functionality is also mostly untested. PDF and IDE testing should be added in +the future. + +[`comemo`]: https://github.com/typst/comemo/ diff --git a/docs/guides/guide-for-latex-users.md b/docs/guides/guide-for-latex-users.md new file mode 100644 index 00000000..b51e8cf1 --- /dev/null +++ b/docs/guides/guide-for-latex-users.md @@ -0,0 +1,602 @@ +--- +description: | + Are you a LaTeX user? This guide explains the differences and + similarities between Typst and LaTeX so you can get started quickly. +--- + +# Guide for LaTeX users +This page is a good starting point if you have used LaTeX before and want to try +out Typst. We will explore the main differences between these two systems from a +user perspective. Although Typst is not built upon LaTeX and has a different +syntax, you will learn how to use your LaTeX skills to get a head start. + + + +Just like LaTeX, Typst is a markup-based typesetting system: You compose your +document in a text file and mark it up with commands and other syntax. Then, you +use a compiler to typeset the source file into a PDF. However, Typst also +differs from LaTeX in several aspects: For one, Typst uses more dedicated syntax +(like you may know from Markdown) for common tasks. Typst's commands are also +more principled: They all work the same, so unlike in LaTeX, you just need to +understand a few general concepts instead of learning different conventions for +each package. Moreover Typst compiles faster than LaTeX: Compilation usually +takes milliseconds, not seconds, so the web app and the compiler can both +provide instant previews. + +In the following, we will cover some of the most common questions a user +switching from LaTeX will have when composing a document in Typst. If you prefer +a step-by-step introduction to Typst, check out our [tutorial]($tutorial). + +## How do I create a new, empty document? { #getting-started } +That's easy. You just create a new, empty text file (the file extension is +`.typ`). No boilerplate is needed to get started. Simply start by writing your +text. It will be set on an empty A4-sized page. If you are using the web app, +click "+ Empty document" to create a new project with a file and enter the +editor. [Paragraph breaks]($func/parbreak) work just as they do in LaTeX, just +use a blank line. + +```example +Hey there! + +Here are two paragraphs. The +output is shown to the right. +``` + +## How do I create section headings, emphasis, ...? { #elements } +LaTeX uses the command `\section` to create a section heading. Nested headings +are indicated with `\subsection`, `\subsubsection`, etc. Depending on your +document class, there is also `\part` or `\chapter`. + +In Typst, [headings]($func/heading) are less verbose: You prefix the line with +the heading on it with an equals sign and a space to get a first-order heading: +`[= Introduction]`. If you need a second-order heading, you use two equals +signs: `[== In this paper]`. You can nest headings as deeply as you'd like by +adding more equals signs. + +Emphasis (usually rendered as italic text) is expressed by enclosing text in +`[_underscores_]` and strong emphasis (usually rendered in boldface) by using +`[*stars*]` instead. + +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`]($func/strong) | +| Emphasis | `\emph{emphasis}` | `[_emphasis_]` | [`emph`]($func/emph) | +| Monospace / code | `\texttt{print(1)}` | ``[`print(1)`]`` | [`raw`]($func/raw) | +| Link | `\url{https://typst.app}` | `[https://typst.app/]` | [`link`]($func/link) | +| Label | `\label{intro}` | `[]` | [`label`]($func/label) | +| Reference | `\ref{intro}` | `[@intro]` | [`ref`]($func/ref) | +| Citation | `\cite{humphrey97}` | `[@humphrey97]` | [`cite`]($func/cite) | +| Bullet list | `itemize` environment | `[- List]` | [`list`]($func/list) | +| Numbered list | `enumerate` environment | `[+ List]` | [`enum`]($func/enum) | +| Term list | `description` environment | `[/ Term: List]` | [`terms`]($func/terms) | +| Figure | `figure` environment | `figure` function | [`figure`]($func/figure) | +| Table | `table` environment | `table` function | [`table`]($func/table) | +| Equation | `$x$`, `align` / `equation` environments | `[$x$]`, `[$ x = y $]` | [`equation`]($func/math.equation) | + +[Lists]($func/list) do not rely on environments in Typst. Instead, they have +lightweight syntax like headings. To create an unordered list (`itemize`), +prefix each line of an item with a hyphen: + +````example +To write this list in Typst... + +```latex +\begin{itemize} + \item Fast + \item Flexible + \item Intuitive +\end{itemize} +``` + +...just type this: + +- Fast +- Flexible +- Intuitive + +```` + +Nesting lists works just by using proper indentation. Adding a blank line in +between items results in a more [widely]($func/list.tight) spaced list. + +To get a [numbered list]($func/enum) (`enumerate`) instead, use a `+` instead of +the hyphen. For a [term list]($func/terms) (`description`), write +`[/ Term: Description]` instead. + +## 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. +Some commands accept arguments, which are most frequently enclosed in curly +braces: `\cite{rasmus}`. + +Typst differentiates between [markup mode and code mode]($scripting/#blocks). +The default is markup mode, where you compose text and apply syntactic +constructs such as `[*stars for bold text*]`. Code mode, on the other hand, +parallels programming languages like Python, providing the option to input +and execute segments of code. + +Within Typst's markup, you can switch to code mode for a single command (or +rather, _expression_) using a hashtag (`#`). This is how you call functions to, +for example, split your project into different [files]($scripting/#modules) +or render text based on some [condition]($scripting/#conditionals). +Within code mode, it is possible to include normal markup +[_content_]($type/content) by using square brackets. Within code mode, this +content is treated just as any other normal value for a variable. + +```example +First, a rectangle: +#rect() + +Let me show how to do +#underline([_underlined_ text]) + +We can also do some maths: +#calc.max(3, 2 * 4) + +And finally a little loop: +#for x in range(3) [ + Hi #x. +] +``` + +A function call always involves the name of the function ([`rect`]($func/rect), +[`underline`]($func/underline), [`calc.max`]($func/calc.max), +[`range`]($func/range)) followed by parentheses (as opposed to LaTeX where the +square brackets and curly braces are optional if the macro requires no +arguments). The expected list of arguments passed within those parentheses +depends on the concrete function and is specified in the +[reference]($reference). + +### Arguments { #arguments } +A function can have multiple arguments. Some arguments are positional, i.e., you +just provide the value: The function `[#lower("SCREAM")]` returns its argument +in all-lowercase. Many functions use named arguments instead of positional +arguments to increase legibility. For example, the dimensions and stroke of a +rectangle are defined with named arguments: + +```example +#rect( + width: 2cm, + height: 1cm, + stroke: red, +) +``` + +You specify a named argument by first entering its name (above, it's `width`, +`height`, and `stroke`), then a colon, followed by the value (`2cm`, `1cm`, +`red`). You can find the available named arguments in the [reference +page]($reference) for each function or in the autocomplete panel when typing. +Named arguments are similar to how some LaTeX environments are configured, for +example, you would type `\begin{enumerate}[label={\alph*)}]` to start a list +with the labels `a)`, `b)`, and so on. + +Often, you want to provide some [content]($type/content) to a function. For +example, the LaTeX command `\underline{Alternative A}` would translate to +`[#underline([Alternative A])]` in Typst. The square brackets indicate that a +value is [content]($type/content). Within these brackets, you can use normal +markup. However, that's a lot of parentheses for a pretty simple construct. +This is why you can also move trailing content arguments after the parentheses +(and omit the parentheses if they would end up empty). + +```example +Typst is an #underline[alternative] +to LaTeX. + +#rect(fill: aqua)[Get started here!] +``` + +### Data types { #data-types } +You likely already noticed that the arguments have distinctive data types. Typst +supports [many data types]($type). Below, there is a table with some of the most +important ones and how to write them. In order to specify values of any of these +types, you have to be in code mode! + +| Data type | Example | +|:-------------------------------------|:----------------------------------| +| [Content]($type/content) | `{[*fast* typesetting]}` | +| [String]($type/string) | `{"Pietro S. Author"}` | +| [Integer]($type/integer) | `{23}` | +| [Floating point number]($type/float) | `{1.459}` | +| [Absolute length]($type/length) | `{12pt}`, `{5in}`, `{0.3cm}`, ... | +| [Relative length]($type/ratio) | `{65%}` | + +The difference between content and string is that content can contain markup, +including function calls, while a string really is just a plain sequence of +characters. + +Typst provides [control flow constructs]($scripting/#conditionals) and +[operators]($scripting/#operators) such as `+` for adding things or `==` for +checking equality between two variables. You can also define your own +[variables]($scripting/#bindings) and perform computations on them. + +### Commands to affect the remaining document { #rules } +In LaTeX, some commands like `\textbf{bold text}` receive an argument in curly +braces and only affect that argument. Other commands such as +`\bfseries bold text` act as switches, altering the appearance of all subsequent +content within the document or current scope. + +In Typst, the same function can be used both to affect the appearance for the +remainder of the document, a block (or scope), or just its arguments. For example, +`[#text(weight: "bold")[bold text]]` will only embolden its argument, while +`[#set text(weight: "bold")]` will embolden any text until the end of the +current block, or, if there is none, document. The effects of a function are +immediately obvious based on whether it is used in a call or a +[set rule.]($styling/#set-rules) + +```example +I am starting out with small text. + +#set text(14pt) + +This is a bit #text(18pt)[larger,] +don't you think? +``` + +Set rules may appear anywhere in the document. They can be thought of as +default argument values of their respective function: + +```example +#set enum(numbering: "I.") + +Good results can only be obtained by ++ following best practices ++ being aware of current results + of other researchers ++ checking the data for biases +``` + +The `+` is syntactic sugar (think of it as an abbreviation) for a call to the +[`{enum}`]($func/enum) function, to which we apply a set rule above. [Most +syntax is linked to a function in this way.]($syntax) If you need to style an +element beyond what its arguments enable, you can completely redefine its +appearance with a [show rule]($styling/#show-rules) (somewhat comparable to +`\renewcommand`). + +## How do I load a document class? { #templates } +In LaTeX, you start your main `.tex` file with the `\documentclass{article}` +command to define how your document is supposed to look. In that command, you +may have replaced `article` with another value such as `report` and `amsart` to +select a different look. + +When using Typst, you style your documents with [functions]($type/function). +Typically, you use a template that provides a function that styles your whole +document. First, you import the function from a template file. Then, you apply +it to your whole document. This is accomplished with a +[show rule]($styling/#show-rules) that wraps the following document in a given +function. The following example illustrates how it works: + +```example:single +>>> #let conf( +>>> title: none, +>>> authors: (), +>>> abstract: [], +>>> doc, +>>> ) = { +>>> set text(font: "Linux Libertine", 11pt) +>>> set par(justify: true) +>>> set page( +>>> "us-letter", +>>> margin: auto, +>>> header: align( +>>> right + horizon, +>>> title +>>> ), +>>> numbering: "1", +>>> ) +>>> +>>> show heading.where( +>>> level: 1 +>>> ): it => block( +>>> align(center, +>>> text( +>>> 13pt, +>>> weight: "regular", +>>> smallcaps(it.body), +>>> ) +>>> ), +>>> ) +>>> show heading.where( +>>> level: 2 +>>> ): it => box( +>>> text( +>>> 11pt, +>>> weight: "regular", +>>> style: "italic", +>>> it.body + [.], +>>> ) +>>> ) +>>> +>>> set align(center) +>>> text(17pt, title) +>>> +>>> let count = calc.min(authors.len(), 3) +>>> grid( +>>> columns: (1fr,) * count, +>>> row-gutter: 24pt, +>>> ..authors.map(author => [ +>>> #author.name \ +>>> #author.affiliation \ +>>> #link("mailto:" + author.email) +>>> ]), +>>> ) +>>> +>>> par(justify: false)[ +>>> *Abstract* \ +>>> #abstract +>>> ] +>>> +>>> set align(left) +>>> columns(2, doc) +>>>} +<<< #import "conf.typ": conf +#show: conf.with( + title: [ + Towards Improved Modelling + ], + authors: ( + ( + name: "Theresa Tungsten", + affiliation: "Artos Institute", + email: "tung@artos.edu", + ), + ( + name: "Eugene Deklan", + affiliation: "Honduras State", + email: "e.deklan@hstate.hn", + ), + ), + abstract: lorem(80), +) + +Let's get started writing this +article by putting insightful +paragraphs right here! +``` + +The [`{import}`]($scripting/#modules) statement makes +[functions]($type/function) (and other definitions) from another file available. +In this example, it imports the `conf` function from the `conf.typ` file. This +function formats a document as a conference article. We use a show rule to apply +it to the document and also configure some metadata of the article. After +applying the show rule, we can start writing our article right away! + +
+ +Functions are Typst's "commands" and can transform their arguments to an output +value, including document _content._ Functions are "pure", which means that they +cannot have any effects beyond creating an output value / output content. This +is in stark contrast to LaTeX macros that can have arbitrary effects on your +document. + +To let a function style your whole document, the show rule processes everything +that comes after it and calls the function specified after the colon with the +result as an argument. The `.with` part is a _method_ that takes the `conf` +function and pre-configures some if its arguments before passing it on to the +show rule. +
+ +In the web app, you can choose from predefined templates or even +create your own using the template wizard. You can also check out the +[`awesome-typst` repository](https://github.com/qjcg/awesome-typst) to find +templates made by the community. We plan to build a package manager to make +templates even easier to share in the future! + +You can also [create your own, custom templates.]($tutorial/making-a-template) +They are shorter and more readable than the corresponding LaTeX `.sty` files by +orders of magnitude, so give it a try! + +## How do I load packages? { #packages } +Typst is "batteries included," so the equivalent of many popular LaTeX packages +is built right-in. Below, we compiled a table with frequently loaded packages +and their corresponding Typst functions. + +| LaTeX Package | Typst Alternative | +|:--------------------------------|:---------------------------------------------------------------------| +| graphicx, svg | [`image`]($func/image) function | +| tabularx | [`table`]($func/table), [`grid`]($func/grid) functions | +| fontenc, inputenc, unicode-math | Just start writing! | +| babel, polyglossia | [`text`]($func/text.lang) function: `[#set text(lang: "zh")]` | +| amsmath | [Math mode]($category/math) | +| amsfonts, amssymb | [`sym`]($category/symbols) module and [syntax]($syntax/#math) | +| geometry, fancyhdr | [`page`]($func/page) function | +| xcolor | [`text`]($func/text.fill) function: `[#set text(fill: rgb("#0178A4"))]` | +| hyperref | [`link`]($func/link) function | +| bibtex, biblatex, natbib | [`cite`]($func/cite), [`bibliography`]($func/bibliography) functions | +| lstlisting, minted | [`raw`]($func/raw) function and syntax | +| parskip | [`block`]($func/block.spacing) and [`par`]($func/par.first-line-indent) functions | +| csquotes | Set the [`text`]($func/text.lang) language and type `["]` or `[']` | +| caption | [`figure`]($func/figure) function | +| enumitem | [`list`]($func/list), [`enum`]($func/enum), [`terms`]($func/terms) functions | + +If you need to load functions and variables from another file, for example, to +use a template, you can use an [`import`]($scripting/#modules) statement. If you +want to include the textual content of another file instead, you can use an +[`{include}`]($scripting/#modules) statement. It will retrieve the content of +the specified file and put it in your document. + +Currently, there is no package manager for Typst, but we plan to build one so +that you can easily use packages with tools and templates from the community and +publish your own. Until then, you might want to check out the +[awesome-typst repository](https://github.com/qjcg/awesome-typst), which +compiles a curated list of libraries created for Typst. + +## How do I input maths? { #maths } +To enter math mode in Typst, just enclose your equation in dollar signs. You can +enter display mode by adding spaces or newlines between the equation's contents +and its enclosing dollar signs. + +```example +The sum of the numbers from +$1$ to $n$ is: + +$ sum_(k=1)^n k = (n(n+1))/2 $ +``` + +[Math mode]($category/math) works differently than regular markup or code mode. +Numbers and single characters are displayed verbatim, while multiple consecutive +(non-number) characters will be interpreted as Typst variables. + +Typst pre-defines a lot of useful variables in math mode. All Greek (`alpha`, +`beta`, ...) and some Hebrew letters (`alef`, `bet`, ...) are available through +their name. Some symbols are additionally available through shorthands, such as +`<=`, `>=`, and `->`. + +Refer to the [symbol page]($func/symbol) for a full list of the symbols. +If a symbol is missing, you can also access it through a +[Unicode escape sequence]($syntax/#escapes). + +Alternate and related forms of symbols can often be selected by +[appending a modifier]($type/symbol) after a period. For example, +`arrow.l.squiggly` inserts a squiggly left-pointing arrow. If you want to insert +multiletter text in your expression instead, enclose it in double quotes: + +```example +$ delta "if" x <= 5 $ +``` + +In Typst, delimiters will scale automatically for their expressions, just as if +`\left` and `\right` commands were implicitly inserted in LaTeX. You can +customize delimiter behavior using the [`lr` function]($func/math.lr). To +prevent a pair of delimiters from scaling, you can escape them with backslashes. + +Typst will automatically set terms around a slash `/` as a fraction while +honoring operator precedence. All round parentheses not made redundant by the +fraction will appear in the output. + +```example +$ f(x) = (x + 1) / x $ +``` + +[Sub- and superscripts]($func/math.attach) work similarly in Typst and LaTeX. +`{$x^2$}` will produce a superscript, `{$x_2$}` yields a subscript. If you want +to include more than one value in a sub- or superscript, enclose their contents +in parentheses: `{$x_(a -> epsilon)$}`. + +Since variables in math mode do not need to be preprended with a `#` or a `/`, +you can also call functions without these special characters: + +```example +$ f(x, y) := cases( + 1 "if" (x dot y)/2 <= 0, + 2 "if" x "is even", + 3 "if" x in NN, + 4 "else", +) $ +``` + +The above example uses the [`cases` function]($func/math.cases) to describe f. Within +the cases function, arguments are delimited using commas and the arguments are +also interpreted as math. If you need to interpret arguments as Typst +values instead, prefix them with a `#`: + +```example +$ (a + b)^2 + = a^2 + + text(fill: #maroon, 2 a b) + + b^2 $ +``` + +You can use all Typst functions within math mode and insert any content. If you +want them to work normally, with code mode in the argument list, you can prefix +their call with a `#`. Nobody can stop you from using rectangles or emoji as +your variables anymore: + +```example +$ sum^10_(🥸=1) + #rect(width: 4mm, height: 2mm)/🥸 + = 🧠 maltese $ +``` + +If you'd like to enter your mathematical symbols directly as Unicode, that is +possible, too! + +Math calls can have two-dimensional argument lists using `;` as a delimiter. The +most common use for this is the [`mat` function]($func/math.mat) that creates +matrices: + +```example +$ mat( + 1, 2, ..., 10; + 2, 2, ..., 10; + dots.v, dots.v, dots.down, dots.v; + 10, 10, ..., 10; +) $ +``` + +## How do I get the "LaTeX look?" { #latex-look } +Papers set in LaTeX have an unmistakeable look. This is mostly due to their +font, Computer Modern, justification, narrow line spacing, and wide margins. + +The example below +- sets wide [margins]($func/page.margin) +- enables [justification]($func/par.justify), [tighter lines]($func/par.leading) + and [first-line-indent]($func/par.first-line-indent) +- [sets the font]($func/text.font) to "New Computer Modern", an OpenType + derivate of Computer Modern for both text and [code blocks]($func/raw) +- disables paragraph [spacing]($func/block.spacing) +- increases [spacing]($func/block.spacing) around [headings]($func/heading) + +```typ +#set page(margin: 1.75in) +#set par(leading: 0.55em, first-line-indent: 1.8em, justify: true) +#set text(font: "New Computer Modern") +#show raw: set text(font: "New Computer Modern Mono") +#show par: set block(spacing: 0.55em) +#show heading: set block(above: 1.4em, below: 1em) +``` + +This should be a good starting point! If you want to go further, why not create +a reusable template? + +## What limitations does Typst currently have compared to LaTeX? { #limitations } +Although Typst can be a LaTeX replacement for many today, there are still +features that Typst does not (yet) support. Here is a list of them which, where +applicable, contains possible workarounds. + +- **Native charts and plots.** LaTeX users often create charts along with their + documents in PGF/TikZ. Typst does not yet include tools to draw diagrams, but + the community is stepping up with solutions such as + [`typst-canvas`](https://github.com/johannes-wolf/typst-canvas), + [`typst-plot`](https://github.com/johannes-wolf/typst-plot), and + [`circuitypst`](https://github.com/fenjalien/circuitypst). You can add those + to your document to get started with drawing diagrams. + +- **Change page margins without a pagebreak.** In LaTeX, margins can always be + adjusted, even without a pagebreak. To change margins in Typst, you use the + [`page` function]($func/page) which will force a page break. If you just want + a few paragraphs to stretch into the margins, then reverting to the old + margins, you can use the [`pad` function]($func/pad) with negative padding. + +- **Floating figures.** The figure command of LaTeX will smartly choose where to + place a figure, be it on the top or bottom of the page, or a dedicated figure + page. Typst's figure will always appear at the spot where they have been + inserted in the markup. While this behavior can save some headache, it is + often cumbersome to manually place figures. We will be adding this feature + soon! + +- **Include PDFs as images.** In LaTeX, it has become customary to insert vector + graphics as PDF or EPS files. Typst supports neither format as an image + format, but you can easily convert both into SVG files with [online + tools](https://cloudconvert.com/pdf-to-svg) or + [Inkscape](https://inkscape.org/). We plan to add automatic conversion for + these file formats to the Typst web app, too! + +- **Page break optimization.** LaTeX runs some smart algorithms to not only + optimize line but also page breaks. While Typst tries to avoid widows and + orphans, it uses less sophisticated algorithms to determine page breaks. You + can insert custom page breaks in Typst using `[#pagebreak(weak: true)]` before + submitting your document. The argument `weak` ensures that no double page + break will be created if this spot would be a natural page break + anyways. You can also use `[#v(1fr)]` to distribute space on your page. It + works quite similar to LaTeX's `\vfill`. + +- **Bibliographies are not customizable.** In LaTeX, the packages `bibtex`, + `biblatex`, and `natbib` provide a wide range of reference and bibliography + formats. You can also use custom `.bbx` files to define your own styles there. + Typst only supports a small set of citation styles at the moment, but we want + to build upon this by supporting [Citation Style Language + (CSL)](https://citationstyles.org), an XML-based format backed by Zotero that + allows you to describe your own bibliography styles. diff --git a/docs/guides/welcome.md b/docs/guides/welcome.md new file mode 100644 index 00000000..43ecd181 --- /dev/null +++ b/docs/guides/welcome.md @@ -0,0 +1,11 @@ +--- +description: Guides for Typst. +--- + +# Guides +Welcome to the Guides section! Here, you'll find helpful material for specific +user groups or use cases. Currently, one guide is available: An introduction +to Typst for LaTeX users. Feel free to propose other topics for guides! + +## List of Guides { #list-of-guides } +- [Guide for LaTeX users]($guides/guide-for-latex-users) diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 00000000..e3fa3b3c --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,15 @@ +--- +description: | + Learn how to use Typst to compose documents faster. Get started with the + tutorial, or dive into the reference. +--- + +# Overview +Welcome to Typst's documentation! Typst is a new markup-based typesetting system +for the sciences. It is designed to be an alternative both to advanced tools +like LaTeX and simpler tools like Word and Google Docs. Our goal with Typst is +to build a typesetting tool that is highly capable _and_ a pleasure to use. + +This documentation is split into two parts: A beginner-friendly tutorial that introduces Typst through a practical use case and a comprehensive reference that explains all of Typst's concepts and features. + +We also invite you to join the community we're building around Typst. Typst is still a very young project, so your feedback is more than valuable. diff --git a/docs/reference/details.yml b/docs/reference/details.yml new file mode 100644 index 00000000..8e9af3a0 --- /dev/null +++ b/docs/reference/details.yml @@ -0,0 +1,174 @@ +types: | + To style your document, you need to work with values of different kinds: Lengths + specifying the size of your elements, colors for your text and shapes, and more. + Typst categorizes these into clearly defined _types_ and tells you where it + expects which type of value. + + Apart from very basic types for numeric values and typical types known from + programming languages, Typst provides a special type for _content._ A value of + this type can hold anything that you can enter into your document: Text, + elements like headings and shapes, and style information. + + In some places of Typst more specialized data types are used. Instead of listing + all of them here, they are explained where they are relevant. + +text: | + Text styling. + + The [text function]($func/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 $]`). + + 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 + [hashtag 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 $ + ``` + + 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]($type/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 $ + ``` + + 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 $ + ``` + + Math mode supports special function calls without the hashtag 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 hashtag 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 hashtag are normal code function calls and not + affected by these rules. + + 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. For example, to set the font used for + equations, write: + + ```example + #show math.equation: set text(font: "Fira Math") + $ sum_(i in NN) 1 + i $ + ``` + +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. + + _Note:_ Functions for plotting and diagrams are not yet available. They will + be in the future. + +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. + +foundations: | + Foundational functions for computation. + +calculate: | + Calculations and processing of numeric values. + + These functions are part of the `calc` module and not imported by default. In + addition to the functions listed below, the `calc` module also defines the + constants `pi`, `e`, `inf`, and `nan`. + +construct: | + Construction of and conversions between values of different types. + +data-loading: | + Data loading from external files. + + These functions help you with embedding data from experiments in your + documents. + +utility: | + Useful utility functions. + +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 new file mode 100644 index 00000000..3bc80339 --- /dev/null +++ b/docs/reference/groups.yml @@ -0,0 +1,76 @@ +# This is responsible for the fact that certain math functions are grouped +# together into one documentation page although they are not part of any scope. + +- name: variants + display: Variants + functions: ["serif", "sans", "frak", "mono", "bb", "cal"] + description: | + Alternate typefaces within formulas. + + These functions are distinct from the [`text`]($func/text) function because + math fonts contain multiple variants of each letter. + +- name: styles + display: Styles + functions: ["upright", "italic", "bold"] + description: | + Alternate letterforms within formulas. + + These functions are distinct from the [`text`]($func/text) function because + math fonts contain multiple variants of each letter. + +- name: sizes + display: Sizes + functions: ["display", "inline", "script", "sscript"] + description: | + Forced size styles for expressions within formulas. + + These functions allow manual configuration of the size of equation elements + to make them look as in a display/inline equation or as if used in a root or + sub/superscripts. + +- name: underover + display: Under/Over + functions: [ + "underline", + "overline", + "underbrace", + "overbrace", + "underbracket", + "overbracket", + ] + description: | + 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 + functions: ["root", "sqrt"] + description: Square and non-square roots. + +- name: attach + display: Attach + functions: ["attach", "scripts", "limits"] + description: | + Subscript, superscripts, and limits. + + The `attach` function backs the `[$a_b^c$]` syntax that adds top and bottom + attachments to a part of an equation. Attachments can be displayed either as + sub/superscripts, or limits. Typst automatically decides which is more + suitable depending on the base, but you can also control this manually with + the `scripts` and `limits` functions. + +- name: lr + display: Left/Right + functions: ["lr", "abs", "norm", "floor", "ceil", "round"] + description: | + Delimiter matching. + + The `lr` function allows you to match two delimiters and scale them with the + content they contain. While this also happens automatically for delimiters + that match syntactically, `lr` allows you to match two arbitrary delimiters + and control their size exactly. Apart from the `lr` function, Typst provides + a few more functions that create delimiter pairings for absolute, ceiled, + and floored values as well as norms. diff --git a/docs/reference/scripting.md b/docs/reference/scripting.md new file mode 100644 index 00000000..c18bdc4b --- /dev/null +++ b/docs/reference/scripting.md @@ -0,0 +1,345 @@ +--- +description: Automate your document with Typst's scripting capabilities. +--- + +# Scripting +Typst embeds a powerful scripting language. You can automate your documents and +create more sophisticated styles with code. Below is an overview over the +scripting concepts. + +## Expressions { #expressions } +In Typst, markup and code are fused into one. All but the most common elements +are created with _functions._ To make this as convenient as possible, Typst +provides compact syntax to embed a code expression into markup: An expression is +introduced with a hashtag (`#`) and normal markup parsing resumes after the +expression is finished. If a character would continue the expression but should +be interpreted as text, the expression can forcibly be ended with a semicolon +(`;`). + +```example +#emph[Hello] \ +#emoji.face \ +#"hello".len() +``` + +The example above shows a few of the available expressions, including +[function calls]($type/function), +[field accesses]($scripting/#fields), and +[method calls]($scripting/#methods). More kinds of expressions are +discussed in the remainder of this chapter. A few kinds of expressions are not +compatible with the hashtag syntax (e.g. binary operator expressions). To embed +these into markup, you can use parentheses, as in `[#(1 + 2)]`. + +## Blocks { #blocks } +To structure your code and embed markup into it, Typst provides two kinds of +_blocks:_ + +- **Code block:** `{{ let x = 1; x + 2 }}` \ + When writing code, you'll probably want to split up your computation into + multiple statements, create some intermediate variables and so on. Code blocks + let you write multiple expressions where one is expected. The individual + expressions in a code block should be separated by line breaks or semicolons. + The output values of the individual expressions in a code block are joined to + determine the block's value. Expressions without useful output, like `{let}` + bindings yield `{none}`, which can be joined with any value without effect. + +- **Content block:** `{[*Hey* there!]}` \ + With content blocks, you can handle markup/content as a programmatic value, + store it in variables and pass it to [functions]($type/function). Content + blocks are delimited by square brackets and can contain arbitrary markup. A + content block results in a value of type [content]($type/content). An + arbitrary number of content blocks can be passed as trailing arguments to + functions. That is, `{list([A], [B])}` is equivalent to `{list[A][B]}`. + +Content and code blocks can be nested arbitrarily. In the example below, +`{[hello]}` is joined with the output of `{a + [ the ] + b}` yielding +`{[hello from the *world*]}`. + +```example +#{ + let a = [from] + let b = [*world*] + [hello ] + a + [ the ] + b +} +``` + +## Bindings and Destructuring { #bindings } +As already demonstrated above, variables can be defined with `{let}` bindings. +The variable is assigned the value of the expression that follows the `=` sign. +The assignment of a value is optional, if no value is assigned, the variable +will be initialized as `{none}`. The `{let}` keyword can also be used to create +a [custom named function]($type/function/#definitions). Let bindings can be +accessed for the rest of the containing block or document. + +```example +#let name = "Typst" +This is #name's documentation. +It explains #name. + +#let add(x, y) = x + y +Sum is #add(2, 3). +``` + +Let bindings can also be used to destructure [arrays]($type/array) and +[dictionaries]($type/dictionary). In this case, the left-hand side of the +assignment should mirror an array or dictionary. The `..` operator can be used +once in the pattern to collect the remainder of the array's or dictionary's +items. + +```example +#let (x, y) = (1, 2) +The coordinates are #x, #y. + +#let (a, .., b) = (1, 2, 3, 4) +The first element is #a. +The last element is #b. + +#let books = ( + Shakespeare: "Hamlet", + Homer: "The Odyssey", + Austen: "Persuasion", +) + +#let (Austen,) = books +Austen wrote #Austen. + +#let (Homer: h) = books +Homer wrote #h. + +#let (Homer, ..other) = books +#for (author, title) in other [ + #author wrote #title. +] +``` + +You can use the underscore to discard elements in a destructuring pattern: + +```example +#let (_, y, _) = (1, 2, 3) +The y coordinate is #y. +``` + +Destructuring also work in argument lists of functions ... + +```example +#let left = (2, 4, 5) +#let right = (3, 2, 6) +#left.zip(right).map( + ((a,b)) => a + b +) +``` + +... and on the left-hand side of normal assignments. This can be useful to +swap variables among other things. + +```example +#{ + let a = 1 + let b = 2 + (a, b) = (b, a) + [a = #a, b = #b] +} +``` + +## Conditionals { #conditionals } +With a conditional, you can display or compute different things depending on +whether some condition is fulfilled. Typst supports `{if}`, `{else if}` and +`{else}` expression. When the condition evaluates to `{true}`, the conditional +yields the value resulting from the if's body, otherwise yields the value +resulting from the else's body. + +```example +#if 1 < 2 [ + This is shown +] else [ + This is not. +] +``` + +Each branch can have a code or content block as its body. + +- `{if condition {..}}` +- `{if condition [..]}` +- `{if condition [..] else {..}}` +- `{if condition [..] else if condition {..} else [..]}` + +## Loops { #loops } +With loops, you can repeat content or compute something iteratively. Typst +supports two types of loops: `{for}` and `{while}` loops. The former iterate +over a specified collection whereas the latter iterate as long as a condition +stays fulfilled. Just like blocks, loops _join_ the results from each iteration +into one value. + +In the example below, the three sentences created by the for loop join together +into a single content value and the length-1 arrays in the while loop join +together into one larger array. + +```example +#for c in "ABC" [ + #c is a letter. +] + +#let n = 2 +#while n < 10 { + n = (n * 2) - 1 + (n,) +} +``` + +For loops can iterate over a variety of collections: + +- `{for letter in "abc" {..}}` \ + Iterates over the characters of the [string]($type/string). + (Technically, iterates over the grapheme clusters of the string. Most of the + time, a grapheme cluster is just a single character/codepoint. However, some + constructs like flag emojis that consist of multiple codepoints are still only + one cluster.) + +- `{for value in array {..}}` \ + Iterates over the items in the [array]($type/array). The destructuring syntax + described in [Let binding]($scripting/#bindings) can also be used here. + +- `{for pair in dict {..}}` \ + Iterates over the key-value pairs of the [dictionary]($type/dictionary). + The pairs can also be destructured by using `{for (key, value) in dict {..}}`. + +To control the execution of the loop, Typst provides the `{break}` and +`{continue}` statements. The former performs an early exit from the loop while +the latter skips ahead to the next iteration of the loop. + +```example +#for letter in "abc nope" { + if letter == " " { + break + } + + letter +} +``` + +The body of a loop can be a code or content block: + +- `{for .. in collection {..}}` +- `{for .. in collection [..]}` +- `{while condition {..}}` +- `{while condition [..]}` + +## Fields { #fields } +You can use _dot notation_ to access fields on a value. The value in question +can be either: +- a [dictionary]($type/dictionary) that has the specified key, +- a [symbol]($type/symbol) that has the specified modifier, +- a [module]($type/module) containing the specified definition, +- [content]($type/content) consisting of an element that has the specified + field. The available fields match the arguments of the + [element function]($type/function/#element-functions) that were given when + the element was constructed. + +```example +#let dict = (greet: "Hello") +#dict.greet \ +#emoji.face + +#let it = [= Heading] +#it.body \ +#it.level +``` + +## Methods { #methods } +A method is a kind of a [function]($type/function) that is tightly coupled with +a specific type. It is called on a value of its type using the same dot notation +that is also used for fields: `{value.method(..)}`. The +[type documentation]($type) lists the available methods for each of the built-in +types. You cannot define your own methods. + +```example +#let array = (1, 2, 3, 4) +#array.pop() \ +#array.len() \ + +#("a, b, c" + .split(", ") + .join[ --- ]) +``` + +Methods are the only functions in Typst that can modify the value they are +called on. + +## Modules { #modules } +You can split up your Typst projects into multiple files called _modules._ A +module can refer to the content and definitions of another module in multiple +ways: + +- **Including:** `{include "bar.typ"}` \ + Evaluates the file at the path `bar.typ` and returns the resulting + [content]($type/content). + +- **Import:** `{import "bar.typ"}` \ + Evaluates the file at the path `bar.typ` and inserts the resulting + [module]($type/module) into the current scope as `bar` (filename without + extension). + +- **Import items:** `{import "bar.typ": a, b}` \ + Evaluates the file at the path `bar.typ`, extracts the values of the variables + `a` and `b` (that need to be defined in `bar.typ`, e.g. through `{let}` + bindings) and defines them in the current file.Replacing `a, b` with `*` loads + all variables defined in a module. + +Instead of a path, you can also use a [module value]($type/module), as shown in +the following example: + +```example +#import emoji: face +#face.grin +``` + +## Packages { #packages } +To reuse building blocks across projects, you can also create and import Typst +_packages._ A package import is specified as a triple of a namespace, a name, +and a version. + +```example +>>> #let add(x, y) = x + y +<<< #import "@preview/example:0.1.0": add +#add(2, 7) +``` + +The `preview` namespace contains packages shared by the community. You can find +a searchable list of available community packages in the [packages]($packages) +section. + +If you are using Typst locally, you can also create your own system-local +packages. For more details on this, see the +[package repository](https://github.com/typst/packages). + +## Operators { #operators } +The following table lists all available unary and binary operators with effect, +arity (unary, binary) and precedence level (higher binds stronger). + +| Operator | Effect | Arity | Precedence | +|:----------:|---------------------------------|:------:|:----------:| +| `{-}` | Negation | Unary | 7 | +| `{+}` | No effect (exists for symmetry) | Unary | 7 | +| `{*}` | Multiplication | Binary | 6 | +| `{/}` | Division | Binary | 6 | +| `{+}` | Addition | Binary | 5 | +| `{-}` | Subtraction | Binary | 5 | +| `{==}` | Check equality | Binary | 4 | +| `{!=}` | Check inequality | Binary | 4 | +| `{<}` | Check less-than | Binary | 4 | +| `{<=}` | Check less-than or equal | Binary | 4 | +| `{>}` | Check greater-than | Binary | 4 | +| `{>=}` | Check greater-than or equal | Binary | 4 | +| `{in}` | Check if in collection | Binary | 4 | +| `{not in}` | Check if not in collection | Binary | 4 | +| `{not}` | Logical "not" | Unary | 3 | +| `{and}` | Short-circuiting logical "and" | Binary | 3 | +| `{or}` | Short-circuiting logical "or | Binary | 2 | +| `{=}` | Assignment | Binary | 1 | +| `{+=}` | Add-Assignment | Binary | 1 | +| `{-=}` | Subtraction-Assignment | Binary | 1 | +| `{*=}` | Multiplication-Assignment | Binary | 1 | +| `{/=}` | Division-Assignment | Binary | 1 | + +[semver]: https://semver.org/ diff --git a/docs/reference/styling.md b/docs/reference/styling.md new file mode 100644 index 00000000..85095e34 --- /dev/null +++ b/docs/reference/styling.md @@ -0,0 +1,145 @@ +--- +description: All concepts needed to style your document with Typst. +--- + +# Styling +Typst includes a flexible styling system that automatically applies styling of +your choice to your document. With _set rules,_ you can configure basic +properties of elements. This way, you create most common styles. However, there +might not be a built-in property for everything you wish to do. For this reason, +Typst further supports _show rules_ that can completely redefine the appearance +of elements. + +## Set rules { #set-rules } +With set rules, you can customize the appearance of elements. They are written +as a [function call]($type/function) to an +[element function]($type/function/#element-functions) preceded by the `{set}` +keyword (or `[#set]` in markup). Only optional parameters of that function can +be provided to the set rule. Refer to each function's documentation to see which +parameters are optional. In the example below, we use two set rules to change +the [font family]($func/text.font) and +[heading numbering]($func/heading.numbering). + +```example +#set heading(numbering: "I.") +#set text( + font: "New Computer Modern" +) + += Introduction +With set rules, you can style +your document. +``` + +A top level set rule stays in effect until the end of the file. When nested +inside of a block, it is only in effect until the end of that block. With a +block, you can thus restrict the effect of a rule to a particular segment of +your document. Below, we use a content block to scope the list styling to one +particular list. + +```example +This list is affected: #[ + #set list(marker: [--]) + - Dash +] + +This one is not: +- Bullet +``` + +Sometimes, you'll want to apply a set rule conditionally. For this, you can use +a _set-if_ rule. + +```example +#let task(body, critical: false) = { + set text(red) if critical + [- #body] +} + +#task(critical: true)[Food today?] +#task(critical: false)[Work deadline] +``` + +## Show rules { #show-rules } +With show rules, you can deeply customize the look of a type of element. The +most basic form of show rule is a _show-set rule._ Such a rule is written as the +`{show}` keyword followed by a [selector]($type/selector), a colon and then a set rule. The most basic form of selector is an +[element function]($type/function/#element-functions). This lets the set rule +only apply to the selected element. In the example below, headings become dark +blue while all other text stays black. + +```example +#show heading: set text(navy) + += This is navy-blue +But this stays black. +``` + +With show-set rules you can mix and match properties from different functions to +achieve many different effects. But they still limit you to what is predefined +in Typst. For maximum flexibility, you can instead write a show rule that +defines how to format an element from scratch. To write such a show rule, +replace the set rule behind the colon with an arbitrary +[function]($type/function). This function receives the element in question and +can return arbitrary content. Different +[fields]($scripting/#fields) are available on the element passed +to the function. Below, we define a show rule that formats headings for a +fantasy encyclopedia. + +```example +#set heading(numbering: "(I)") +#show heading: it => block[ + #set align(center) + #set text(font: "Inria Serif") + \~ #emph(it.body) + #counter(heading).display() \~ +] + += Dragon +With a base health of 15, the +dragon is the most powerful +creature. + += Manticore +While less powerful than the +dragon, the manticore gets +extra style points. +``` + +Like set rules, show rules are in effect until the end of the current block or +file. + +Instead of a function, the right-hand side of a show rule can also take a +literal string or content block that should be directly substituted for the +element. And apart from a function, the left-hand side of a show rule can also +take a number of other _selectors_ that define what to apply the transformation +to: + +- **Everything:** `{show: rest => ..}` \ + Transform everything after the show rule. This is useful to apply a more + complex layout to your whole document without wrapping everything in a giant + function call. + +- **Text:** `{show "Text": ..}` \ + Style, transform or replace text. + +- **Regex:** `{show regex("\w+"): ..}` \ + Select and transform text with a regular expression for even more flexibility. + See the documentation of the [`regex` function]($func/regex) for details. + +- **Function with fields:** `{show heading.where(level: 1): ..}` \ + Transform only elements that have the specified fields. For example, you might + want to only change the style of level-1 headings. + +- **Label:** `{show : ..}` \ + Select and transform elements that have the specified label. + See the documentation of the [`label` function]($func/label) for more details. + +```example +#show "Project": smallcaps +#show "badly": "great" + +We started Project in 2019 +and are still working on it. +Project is progressing badly. +``` diff --git a/docs/reference/syntax.md b/docs/reference/syntax.md new file mode 100644 index 00000000..d0cd80d7 --- /dev/null +++ b/docs/reference/syntax.md @@ -0,0 +1,138 @@ +--- +description: | + A compact reference for Typst's syntax. Learn more about the language within + markup, math, and code mode. +--- + +# Syntax +Typst is a markup language. This means that you can use simple syntax to +accomplish common layout tasks. The lightweight markup syntax is complemented by +set and show rules, which let you style your document easily and automatically. +All this is backed by a tightly integrated scripting language with built-in and +user-defined functions. + +## Markup { #markup } +Typst provides built-in markup for the most common document elements. Most of +the syntax elements are just shortcuts for a corresponding function. The table +below lists all markup that is available and links to the best place to learn +more about their syntax and usage. + +| Name | Example | See | +| ------------------ | ------------------------ | ---------------------------- | +| Paragraph break | Blank line | [`parbreak`]($func/parbreak) | +| Strong emphasis | `[*strong*]` | [`strong`]($func/strong) | +| Emphasis | `[_emphasis_]` | [`emph`]($func/emph) | +| Raw text | ``[`print(1)`]`` | [`raw`]($func/raw) | +| Link | `[https://typst.app/]` | [`link`]($func/link) | +| Label | `[]` | [`label`]($func/label) | +| Reference | `[@intro]` | [`ref`]($func/ref) | +| Heading | `[= Heading]` | [`heading`]($func/heading) | +| Bullet list | `[- item]` | [`list`]($func/list) | +| Numbered list | `[+ item]` | [`enum`]($func/enum) | +| Term list | `[/ Term: description]` | [`terms`]($func/terms) | +| Math | `[$x^2$]` | [Math]($category/math) | +| Line break | `[\]` | [`linebreak`]($func/linebreak) | +| Smart quote | `['single' or "double"]` | [`smartquote`]($func/smartquote) | +| Symbol shorthand | `[~, ---]` | [Symbols]($category/symbols/sym) | +| Code expression | `[#rect(width: 1cm)]` | [Scripting]($scripting/#expressions) | +| Character escape | `[Tweet at us \#ad]` | [Below](#escapes) | +| Comment | `[/* block */, // line]` | [Below](#comments) | + +## Math mode { #math } +Math mode is a special markup mode that is used to typeset mathematical +formulas. It is entered by wrapping an equation in `[$]` characters. The +equation will be typeset into its own block if it starts and ends with at least +one space (e.g. `[$ x^2 $]`). Inline math can be produced by omitting the +whitespace (e.g. `[$x^2$]`). An overview over the syntax specific to math mode +follows: + +| Name | Example | See | +| ---------------------- | ------------------------ | ------------------------ | +| Inline math | `[$x^2$]` | [Math]($category/math) | +| Block-level math | `[$ x^2 $]` | [Math]($category/math) | +| Bottom attachment | `[$x_1$]` | [`attach`]($category/math/attach) | +| Top attachment | `[$x^2$]` | [`attach`]($category/math/attach) | +| Fraction | `[$1 + (a+b)/5$]` | [`frac`]($func/math.frac) | +| Line break | `[$x \ y$]` | [`linebreak`]($func/linebreak) | +| Alignment point | `[$x &= 2 \ &= 3$]` | [Math]($category/math) | +| Variable access | `[$#x$, $pi$]` | [Math]($category/math) | +| Field access | `[$arrow.r.long$]` | [Scripting]($scripting/#fields) | +| Implied multiplication | `[$x y$]` | [Math]($category/math) | +| Symbol shorthand | `[$->, !=$]` | [Symbols]($category/symbols/sym) | +| Text/string in math | `[$a "is natural"$]` | [Math]($category/math) | +| Math function call | `[$floor(x)$]` | [Math]($category/math) | +| Code expression | `[$#rect(width: 1cm)$]` | [Scripting]($scripting/#expressions) | +| Character escape | `[$x\^2$]` | [Below](#escapes) | +| Comment | `[$/* comment */$]` | [Below](#comments) | + +## Code mode { #code } +Within code blocks and expressions, new expressions can start without a leading +`#` character. Many syntactic elements are specific to expressions. Below is +a table listing all syntax that is available in code mode: + +| Name | Example | See | +| ------------------------ | ----------------------------- | ---------------------------------- | +| Variable access | `{x}` | [Scripting]($scripting/#blocks) | +| Any literal | `{1pt, "hey"}` | [Types]($types) | +| Code block | `{{ let x = 1; x + 2 }}` | [Scripting]($scripting/#blocks) | +| Content block | `{[*Hello*]}` | [Scripting]($scripting/#blocks) | +| Parenthesized expression | `{(1 + 2)}` | [Scripting]($scripting/#blocks) | +| Array | `{(1, 2, 3)}` | [Array]($type/array) | +| Dictionary | `{(a: "hi", b: 2)}` | [Dictionary]($type/dictionary) | +| Unary operator | `{-x}` | [Scripting]($scripting/#operators) | +| Binary operator | `{x + y}` | [Scripting]($scripting/#operators) | +| Assignment | `{x = 1}` | [Scripting]($scripting/#operators) | +| Field access | `{x.y}` | [Scripting]($scripting/#fields) | +| Method call | `{x.flatten()}` | [Scripting]($scripting/#methods) | +| Function call | `{min(x, y)}` | [Function]($type/function) | +| Unnamed function | `{(x, y) => x + y}` | [Function]($type/function) | +| Let binding | `{let x = 1}` | [Scripting]($scripting/#bindings) | +| Named function | `{let f(x) = 2 * x}` | [Function]($type/function) | +| Set rule | `{set text(14pt)}` | [Styling]($styling/#set-rules) | +| Set-if rule | `{set text(..) if .. }` | [Styling]($styling/#set-rules) | +| Show-set rule | `{show par: set block(..)}` | [Styling]($styling/#show-rules) | +| Show rule with function | `{show raw: it => {..}}` | [Styling]($styling/#show-rules) | +| Show-everything rule | `{show: columns.with(2)}` | [Styling]($styling/#show-rules) | +| Conditional | `{if x == 1 {..} else {..}}` | [Scripting]($scripting/#conditionals) | +| For loop | `{for x in (1, 2, 3) {..}}` | [Scripting]($scripting/#loops) | +| While loop | `{while x < 10 {..}}` | [Scripting]($scripting/#loops) | +| Loop control flow | `{break, continue}` | [Scripting]($scripting/#loops) | +| Return from function | `{return x}` | [Function]($type/function) | +| Include module | `{include "bar.typ"}` | [Scripting]($scripting/#modules) | +| Import module | `{import "bar.typ"}` | [Scripting]($scripting/#modules) | +| Import items from module | `{import "bar.typ": a, b, c}` | [Scripting]($scripting/#modules) | +| Comment | `[/* block */, // line]` | [Below](#comments) | + +## Comments { #comments } +Comments are ignored by Typst and will not be included in the output. This +is useful to exclude old versions or to add annotations. +To comment out a single line, start it with `//`: +```example +// our data barely supports +// this claim + +We show with $p < 0.05$ +that the difference is +significant. +``` + +Comments can also be wrapped between `/*` and `*/`. In this case, the comment +can span over multiple lines: +```example +Our study design is as follows: +/* Somebody write this up: + - 1000 participants. + - 2x2 data design. */ +``` + +## Escape sequences { #escapes } +Escape sequences are used to insert special characters that are hard to type or +otherwise have special meaning in Typst. To escape a character, precede it with +a backslash. To insert any Unicode codepoint, you can write a hexadecimal +escape sequence: `[\u{1f600}]`. The same kind of escape sequences also work in +[strings]($type/string). + +```example +I got an ice cream for +\$1.50! \u{1f600} +``` diff --git a/docs/reference/types.md b/docs/reference/types.md new file mode 100644 index 00000000..3e08d670 --- /dev/null +++ b/docs/reference/types.md @@ -0,0 +1,1190 @@ +# None +A value that indicates the absence of any other value. + +The none type has exactly one value: `{none}`. + +When inserted into the document, it is not visible. +This is also the value that is produced by empty code blocks. +It can be [joined]($scripting/#blocks) with any value, yielding +the other value. + +## Example +```example +Not visible: #none +``` + +# Auto +A value that indicates a smart default. + +The auto type has exactly one value: `{auto}`. + +Parameters that support the `{auto}` value have some smart default or contextual +behaviour. A good example is the [text direction]($func/text.dir) parameter. +Setting it to `{auto}` lets Typst automatically determine the direction from the +[text language]($func/text.lang). + +# Boolean +Either `{true}` or `{false}`. + +The boolean type has two values: `{true}` and `{false}`. It denotes whether +something is active or enabled. + +## Example +```example +#false \ +#true \ +#(1 < 2) +``` + +# Integer +A whole number. + +The number can be negative, zero, or positive. As Typst uses 64 bits to store +integers, integers cannot be smaller than `{-9223372036854775808}` or larger than +`{9223372036854775807}`. + +The number can also be specified as hexadecimal, octal, or binary by starting it +with a zero followed by either `x`, `o`, or `b`. + +## Example +```example +#(1 + 2) \ +#(2 - 5) \ +#(3 + 4 < 8) + +#0xff \ +#0o10 \ +#0b1001 +``` + +# Float +A floating-pointer number. + +A limited-precision representation of a real number. Typst uses 64 bits to +store floats. Wherever a float is expected, you can also pass an +[integer]($type/integer). + +## Example +```example +#3.14 \ +#1e4 \ +#(10 / 4) +``` + +# Length +A size or distance, possibly expressed with contextual units. +Typst supports the following length units: + +- Points: `{72pt}` +- Millimeters: `{254mm}` +- Centimeters: `{2.54cm}` +- Inches: `{1in}` +- Relative to font size: `{2.5em}` + +## Example +```example +#rect(width: 20pt) +#rect(width: 2em) +#rect(width: 1in) +``` + +# Angle +An angle describing a rotation. +Typst supports the following angular units: + +- Degrees: `{180deg}` +- Radians: `{3.14rad}` + +## Example +```example +#rotate(10deg)[Hello there!] +``` + +# Ratio +A ratio of a whole. + +Written as a number, followed by a percent sign. + +## Example +```example +#set align(center) +#scale(x: 150%)[ + Scaled apart. +] +``` + +# Relative Length +A length in relation to some known length. + +This type is a combination of a [length]($type/length) with a +[ratio]($type/ratio). It results from addition and subtraction +of a length and a ratio. Wherever a relative length is expected, you can also +use a bare length or ratio. + +## Example +```example +#rect(width: 100% - 50pt) +``` + +# Fraction +Defines how the the remaining space in a layout is distributed. + +Each fractionally sized element gets space based on the ratio of its fraction to +the sum of all fractions. + +For more details, also see the [h]($func/h) and [v]($func/v) functions and the +[grid function]($func/grid). + +## Example +```example +Left #h(1fr) Left-ish #h(2fr) Right +``` + +# Color +A color in a specific color space. + +Typst supports: +- sRGB through the [`rgb` function]($func/rgb) +- Device CMYK through [`cmyk` function]($func/cmyk) +- D65 Gray through the [`luma` function]($func/luma) + +Furthermore, Typst provides the following built-in colors: + +`black`, `gray`, `silver`, `white`, `navy`, `blue`, `aqua`, `teal`, `eastern`, +`purple`, `fuchsia`, `maroon`, `red`, `orange`, `yellow`, `olive`, `green`, and +`lime`. + +## Methods +### lighten() +Lightens a color. + +- amount: ratio (positional, required) + The factor to lighten the color by. +- returns: color + +### darken() +Darkens a color. + +- amount: ratio (positional, required) + The factor to darken the color by. +- returns: color + +### negate() +Produces the negative of the color. + +- returns: color + +# Datetime +Represents a date, a time, or a combination of both. Can be created by either +specifying a custom datetime using the [`datetime`]($func/datetime) function or +getting the current date with [`datetime.today`]($func/datetime.today). + +## Example +```example +#let date = datetime( + year: 2020, + month: 10, + day: 4, +) + +#date.display() \ +#date.display( + "y:[year repr:last_two]" +) + +#let time = datetime( + hour: 18, + minute: 2, + second: 23, +) + +#time.display() \ +#time.display( + "h:[hour repr:12][period]" +) +``` + +## Format +You can specify a customized formatting using the +[`display`]($type/datetime.display) method. The format of a datetime is +specified by providing _components_ with a specified number of _modifiers_. A +component represents a certain part of the datetime that you want to display, +and with the help of modifiers you can define how you want to display that +component. In order to display a component, you wrap the name of the component +in square brackets (e.g. `[[year]]` will display the year). In order to add +modifiers, you add a space after the component name followed by the name of the +modifier, a colon and the value of the modifier (e.g. `[[month repr:short]]` +will display the short representation of the month). + +The possible combination of components and their respective modifiers is as +follows: + +* `year`: Displays the year of the datetime. + * `padding`: Can be either `zero`, `space` or `none`. Specifies how the year + is padded. + * `repr` Can be either `full` in which case the full year is displayed or + `last_two` in which case only the last two digits are displayed. + * `sign`: Can be either `automatic` or `mandatory`. Specifies when the sign + should be displayed. +* `month`: Displays the month of the datetime. + * `padding`: Can be either `zero`, `space` or `none`. Specifies how the month + is padded. + * `repr`: Can be either `numerical`, `long` or `short`. Specifies if the month + should be displayed as a number or a word. Unfortunately, when choosing the + word representation, it can currently only display the English version. In + the future, it is planned to support localization. +* `day`: Displays the day of the datetime. + * `padding`: Can be either `zero`, `space` or `none`. Specifies how the day + is padded. +* `week_number`: Displays the week number of the datetime. + * `padding`: Can be either `zero`, `space` or `none`. Specifies how the week + number is padded. + * `repr`: Can be either `ISO`, `sunday` or `monday`. In the case of `ISO`, + week numbers are between 1 and 53, while the other ones are between 0 + and 53. +* `weekday`: Displays the weekday of the date. + * `repr` Can be either `long`, `short`, `sunday` or `monday`. In the case of + `long` and `short`, the corresponding English name will be displayed (same + as for the month, other languages are currently not supported). In the case + of `sunday` and `monday`, the numerical value will be displayed (assuming + Sunday and Monday as the first day of the week, respectively). + * `one_indexed`: Can be either `true` or `false`. Defines whether the + numerical representation of the week starts with 0 or 1. +* `hour`: Displays the hour of the date. + * `padding`: Can be either `zero`, `space` or `none`. Specifies how the hour + is padded. + * `repr`: Can be either `24` or `12`. Changes whether the hour is displayed in + the 24-hour or 12-hour format. +* `period`: The AM/PM part of the hour + * `case`: Can be `lower` to display it in lower case and `upper` to display it + in upper case. +* `minute`: Displays the minute of the date. + * `padding`: Can be either `zero`, `space` or `none`. Specifies how the minute + is padded. +* `second`: Displays the second of the date. + * `padding`: Can be either `zero`, `space` or `none`. Specifies how the second + is padded. + +Keep in mind that not always all components can be used. For example, if +you create a new datetime with `{datetime(year: 2023, month: 10, day: 13)}`, it +will be stored as a plain date internally, meaning that you cannot use +components such as `hour` or `minute`, which would only work on datetimes +that have a specified time. + +## Methods +### display() +Displays the datetime in a certain way. Depending on whether you have defined +just a date, a time or both, the default format will be different. +If you specified a date, it will be `[[year]-[month]-[day]]`. If you specified a +time, it will be `[[hour]:[minute]:[second]]`. In the case of a datetime, it +will be `[[year]-[month]-[day] [hour]:[minute]:[second]]`. + +- pattern: string (positional) + The format used to display the datetime. +- returns: string + +### year() +Returns the year of the datetime, if it exists. Otherwise, it returns `{none}`. + +- returns: integer or none + +### month() +Returns the month of the datetime, if it exists. Otherwise, it returns `{none}`. + +- returns: integer or none + +### weekday() +Returns the weekday of the datetime as a number starting with 1 from Monday, if +it exists. Otherwise, it returns `{none}`. + +- returns: integer or none + +### day() +Returns the day of the datetime, if it exists. Otherwise, it returns `{none}`. + +- returns: integer or none + +### hour() +Returns the hour of the datetime, if it exists. Otherwise, it returns `{none}`. + +- returns: integer or none + +### minute() +Returns the minute of the datetime, if it exists. Otherwise, it returns +`{none}`. + +- returns: integer or none + +### second() +Returns the second of the datetime, if it exists. Otherwise, it returns +`{none}`. + +- returns: integer or none + +# Symbol +A Unicode symbol. + +Typst defines common symbols so that they can easily be written with standard +keyboards. The symbols are defined in modules, from which they can be accessed +using [field access notation]($scripting/#fields): + +- General symbols are defined in the [`sym` module]($category/symbols/sym) +- Emoji are defined in the [`emoji` module]($category/symbols/emoji) + +Moreover, you can define custom symbols with the [symbol]($func/symbol) +function. + +```example +#sym.arrow.r \ +#sym.gt.eq.not \ +$gt.eq.not$ \ +#emoji.face.halo +``` + +Many symbols have different variants, which can be selected by appending the +modifiers with dot notation. The order of the modifiers is not relevant. Visit +the documentation pages of the symbol modules and click on a symbol to see its +available variants. + +```example +$arrow.l$ \ +$arrow.r$ \ +$arrow.t.quad$ +``` + +# String +A sequence of Unicode codepoints. + +You can iterate over the grapheme clusters of the string using a +[for loop]($scripting/#loops). Grapheme clusters are basically characters but +keep together things that belong together, e.g. multiple codepoints that +together form a flag emoji. Strings can be added with the `+` operator, +[joined together]($scripting/#blocks) and multiplied with integers. + +Typst provides utility methods for string manipulation. Many of these methods +(e.g., `split`, `trim` and `replace`) operate on _patterns:_ A pattern can be +either a string or a [regular expression]($func/regex). This makes the methods +quite versatile. + +All lengths and indices are expressed in terms of UTF-8 characters. Indices are +zero-based and negative indices wrap around to the end of the string. + +### Example +```example +#"hello world!" \ +#"\"hello\n world\"!" \ +#"1 2 3".split() \ +#"1,2;3".split(regex("[,;]")) \ +#(regex("\d+") in "ten euros") \ +#(regex("\d+") in "10 euros") +``` + +### Escape sequences +Just like in markup, you can escape a few symbols in strings: +- `[\\]` for a backslash +- `[\"]` for a quote +- `[\n]` for a newline +- `[\r]` for a carriage return +- `[\t]` for a tab +- `[\u{1f600}]` for a hexadecimal Unicode escape sequence + +## Methods +### len() +The length of the string in UTF-8 encoded bytes. + +- returns: integer + +### first() +Extract the first grapheme cluster of the string. +Fails with an error if the string is empty. + +- returns: any + +### last() +Extract the last grapheme cluster of the string. +Fails with an error if the string is empty. + +- returns: any + +### at() +Extract the first grapheme cluster after the specified index. Returns the +default value if the index is out of bounds or fails with an error if no default +value was specified. + +- index: integer (positional, required) + The byte index. +- default: any (named) + A default value to return if the index is out of bounds. +- returns: string + +### slice() +Extract a substring of the string. +Fails with an error if the start or end index is out of bounds. + +- start: integer (positional, required) + The start byte index (inclusive). +- end: integer (positional) + The end byte index (exclusive). If omitted, the whole slice until the end of the + string is extracted. +- count: integer (named) + The number of bytes to extract. This is equivalent to passing `start + count` + as the `end` position. Mutually exclusive with `end`. +- returns: string + +### clusters() +Returns the grapheme clusters of the string as an array of substrings. + +- returns: array + +### codepoints() +Returns the Unicode codepoints of the string as an array of substrings. + +- returns: array + +### contains() +Whether the string contains the specified pattern. + +This method also has dedicated syntax: You can write `{"bc" in "abcd"}` instead +of `{"abcd".contains("bc")}`. + +- pattern: string or regex (positional, required) + The pattern to search for. +- returns: boolean + +### starts-with() +Whether the string starts with the specified pattern. + +- pattern: string or regex (positional, required) + The pattern the string might start with. +- returns: boolean + +### ends-with() +Whether the string ends with the specified pattern. + +- pattern: string or regex (positional, required) + The pattern the string might end with. +- returns: boolean + +### find() +Searches for the specified pattern in the string and returns the first match +as a string or `{none}` if there is no match. + +- pattern: string or regex (positional, required) + The pattern to search for. +- returns: string or none + +### position() +Searches for the specified pattern in the string and returns the index of the +first match as an integer or `{none}` if there is no match. + +- pattern: string or regex (positional, required) + The pattern to search for. +- returns: integer or none + +### match() +Searches for the specified pattern in the string and returns a dictionary +with details about the first match or `{none}` if there is no match. + +The returned dictionary has the following keys: +* `start`: The start offset of the match +* `end`: The end offset of the match +* `text`: The text that matched. +* `captures`: An array containing a string for each matched capturing group. The + first item of the array contains the first matched capturing, not the whole + match! This is empty unless the `pattern` was a regex with capturing groups. + +- pattern: string or regex (positional, required) + The pattern to search for. +- returns: dictionary or none + +### matches() +Searches for the specified pattern in the string and returns an array of +dictionaries with details about all matches. For details about the returned +dictionaries, see above. + +- pattern: string or regex (positional, required) + The pattern to search for. +- returns: array + +### replace() +Replaces all or a specified number of matches of a pattern with a replacement +string and returns the resulting string. + +- pattern: string or regex (positional, required) + The pattern to search for. +- replacement: string or function (positional, required) + The string to replace the matches with or a function that gets a dictionary for each match and can return individual replacement strings. +- count: integer (named) + If given, only the first `count` matches of the pattern are placed. +- returns: string + +### trim() +Removes matches of a pattern from one or both sides of the string, once or +repeatedly and returns the resulting string. + +- pattern: string or regex (positional, required) + The pattern to search for. +- at: alignment (named) + Can be `start` or `end` to only trim the start or end of the string. + If omitted, both sides are trimmed. +- repeat: boolean (named) + Whether to repeatedly removes matches of the pattern or just once. + Defaults to `{true}`. +- returns: string + +### split() +Splits a string at matches of a specified pattern and returns an array of +the resulting parts. + +- pattern: string or regex (positional) + The pattern to split at. Defaults to whitespace. +- returns: array + +# Content +A piece of document content. + +This type is at the heart of Typst. All markup you write and most +[functions]($type/function) you call produce content values. You can create a +content value by enclosing markup in square brackets. This is also how you pass +content to functions. + +```example +Type of *Hello!* is +#type([*Hello!*]) +``` + +Content can be added with the `+` operator, +[joined together]($scripting/#blocks) and multiplied with +integers. Wherever content is expected, you can also pass a +[string]($type/string) or `{none}`. + +## Representation +Content consists of elements with fields. When constructing an element with +its _element function,_ you provide these fields as arguments and when you have +a content value, you can access its fields with +[field access syntax]($scripting/#field-access). + +Some fields are required: These must be provided when constructing an element +and as a consequence, they are always available through field access on content +of that type. Required fields are marked as such in the documentation. + +Most fields are optional: Like required fields, they can be passed to the +element function to configure them for a single element. However, these can also +be configured with [set rules]($styling/#set-rules) to apply them to all +elements within a scope. Optional fields are only available with field access +syntax when they are were explicitly passed to the element function, not when +they result from a set rule. + +Each element has a default appearance. However, you can also completely +customize its appearance with a [show rule]($styling/#show-rules). The show rule +is passed the element. It can access the element's field and produce arbitrary +content from it. + +In the web app, you can hover over a content variable to see exactly which +elements the content is composed of and what fields they have. Alternatively, +you can inspect the output of the [`repr`]($func/repr) function. + +## Methods +### func() +The content's element function. This function can be used to create the element +contained in this content. It can be used in set and show rules for the element. +Can be compared with global functions to check whether you have a specific +kind of element. + +- returns: function + +### has() +Whether the content has the specified field. + +- field: string (positional, required) + The field to look for. +- returns: boolean + +### at() +Access the specified field on the content. Returns the default value if the +field does not exist or fails with an error if no default value was specified. + +- field: string (positional, required) + The field to access. +- default: any (named) + A default value to return if the field does not exist. +- returns: any + +### fields() +Return the fields of this content. + +```example +#rect( + width: 10cm, + height: 10cm, +).fields() +``` + +### location() +The location of the content. This is only available on content returned by +[query]($func/query), for other content it will fail with an error. The +resulting location can be used with [counters]($func/counter), +[state]($func/state) and [queries]($func/query). + +- returns: location + +# Array +A sequence of values. + +You can construct an array by enclosing a comma-separated sequence of values +in parentheses. The values do not have to be of the same type. + +You can access and update array items with the `.at()` method. Indices are +zero-based and negative indices wrap around to the end of the array. You can +iterate over an array using a [for loop]($scripting/#loops). +Arrays can be added together with the `+` operator, +[joined together]($scripting/#blocks) and multiplied with +integers. + +**Note:** An array of length one needs a trailing comma, as in `{(1,)}`. This is +to disambiguate from a simple parenthesized expressions like `{(1 + 2) * 3}`. +An empty array is written as `{()}`. + +## Example +```example +#let values = (1, 7, 4, -3, 2) + +#values.at(0) \ +#(values.at(0) = 3) +#values.at(-1) \ +#values.find(calc.even) \ +#values.filter(calc.odd) \ +#values.map(calc.abs) \ +#values.rev() \ +#(1, (2, 3)).flatten() \ +#(("A", "B", "C") + .join(", ", last: " and ")) +``` + +## Methods +### len() +The number of values in the array. + +- returns: integer + +### first() +Returns the first item in the array. +May be used on the left-hand side of an assignment. +Fails with an error if the array is empty. + +- returns: any + +### last() +Returns the last item in the array. +May be used on the left-hand side of an assignment. +Fails with an error if the array is empty. + +- returns: any + +### at() +Returns the item at the specified index in the array. May be used on the +left-hand side of an assignment. Returns the default value if the index is out +of bounds or fails with an error if no default value was specified. + +- index: integer (positional, required) + The index at which to retrieve the item. +- default: any (named) + A default value to return if the index is out of bounds. +- returns: any + +### push() +Add a value to the end of the array. + +- value: any (positional, required) + The value to insert at the end of the array. + +### pop() +Remove the last item from the array and return it. +Fails with an error if the array is empty. + +- returns: any + The removed last value. + +### insert() +Insert a value into the array at the specified index. +Fails with an error if the index is out of bounds. + +- index: integer (positional, required) + The index at which to insert the item. +- value: any (positional, required) + The value to insert into the array. + +### remove() +Remove the value at the specified index from the array and return it. + +- index: integer (positional, required) + The index at which to remove the item. +- returns: any + +### slice() +Extract a subslice of the array. +Fails with an error if the start or index is out of bounds. + +- start: integer (positional, required) + The start index (inclusive). +- end: integer (positional) + The end index (exclusive). If omitted, the whole slice until the end of the + array is extracted. +- count: integer (named) + The number of items to extract. This is equivalent to passing `start + + count` as the `end` position. Mutually exclusive with `end`. +- returns: array + +### contains() +Whether the array contains the specified value. + +This method also has dedicated syntax: You can write `{2 in (1, 2, 3)}` instead +of `{(1, 2, 3).contains(2)}`. + +- value: any (positional, required) + The value to search for. +- returns: boolean + +### find() +Searches for an item for which the given function returns `{true}` and +returns the first match or `{none}` if there is no match. + +- searcher: function (positional, required) + The function to apply to each item. Must return a boolean. +- returns: any or none + +### position() +Searches for an item for which the given function returns `{true}` and +returns the index of the first match or `{none}` if there is no match. + +- searcher: function (positional, required) + The function to apply to each item. Must return a boolean. +- returns: integer or none + +### filter() +Produces a new array with only the items from the original one for which the +given function returns true. + +- test: function (positional, required) + The function to apply to each item. Must return a boolean. +- returns: array + +### map() +Produces a new array in which all items from the original one were +transformed with the given function. + +- mapper: function (positional, required) + The function to apply to each item. +- returns: array + +### enumerate() +Returns a new array with the values alongside their indices. + +The returned array consists of `(index, value)` pairs in the form of length-2 +arrays. These can be [destructured]($scripting/#bindings) with a let binding or +for loop. + +- returns: array + +### zip() +Zips the array with another array. If the two arrays are of unequal length, it +will only zip up until the last element of the smaller array and the remaining +elements will be ignored. The return value is an array where each element is yet +another array of size 2. + +- other: array (positional, required) + The other array which should be zipped with the current one. +- returns: array + +### fold() +Folds all items into a single value using an accumulator function. + +- init: any (positional, required) + The initial value to start with. +- folder: function (positional, required) + The folding function. Must have two parameters: One for the accumulated value + and one for an item. +- returns: any + +### sum() +Sums all items (works for any types that can be added). + +- default: any (named) + What to return if the array is empty. Must be set if the array can be empty. +- returns: any + +### product() +Calculates the product all items (works for any types that can be multiplied) + +- default: any (named) + What to return if the array is empty. Must be set if the array can be empty. +- returns: any + +### any() +Whether the given function returns `{true}` for any item in the array. + +- test: function (positional, required) + The function to apply to each item. Must return a boolean. +- returns: boolean + +### all() +Whether the given function returns `{true}` for all items in the array. + +- test: function (positional, required) + The function to apply to each item. Must return a boolean. +- returns: boolean + +### flatten() +Combine all nested arrays into a single flat one. + +- returns: array + +### rev() +Return a new array with the same items, but in reverse order. + +- returns: array + +### join() +Combine all items in the array into one. + +- separator: any (positional) + A value to insert between each item of the array. +- last: any (named) + An alternative separator between the last two items +- returns: any + +### sorted() +Return a new array with the same items, but sorted. + +- key: function (named) + If given, applies this function to the elements in the array to determine the keys to sort by. +- returns: array + +# Dictionary +A map from string keys to values. + +You can construct a dictionary by enclosing comma-separated `key: value` pairs +in parentheses. The values do not have to be of the same type. Since empty +parentheses already yield an empty array, you have to use the special `(:)` +syntax to create an empty dictionary. + +A dictionary is conceptually similar to an array, but it is indexed by strings +instead of integers. You can access and create dictionary entries with the +`.at()` method. If you know the key statically, you can alternatively use +[field access notation]($scripting/#fields) (`.key`) to access +the value. Dictionaries can be added with the `+` operator and +[joined together]($scripting/#blocks). +To check whether a key is present in the dictionary, use the `in` keyword. + +You can iterate over the pairs in a dictionary using a +[for loop]($scripting/#loops). This will iterate in the order the pairs were +inserted / declared. + +## Example +```example +#let dict = ( + name: "Typst", + born: 2019, +) + +#dict.name \ +#(dict.launch = 20) +#dict.len() \ +#dict.keys() \ +#dict.values() \ +#dict.at("born") \ +#dict.insert("city", "Berlin ") +#("name" in dict) +``` + +## Methods +### len() +The number of pairs in the dictionary. + +- returns: integer + +### at() +Returns the value associated with the specified key in the dictionary. May be +used on the left-hand side of an assignment if the key is already present in the +dictionary. Returns the default value if the key is not part of the dictionary +or fails with an error if no default value was specified. + +- key: string (positional, required) + The key at which to retrieve the item. +- default: any (named) + A default value to return if the key is not part of the dictionary. +- returns: any + +### insert() +Insert a new pair into the dictionary and return the value. +If the dictionary already contains this key, the value is updated. + +- key: string (positional, required) + The key of the pair that should be inserted. +- value: any (positional, required) + The value of the pair that should be inserted. + +### keys() +Returns the keys of the dictionary as an array in insertion order. + +- returns: array + +### values() +Returns the values of the dictionary as an array in insertion order. + +- returns: array + +### pairs() +Returns the keys and values of the dictionary as an array of pairs. Each pair is +represented as an array of length two. + +- returns: array + +### remove() +Remove a pair from the dictionary by key and return the value. + +- key: string (positional, required) + The key of the pair that should be removed. +- returns: any + +# Function +A mapping from argument values to a return value. + +You can call a function by writing a comma-separated list of function +_arguments_ enclosed in parentheses directly after the function name. +Additionally, you can pass any number of trailing content blocks arguments to a +function _after_ the normal argument list. If the normal argument list would +become empty, it can be omitted. Typst supports positional and named arguments. +The former are identified by position and type, while the later are written as +`name: value`. + +Within math mode, function calls have special behaviour. See the +[math documentation]($category/math) for more details. + +### Example +```example +// Call a function. +#list([A], [B]) + +// Named arguments and trailing +// content blocks. +#enum(start: 2)[A][B] + +// Version without parentheses. +#list[A][B] +``` + +Functions are a fundamental building block of Typst. Typst provides functions +for a variety of typesetting tasks. Moreover, the markup you write is backed by +functions and all styling happens through functions. This reference lists all +available functions and how you can use them. Please also refer to the +documentation about [set]($styling/#set-rules) and +[show]($styling/#show-rules) rules to learn about additional ways +you can work with functions in Typst. + +### Element functions { #element-functions } +Some functions are associated with _elements_ like [headings]($func/heading) or +[tables]($func/table). When called, these create an element of their respective +kind. In contrast to normal functions, they can further be used in +[set rules]($styling/#set-rules), [show rules]($styling/#show-rules), and +[selectors]($type/selector). + +### Function scopes { #function-scopes } +Functions can hold related definitions in their own scope, similar to a +[module]($scripting/#modules). Examples of this are +[`assert.eq`]($func/assert.eq) or [`list.item`]($func/list.item). However, this +feature is currently only available for built-in functions. + +### Defining functions { #definitions } +You can define your own function with a +[let binding]($scripting/#bindings) that has a parameter list after +the binding's name. The parameter list can contain positional parameters, +named parameters with default values and +[argument sinks]($type/arguments). +The right-hand side of the binding can be a block or any other expression. It +defines the function's return value and can depend on the parameters. + +```example +#let alert(body, fill: red) = { + set text(white) + set align(center) + rect( + fill: fill, + inset: 8pt, + radius: 4pt, + [*Warning:\ #body*], + ) +} + +#alert[ + Danger is imminent! +] + +#alert(fill: blue)[ + KEEP OFF TRACKS +] +``` + +### Unnamed functions { #unnamed } +You can also created an unnamed function without creating a binding by +specifying a parameter list followed by `=>` and the function body. If your +function has just one parameter, the parentheses around the parameter list are +optional. Unnamed functions are mainly useful for show rules, but also for +settable properties that take functions like the page function's +[`footer`]($func/page.footer) property. + +```example +#show "once?": it => [#it #it] +once? +``` + +### Notable fact +In Typst, all functions are _pure._ This means that for the same +arguments, they always return the same result. They cannot "remember" things to +produce another value when they are called a second time. + +The only exception are built-in methods like +[`array.push(value)`]($type/array.push). These can modify the values they are +called on. + +## Methods +### with() +Returns a new function that has the given arguments pre-applied. + +- arguments: any (variadic) + The named and positional arguments to apply. +- returns: function + +### where() +Returns a selector that filters for elements belonging to this function +whose fields have the values of the given arguments. + +- fields: any (named, variadic) + The field values to filter by. +- returns: selector + +# Arguments +Captured arguments to a function. + +Like built-in functions, custom functions can also take a variable number of +arguments. You can specify an _argument sink_ which collects all excess +arguments as `..sink`. The resulting `sink` value is of the `arguments` type. It +exposes methods to access the positional and named arguments and is iterable +with a [for loop]($scripting/#loops). Inversely, you can spread +arguments, arrays and dictionaries into a function call with the spread operator: +`{func(..args)}`. + +## Example +```example +#let format(title, ..authors) = [ + *#title* \ + _Written by #(authors + .pos() + .join(", ", last: " and "));._ +] + +#format("ArtosFlow", "Jane", "Joe") +``` + +## Methods +### pos() +Returns the captured positional arguments as an array. + +- returns: array + +### named() +Returns the captured named arguments as a dictionary. + +- returns: dictionary + +# Selector +A filter for selecting elements within the document. + +You can construct a selector in the following ways: +- you can use an element [function]($type/function) +- you can filter for an element function with + [specific fields]($type/function.where) +- you can use a [string]($type/string) or [regular expression]($func/regex) +- you can use a [`{