From 240b917399148f8aa2f28ea37a03c1fd7e23832e Mon Sep 17 00:00:00 2001 From: Laurenz Date: Tue, 15 Oct 2024 14:54:16 +0200 Subject: Docs and changelog improvements (#5147) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Malo <57839069+MDLC01@users.noreply.github.com> Co-authored-by: Andrew Voynov <37143421+Andrew15-5@users.noreply.github.com> Co-authored-by: PgBiel <9021226+PgBiel@users.noreply.github.com> Co-authored-by: Jeremie Knuesel Co-authored-by: +merlan #flirora <2975203+bluebear94@users.noreply.github.com> Co-authored-by: Anselm Schüler --- docs/changelog.md | 75 +++++++++++++++++++++++++++------------------ docs/guides/tables.md | 2 +- docs/reference/groups.yml | 2 +- docs/reference/scripting.md | 3 +- docs/tutorial/4-template.md | 11 ++++--- 5 files changed, 55 insertions(+), 38 deletions(-) (limited to 'docs') diff --git a/docs/changelog.md b/docs/changelog.md index 2027f986..f88aacea 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -12,20 +12,20 @@ description: | [figures]($figure.scope) - Added support for automatic [line numbering]($par.line) (often used in academic papers) -- Typst's layout engine is now multi-threaded. Typical speedups are 2-3x for - larger documents. The multi-threading operates on page break boundaries, so +- Typst's layout engine is now multithreaded. Typical speedups are 2-3x for + larger documents. The multithreading operates on page break boundaries, so explicit page breaks are necessary for it to kick in. - Paragraph justification was optimized with a new two-pass algorithm. Speedups - are larger for shorter paragraphs and range from 1-6x. + are larger for shorter paragraphs and go up to 6x. - Highly reduced PDF file sizes due to better font subsetting (thanks to [@LaurenzV](https://github.com/LaurenzV)) - Emoji are now exported properly in PDF -- Added initial support for PDF/A. For now, only the standard PDF/A-2b is +- Added initial support for PDF/A. For now, only the PDF/A-2b profile is supported, but more is planned for the future. - Added various options for configuring the CLI's environment (fonts, package paths, etc.) - Text show rules now match across multiple text elements -- Block-level equations can now break over multiple pages +- Block-level equations can now optionally break over multiple pages - Fixed a bug where some fonts would not print correctly on professional printers - Fixed a long-standing bug which could cause headings to be orphaned at the @@ -42,6 +42,9 @@ description: | - Added [`par.spacing`] property for configuring paragraph spacing. This should now be used instead of `{show par: set block(spacing: ..)}` (**Breaking change**) + - Block-level elements like lists, grids, and stacks now show themselves as + blocks and are thus affected by all block properties (e.g. `stroke`) rather + than just `spacing` (**Breaking change**) - Added [`block.sticky`] property which prevents a page break after a block - Added [`place.flush`] function which forces all floating figures to be placed before any further content @@ -55,18 +58,20 @@ description: | combination with [`layout`]. - The height of a `block`, `image`, `rect`, `square`, `ellipse`, or `circle` can now be specified in [fractional units]($fraction) - - The [`scale`] function now supports non-relative lengths for `x` and `y`. + - The [`scale`] function now supports absolute lengths for `x`, `y`, `factor`. This way an element of unknown size can be scaled to a fixed size. - The values of `block.above` and `block.below` can now be retrieved in context expressions. + - Increased accuracy of conversions between absolute units (pt, mm, cm, in) - Fixed a bug which could cause headings to be orphaned at the bottom of the page - Fixed footnotes within breakable blocks appearing on the page where the breakable block ends instead of at the page where the footnote marker is + - Fixed numbering of nested footnotes and footnotes in floats - Fixed empty pages appearing when a [context] expression wraps whole pages - Fixed `{set block(spacing: x)}` behaving differently from `{set block(above: x, below: x)}` - - Fixed behaviour of [`rotate`] and [`scale`] with `{reflow: true}` + - Fixed behavior of [`rotate`] and [`scale`] with `{reflow: true}` - Fixed interaction of `{align(horizon)}` and `{v(1fr)}` - Fixed various bugs where floating placement would yield overlapping results - Fixed a bug where widow/orphan prevention would unnecessarily move text into @@ -113,8 +118,8 @@ description: | - Updated bundled New Computer Modern fonts to version 6.0 - Math - - Block-level equations can now break over multiple pages. This behaviour can - be disabled via `{show math.equation: set block(breakable: false)}`. + - Block-level equations can now break over multiple pages if enabled via + `{show math.equation: set block(breakable: true)}`. - Matrix and vector sizing is now more consistent across different cell contents - Added [`stretch`]($math.stretch) function for manually or automatically @@ -124,10 +129,11 @@ description: | - Improved layout of nested attachments resulting from code like `[#let a0 = $a_0$; $a0^1$]` - Improved layout of primes close to superscripts - - Typst now makes use of math-specific height-dependant kerning information in + - Improved layout of fractions + - Typst now makes use of math-specific height-dependent kerning information in some fonts for better attachment layout - - The `floor` and `ceil` functions in math are now callable symbols instead, - such that `[$ floor(x) = lr(floor.l x floor.r) $]` + - The `floor` and `ceil` functions in math are now callable symbols, such that + `[$ floor(x) = lr(floor.l x floor.r) $]` - The [`mat.delim`]($math.mat.delim), [`vec.delim`]($math.vec.delim), and [`cases.delim`]($math.cases.delim) parameters now allow any character that is considered a delimiter or "fence" (e.g. |) by Unicode. The @@ -136,8 +142,8 @@ description: | - Added [`vec.align`]($math.vec.align) and [`mat.align`]($math.mat.align) parameters - Added [`underparen`]($math.underparen), [`overparen`]($math.overparen), - [`undershell`]($math.undershell), and [`overshell`]($math.underparen) - - Added `~` shorthand for `tilde.op` (**Minor breaking change**) + [`undershell`]($math.undershell), and [`overshell`]($math.overshell) + - Added `~` shorthand for `tilde.op` in math mode (**Minor breaking change**) - Fixed baseline alignment of equation numbers - Fixed positioning of corner brackets (⌜, ⌝, ⌞, ⌟) - Fixed baseline of large roots @@ -148,21 +154,25 @@ description: | - Fixed a crash with recursive show rules in math - Fixed [`lr.size`]($math.lr.size) not affecting characters enclosed in [`mid`]($math.mid) in some cases + - Fixed resolving of em units in sub- and superscripts + - Fixed bounding box of inline equations when a [text edge]($text.top-edge) is + set to `{"bounds"}` - Introspection - Implemented a new system by which Typst tracks where elements end up on the - pages. This may lead to subtly different behaviour in introspections. + pages. This may lead to subtly different behavior in introspections. (**Breaking change**) - - Fixed various bugs with wrong counter behaviour in complex layout + - Fixed various bugs with wrong counter behavior in complex layout situations, through a new, more principled implementation - Counter updates can now be before the first, in between, and after the last page when isolated by weak page breaks. This allows, for instance, updating a counter before the first page header and background. + - Fixed logical ordering of introspections within footnotes and figures - Fixed incorrect [`here().position()`]($here) when [`place`] was used in a context expression - Fixed resolved positions of elements (in particular, headings) whose show rule emits an invisible element (like a state update) before a page break - - Fixed behaviour of stepping a counter at a deeper level that its current + - Fixed behavior of stepping a counter at a deeper level than its current state has - Fixed citation formatting not working in table headers and a few other places @@ -231,8 +241,8 @@ description: | - Fixed rare crash in parsing of parenthesized expressions - Scripting - - Added new fixed-point [`decimal`] number type for when highly precise - arithmetic is needed, such as for finance + - Added new fixed-point [`decimal`] number type for highly precise arithmetic + on numbers in base 10, as needed for finance - Added `std` module for accessing standard library definitions even when a variable with the same name shadows/overwrites it - Added [`array.to-dict`], [`array.reduce`], [`array.windows`] methods @@ -240,18 +250,20 @@ description: | - Added [`arguments.at`] method - Added [`int.from-bytes`], [`int.to-bytes`], [`float.from-bytes`], and [`float.to-bytes`] - - [`calc.round`] no longer accepts negative digits (**Minor breaking change**) + - Added proper support for negative values of the `digits` parameter of + [`calc.round`] (the behaviour existed before but was subtly broken) - Conversions from [`int`] to [`float`] will now error instead of saturating if the float is too large (**Minor breaking change**) - Added `float.nan` and `float.inf`, removed `calc.nan` (**Minor breaking change**) - Certain symbols are now generally callable like functions and not only - specifically in math. Examples are accents or `floor` and `ceil`. + specifically in math. Examples are accents or [`floor`]($math.floor) and + [`ceil`]($math.ceil). - Improved [`repr`] of relative values, sequences, infinities, NaN, `{type(none)}` and `{type(auto)}` - Fixed crash on whole packages (rather than just files) cyclically importing each other - - Fixed behaviour of [`calc.round`] on integers when a non-zero value is + - Fixed return type of [`calc.round`] on integers when a non-zero value is provided for `digits` - Styling @@ -280,11 +292,12 @@ description: | - Fixed a bug where transparency could leak from one PDF object to another - Fixed a bug with CMYK gradients in PDF - Fixed various bugs with export of Oklab gradients in PDF + - Fixed crashes related to rendering of non-outline glyphs - Two small fixes for PDF standard conformance - Performance - - Typst's layout engine is now multi-threaded. Typical speedups are 2-3x for - larger documents. The multi-threading operates on page break boundaries, so + - Typst's layout engine is now multithreaded. Typical speedups are 2-3x for + larger documents. The multithreading operates on page break boundaries, so explicit page breaks are necessary for it to kick in. - Paragraph justification was optimized with a new two-pass algorithm. Speedups are larger for shorter paragraphs and range from 1-6x. @@ -299,9 +312,11 @@ description: | - Added `--make-deps` argument for outputting the dependencies of the current compilation as a Makefile - Added `--pretty` option to `typst query`, with the default now being to - minify + minify (only applies to JSON format) - Added `--backup-path` to `typst update` to configure where the previous version is backed up + - Added useful links to help output + - The CLI will now greet users who invoke just `typst` for the first time - The document can now be written to stdout by passing `-` as the output filename (for PDF or single-page image export) - Typst will now emit a proper error message instead of failing silently when @@ -381,7 +396,7 @@ description: | - Added `typst-kit` crate which provides useful APIs for `World` implementors - Added go-to-definition API in `typst-ide` - Added package manifest parsing APIs to `typst-syntax` - - As the compiler is now capable of multi-threading, `World` implementations + - As the compiler is now capable of multithreading, `World` implementations must satisfy `Send` and `Sync` - Changed signature of `World::main` to allow for the scenario where the main file could not be loaded @@ -725,7 +740,7 @@ description: | - Fixed missing title in some bibliography styles - Fixed printing of volumes in some styles - Fixed delimiter order for contributors in some styles (e.g. APA) - - Fixed behaviour of alphanumeric style + - Fixed behavior of alphanumeric style - Fixed multiple bugs with GB/T 7714 style - Fixed escaping in Hayagriva values - Fixed crashes with empty dates in Hayagriva files @@ -915,7 +930,7 @@ description: | - Fixed line breaking of composite emoji like 🏳️‍🌈 - Fixed missing text in some SVGs - Fixed font fallback in SVGs - - Fixed behaviour of [`to`]($pagebreak.to) argument on `pagebreak` function + - Fixed behavior of [`to`]($pagebreak.to) argument on `pagebreak` function - Fixed `{set align(..)}` for equations - Fixed spacing around [placed]($place) elements - Fixed coalescing of [`above`]($block.above) and [`below`]($block.below) @@ -1513,7 +1528,7 @@ description: | - 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`]($calc.rem) to more accurately reflect the - behaviour. It will remain available as `mod` until the next update as a + behavior. 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 @@ -1635,7 +1650,7 @@ description: | `{"chicago-author-title"}` - Figure improvements - - Figures now automatically detect their content and adapt their behaviour. + - Figures now automatically detect their content and adapt their behavior. 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 diff --git a/docs/guides/tables.md b/docs/guides/tables.md index 39eb39f6..d5907367 100644 --- a/docs/guides/tables.md +++ b/docs/guides/tables.md @@ -527,7 +527,7 @@ is useful if you are writing a template or want to style your whole document. ``` For small tables, you sometimes want to suppress all strokes because they add -too much visual noise. To do this, just set the stroke argument to `none`: +too much visual noise. To do this, just set the stroke argument to `{none}`: ```example #table( diff --git a/docs/reference/groups.yml b/docs/reference/groups.yml index 3f2bef23..961d675d 100644 --- a/docs/reference/groups.yml +++ b/docs/reference/groups.yml @@ -128,7 +128,7 @@ These definitions 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`, `tau`, `e`, `inf`, and `nan`. + the constants `pi`, `tau`, `e`, and `inf`. - name: sys title: System diff --git a/docs/reference/scripting.md b/docs/reference/scripting.md index 44f5200c..590bb6ec 100644 --- a/docs/reference/scripting.md +++ b/docs/reference/scripting.md @@ -302,7 +302,8 @@ ways: - **Import:** `{import "bar.typ"}` \ 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}` + `as` keyword to rename the imported module: `{import "bar.typ" as baz}`. You + can import nested items using dot notation: `{import "bar.typ": baz.a}`. - **Import items:** `{import "bar.typ": a, b}` \ Evaluates the file at the path `bar.typ`, extracts the values of the variables diff --git a/docs/tutorial/4-template.md b/docs/tutorial/4-template.md index 0ec4a978..3416e6e4 100644 --- a/docs/tutorial/4-template.md +++ b/docs/tutorial/4-template.md @@ -361,7 +361,7 @@ want to import. ``` We have now converted the conference paper into a reusable template for that -conference! Why not share it on +conference! Why not share it in the [Forum](https://forum.typst.app/) or on [Typst's Discord server](https://discord.gg/2uDybryKPe) so that others can use it too? @@ -372,9 +372,10 @@ that define reusable document styles. You've made it far and learned a lot. You can now use Typst to write your own documents and share them with others. We are still a super young project and are looking for feedback. If you have any -questions, suggestions or you found a bug, please let us know on -[Typst's Discord server](https://discord.gg/2uDybryKPe), on our -[contact form](https://typst.app/contact), or on -[social media.](https://twitter.com/typstapp) +questions, suggestions or you found a bug, please let us know +in the [Forum](https://forum.typst.app/), +on our [Discord server](https://discord.gg/2uDybryKPe), +on [GitHub](https://github.com/typst/typst/), +or via the web app's feedback form (always available in the Help menu). So what are you waiting for? [Sign up](https://typst.app) and write something! -- cgit v1.2.3