Fix text examples

Fixes #1251
Fixes #1252
Fixes #1253
Fixes #1254
Fixes #1255

1 files changed, 26 insertions, 14 deletions

diff --git a/library/src/text/mod.rs b/library/src/text/mod.rs
index 6e3f1acf..1fefc6cb 100644
--- a/library/src/text/mod.rs
+++ b/library/src/text/mod.rs
@@ -131,6 +131,8 @@ pub struct TextElem {
     /// emphasis.
     ///
     /// ```example
+    /// #set text(font: "IBM Plex Sans")
+    ///
     /// #text(weight: "light")[Light] \
     /// #text(weight: "regular")[Regular] \
     /// #text(weight: "medium")[Medium] \
@@ -141,7 +143,12 @@ pub struct TextElem {
 
     /// The desired width of the glyphs. Accepts a ratio between `{50%}` and
     /// `{200%}`. When the desired weight is not available, Typst selects the
-    /// font from the family that is closest in stretch.
+    /// font from the family that is closest in stretch. This will only stretch
+    /// the text if a condensed or expanded version of the font is available.
+    ///
+    /// If you want to adjust the amount of space between characters instead of
+    /// stretching the glyphs itself, use the [`tracking`]($func/text.tracking)
+    /// property instead.
     ///
     /// ```example
     /// #text(stretch: 75%)[Condensed] \
@@ -188,6 +195,9 @@ pub struct TextElem {
     /// Can be given as an absolute length, but also relative to the width of
     /// the space character in the font.
     ///
+    /// If you want to adjust the amount of space between characters rather than
+    /// words, use the [`tracking`]($func/text.tracking) property instead.
+    ///
     /// ```example
     /// #set text(spacing: 200%)
     /// Text with distant words.
@@ -210,20 +220,16 @@ pub struct TextElem {
     ///
     /// ```example
     /// #set par(justify: true)
-    /// In this particular text, the
-    /// justification produces a hyphen
-    /// in the first line. Letting this
-    /// hyphen hang slightly into the
-    /// margin makes for a clear
-    /// paragraph edge.
+    /// This justified text has a hyphen in
+    /// the paragraph's first line. Hanging
+    /// the hyphen slightly into the margin
+    /// results in a clearer paragraph edge.
     ///
     /// #set text(overhang: false)
-    /// In this particular text, the
-    /// justification produces a hyphen
-    /// in the first line. This time the
-    /// hyphen does not hang into the
-    /// margin, making the paragraph's
-    /// edge less clear.
+    /// This justified text has a hyphen in
+    /// the paragraph's first line. Hanging
+    /// the hyphen slightly into the margin
+    /// results in a clearer paragraph edge.
     /// ```
     #[default(true)]
     pub overhang: bool,
@@ -319,6 +325,8 @@ pub struct TextElem {
     /// hyphenation patterns are used.
     ///
     /// ```example
+    /// #set page(width: 200pt)
+    ///
     /// #set par(justify: true)
     /// This text illustrates how
     /// enabling hyphenation can
@@ -357,7 +365,11 @@ pub struct TextElem {
     /// `salt` font feature.
     ///
     /// ```example
-    /// #set text(size: 20pt)
+    /// #set text(
+    ///   font: "IBM Plex Sans",
+    ///   size: 20pt,
+    /// )
+    ///
     /// 0, a, g, ß
     ///
     /// #set text(alternates: true)