Repository: typst/typst
File: crates/typst/src/text/mod.rs (Rust)

Code before:
    /// as a ratio of the default cost, so `50%` will make text layout twice as
    /// eager to make a given choice, while `200%` (or 2) will make it half as
    /// eager.
    ///
    /// Currently, the following costs can be customized:
    /// - `hyphenation`: splitting a word across multiple lines
    /// - `runt`: ending a paragraph with a line with a single word
    /// - `widow`: leaving a single line of paragraph on the next page
    /// - `orphan`: leaving single line of paragraph on the previous page
    ///
    /// Hyphenation is generally avoided by placing the whole word on the next
    /// line, so a higher hyphenation cost can result in awkward justification
    /// spacing.
    ///
    /// Runts are avoided by placing more or fewer words on previous lines, so a
    /// higher runt cost can result in more awkward in justification spacing.
    ///
    /// Text layout prevents widows and orphans by default because they are
    /// generally discouraged by style guides. However, in some contexts they
    /// should not be avoided because the prevention method, which moves a line
    /// to the next page, can result in an uneven number of lines between pages,
    /// which leads to asymmetry and breaking the flow of dense prose. This
    /// option allows disabling any such modification. (Currently, 0% disables
    /// widow/orphan avoidance and anything else, including the default of
    /// `auto`, enables it. More nuanced cost specification for these
    /// modifications is planned for the future.)
    ///
    /// The default costs are an acceptable balance, but some may find that it
    /// hyphenates or avoids runs too eagerly, breaking the flow of dense prose.
    /// A cost of 600% (six times the normal cost) may work better for such
    /// contexts.
    #[fold]
    pub costs: Costs,

    /// Whether to apply kerning.
    ///
    /// When enabled, specific letter pairings move closer together or further
    /// apart for a more visually pleasing result. The example below
    /// demonstrates how decreasing the gap between the "T" and "o" results in a
    /// more natural look. Setting this to `{false}` disables kerning by turning
    /// off the OpenType `kern` font feature.
    ///
    /// ```example
    /// #set text(size: 25pt)
    /// Totally
    ///
    /// #set text(kerning: false)
    /// Totally
    /// ```
    #[default(true)]
    #[ghost]

Review comment (suggestion):
This part is a bit hard to read because
- the first sentence is very long
- of the double negation in `should not be avoided`
- of the double negation in `disable widow/orphan avoidance`
- I would also put a full stop before "anything else, ..., enables it." Currently, the comma situation had me re-reading it twice.

Code after:
    /// 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.
    ///
    /// Currently, the following costs can be customized:
    /// - `hyphenation`: splitting a word across multiple lines
    /// - `runt`: ending a paragraph with a line with a single word
    /// - `widow`: leaving a single line of paragraph on the next page
    /// - `orphan`: leaving single line of paragraph on the previous page
    ///
    /// Hyphenation is generally avoided by placing the whole word on the next
    /// line, so a higher hyphenation cost can result in awkward justification
    /// spacing.
    ///
    /// Runts are avoided by placing more or fewer words on previous lines, so a
    /// higher runt cost can result in more awkward in justification spacing.
    ///
    /// 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
    /// these modifications is planned for the future.)
    ///
    /// The default costs are an acceptable balance, but some may find that it
    /// hyphenates or avoids runs too eagerly, breaking the flow of dense prose.
    /// A cost of 600% (six times the normal cost) may work better for such
    /// contexts.
    ///
    /// ```example
    /// #set text(hyphenate: true, size: 11.4pt)
    /// #set par(justify: true)
    ///
    /// #lorem(10)
    ///
    /// // Set hyphenation to ten times the normal cost.
    /// #set text(costs: (hyphenation: 1000%))
    ///
    /// #lorem(10)
    /// ```
    #[fold]
    pub costs: Costs,

    /// Whether to apply kerning.
    ///
    /// When enabled, specific letter pairings move closer together or further
    /// apart for a more visually pleasing result. The example below
    /// demonstrates how decreasing the gap between the "T" and "o" results in a