diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/changelog.md | 190 | ||||
| -rw-r--r-- | docs/guides/guide-for-latex-users.md | 92 | ||||
| -rw-r--r-- | docs/guides/page-setup.md | 38 | ||||
| -rw-r--r-- | docs/reference/context.md | 38 | ||||
| -rw-r--r-- | docs/reference/groups.yml | 12 | ||||
| -rw-r--r-- | docs/reference/scripting.md | 49 | ||||
| -rw-r--r-- | docs/reference/styling.md | 19 | ||||
| -rw-r--r-- | docs/reference/syntax.md | 28 | ||||
| -rw-r--r-- | docs/reference/welcome.md | 8 | ||||
| -rw-r--r-- | docs/roadmap.md | 2 | ||||
| -rw-r--r-- | docs/src/html.rs | 28 | ||||
| -rw-r--r-- | docs/src/lib.rs | 3 | ||||
| -rw-r--r-- | docs/tutorial/1-writing.md | 15 | ||||
| -rw-r--r-- | docs/tutorial/2-formatting.md | 61 | ||||
| -rw-r--r-- | docs/tutorial/3-advanced.md | 41 | ||||
| -rw-r--r-- | docs/tutorial/4-template.md | 22 |
16 files changed, 328 insertions, 318 deletions
diff --git a/docs/changelog.md b/docs/changelog.md index a803508c..feb0100e 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -53,8 +53,8 @@ description: | Chinese, French, and Russian - Changed default [figure supplement]($figure.supplement) for Russian to short form - - Fixed [CJK-Latin-spacing]($text.cjk-latin-spacing) before line breaks - and in [`locate`]($locate) calls + - Fixed [CJK-Latin-spacing]($text.cjk-latin-spacing) before line breaks and in + [`locate`] calls - Fixed line breaking at the end of links - Math @@ -68,13 +68,13 @@ description: | - Scripting - Any non-identifier dictionary key is now interpreted as an expression: For instance, `{((key): value)}` will create a dictionary with a dynamic key - - The [`stroke`]($stroke) type now has a constructor that converts a value to - a stroke or creates one from its parts - - Added constructor for [`arguments`]($arguments) type + - The [`stroke`] type now has a constructor that converts a value to a stroke + or creates one from its parts + - Added constructor for [`arguments`] type - Added [`calc.div-euclid`]($calc.div-euclid) and [`calc.rem-euclid`]($calc.rem-euclid) functions - - Fixed equality of [`arguments`]($arguments) - - Fixed [`repr`]($repr) of [`cmyk`]($color.cmyk) colors + - Fixed equality of [`arguments`] + - Fixed [`repr`]of [`cmyk`]($color.cmyk) colors - Fixed crashes with provided elements like figure captions, outline entries, and footnote entries @@ -117,10 +117,10 @@ description: | of just a string - The [`number-align`]($enum.number-align) parameter on numbered lists now also accepts vertical alignments - - Fixed selectors on [quote]($quote) elements + - Fixed selectors on [quote] elements - Fixed parsing of `[#return]` expression in markup - Fixed bug where inline equations were displayed in equation outlines - - Fixed potential CRLF issue in [`raw`]($raw) blocks + - Fixed potential CRLF issue in [`raw`] blocks - Fixed a bug where Chinese numbering couldn't exceed the number 255 - Development @@ -138,11 +138,11 @@ description: | - Added new [`form`]($cite.form) argument to the `cite` function to produce different forms of citations (e.g. for producing a citation suitable for inclusion in prose) - - The [`cite`]($cite) function now takes only a single label/key instead of - allowing multiple. Adjacent citations are merged and formatted according to - the citation style's rules automatically. This works both with the reference + - The [`cite`] function now takes only a single label/key instead of allowing + multiple. Adjacent citations are merged and formatted according to the + citation style's rules automatically. This works both with the reference syntax and explicit calls to the `cite` function. (**Breaking change**) - - The `cite` function now takes a [label]($label) instead of a string + - The `cite` function now takes a [label] instead of a string (**Breaking change**) - Added [`full`]($bibliography.full) argument to bibliography function to print the full bibliography even if not all works were cited @@ -172,8 +172,8 @@ description: | stroke widths - Added support for properly clipping [boxes]($box.clip) and [blocks]($block.clip) with a border radius - - Added `background` parameter to [`overline`]($overline), - [`underline`]($underline), and [`strike`]($strike) functions + - Added `background` parameter to [`overline`], [`underline`], and [`strike`] + functions - Fixed inaccurate color embedding in PDFs - Fixed ICC profile handling for images embedded in PDFs @@ -182,8 +182,8 @@ description: | [spacing]($text.cjk-latin-spacing) between CJK and Latin text (enabled by default) - Added support for automatic adjustment of more CJK punctuation - - Added [`quote`]($quote) element for inserting inline and block quotes with - optional attributions + - Added [`quote`] element for inserting inline and block quotes with optional + attributions - Added [`raw.line`]($raw.line) element for customizing the display of individual lines of raw text, e.g. to add line numbers while keeping proper syntax highlighting @@ -212,8 +212,8 @@ description: | - Fixed spacing around [placed]($place) elements - Fixed coalescing of [`above`]($block.above) and [`below`]($block.below) spacing if given in em units and the font sizes differ - - Fixed handling of `extent` parameter of [`underline`]($underline), - [`overline`]($overline), and [`strike`]($strike) functions + - Fixed handling of `extent` parameter of [`underline`], [`overline`], and + [`strike`] functions - Fixed crash for [floating placed elements]($place.float) with no specified vertical alignment - Partially fixed a bug with citations in footnotes @@ -290,12 +290,11 @@ description: | PNG or SVG export - Miscellaneous Improvements - - Added [`version`]($version) type and `sys.version` constant specifying the - current compiler version. Can be used to gracefully support multiple - versions. + - Added [`version`] type and `sys.version` constant specifying the current + compiler version. Can be used to gracefully support multiple versions. - The U+2212 MINUS SIGN is now used when displaying a numeric value, in the - [`repr`]($repr) of any numeric value and to replace a normal hyphen in text - mode when before a digit. This improves, in particular, how negative integer + [`repr`] of any numeric value and to replace a normal hyphen in text mode + when before a digit. This improves, in particular, how negative integer values are displayed in math mode. - Added support for specifying a default value instead of failing for `remove` function in [array]($array.remove) and @@ -329,9 +328,9 @@ description: | - Plugins can be shipped as part of [packages]($scripting/#packages) - Plugins work just the same in the web app - Types are now first-class values (**Breaking change**) - - A [type]($type) is now itself a value + - A [type] is now itself a value - Some types can be called like functions (those that have a constructor), - e.g. [`int`]($int) and [`str`]($str) + e.g. [`int`] and [`str`] - Type checks are now of the form `{type(10) == int}` instead of the old `{type(10) == "integer"}`. [Compatibility]($type/#compatibility) with the old way will remain for a while to give package authors time to upgrade, @@ -339,7 +338,7 @@ description: | - Methods are now syntax sugar for calling a function scoped to a type, meaning that `{"hello".len()}` is equivalent to `{str.len("hello")}` - Added support for [`import`]($scripting/#modules) renaming with `as` - - Added a [`duration`]($duration) type + - Added a [`duration`] type - Added support for [CBOR]($cbor) encoding and decoding - Added encoding and decoding functions from and to bytes for data formats: [`json.decode`]($json.decode), [`json.encode`]($json.encode), and similar @@ -347,9 +346,9 @@ description: | - Added [`array.intersperse`]($array.intersperse) function - Added [`str.rev`]($str.rev) function - Added `calc.tau` constant - - Made [bytes]($bytes) joinable and addable + - Made [bytes] joinable and addable - Made [`array.zip`]($array.zip) function variadic - - Fixed bug with [`eval`]($eval) when the `mode` was set to `{"math"}` + - Fixed bug with [`eval`] when the `mode` was set to `{"math"}` - Fixed bug with [`ends-with`]($str.ends-with) function on strings - Fixed bug with destructuring in combination with break, continue, and return - Fixed argument types of [hyperbolic functions]($calc.cosh), they don't allow @@ -365,11 +364,11 @@ description: | [page numbering]($page.numbering) style in the PDF - Text and Layout - - Added [`highlight`]($highlight) function for highlighting text with a + - Added [`highlight`] function for highlighting text with a background color - Added [`polygon.regular`]($polygon.regular) function for drawing a regular polygon - - Added support for tabs in [`raw`]($raw) elements alongside + - Added support for tabs in [`raw`] elements alongside [`tab-width`]($raw.tab-size) parameter - The layout engine now tries to prevent "runts" (final lines consisting of just a single word) @@ -514,18 +513,16 @@ description: | - Added `inv` method to [2d alignments]($align.alignment) - Added `start` argument to [`enumerate`]($array.enumerate) method on arrays - Added [`color.mix`]($color.mix) function - - Added `mode` and `scope` arguments to [`eval`]($eval) function - - Added [`bytes`]($bytes) type for holding large byte buffers + - Added `mode` and `scope` arguments to [`eval`] function + - Added [`bytes`] type for holding large byte buffers - Added [`encoding`]($read.encoding) argument to read function to read a file as bytes instead of a string - Added [`image.decode`]($image.decode) function for decoding an image directly from a string or bytes - - Added [`bytes`]($bytes) function for converting a string or an array of - integers to bytes - - Added [`array`]($array) function for converting bytes to an array of - integers - - Added support for converting bytes to a string with the [`str`]($str) - function + - Added [`bytes`] function for converting a string or an array of integers + to bytes + - Added [`array`] function for converting bytes to an array of integers + - Added support for converting bytes to a string with the [`str`] function - Tooling and Diagnostics - Added support for compiler warnings @@ -560,15 +557,15 @@ description: | whether a heading becomes part of the PDF outline - Added [`caption-pos`]($figure.caption.position) argument to control the position of a figure's caption - - Added [`metadata`]($metadata) function for exposing an arbitrary value to - the introspection system - - Fixed that a [`state`]($state) was identified by the pair `(key, init)` - instead of just its `key` + - Added [`metadata`] function for exposing an arbitrary value to the + introspection system + - Fixed that a [`state`] was identified by the pair `(key, init)` instead of + just its `key` - Improved indent logic of [enumerations]($enum). Instead of requiring at least as much indent as the end of the marker, they now require only one more space indent than the start of the marker. As a result, even long markers like `12.` work with just 2 spaces of indent. - - Fixed bug with indent logic of [`raw`]($raw) blocks + - Fixed bug with indent logic of [`raw`] blocks - Fixed a parsing bug with dictionaries - Development @@ -626,10 +623,10 @@ description: | - Added [`outline.entry`]($outline.entry) to customize outline entries with show rules - Added some hints for error messages - - Added some missing syntaxes for [`raw`]($raw) highlighting + - Added some missing syntaxes for [`raw`] highlighting - Improved rendering of rotated images in PNG export and web app - Made [footnotes]($footnote) reusable and referenceable - - Fixed bug with citations and bibliographies in [`locate`]($locate) + - Fixed bug with citations and bibliographies in [`locate`] - Fixed inconsistent tense in documentation - Development @@ -641,8 +638,8 @@ description: | ## Version 0.5.0 (June 9, 2023) { #v0.5.0 } - Text and Layout - - Added [`raw`]($raw) syntax highlighting for many more languages - - Added support for Korean [numbering]($numbering) + - Added [`raw`] syntax highlighting for many more languages + - Added support for Korean [numbering] - Added basic i18n for a few more languages (NL, SV, DA) - Improved line breaking for East Asian languages - Expanded functionality of outline [`indent`]($outline.indent) property @@ -651,7 +648,7 @@ description: | - 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`]($line) elements + - Fixed alignment of [`line`] elements - Math - **Breaking change:** The syntax rules for mathematical @@ -668,12 +665,12 @@ description: | - Fixed a crash in the [`attach`]($math.attach) function - Scripting - - Added new [`datetime`]($datetime) type and - [`datetime.today`]($datetime.today) to retrieve the current date + - Added new [`datetime`] type and [`datetime.today`]($datetime.today) to + retrieve the current date - Added [`str.from-unicode`]($str.from-unicode) and [`str.to-unicode`]($str.to-unicode) functions - Added [`fields`]($content.fields) method on content - - Added `base` parameter to [`str`]($str) function + - Added `base` parameter to [`str`] function - Added [`calc.exp`]($calc.exp) and [`calc.ln`]($calc.ln) - Improved accuracy of [`calc.pow`]($calc.pow) and [`calc.log`]($calc.log) for specific bases @@ -695,7 +692,7 @@ description: | - 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`]($hide) + - Fixed citations and other searchable elements in [`hide`] - Fixed bugs with [reference supplements]($ref.supplement) - Fixed Nix flake @@ -704,7 +701,7 @@ description: | ## Version 0.4.0 (May 20, 2023) { #v0.4.0 } - Footnotes - Implemented support for footnotes - - The [`footnote`]($footnote) function inserts a footnote + - The [`footnote`] function inserts a footnote - The [`footnote.entry`]($footnote.entry) function can be used to customize the footnote listing - The `{"chicago-notes"}` [citation style]($cite.style) is now available @@ -714,7 +711,7 @@ description: | - 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]($outline) function. Suggestions for more keywords are welcome! + the [outline] function. Suggestions for more keywords are welcome! - Fixed issue with search result ranking - Fixed many more small issues @@ -736,8 +733,8 @@ description: | - Scripting - Added function scopes: A function can now hold related definitions in its own scope, similar to a module. The new [`assert.eq`]($assert.eq) function, - for instance, is part of the [`assert`]($assert) function's scope. Note that - function scopes are currently only available for built-in functions. + for instance, is part of the [`assert`] function's scope. Note that function + scopes are currently only available for built-in functions. - Added [`assert.eq`]($assert.eq) and [`assert.ne`]($assert.ne) functions for simpler equality and inequality assertions with more helpful error messages - Exposed [list]($list.item), [enum]($enum.item), and [term list]($terms.item) @@ -811,8 +808,8 @@ description: | 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`]($query). This is now - handled through flexible [selectors]($selector) combinator methods + - Removed `before` and `after` arguments from [`query`]. This is now handled + through flexible [selectors]($selector) combinator methods - Added support for [attachments]($math.attach) (sub-, superscripts) that precede the base symbol. The `top` and `bottom` arguments have been renamed to `t` and `b`. @@ -824,7 +821,7 @@ description: | - Added support for [destructuring]($scripting/#bindings) in argument lists and assignments - Added [`alt`]($image.alt) text argument to image function - - Added [`toml`]($toml) function for loading data from a TOML file + - Added [`toml`] function for loading data from a TOML file - Added [`zip`]($array.zip), [`sum`]($array.sum), and [`product`]($array.product) methods for arrays - Added `fact`, `perm`, `binom`, `gcd`, `lcm`, `atan2`, `quo`, `trunc`, and @@ -839,8 +836,8 @@ description: | - Locations are now a valid kind of selector - Added a few symbols for algebra - Added Spanish smart quote support - - Added [`selector`]($selector) function to turn a selector-like value into a - selector on which combinator methods can be called + - Added [`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 @@ -886,9 +883,9 @@ description: | - Added [unpacking syntax]($scripting/#bindings) for let bindings, which allows things like `{let (1, 2) = array}` - Added [`enumerate`]($array.enumerate) method - - Added [`path`]($path) function for drawing Bézier paths - - Added [`layout`]($layout) function to access the size of the surrounding - page or container + - Added [`path`] function for drawing Bézier paths + - Added [`layout`] function to access the size of the surrounding page or + container - Added `key` parameter to [`sorted`]($array.sorted) method - Command line interface @@ -904,7 +901,7 @@ description: | (AR, NB, CS, NN, PL, SL, ES, UA, VI) - Added a few numbering patterns (Ihora, Chinese) - Added `sinc` [operator]($math.op) - - Fixed bug where math could not be hidden with [`hide`]($hide) + - Fixed bug where math could not be hidden with [`hide`] - Fixed sizing issues with box, block, and shapes - Fixed some translations - Fixed inversion of "R" in [`cal`]($math.cal) and [`frak`]($math.frak) styles @@ -912,7 +909,7 @@ description: | - Fixed supplements of references to headings - Fixed syntax highlighting of identifiers in certain scenarios - [Ratios]($ratio) can now be multiplied with more types and be converted to - [floats]($float) with the [`float`]($float) function + [floats]($float) with the [`float`] function <contributors from="v0.1.0" to="v0.2.0" /> @@ -937,8 +934,8 @@ description: | gives access to the automatically resolved kind, supplement, and counter - Bibliography improvements - - The [`bibliography`]($bibliography) now also accepts multiple bibliography - paths (as an array) + - The [`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) @@ -946,7 +943,7 @@ description: | - Fixed APA bibliography ordering - Drawing additions - - Added [`polygon`]($polygon) function for drawing polygons + - Added [`polygon`] function for drawing polygons - Added support for clipping in [boxes]($box.clip) and [blocks]($block.clip) - Command line interface @@ -957,12 +954,12 @@ description: | - Added `--open` flag to directly open the PDF - Miscellaneous improvements - - Added [`yaml`]($yaml) function to load data from YAML files + - Added [`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]($int) with base 2, 8, and 16 - Added symbols for double bracket and laplace operator - - The [`link`]($link) function now accepts [labels]($label) + - The [`link`] function now accepts [labels]($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 @@ -976,7 +973,7 @@ description: | - 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`]($symbol) function was called without arguments + - Fixed crash when [`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 @@ -1005,7 +1002,7 @@ description: | - Numberings now allow zeros. To reset a counter, you can write `[#counter(..).update(0)]` - Added documentation for `{page()}` and `{position()}` methods on - [`location`]($location) type + [`location`] type - Added symbols for double, triple, and quadruple dot accent - Added smart quotes for Norwegian Bokmål - Added Nix flake @@ -1014,8 +1011,7 @@ description: | - 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`]($repeat) is used in page with automatic - width + - Fixed compiler crash if [`repeat`] is used in page with automatic width - Fixed [matrices]($math.mat) with explicit delimiter - Fixed [`indent`]($terms.indent) property of term lists - Numerous documentation fixes @@ -1035,57 +1031,57 @@ description: | - `[$ A = pi r^2 $ <area>]` - Introspection system for interactions between different parts of the document - - [`counter`]($counter) function + - [`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`]($state) function + - [`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`]($query) function + - [`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`]($locate) function + - [`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`]($measure) function +- New [`measure`] function - Measure the layouted size of elements - - To be used in combination with the new [`style`]($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) + - To be used in combination with the new [`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`]($repr) + - Can be observed in hover tooltips or with [`repr`] - New [methods]($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`]($figure) function + - Added [`figure`] function - Added [`numbering`]($math.equation.numbering) parameter on equation function - Added [`numbering`]($page.numbering) and [`number-align`]($page.number-align) parameters on page function - The page function's [`header`]($page.header) and [`footer`]($page.footer) parameters do not take functions anymore. If you want to customize them based on the page number, use the new [`numbering`]($page.numbering) - parameter or [`counter`]($counter) function instead. + parameter or [`counter`] function instead. - Added [`footer-descent`]($page.footer-descent) and [`header-ascent`]($page.header-ascent) parameters - Better default alignment in header and footer @@ -1097,7 +1093,7 @@ description: | - Renamed paragraph `indent` to [`first-line-indent`]($par.first-line-indent) - More accurate [logarithm]($calc.log) when base is `2` or `10` - Improved some error messages - - Fixed layout of [`terms`]($terms) list + - Fixed layout of [`terms`] list - Web app improvements - Added template gallery @@ -1124,9 +1120,9 @@ description: | - 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`]($smallcaps) function + corresponding main font and the [`smallcaps`] function - Improved default spacing for headings -- Added [`panic`]($panic) function +- Added [`panic`] function - Added [`clusters`]($str.clusters) and [`codepoints`]($str.codepoints) methods for strings - Support for multiple authors in [`set document`]($document.author) @@ -1139,14 +1135,14 @@ description: | - Improved incremental compilation for user-defined functions ## February 15, 2023 { #_ } -- [Box]($box) and [block]($block) have gained `fill`, `stroke`, `radius`, and - `inset` properties +- [Box]($box) and [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`]($block.breakable) or not - [Numbering style]($enum.numbering) can now be configured for nested enums - [Markers]($list.marker) can now be configured for nested lists -- The [`eval`]($eval) function now expects code instead of markup and returns an +- The [`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 @@ -1156,8 +1152,8 @@ description: | ## February 12, 2023 { #_ } - Shapes, images, and transformations (move/rotate/scale/repeat) are now - block-level. To integrate them into a paragraph, use a [`box`]($box) as with - other elements. + block-level. To integrate them into a paragraph, use a [`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. @@ -1170,14 +1166,14 @@ description: | - 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`]($place) function +- Fixed relative displacement in [`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`]($box.baseline) property on [`box`]($box) +- Added [`baseline`]($box.baseline) property on [`box`] - Added [`tg`]($math.op) and [`ctg`]($math.op) operators in math - Added delimiter setting for [`cases`]($math.cases) function - Parentheses are now included when accepting a function autocompletion diff --git a/docs/guides/guide-for-latex-users.md b/docs/guides/guide-for-latex-users.md index d991ef78..0b921fc9 100644 --- a/docs/guides/guide-for-latex-users.md +++ b/docs/guides/guide-for-latex-users.md @@ -25,7 +25,7 @@ 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). +a step-by-step introduction to Typst, check out our [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 @@ -65,20 +65,20 @@ Emphasis (usually rendered as italic text) is expressed by enclosing text in Here is a list of common markup commands used in LaTeX and their Typst equivalents. You can also check out the [full syntax cheat sheet]($syntax). -| Element | LaTeX | Typst | See -|:-----------------|:--------------------------|:-----------------------|:-------------------- -| Strong emphasis | `\textbf{strong}` | `[*strong*]` | [`strong`]($strong) | -| Emphasis | `\emph{emphasis}` | `[_emphasis_]` | [`emph`]($emph) | -| Monospace / code | `\texttt{print(1)}` | ``[`print(1)`]`` | [`raw`]($raw) | -| Link | `\url{https://typst.app}` | `[https://typst.app/]` | [`link`]($link) | -| Label | `\label{intro}` | `[<intro>]` | [`label`]($label) | -| Reference | `\ref{intro}` | `[@intro]` | [`ref`]($ref) | -| Citation | `\cite{humphrey97}` | `[@humphrey97]` | [`cite`]($cite) | -| Bullet list | `itemize` environment | `[- List]` | [`list`]($list) | -| Numbered list | `enumerate` environment | `[+ List]` | [`enum`]($enum) | -| Term list | `description` environment | `[/ Term: List]` | [`terms`]($terms) | -| Figure | `figure` environment | `figure` function | [`figure`]($figure) | -| Table | `table` environment | `table` function | [`table`]($table) | +| Element | LaTeX | Typst | See | +|:-----------------|:--------------------------|:-----------------------|:-----------| +| Strong emphasis | `\textbf{strong}` | `[*strong*]` | [`strong`] | +| Emphasis | `\emph{emphasis}` | `[_emphasis_]` | [`emph`] | +| Monospace / code | `\texttt{print(1)}` | ``[`print(1)`]`` | [`raw`] | +| Link | `\url{https://typst.app}` | `[https://typst.app/]` | [`link`] | +| Label | `\label{intro}` | `[<intro>]` | [`label`] | +| Reference | `\ref{intro}` | `[@intro]` | [`ref`] | +| Citation | `\cite{humphrey97}` | `[@humphrey97]` | [`cite`] | +| Bullet list | `itemize` environment | `[- List]` | [`list`] | +| Numbered list | `enumerate` environment | `[+ List]` | [`enum`] | +| Term list | `description` environment | `[/ Term: List]` | [`terms`] | +| Figure | `figure` environment | `figure` function | [`figure`] | +| Table | `table` environment | `table` function | [`table`] | | Equation | `$x$`, `align` / `equation` environments | `[$x$]`, `[$ x = y $]` | [`equation`]($math.equation) | [Lists]($list) do not rely on environments in Typst. Instead, they have @@ -147,12 +147,12 @@ And finally a little loop: ] ``` -A function call always involves the name of the function ([`rect`]($rect), -[`underline`]($underline), [`calc.max`]($calc.max), [`range`]($array.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). +A function call always involves the name of the function ([`rect`], +[`underline`], [`calc.max`]($calc.max), [`range`]($array.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]. ### Arguments A function can have multiple arguments. Some arguments are positional, i.e., you @@ -177,10 +177,10 @@ 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]($content) to a function. For example, -the LaTeX command `\underline{Alternative A}` would translate to +Often, you want to provide some [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]($content). Within these brackets, you can use normal markup. +value is [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). @@ -283,11 +283,11 @@ You can achieve the effects of LaTeX commands like `\textbf`, `\textsf`, `\rmfamily`, `\mdseries`, and `\itshape` with the [`font`]($text.font), [`style`]($text.style), and [`weight`]($text.weight) arguments of the `text` function. The text function can be used in a set rule (declaration style) or -with a content argument. To replace `\textsc`, you can use the -[`smallcaps`]($smallcaps) function, which renders its content argument as -smallcaps. Should you want to use it declaration style (like `\scshape`), you -can use an [_everything_ show rule]($styling/#show-rules) that applies the -function to the rest of the scope: +with a content argument. To replace `\textsc`, you can use the [`smallcaps`] +function, which renders its content argument as smallcaps. Should you want to +use it declaration style (like `\scshape`), you can use an +[_everything_ show rule]($styling/#show-rules) that applies the function to the +rest of the scope: ```example #show: smallcaps @@ -433,23 +433,23 @@ 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`]($image) function | -| tabularx | [`table`]($table), [`grid`]($grid) functions | -| fontenc, inputenc, unicode-math | Just start writing! | -| babel, polyglossia | [`text`]($text.lang) function: `[#set text(lang: "zh")]` | -| amsmath | [Math mode]($category/math) | +| LaTeX Package | Typst Alternative | +|:--------------------------------|:-------------------------------------------| +| graphicx, svg | [`image`] function | +| tabularx | [`table`], [`grid`] functions | +| fontenc, inputenc, unicode-math | Just start writing! | +| babel, polyglossia | [`text`]($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`]($page) function | +| geometry, fancyhdr | [`page`] function | | xcolor | [`text`]($text.fill) function: `[#set text(fill: rgb("#0178A4"))]` | -| hyperref | [`link`]($link) function | -| bibtex, biblatex, natbib | [`cite`]($cite), [`bibliography`]($bibliography) functions | -| lstlisting, minted | [`raw`]($raw) function and syntax | +| hyperref | [`link`] function | +| bibtex, biblatex, natbib | [`cite`], [`bibliography`] functions | +| lstlisting, minted | [`raw`] function and syntax | | parskip | [`block`]($block.spacing) and [`par`]($par.first-line-indent) functions | | csquotes | Set the [`text`]($text.lang) language and type `["]` or `[']` | -| caption | [`figure`]($figure) function | -| enumitem | [`list`]($list), [`enum`]($enum), [`terms`]($terms) functions | +| caption | [`figure`] function | +| enumitem | [`list`], [`enum`], [`terms`] functions | Although _many_ things are built-in, not everything can be. That's why Typst has a built-in [package manager]($packages) where the community can share their @@ -606,8 +606,7 @@ a reusable template? ## Bibliographies Typst includes a fully-featured bibliography system that is compatible with BibTeX files. You can continue to use your `.bib` literature libraries by -loading them with the [`bibliography`]($bibliography) function. Another -possibility is to use +loading them with the [`bibliography`] function. Another possibility is to use [Typst's YAML-based native format](https://github.com/typst/hayagriva/blob/main/docs/file-format.md). Typst uses the Citation Style Language to define and process citation and @@ -619,13 +618,14 @@ your own. You can cite an entry in your bibliography or reference a label in your document with the same syntax: `[@key]` (this would reference an entry called `key`). -Alternatively, you can use the [`cite`]($cite) function. +Alternatively, you can use the [`cite`] function. Alternative forms for your citation, such as year only and citations for natural use in prose (cf. `\citet` and `\textcite`) are available with [`[#cite(<key>, form: "prose")]`]($cite.form). -You can find more information on the documentation page of the [`bibliography`]($bibliography) function. +You can find more information on the documentation page of the [`bibliography`] +function. ## Installation You have two ways to use Typst: In [our web app](https://typst.app/signup/) or diff --git a/docs/guides/page-setup.md b/docs/guides/page-setup.md index a70f025f..14c35e1b 100644 --- a/docs/guides/page-setup.md +++ b/docs/guides/page-setup.md @@ -185,14 +185,13 @@ conditionally remove the header on the first page: #lorem(150) ``` -This example may look intimidating, but let's break it down: We are telling -Typst that the header depends on the current [location]($locate). The `loc` -value allows other functions to find out where on the page we currently are. We -then ask Typst if the page [counter]($counter) is larger than one at our current -position. The page counter starts at one, so we are skipping the header on a -single page. Counters may have multiple levels. This feature is used for items -like headings, but the page counter will always have a single level, so we can -just look at the first one. +This example may look intimidating, but let's break it down: By using the +`{context}` keyword, we are telling Typst that the header depends on where we +are in the document. We then ask Typst if the page [counter] is larger than one +at our (context-dependant) current position. The page counter starts at one, so +we are skipping the header on a single page. Counters may have multiple levels. +This feature is used for items like headings, but the page counter will always +have a single level, so we can just look at the first one. You can, of course, add an `else` to this example to add a different header to the first page instead. @@ -201,8 +200,8 @@ the first page instead. The technique described in the previous section can be adapted to perform more advanced tasks using Typst's labels. For example, pages with big tables could omit their headers to help keep clutter down. We will mark our tables with a -`<big-table>` [label]($label) and use the [query system]($query) to find out if -such a label exists on the current page: +`<big-table>` [label] and use the [query system]($query) to find out if such a +label exists on the current page: ```typ >>> #set page("a5", margin: (x: 2.5cm, y: 3cm)) @@ -334,10 +333,9 @@ This page has a custom footer. ``` In this example, we use the number of pages to create an array of -[circles]($circle). The circles are wrapped in a [box]($box) so they can all -appear on the same line because they are blocks and would otherwise create -paragraph breaks. The length of this [array]($array) depends on the current page -number. +[circles]($circle). The circles are wrapped in a [box] so they can all appear on +the same line because they are blocks and would otherwise create paragraph +breaks. The length of this [array] depends on the current page number. We then insert the circles at the right side of the footer, with 1pt of space between them. The join method of an array will attempt to @@ -354,8 +352,8 @@ want to start with the first page only after the title page. Or maybe you need to skip a few page numbers because you will insert pages into the final printed product. -The right way to modify the page number is to manipulate the page -[counter]($counter). The simplest manipulation is to set the counter back to 1. +The right way to modify the page number is to manipulate the page [counter]. The +simplest manipulation is to set the counter back to 1. ```typ #counter(page).update(1) @@ -373,8 +371,8 @@ In this example, we skip five pages. `n` is the current value of the page counter and `n + 5` is the return value of our function. In case you need to retrieve the actual page number instead of the value of the -page counter, you can use the [`page`]($locate) method on the argument of the -`{locate}` closure: +page counter, you can use the [`page`]($location.page) method on the return +value of the [`here`] function: ```example #counter(page).update(n => n + 5) @@ -384,8 +382,8 @@ page counter, you can use the [`page`]($locate) method on the argument of the #context here().page() ``` -You can also obtain the page numbering pattern from the `{locate}` closure -parameter with the [`page-numbering`]($locate) method. +You can also obtain the page numbering pattern from the location returned by +`here` with the [`page-numbering`]($location.page-numbering) method. ## Add columns { #columns } Add columns to your document to fit more on a page while maintaining legible diff --git a/docs/reference/context.md b/docs/reference/context.md index 5ebcfbe7..8c6ee9de 100644 --- a/docs/reference/context.md +++ b/docs/reference/context.md @@ -53,11 +53,10 @@ properly reacts to the current surroundings. #value ``` -Crucially, upon creation, `value` becomes opaque [content]($content) that we -cannot peek into. It can only be resolved when placed somewhere because only -then the context is known. The body of a context expression may be evaluated -zero, one, or multiple times, depending on how many different places it is put -into. +Crucially, upon creation, `value` becomes opaque [content] that we cannot peek +into. It can only be resolved when placed somewhere because only then the +context is known. The body of a context expression may be evaluated zero, one, +or multiple times, depending on how many different places it is put into. ## Location context Context can not only give us access to set rule values. It can also let us know @@ -89,20 +88,19 @@ resolved numbers. Thus, we get the following result: #context counter(heading).get() ``` -For more flexibility, we can also use the [`here`]($here) function to directly -extract the current [location]($location) from the context. The example below +For more flexibility, we can also use the [`here`] function to directly extract +the current [location] from the context. The example below demonstrates this: - We first have `{counter(heading).get()}`, which resolves to `{(2,)}` as before. -- We then use the more powerful [`counter.at`]($counter.at) with - [`here`]($here), which in combination is equivalent to `get`, and thus get - `{(2,)}`. -- Finally, we use `at` with a [label]($label) to retrieve the value of the - counter at a _different_ location in the document, in our case that of the - introduction heading. This yields `{(1,)}`. Typst's context system gives us - time travel abilities and lets us retrieve the values of any counters and - states at _any_ location in the document. +- We then use the more powerful [`counter.at`] with [`here`], which in + combination is equivalent to `get`, and thus get `{(2,)}`. +- Finally, we use `at` with a [label] to retrieve the value of the counter at a + _different_ location in the document, in our case that of the introduction + heading. This yields `{(1,)}`. Typst's context system gives us time travel + abilities and lets us retrieve the values of any counters and states at _any_ + location in the document. ```example #set heading(numbering: "1.") @@ -121,10 +119,10 @@ demonstrates this: ``` As mentioned before, we can also use context to get the physical position of -elements on the pages. We do this with the [`locate`]($locate) function, which -works similarly to `counter.at`: It takes a location or other -[selector]($selector) that resolves to a unique element (could also be a label) -and returns the position on the pages for that element. +elements on the pages. We do this with the [`locate`] function, which works +similarly to `counter.at`: It takes a location or other [selector] that resolves +to a unique element (could also be a label) and returns the position on the +pages for that element. ```example Background is at: \ @@ -139,7 +137,7 @@ Background is at: \ ``` There are other functions that make use of the location context, most -prominently [`query`]($query). Take a look at the +prominently [`query`]. Take a look at the [introspection]($category/introspection) category for more details on those. ## Nested contexts diff --git a/docs/reference/groups.yml b/docs/reference/groups.yml index 16ded697..0cbf656a 100644 --- a/docs/reference/groups.yml +++ b/docs/reference/groups.yml @@ -9,8 +9,8 @@ details: | Alternate typefaces within formulas. - These functions are distinct from the [`text`]($text) function because math - fonts contain multiple variants of each letter. + These functions are distinct from the [`text`] function because math fonts + contain multiple variants of each letter. - name: styles title: Styles @@ -20,8 +20,8 @@ details: | Alternate letterforms within formulas. - These functions are distinct from the [`text`]($text) function because math - fonts contain multiple variants of each letter. + These functions are distinct from the [`text`] function because math fonts + contain multiple variants of each letter. - name: sizes title: Sizes @@ -131,10 +131,10 @@ This module defines the following items: - - The `sys.version` constant (of type [`version`]($version)) that specifies + - The `sys.version` constant (of type [`version`]) that specifies the currently active Typst compiler version. - - The `sys.inputs` [dictionary]($dictionary), which makes external inputs + - The `sys.inputs` [dictionary], which makes external inputs available to the project. An input specified in the command line as `--input key=value` becomes available under `sys.inputs.key` as `{"value"}`. To include spaces in the value, it may be enclosed with diff --git a/docs/reference/scripting.md b/docs/reference/scripting.md index b66b9896..8cfb9698 100644 --- a/docs/reference/scripting.md +++ b/docs/reference/scripting.md @@ -46,9 +46,9 @@ _blocks:_ With content blocks, you can handle markup/content as a programmatic value, store it in variables and pass it to [functions]($function). Content blocks are delimited by square brackets and can contain arbitrary markup. A - content block results in a value of type [content]($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 block results in a value of 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 @@ -189,14 +189,14 @@ together into one larger array. For loops can iterate over a variety of collections: - `{for value in array {..}}` \ - Iterates over the items in the [array]($array). The destructuring syntax - described in [Let binding]($scripting/#bindings) can also be used here. + Iterates over the items in the [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]($dictionary). - The pairs can also be destructured by using `{for (key, value) in dict {..}}`. - It is more efficient than `{for pair in dict.pairs() {..}}` because it doesn't - create a temporary array of all key-value pairs. + Iterates over the key-value pairs of the [dictionary]. The pairs can also be + destructured by using `{for (key, value) in dict {..}}`. It is more efficient + than `{for pair in dict.pairs() {..}}` because it doesn't create a temporary + array of all key-value pairs. - `{for letter in "abc" {..}}` \ Iterates over the characters of the [string]($str). Technically, it iterates @@ -205,9 +205,9 @@ For loops can iterate over a variety of collections: codepoints, like a flag emoji. - `{for byte in bytes("😀") {..}}` \ - Iterates over the [bytes]($bytes), which can be converted from a [string]($str) - or [read]($read) from a file without encoding. Each byte value is an - [integer]($int) between `{0}` and `{255}`. + Iterates over the [bytes], which can be converted from a [string]($str) or + [read] from a file without encoding. Each byte value is an [integer]($int) + between `{0}` and `{255}`. To control the execution of the loop, Typst provides the `{break}` and `{continue}` statements. The former performs an early exit from the loop while @@ -233,10 +233,10 @@ The body of a loop can be a code or content block: ## Fields You can use _dot notation_ to access fields on a value. The value in question can be either: -- a [dictionary]($dictionary) that has the specified key, -- a [symbol]($symbol) that has the specified modifier, -- a [module]($module) containing the specified definition, -- [content]($content) consisting of an element that has the specified field. The +- a [dictionary] that has the specified key, +- a [symbol] that has the specified modifier, +- a [module] containing the specified definition, +- [content] consisting of an element that has the specified field. The available fields match the arguments of the [element function]($function/#element-functions) that were given when the element was constructed. @@ -253,8 +253,8 @@ can be either: ## Methods A _method call_ is a convenient way to call a function that is scoped to a -value's [type]($type). For example, we can call the [`str.len`]($str.len) -function in the following two equivalent ways: +value's [type]. For example, we can call the [`str.len`]($str.len) function in +the following two equivalent ways: ```example #str.len("abc") is the same as @@ -291,14 +291,12 @@ 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]($content). + Evaluates the file at the path `bar.typ` and returns the resulting [content]. - **Import:** `{import "bar.typ"}` \ - Evaluates the file at the path `bar.typ` and inserts the resulting - [module]($module) into the current scope as `bar` (filename without - extension). You can use the `as` keyword to rename the imported module: - `{import "bar.typ" as baz}` + Evaluates the file at the path `bar.typ` and inserts the resulting [module] + into the current scope as `bar` (filename without extension). You can use the + `as` keyword to rename the imported module: `{import "bar.typ" as baz}` - **Import items:** `{import "bar.typ": a, b}` \ Evaluates the file at the path `bar.typ`, extracts the values of the variables @@ -327,8 +325,7 @@ and a version. ``` The `preview` namespace contains packages shared by the community. You can find -a searchable list of available community packages in the [packages]($packages) -section. +a searchable list of available community packages in the [packages] section. If you are using Typst locally, you can also create your own system-local packages. For more details on this, see the diff --git a/docs/reference/styling.md b/docs/reference/styling.md index 1c3fd173..b0b7ab71 100644 --- a/docs/reference/styling.md +++ b/docs/reference/styling.md @@ -62,11 +62,10 @@ a _set-if_ rule. ## 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]($selector), a colon and then a set -rule. The most basic form of selector is an -[element function]($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. +`{show}` keyword followed by a [selector], a colon and then a set rule. The most +basic form of selector is an [element function]($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) @@ -79,11 +78,11 @@ 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 after the colon with an arbitrary [function]($function). -This function receives the element in question and can return arbitrary content. -The available [fields]($scripting/#fields) on the element passed to the function -again match the parameters of the respective element function. Below, we define -a show rule that formats headings for a fantasy encyclopedia. +replace the set rule after the colon with an arbitrary [function]. This function +receives the element in question and can return arbitrary content. The available +[fields]($scripting/#fields) on the element passed to the function again match +the parameters of the respective element function. Below, we define a show rule +that formats headings for a fantasy encyclopedia. ```example #set heading(numbering: "(I)") diff --git a/docs/reference/syntax.md b/docs/reference/syntax.md index 40213fe9..2cdccc59 100644 --- a/docs/reference/syntax.md +++ b/docs/reference/syntax.md @@ -36,20 +36,20 @@ more about their syntax and usage. | Name | Example | See | | ------------------ | ------------------------ | ---------------------------- | -| Paragraph break | Blank line | [`parbreak`]($parbreak) | -| Strong emphasis | `[*strong*]` | [`strong`]($strong) | -| Emphasis | `[_emphasis_]` | [`emph`]($emph) | -| Raw text | ``[`print(1)`]`` | [`raw`]($raw) | -| Link | `[https://typst.app/]` | [`link`]($link) | -| Label | `[<intro>]` | [`label`]($label) | -| Reference | `[@intro]` | [`ref`]($ref) | -| Heading | `[= Heading]` | [`heading`]($heading) | -| Bullet list | `[- item]` | [`list`]($list) | -| Numbered list | `[+ item]` | [`enum`]($enum) | -| Term list | `[/ Term: description]` | [`terms`]($terms) | +| Paragraph break | Blank line | [`parbreak`] | +| Strong emphasis | `[*strong*]` | [`strong`] | +| Emphasis | `[_emphasis_]` | [`emph`] | +| Raw text | ``[`print(1)`]`` | [`raw`] | +| Link | `[https://typst.app/]` | [`link`] | +| Label | `[<intro>]` | [`label`] | +| Reference | `[@intro]` | [`ref`] | +| Heading | `[= Heading]` | [`heading`] | +| Bullet list | `[- item]` | [`list`] | +| Numbered list | `[+ item]` | [`enum`] | +| Term list | `[/ Term: description]` | [`terms`] | | Math | `[$x^2$]` | [Math]($category/math) | -| Line break | `[\]` | [`linebreak`]($linebreak) | -| Smart quote | `['single' or "double"]` | [`smartquote`]($smartquote) | +| Line break | `[\]` | [`linebreak`] | +| Smart quote | `['single' or "double"]` | [`smartquote`] | | Symbol shorthand | `[~, ---]` | [Symbols]($category/symbols/sym) | | Code expression | `[#rect(width: 1cm)]` | [Scripting]($scripting/#expressions) | | Character escape | `[Tweet at us \#ad]` | [Below](#escapes) | @@ -70,7 +70,7 @@ follows: | Bottom attachment | `[$x_1$]` | [`attach`]($category/math/attach) | | Top attachment | `[$x^2$]` | [`attach`]($category/math/attach) | | Fraction | `[$1 + (a+b)/5$]` | [`frac`]($math.frac) | -| Line break | `[$x \ y$]` | [`linebreak`]($linebreak) | +| Line break | `[$x \ y$]` | [`linebreak`] | | Alignment point | `[$x &= 2 \ &= 3$]` | [Math]($category/math) | | Variable access | `[$#x$, $pi$]` | [Math]($category/math) | | Field access | `[$arrow.r.long$]` | [Scripting]($scripting/#fields) | diff --git a/docs/reference/welcome.md b/docs/reference/welcome.md index d312ba07..1154cc52 100644 --- a/docs/reference/welcome.md +++ b/docs/reference/welcome.md @@ -5,10 +5,10 @@ description: | --- # Reference -This reference documentation is a comprehensive guide to all of Typst's -syntax, concepts, types, and functions. If you are completely new to Typst, we -recommend starting with the [tutorial]($tutorial) and then coming back to -the reference to learn more about Typst's features as you need them. +This reference documentation is a comprehensive guide to all of Typst's syntax, +concepts, types, and functions. If you are completely new to Typst, we recommend +starting with the [tutorial] and then coming back to the reference to learn more +about Typst's features as you need them. ## Language The reference starts with a language part that gives an overview over diff --git a/docs/roadmap.md b/docs/roadmap.md index 9621d664..dc5491b5 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -12,7 +12,7 @@ this roadmap will only list larger, more fundamental ones. Are you missing something on the roadmap? Typst relies on your feedback as a user to plan for and prioritize new features. Get started by filing a new issue on [GitHub](https://github.com/typst/typst/issues) or discuss your feature -request with the [community]($community). +request with the [community]. ## Language and Compiler - **Structure and Styling** diff --git a/docs/src/html.rs b/docs/src/html.rs index 912ad367..bb6204a3 100644 --- a/docs/src/html.rs +++ b/docs/src/html.rs @@ -59,9 +59,27 @@ impl Html { | md::Options::ENABLE_STRIKETHROUGH | md::Options::ENABLE_HEADING_ATTRIBUTES; + // Convert `[foo]` to `[foo]($foo)`. + let mut link = |broken: md::BrokenLink| { + assert_eq!( + broken.link_type, + md::LinkType::Shortcut, + "unsupported link type: {:?}", + broken.link_type, + ); + + Some(( + format!("${}", broken.reference.trim_matches('`')).into(), + broken.reference.into_string().into(), + )) + }; + let ids = Arena::new(); let mut handler = Handler::new(text, resolver, nesting, &ids); - let mut events = md::Parser::new_ext(text, options).peekable(); + let mut events = + md::Parser::new_with_broken_link_callback(text, options, Some(&mut link)) + .peekable(); + let iter = std::iter::from_fn(|| loop { let mut event = events.next()?; handler.peeked = events.peek().and_then(|event| match event { @@ -199,7 +217,13 @@ impl<'a> Handler<'a> { // Rewrite links. md::Event::Start(md::Tag::Link(ty, dest, _)) => { assert!( - matches!(ty, md::LinkType::Inline | md::LinkType::Reference), + matches!( + ty, + md::LinkType::Inline + | md::LinkType::Reference + | md::LinkType::ShortcutUnknown + | md::LinkType::Autolink + ), "unsupported link type: {ty:?}", ); diff --git a/docs/src/lib.rs b/docs/src/lib.rs index 9ec5b087..3856b1be 100644 --- a/docs/src/lib.rs +++ b/docs/src/lib.rs @@ -92,7 +92,8 @@ pub fn provide(resolver: &dyn Resolver) -> Vec<PageModel> { /// Resolve consumer dependencies. pub trait Resolver { - /// Try to resolve a link that the system cannot resolve itself. + /// Try to resolve a link. If this returns `None`, the system will try to + /// resolve the link itself. fn link(&self, link: &str) -> Option<String>; /// Produce an URL for an image file. diff --git a/docs/tutorial/1-writing.md b/docs/tutorial/1-writing.md index de2af62f..5a9fdd4f 100644 --- a/docs/tutorial/1-writing.md +++ b/docs/tutorial/1-writing.md @@ -85,7 +85,7 @@ and emphasized text, respectively. However, having a special symbol for everything we want to insert into our document would soon become cryptic and unwieldy. For this reason, Typst reserves markup symbols only for the most common things. Everything else is inserted with _functions._ For our image to -show up on the page, we use Typst's [`image`]($image) function. +show up on the page, we use Typst's [`image`] function. ```example #image("glacier.jpg") @@ -116,9 +116,9 @@ page's width. We also could have specified an absolute value like `{1cm}` or `{0.7in}`. Just like text, the image is now aligned at the left side of the page by -default. It's also lacking a caption. Let's fix that by using the -[figure]($figure) function. This function takes the figure's contents as a -positional argument and an optional caption as a named argument. +default. It's also lacking a caption. Let's fix that by using the [figure] +function. This function takes the figure's contents as a positional argument and +an optional caption as a named argument. Within the argument list of the `figure` function, Typst is already in code mode. This means, you now have to remove the hash before the image function call. @@ -178,8 +178,8 @@ valid kind of content. ## Adding a bibliography { #bibliography } As you write up your report, you need to back up some of your claims. You can -add a bibliography to your document with the [`bibliography`]($bibliography) -function. This function expects a path to a bibliography file. +add a bibliography to your document with the [`bibliography`] function. This +function expects a path to a bibliography file. Typst's native bibliography format is [Hayagriva](https://github.com/typst/hayagriva/blob/main/docs/file-format.md), @@ -300,8 +300,7 @@ emphasize text, write lists, insert images, align content, and typeset mathematical expressions. You also learned about Typst's functions. There are many more kinds of content that Typst lets you insert into your document, such as [tables]($table), [shapes]($category/visualize), and [code blocks]($raw). You -can peruse the [reference]($reference) to learn more about these and other -features. +can peruse the [reference] to learn more about these and other features. For the moment, you have completed writing your report. You have already saved a PDF by clicking on the download button in the top right corner. However, you diff --git a/docs/tutorial/2-formatting.md b/docs/tutorial/2-formatting.md index 58095f94..e51f96e7 100644 --- a/docs/tutorial/2-formatting.md +++ b/docs/tutorial/2-formatting.md @@ -11,11 +11,10 @@ your report using Typst's styling system. ## Set rules As we have seen in the previous chapter, Typst has functions that _insert_ -content (e.g. the [`image`]($image) function) and others that _manipulate_ -content that they received as arguments (e.g. the [`align`]($align) function). -The first impulse you might have when you want, for example, to justify the -report, could be to look for a function that does that and wrap the complete -document in it. +content (e.g. the [`image`] function) and others that _manipulate_ content that +they received as arguments (e.g. the [`align`] function). The first impulse you +might have when you want, for example, to justify the report, could be to look +for a function that does that and wrap the complete document in it. ```example #par(justify: true)[ @@ -38,9 +37,9 @@ do in Typst, there is special syntax for it: Instead of putting the content inside of the argument list, you can write it in square brackets directly after the normal arguments, saving on punctuation. -As seen above, that works. The [`par`]($par) function justifies all paragraphs -within it. However, wrapping the document in countless functions and applying -styles selectively and in-situ can quickly become cumbersome. +As seen above, that works. The [`par`] function justifies all paragraphs within +it. However, wrapping the document in countless functions and applying styles +selectively and in-situ can quickly become cumbersome. Fortunately, Typst has a more elegant solution. With _set rules,_ you can apply style properties to all occurrences of some kind of content. You write a set @@ -89,13 +88,12 @@ Back to set rules: When writing a rule, you choose the function depending on what type of element you want to style. Here is a list of some functions that are commonly used in set rules: -- [`text`]($text) to set font family, size, color, and other properties of text -- [`page`]($page) to set the page size, margins, headers, enable columns, and - footers -- [`par`]($par) to justify paragraphs, set line spacing, and more -- [`heading`]($heading) to set the appearance of headings and enable numbering -- [`document`]($document) to set the metadata contained in the PDF output, such - as title and author +- [`text`] to set font family, size, color, and other properties of text +- [`page`] to set the page size, margins, headers, enable columns, and footers +- [`par`] to justify paragraphs, set line spacing, and more +- [`heading`] to set the appearance of headings and enable numbering +- [`document`] to set the metadata contained in the PDF output, such as title + and author Not all function parameters can be set. In general, only parameters that tell a function _how_ to do something can be set, not those that tell it _what_ to @@ -149,24 +147,24 @@ behaviour of these natural structures. There are a few things of note here. -First is the [`page`]($page) set rule. It receives two arguments: the page size -and margins for the page. The page size is a string. Typst accepts -[many standard page sizes,]($page.paper) but you can also specify a custom page -size. The margins are specified as a [dictionary.]($dictionary) Dictionaries are -a collection of key-value pairs. In this case, the keys are `x` and `y`, and the +First is the [`page`] set rule. It receives two arguments: the page size and +margins for the page. The page size is a string. Typst accepts [many standard +page sizes,]($page.paper) but you can also specify a custom page size. The +margins are specified as a [dictionary.]($dictionary) Dictionaries are a +collection of key-value pairs. In this case, the keys are `x` and `y`, and the values are the horizontal and vertical margins, respectively. We could also have specified separate margins for each side by passing a dictionary with the keys `{left}`, `{right}`, `{top}`, and `{bottom}`. -Next is the set [`text`]($text) set rule. Here, we set the font size to `{10pt}` -and font family to `{"New Computer Modern"}`. The Typst app comes with many -fonts that you can try for your document. When you are in the text function's -argument list, you can discover the available fonts in the autocomplete panel. +Next is the set [`text`] set rule. Here, we set the font size to `{10pt}` and +font family to `{"New Computer Modern"}`. The Typst app comes with many fonts +that you can try for your document. When you are in the text function's argument +list, you can discover the available fonts in the autocomplete panel. We have also set the spacing between lines (a.k.a. leading): It is specified as -a [length]($length) value, and we used the `em` unit to specify the leading -relative to the size of the font: `{1em}` is equivalent to the current font size -(which defaults to `{11pt}`). +a [length] value, and we used the `em` unit to specify the leading relative to +the size of the font: `{1em}` is equivalent to the current font size (which +defaults to `{11pt}`). Finally, we have bottom aligned our image by adding a vertical alignment to our center alignment. Vertical and horizontal alignments can be combined with the @@ -174,8 +172,7 @@ center alignment. Vertical and horizontal alignments can be combined with the ## A hint of sophistication { #sophistication } To structure our document more clearly, we now want to number our headings. We -can do this by setting the `numbering` parameter of the [`heading`]($heading) -function. +can do this by setting the `numbering` parameter of the [`heading`] function. ```example >>> #set text(font: "New Computer Modern") @@ -210,9 +207,9 @@ for our headings: #lorem(15) ``` -This example also uses the [`lorem`]($lorem) function to generate some -placeholder text. This function takes a number as an argument and generates that -many words of _Lorem Ipsum_ text. +This example also uses the [`lorem`] function to generate some placeholder text. +This function takes a number as an argument and generates that many words of +_Lorem Ipsum_ text. <div class="info-box"> diff --git a/docs/tutorial/3-advanced.md b/docs/tutorial/3-advanced.md index 2393a474..57b3dc0d 100644 --- a/docs/tutorial/3-advanced.md +++ b/docs/tutorial/3-advanced.md @@ -125,17 +125,17 @@ supervisor, we'll add our own and their name. ) ``` -The two author blocks are laid out next to each other. We use the -[`grid`]($grid) function to create this layout. With a grid, we can control -exactly how large each column is and which content goes into which cell. The -`columns` argument takes an array of [relative lengths]($relative) or -[fractions]($fraction). In this case, we passed it two equal fractional sizes, -telling it to split the available space into two equal columns. We then passed -two content arguments to the grid function. The first with our own details, and -the second with our supervisors'. We again use the `align` function to center -the content within the column. The grid takes an arbitrary number of content -arguments specifying the cells. Rows are added automatically, but they can also -be manually sized with the `rows` argument. +The two author blocks are laid out next to each other. We use the [`grid`] +function to create this layout. With a grid, we can control exactly how large +each column is and which content goes into which cell. The `columns` argument +takes an array of [relative lengths]($relative) or [fractions]($fraction). In +this case, we passed it two equal fractional sizes, telling it to split the +available space into two equal columns. We then passed two content arguments to +the grid function. The first with our own details, and the second with our +supervisors'. We again use the `align` function to center the content within the +column. The grid takes an arbitrary number of content arguments specifying the +cells. Rows are added automatically, but they can also be manually sized with +the `rows` argument. Now, let's add the abstract. Remember that the conference wants the abstract to be set ragged and centered. @@ -248,11 +248,10 @@ on another title, we can easily change it in one place. ## Adding columns and headings { #columns-and-headings } The paper above unfortunately looks like a wall of lead. To fix that, let's add -some headings and switch our paper to a two-column layout. The -[`columns`]($columns) function takes a number and content, and layouts the -content into the specified number of columns. Since we want everything after the -abstract to be in two columns, we need to apply the column function to our whole -document. +some headings and switch our paper to a two-column layout. The [`columns`] +function takes a number and content, and layouts the content into the specified +number of columns. Since we want everything after the abstract to be in two +columns, we need to apply the column function to our whole document. Instead of wrapping the whole document in a giant function call, we can use an "everything" show rule. To write such a show rule, put a colon directly behind @@ -386,8 +385,7 @@ function that gets passed the heading as a parameter. That parameter can be used as content but it also has some fields like `title`, `numbers`, and `level` from which we can compose a custom look. Here, we are center-aligning, setting the font weight to `{"regular"}` because headings are bold by default, and use the -[`smallcaps`]($smallcaps) function to render the heading's title in small -capitals. +[`smallcaps`] function to render the heading's title in small capitals. The only remaining problem is that all headings look the same now. The "Motivation" and "Problem Statement" subsections ought to be italic run in @@ -479,7 +477,8 @@ Let's review the conference's style guide: - The paper contains a single-column abstract and two-column main text ✓ - The abstract should be centered ✓ - The main text should be justified ✓ -- First level section headings should be centered, rendered in small caps and in 13pt ✓ +- First level section headings should be centered, rendered in small caps and in + 13pt ✓ - Second level headings are run-ins, italicized and have the same size as the body text ✓ - Finally, the pages should be US letter sized, numbered in the center and the @@ -496,7 +495,9 @@ the conference! The finished paper looks like this: ## Review You have now learned how to create headers and footers, how to use functions and -scopes to locally override styles, how to create more complex layouts with the [`grid`]($grid) function and how to write show rules for individual functions, and the whole document. You also learned how to use the +scopes to locally override styles, how to create more complex layouts with the +[`grid`] function and how to write show rules for individual functions, and the +whole document. You also learned how to use the [`where` selector]($styling/#show-rules) to filter the headings by their level. The paper was a great success! You've met a lot of like-minded researchers at diff --git a/docs/tutorial/4-template.md b/docs/tutorial/4-template.md index 3b745db5..a96e7c0a 100644 --- a/docs/tutorial/4-template.md +++ b/docs/tutorial/4-template.md @@ -195,17 +195,17 @@ Next, we copy the code that generates title, abstract and authors from the previous chapter into the template, replacing the fixed details with the parameters. -The new `authors` parameter expects an [array]($array) of -[dictionaries]($dictionary) with the keys `name`, `affiliation` and `email`. -Because we can have an arbitrary number of authors, we dynamically determine if -we need one, two or three columns for the author list. First, we determine the -number of authors using the [`.len()`]($array.len) method on the `authors` -array. Then, we set the number of columns as the minimum of this count and -three, so that we never create more than three columns. If there are more than -three authors, a new row will be inserted instead. For this purpose, we have -also added a `row-gutter` parameter to the `grid` function. Otherwise, the rows -would be too close together. To extract the details about the authors from the -dictionary, we use the [field access syntax]($scripting/#fields). +The new `authors` parameter expects an [array] of [dictionaries]($dictionary) +with the keys `name`, `affiliation` and `email`. Because we can have an +arbitrary number of authors, we dynamically determine if we need one, two or +three columns for the author list. First, we determine the number of authors +using the [`.len()`]($array.len) method on the `authors` array. Then, we set the +number of columns as the minimum of this count and three, so that we never +create more than three columns. If there are more than three authors, a new row +will be inserted instead. For this purpose, we have also added a `row-gutter` +parameter to the `grid` function. Otherwise, the rows would be too close +together. To extract the details about the authors from the dictionary, we use +the [field access syntax]($scripting/#fields). We still have to provide an argument to the grid for each author: Here is where the array's [`map` method]($array.map) comes in handy. It takes a function as an |