diff options
29 files changed, 229 insertions, 117 deletions
@@ -129,7 +129,7 @@ Typst's CLI is available from different sources: `nix run github:typst/typst -- --version`. - Docker users can run a prebuilt image with - `docker run -it ghcr.io/typst/typst:latest`. + `docker run ghcr.io/typst/typst:latest --help`. ## Usage Once you have installed Typst, you can use it like this: diff --git a/crates/typst-cli/src/args.rs b/crates/typst-cli/src/args.rs index 7436d25c..a4ac4bd9 100644 --- a/crates/typst-cli/src/args.rs +++ b/crates/typst-cli/src/args.rs @@ -209,7 +209,9 @@ pub struct QueryCommand { #[clap(long = "format", default_value = "json")] pub format: SerializationFormat, - /// Whether to pretty-print the serialized output + /// Whether to pretty-print the serialized output. + /// + /// Only applies to JSON format. #[clap(long)] pub pretty: bool, } diff --git a/crates/typst/src/foundations/array.rs b/crates/typst/src/foundations/array.rs index 6631af21..77d8829d 100644 --- a/crates/typst/src/foundations/array.rs +++ b/crates/typst/src/foundations/array.rs @@ -486,7 +486,8 @@ impl Array { /// function is a bit involved, so we parse the positional arguments manually). args: &mut Args, /// Whether all arrays have to have the same length. - /// For example, `(1, 2).zip((1, 2, 3), exact: true)` produces an error. + /// For example, `{(1, 2).zip((1, 2, 3), exact: true)}` produces an + /// error. #[named] #[default(false)] exact: bool, diff --git a/crates/typst/src/foundations/calc.rs b/crates/typst/src/foundations/calc.rs index 5c818368..a4dbab88 100644 --- a/crates/typst/src/foundations/calc.rs +++ b/crates/typst/src/foundations/calc.rs @@ -92,7 +92,7 @@ cast! { /// Raises a value to some exponent. /// /// ```example -/// #calc.pow(2, 3) +/// #calc.pow(2, 3) \ /// #calc.pow(decimal("2.5"), 2) /// ``` #[func(title = "Power")] @@ -236,7 +236,6 @@ pub fn root( /// radians. /// /// ```example -/// #assert(calc.sin(90deg) == calc.sin(-270deg)) /// #calc.sin(1.5) \ /// #calc.sin(90deg) /// ``` @@ -258,7 +257,6 @@ pub fn sin( /// radians. /// /// ```example -/// #calc.cos(90deg) \ /// #calc.cos(1.5) \ /// #calc.cos(90deg) /// ``` @@ -621,10 +619,10 @@ pub fn lcm( /// 64-bit signed integer or smaller than the minimum for that type. /// /// ```example +/// #calc.floor(500.1) /// #assert(calc.floor(3) == 3) /// #assert(calc.floor(3.14) == 3) /// #assert(calc.floor(decimal("-3.14")) == -4) -/// #calc.floor(500.1) /// ``` #[func] pub fn floor( @@ -648,10 +646,10 @@ pub fn floor( /// 64-bit signed integer or smaller than the minimum for that type. /// /// ```example +/// #calc.ceil(500.1) /// #assert(calc.ceil(3) == 3) /// #assert(calc.ceil(3.14) == 4) /// #assert(calc.ceil(decimal("-3.14")) == -3) -/// #calc.ceil(500.1) /// ``` #[func] pub fn ceil( @@ -675,10 +673,10 @@ pub fn ceil( /// 64-bit signed integer or smaller than the minimum for that type. /// /// ```example +/// #calc.trunc(15.9) /// #assert(calc.trunc(3) == 3) /// #assert(calc.trunc(-3.7) == -3) /// #assert(calc.trunc(decimal("8493.12949582390")) == 8493) -/// #calc.trunc(15.9) /// ``` #[func(title = "Truncate")] pub fn trunc( @@ -698,9 +696,9 @@ pub fn trunc( /// If the number is an integer, returns `0`. /// /// ```example +/// #calc.fract(-3.1) /// #assert(calc.fract(3) == 0) /// #assert(calc.fract(decimal("234.23949211")) == decimal("0.23949211")) -/// #calc.fract(-3.1) /// ``` #[func(title = "Fractional")] pub fn fract( @@ -734,6 +732,7 @@ pub fn fract( /// for maximum and minimum respectively. /// /// ```example +/// #calc.round(3.1415, digits: 2) /// #assert(calc.round(3) == 3) /// #assert(calc.round(3.14) == 3) /// #assert(calc.round(3.5) == 4.0) @@ -745,7 +744,6 @@ pub fn fract( /// #assert(calc.round(decimal("7.123456789"), digits: 6) == decimal("7.123457")) /// #assert(calc.round(decimal("3333.45"), digits: -2) == decimal("3300")) /// #assert(calc.round(decimal("-48953.45"), digits: -3) == decimal("-49000")) -/// #calc.round(3.1415, digits: 2) /// ``` #[func] pub fn round( @@ -776,11 +774,11 @@ pub fn round( /// Clamps a number between a minimum and maximum value. /// /// ```example +/// #calc.clamp(5, 0, 4) /// #assert(calc.clamp(5, 0, 10) == 5) /// #assert(calc.clamp(5, 6, 10) == 6) /// #assert(calc.clamp(decimal("5.45"), 2, decimal("45.9")) == decimal("5.45")) /// #assert(calc.clamp(decimal("5.45"), decimal("6.75"), 12) == decimal("6.75")) -/// #calc.clamp(5, 0, 4) /// ``` #[func] pub fn clamp( @@ -991,7 +989,7 @@ pub fn div_euclid( /// #calc.rem-euclid(7, -3) \ /// #calc.rem-euclid(-7, 3) \ /// #calc.rem-euclid(-7, -3) \ -/// #calc.rem-euclid(1.75, 0.5) +/// #calc.rem-euclid(1.75, 0.5) \ /// #calc.rem-euclid(decimal("1.75"), decimal("0.5")) /// ``` #[func(title = "Euclidean Remainder")] diff --git a/crates/typst/src/foundations/decimal.rs b/crates/typst/src/foundations/decimal.rs index 6ba4c1a6..809b298a 100644 --- a/crates/typst/src/foundations/decimal.rs +++ b/crates/typst/src/foundations/decimal.rs @@ -34,9 +34,10 @@ use crate::World; /// constructing a decimal from a [floating-point number]($float), while /// supported, **is an imprecise conversion and therefore discouraged.** A /// warning will be raised if Typst detects that there was an accidental `float` -/// to `decimal` cast through its constructor (e.g. if writing `{decimal(3.14)}` -/// - note the lack of double quotes, indicating this is an accidental `float` -/// cast and therefore imprecise). +/// to `decimal` cast through its constructor, e.g. if writing `{decimal(3.14)}` +/// (note the lack of double quotes, indicating this is an accidental `float` +/// cast and therefore imprecise). It is recommended to use strings for +/// constant decimal values instead (e.g. `{decimal("3.14")}`). /// /// The precision of a `float` to `decimal` cast can be slightly improved by /// rounding the result to 15 digits with [`calc.round`]($calc.round), but there @@ -81,11 +82,11 @@ use crate::World; /// multiplication, and [power]($calc.pow) to an integer, will be highly precise /// due to their fixed-point representation. Note, however, that multiplication /// and division may not preserve all digits in some edge cases: while they are -/// considered precise, digits past the limits specified below are rounded off +/// considered precise, digits past the limits specified above are rounded off /// and lost, so some loss of precision beyond the maximum representable digits /// is possible. Note that this behavior can be observed not only when dividing, /// but also when multiplying by numbers between 0 and 1, as both operations can -/// push a number's fractional digits beyond the limits described below, leading +/// push a number's fractional digits beyond the limits described above, leading /// to rounding. When those two operations do not surpass the digit limits, they /// are fully precise. #[ty(scope, cast)] @@ -287,7 +288,7 @@ impl Decimal { /// writing `{decimal(1.234)}` (note the lack of double quotes), which is /// why Typst will emit a warning in that case. Please write /// `{decimal("1.234")}` instead for that particular case (initialization of - /// a constant decimal). Also note that floats equal to NaN and infinity + /// a constant decimal). Also note that floats that are NaN or infinite /// cannot be cast to decimals and will raise an error. /// /// ```example @@ -296,6 +297,7 @@ impl Decimal { #[func(constructor)] pub fn construct( engine: &mut Engine, + /// The value that should be converted to a decimal. value: Spanned<ToDecimal>, ) -> SourceResult<Decimal> { match value.v { diff --git a/crates/typst/src/foundations/float.rs b/crates/typst/src/foundations/float.rs index 8318641a..752b01d6 100644 --- a/crates/typst/src/foundations/float.rs +++ b/crates/typst/src/foundations/float.rs @@ -97,7 +97,7 @@ impl f64 { /// /// - If the number is positive (including `{+0.0}`), returns `{1.0}`. /// - If the number is negative (including `{-0.0}`), returns `{-1.0}`. - /// - If the number is `{float.nan}`, returns `{float.nan}`. + /// - If the number is NaN, returns `{float.nan}`. /// /// ```example /// #(5.0).signum() \ diff --git a/crates/typst/src/introspection/location.rs b/crates/typst/src/introspection/location.rs index 8a7063fc..5c520d25 100644 --- a/crates/typst/src/introspection/location.rs +++ b/crates/typst/src/introspection/location.rs @@ -85,8 +85,8 @@ impl Location { /// local numbering. This is useful if you are building custom indices or /// outlines. /// - /// If the page numbering is set to `none` at that location, this function - /// returns `none`. + /// If the page numbering is set to `{none}` at that location, this function + /// returns `{none}`. #[func] pub fn page_numbering(self, engine: &mut Engine) -> Option<Numbering> { engine.introspector.page_numbering(self).cloned() diff --git a/crates/typst/src/layout/align.rs b/crates/typst/src/layout/align.rs index 9d3fe26c..e8ba4d7c 100644 --- a/crates/typst/src/layout/align.rs +++ b/crates/typst/src/layout/align.rs @@ -64,6 +64,15 @@ use crate::text::TextElem; /// left. /// ]) /// ``` +/// +/// # Alignment within the same line +/// The `align` function performs block-level alignment and thus always +/// interrupts the current paragraph. To have different alignment for parts +/// of the same line, you should use [fractional spacing]($h) instead: +/// +/// ```example +/// Start #h(1fr) End +/// ``` #[elem(Show)] pub struct AlignElem { /// The [alignment] along both axes. diff --git a/crates/typst/src/layout/measure.rs b/crates/typst/src/layout/measure.rs index 92d4c5c3..ad68b948 100644 --- a/crates/typst/src/layout/measure.rs +++ b/crates/typst/src/layout/measure.rs @@ -19,8 +19,8 @@ use crate::syntax::Span; /// /// # Example /// The same content can have a different size depending on the [context] that -/// it is placed into. For example, in the example below `[#content]` is of -/// course bigger when we increase the font size. +/// it is placed into. In the example below, the `[#content]` is of course +/// bigger when we increase the font size. /// /// ```example /// #let content = [Hello!] @@ -53,12 +53,12 @@ pub fn measure( span: Span, /// The width available to layout the content. /// - /// Defaults to `{auto}`, which denotes an infinite width. + /// Setting this to `{auto}` indicates infinite available width. /// - /// Using the `width` and `height` parameters of this function is - /// different from measuring a [`box`] containing the content; - /// the former will get the dimensions of the inner content - /// instead of the dimensions of the box: + /// Note that using the `width` and `height` parameters of this function is + /// different from measuring a sized [`block`] containing the content. In + /// the following example, the former will get the dimensions of the inner + /// content instead of the dimensions of the block. /// /// ```example /// #context measure(lorem(100), width: 400pt) @@ -70,7 +70,7 @@ pub fn measure( width: Smart<Length>, /// The height available to layout the content. /// - /// Defaults to `{auto}`, which denotes an infinite height. + /// Setting this to `{auto}` indicates infinite available height. #[named] #[default(Smart::Auto)] height: Smart<Length>, diff --git a/crates/typst/src/layout/page.rs b/crates/typst/src/layout/page.rs index 66c2c076..95b3cd1b 100644 --- a/crates/typst/src/layout/page.rs +++ b/crates/typst/src/layout/page.rs @@ -189,8 +189,8 @@ pub struct PageElem { /// /// When set to `{none}`, the background becomes transparent. Note that PDF /// pages will still appear with a (usually white) background in viewers, - /// but they are conceptually transparent. (If you print them, no color is - /// used for the background.) + /// but they are actually transparent. (If you print them, no color is used + /// for the background.) /// /// The default of `{auto}` results in `{none}` for PDF output, and /// `{white}` for PNG and SVG. diff --git a/crates/typst/src/layout/place.rs b/crates/typst/src/layout/place.rs index 6e34f4e2..bedeb507 100644 --- a/crates/typst/src/layout/place.rs +++ b/crates/typst/src/layout/place.rs @@ -24,7 +24,7 @@ use crate::layout::{Alignment, Em, Length, Rel}; /// /// # Examples /// ```example -/// #set page(height: 60pt) +/// #set page(height: 120pt) /// Hello, world! /// /// #rect( diff --git a/crates/typst/src/layout/spacing.rs b/crates/typst/src/layout/spacing.rs index af0b1e64..c7c0823c 100644 --- a/crates/typst/src/layout/spacing.rs +++ b/crates/typst/src/layout/spacing.rs @@ -11,13 +11,23 @@ use crate::utils::Numeric; /// # Example /// ```example /// First #h(1cm) Second \ -/// First #h(30%) Second \ +/// First #h(30%) Second +/// ``` +/// +/// # Fractional spacing +/// With fractional spacing, you can align things within a line without forcing +/// a paragraph break (like [`align`] would). Each fractionally sized element +/// gets space based on the ratio of its fraction to the sum of all fractions. +/// +/// ```example +/// First #h(1fr) Second \ +/// First #h(1fr) Second #h(1fr) Third \ /// First #h(2fr) Second #h(1fr) Third /// ``` /// /// # Mathematical Spacing { #math-spacing } /// In [mathematical formulas]($category/math), you can additionally use these -/// constants to add spacing between elements: `thin` (1/6 em), `med`(2/9 em), +/// constants to add spacing between elements: `thin` (1/6 em), `med` (2/9 em), /// `thick` (5/18 em), `quad` (1 em), `wide` (2 em). #[elem(title = "Spacing (H)")] pub struct HElem { diff --git a/crates/typst/src/math/equation.rs b/crates/typst/src/math/equation.rs index 6f0290d4..19e3ce57 100644 --- a/crates/typst/src/math/equation.rs +++ b/crates/typst/src/math/equation.rs @@ -43,6 +43,9 @@ use crate::World; /// $ sum_(k=1)^n k = (n(n+1)) / 2 $ /// ``` /// +/// By default, block-level equations will not break across pages. This can be +/// changed through `{show math.equation: set block(breakable: true)}`. +/// /// # Syntax /// This function also has dedicated syntax: Write mathematical markup within /// dollar signs to create an equation. Starting and ending the equation with at diff --git a/crates/typst/src/math/matrix.rs b/crates/typst/src/math/matrix.rs index 15ada1f3..66b83e20 100644 --- a/crates/typst/src/math/matrix.rs +++ b/crates/typst/src/math/matrix.rs @@ -40,6 +40,10 @@ const DEFAULT_STROKE_THICKNESS: Em = Em::new(0.05); pub struct VecElem { /// The delimiter to use. /// + /// Can be a single character specifying the left delimiter, in which case + /// the right delimiter is inferred. Otherwise, can be an array containing a + /// left and a right delimiter. + /// /// ```example /// #set math.vec(delim: "[") /// $ vec(1, 2) $ @@ -113,6 +117,10 @@ impl LayoutMath for Packed<VecElem> { pub struct MatElem { /// The delimiter to use. /// + /// Can be a single character specifying the left delimiter, in which case + /// the right delimiter is inferred. Otherwise, can be an array containing a + /// left and a right delimiter. + /// /// ```example /// #set math.mat(delim: "[") /// $ mat(1, 2; 3, 4) $ @@ -300,6 +308,10 @@ impl LayoutMath for Packed<MatElem> { pub struct CasesElem { /// The delimiter to use. /// + /// Can be a single character specifying the left delimiter, in which case + /// the right delimiter is inferred. Otherwise, can be an array containing a + /// left and a right delimiter. + /// /// ```example /// #set math.cases(delim: "[") /// $ x = cases(1, 2) $ diff --git a/crates/typst/src/model/document.rs b/crates/typst/src/model/document.rs index d37f6c8f..b693d785 100644 --- a/crates/typst/src/model/document.rs +++ b/crates/typst/src/model/document.rs @@ -14,7 +14,7 @@ use crate::layout::Page; /// All documents are automatically wrapped in a `document` element. You cannot /// create a document element yourself. This function is only used with /// [set rules]($styling/#set-rules) to specify document metadata. Such a set -/// rule must appear before any of the document's contents. +/// rule must not occur inside of any layout container. /// /// ```example /// #set document(title: [Hello]) diff --git a/crates/typst/src/model/enum.rs b/crates/typst/src/model/enum.rs index 2f1a110a..fcb62f89 100644 --- a/crates/typst/src/model/enum.rs +++ b/crates/typst/src/model/enum.rs @@ -75,9 +75,10 @@ use crate::text::TextElem; /// part of that item. #[elem(scope, title = "Numbered List", Show)] pub struct EnumElem { - /// If this is `{false}`, the items are spaced apart with - /// [enum spacing]($enum.spacing). If it is `{true}`, they use normal - /// [leading]($par.leading) instead. This makes the enumeration more + /// Defines the default [spacing]($enum.spacing) of the enumeration. If it + /// is `{false}`, the items are spaced apart with + /// [paragraph spacing]($par.spacing). If it is `{true}`, they use + /// [paragraph leading]($par.leading) instead. This makes the list more /// compact, which can look better if the items are short. /// /// In markup mode, the value of this parameter is determined based on diff --git a/crates/typst/src/model/footnote.rs b/crates/typst/src/model/footnote.rs index 813990a9..5468b4f5 100644 --- a/crates/typst/src/model/footnote.rs +++ b/crates/typst/src/model/footnote.rs @@ -176,8 +176,8 @@ cast! { /// An entry in a footnote list. /// -/// This function is not intended to be called directly. Instead, it is used -/// in set and show rules to customize footnote listings. +/// This function is not intended to be called directly. Instead, it is used in +/// set and show rules to customize footnote listings. /// /// ```example /// #show footnote.entry: set text(red) @@ -187,11 +187,10 @@ cast! { /// has red text! /// ``` /// -/// _Note:_ Set and show rules for `footnote.entry` must be defined at the -/// beginning of the document in order to work correctly. See [here][issue] for -/// more information. -/// -/// [issue]: https://github.com/typst/typst/issues/1467#issuecomment-1588799440 +/// _Note:_ Footnote entry properties must be uniform across each page run (a +/// page run is a sequence of pages without an explicit pagebreak in between). +/// For this reason, set and show rules for footnote entries should be defined +/// before any page content, typically at the very start of the document. #[elem(name = "entry", title = "Footnote Entry", Show, ShowSet)] pub struct FootnoteEntry { /// The footnote for this entry. It's location can be used to determine diff --git a/crates/typst/src/model/list.rs b/crates/typst/src/model/list.rs index 617c54c9..3a2bd651 100644 --- a/crates/typst/src/model/list.rs +++ b/crates/typst/src/model/list.rs @@ -47,10 +47,11 @@ use crate::text::TextElem; /// more than an item's marker becomes part of that item. #[elem(scope, title = "Bullet List", Show)] pub struct ListElem { - /// If this is `{false}`, the items are spaced apart with - /// [list spacing]($list.spacing). If it is `{true}`, they use normal - /// [leading]($par.leading) instead. This makes the list more compact, which - /// can look better if the items are short. + /// Defines the default [spacing]($list.spacing) of the list. If it is + /// `{false}`, the items are spaced apart with + /// [paragraph spacing]($par.spacing). If it is `{true}`, they use + /// [paragraph leading]($par.leading) instead. This makes the list more + /// compact, which can look better if the items are short. /// /// In markup mode, the value of this parameter is determined based on /// whether items are separated with a blank line. If items directly follow diff --git a/crates/typst/src/model/outline.rs b/crates/typst/src/model/outline.rs index 5bf2407b..b89a1524 100644 --- a/crates/typst/src/model/outline.rs +++ b/crates/typst/src/model/outline.rs @@ -172,7 +172,7 @@ pub struct OutlineElem { pub indent: Option<Smart<OutlineIndent>>, /// Content to fill the space between the title and the page number. Can be - /// set to `none` to disable filling. + /// set to `{none}` to disable filling. /// /// ```example /// #outline(fill: line(length: 100%)) diff --git a/crates/typst/src/model/par.rs b/crates/typst/src/model/par.rs index 371ee4b3..32fc926f 100644 --- a/crates/typst/src/model/par.rs +++ b/crates/typst/src/model/par.rs @@ -217,8 +217,11 @@ impl Unlabellable for Packed<ParbreakElem> {} /// A paragraph line. /// -/// This element is exclusively used for line number configuration and cannot -/// be placed. +/// This element is exclusively used for line number configuration through set +/// rules and cannot be placed. +/// +/// The [`numbering`]($par.line.numbering) option is used to enable line +/// numbers by specifying a numbering format. /// /// ```example /// >>> #set page(margin: (left: 3em)) @@ -228,6 +231,43 @@ impl Unlabellable for Packed<ParbreakElem> {} /// Violets are blue. \ /// Typst is there for you. /// ``` +/// +/// The `numbering` option takes either a predefined +/// [numbering pattern]($numbering) or a function returning styled content. You +/// can disable line numbers for text inside certain elements by setting the +/// numbering to `{none}` using show-set rules. +/// +/// ```example +/// >>> #set page(margin: (left: 3em)) +/// // Styled red line numbers. +/// #set par.line( +/// numbering: n => text(red)[#n] +/// ) +/// +/// // Disable numbers inside figures. +/// #show figure: set par.line( +/// numbering: none +/// ) +/// +/// Roses are red. \ +/// Violets are blue. +/// +/// #figure( +/// caption: [Without line numbers.] +/// )[ +/// Lorem ipsum \ +/// dolor sit amet +/// ] +/// +/// The text above is a sample \ +/// originating from distant times. +/// ``` +/// +/// This element exposes further options which may be used to control other +/// aspects of line numbering, such as its [alignment]($par.line.number-align) +/// or [margin]($par.line.number-margin). In addition, you can control whether +/// the numbering is reset on each page through the +/// [`numbering-scope`]($par.line.numbering-scope) option. #[elem(name = "line", title = "Paragraph Line", keywords = ["line numbering"], Construct, Locatable)] pub struct ParLine { /// How to number each line. Accepts a @@ -246,13 +286,16 @@ pub struct ParLine { /// The alignment of line numbers associated with each line. /// - /// The default of `auto` will provide a smart default where numbers grow + /// The default of `{auto}` indicates a smart default where numbers grow /// horizontally away from the text, considering the margin they're in and /// the current text direction. /// /// ```example /// >>> #set page(margin: (left: 3em)) - /// #set par.line(numbering: "I", number-align: left) + /// #set par.line( + /// numbering: "I", + /// number-align: left, + /// ) /// /// Hello world! \ /// Today is a beautiful day \ @@ -263,9 +306,18 @@ pub struct ParLine { /// The margin at which line numbers appear. /// + /// _Note:_ In a multi-column document, the line numbers for paragraphs + /// inside the last column will always appear on the `{end}` margin (right + /// margin for left-to-right text and left margin for right-to-left), + /// regardless of this configuration. That behavior cannot be changed at + /// this moment. + /// /// ```example /// >>> #set page(margin: (right: 3em)) - /// #set par.line(numbering: "1", number-margin: right) + /// #set par.line( + /// numbering: "1", + /// number-margin: right, + /// ) /// /// = Report /// - Brightness: Dark, yet darker @@ -284,7 +336,7 @@ pub struct ParLine { /// >>> #set page(margin: (left: 3em)) /// #set par.line( /// numbering: "1", - /// number-clearance: 4pt + /// number-clearance: 4pt, /// ) /// /// Typesetting \ @@ -297,14 +349,16 @@ pub struct ParLine { /// Controls when to reset line numbering. /// - /// Possible options are `"document"`, indicating the line number counter - /// is never reset, or `"page"`, indicating it is reset on every page. + /// _Note:_ The line numbering scope must be uniform across each page run (a + /// page run is a sequence of pages without an explicit pagebreak in + /// between). For this reason, set rules for it should be defined before any + /// page content, typically at the very start of the document. /// /// ```example /// >>> #set page(margin: (left: 3em)) /// #set par.line( /// numbering: "1", - /// numbering-scope: "page" + /// numbering-scope: "page", /// ) /// /// First line \ diff --git a/crates/typst/src/model/terms.rs b/crates/typst/src/model/terms.rs index dead9c66..557895f7 100644 --- a/crates/typst/src/model/terms.rs +++ b/crates/typst/src/model/terms.rs @@ -27,10 +27,11 @@ use crate::utils::Numeric; /// followed by a term, a colon and a description creates a term list item. #[elem(scope, title = "Term List", Show)] pub struct TermsElem { - /// If this is `{false}`, the items are spaced apart with - /// [term list spacing]($terms.spacing). If it is `{true}`, they use normal - /// [leading]($par.leading) instead. This makes the term list more compact, - /// which can look better if the items are short. + /// Defines the default [spacing]($terms.spacing) of the term list. If it is + /// `{false}`, the items are spaced apart with + /// [paragraph spacing]($par.spacing). If it is `{true}`, they use + /// [paragraph leading]($par.leading) instead. This makes the list more + /// compact, which can look better if the items are short. /// /// In markup mode, the value of this parameter is determined based on /// whether items are separated with a blank line. If items directly follow diff --git a/crates/typst/src/text/mod.rs b/crates/typst/src/text/mod.rs index 5b35d60c..6f3f741a 100644 --- a/crates/typst/src/text/mod.rs +++ b/crates/typst/src/text/mod.rs @@ -445,9 +445,10 @@ pub struct TextElem { /// the other way around in `rtl` text. /// /// If you set this to `rtl` and experience bugs or in some way bad looking - /// output, please do get in touch with us through the - /// [contact form](https://typst.app/contact) or our - /// [Discord server](https://discord.gg/2uDybryKPe)! + /// output, please get in touch with us through the + /// [Forum](https://forum.typst.app/), + /// [Discord server](https://discord.gg/2uDybryKPe), + /// or our [contact form](https://typst.app/contact). /// /// ```example /// #set text(dir: rtl) @@ -482,8 +483,9 @@ pub struct TextElem { /// The "cost" of various choices when laying out text. A higher cost means /// the layout engine will make the choice less often. Costs are specified - /// as a ratio of the default cost, so `50%` will make text layout twice as - /// eager to make a given choice, while `200%` will make it half as eager. + /// as a ratio of the default cost, so `{50%}` will make text layout twice + /// as eager to make a given choice, while `{200%}` will make it half as + /// eager. /// /// Currently, the following costs can be customized: /// - `hyphenation`: splitting a word across multiple lines @@ -501,10 +503,10 @@ pub struct TextElem { /// Text layout prevents widows and orphans by default because they are /// generally discouraged by style guides. However, in some contexts they /// are allowed because the prevention method, which moves a line to the - /// next page, can result in an uneven number of lines between pages. - /// The `widow` and `orphan` costs allow disabling these modifications. - /// (Currently, 0% allows widows/orphans; anything else, including the - /// default of `auto`, prevents them. More nuanced cost specification for + /// next page, can result in an uneven number of lines between pages. The + /// `widow` and `orphan` costs allow disabling these modifications. + /// (Currently, `{0%}` allows widows/orphans; anything else, including the + /// default of `{100%}`, prevents them. More nuanced cost specification for /// these modifications is planned for the future.) /// /// ```example @@ -568,9 +570,9 @@ pub struct TextElem { /// This can be set to an integer or an array of integers, all /// of which must be between `{1}` and `{20}`, enabling the /// corresponding OpenType feature(s) from `ss01` to `ss20`. - /// Setting this to `none` will disable all stylistic sets. + /// Setting this to `{none}` will disable all stylistic sets. /// - /// ``` + /// ```example /// #set text(font: "IBM Plex Serif") /// ß vs #text(stylistic-set: 5)[ß] \ /// 10 years ago vs #text(stylistic-set: (1, 2, 3))[10 years ago] diff --git a/crates/typst/src/text/raw.rs b/crates/typst/src/text/raw.rs index 21b6bc00..e669be38 100644 --- a/crates/typst/src/text/raw.rs +++ b/crates/typst/src/text/raw.rs @@ -215,7 +215,7 @@ pub struct RawElem { pub syntaxes_data: Vec<Bytes>, /// The theme to use for syntax highlighting. Theme files should be in the - /// in the [`tmTheme` file format](https://www.sublimetext.com/docs/color_schemes_tmtheme.html). + /// [`tmTheme` file format](https://www.sublimetext.com/docs/color_schemes_tmtheme.html). /// /// Applying a theme only affects the color of specifically highlighted /// text. It does not consider the theme's foreground and background @@ -224,7 +224,7 @@ pub struct RawElem { /// the background with a [filled block]($block.fill). You could also use /// the [`xml`] function to extract these properties from the theme. /// - /// Additionally, you can set the theme to `none` to disable highlighting. + /// Additionally, you can set the theme to `{none}` to disable highlighting. /// /// ````example /// #set raw(theme: "halcyon.tmTheme") diff --git a/crates/typst/src/visualize/line.rs b/crates/typst/src/visualize/line.rs index f25fc58d..e00bf220 100644 --- a/crates/typst/src/visualize/line.rs +++ b/crates/typst/src/visualize/line.rs @@ -33,13 +33,13 @@ pub struct LineElem { #[resolve] pub end: Option<Axes<Rel<Length>>>, - /// The line's length. This is only respected if `end` is `none`. + /// The line's length. This is only respected if `end` is `{none}`. #[resolve] #[default(Abs::pt(30.0).into())] pub length: Rel<Length>, /// The angle at which the line points away from the origin. This is only - /// respected if `end` is `none`. + /// respected if `end` is `{none}`. pub angle: Angle, /// How to [stroke] the line. 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! |