Touch up docs

1 files changed, 35 insertions, 43 deletions

diff --git a/library/src/meta/outline.rs b/library/src/meta/outline.rs
index ea354228..d1bd0676 100644
--- a/library/src/meta/outline.rs
+++ b/library/src/meta/outline.rs
@@ -110,58 +110,50 @@ pub struct OutlineElem {
     /// ```
     pub depth: Option<NonZeroUsize>,
 
-    /// How to indent the outline's entry lines. This defaults to `{none}`,
-    /// which does not apply any indentation at all upon the outline's entries,
-    /// which will then all be placed at the start of each line.
+    /// How to indent the outline's entries.
     ///
-    /// If this option is set to `{auto}`, each entry (usually headings) will
-    /// be indented enough to align with the last character of its parent's
-    /// numbering. For example, if the parent entry is "3. Top heading" and the
-    /// child entry is "3.1. Inner heading", the end result is that the child
-    /// entry's line will begin where the "3." from the parent ends (after the
-    /// last dot), but below. Consequently, if you specify `{auto}` indentation,
-    /// you will only see a visible effect if a
-    /// [heading numbering]($func/heading.numbering) is set for your headings
-    /// (if using headings), or, in general, if your entries have some form of
-    /// automatic numbering (generated by Typst) enabled.
-    ///
-    /// Note that specifying `{true}` (equivalent to `{auto}`) or `{false}`
-    /// (equivalent to `{none}`) for this option is deprecated and will be
-    /// removed in a future release. Please use `{none}` for no indentation
-    /// or `{auto}` for automatic indentation instead.
-    ///
-    /// Alternatively, you may specify a custom indentation method, which
-    /// doesn't depend on numbering. Setting this option to a length, such as
-    /// `{2em}`, will indent each nested level by that much length, multiplied
-    /// by the current nesting level (so a top-level heading, nested 0 times,
-    /// wouldn't be indented at all; a heading nested once would be `{2em}`
-    /// away from the start of the line, a heading nested twice would be
-    /// `{4em}` away, and so on).
-    ///
-    /// It is also possible to set this option to a function, allowing for a
-    /// more complete customization of the indentation. A function is expected
-    /// to take a single parameter indcating the current nesting level
-    /// (starting at `{0}` for top-level headings/elements), and return the
-    /// indentation option for that level (or `{none}`). Such a function could
-    /// be, for example, {n => n * 2em}` (indenting by `{2em}` times the
-    /// nesting level), or `{n => [*!*] * n * n}` (indenting by a bold
-    /// exclamation mark times the nesting level squared). Please note that the
-    /// function is also called for nesting level 0, so be careful to not
-    /// return a fixed value if you don't want to accidentally indent top-level
-    /// entries by it (if that's not your intention), which you can solve by
-    /// returning `{none}` when the received parameter is equal to `{0}`.
+    /// - `{none}`: No indent
+    /// - `{auto}`: Indents the numbering of the nested entry with the title of
+    ///   its parent entry. This only has an effect if the entries are numbered
+    ///   (e.g., via [heading numbering]($func/heading.numbering)).
+    /// - [Relative length]($type/relative): Indents the item by this length
+    ///   multiplied by its nesting level. Specifying `{2em}`, for instance,
+    ///   would indent top-level headings (not nested) by `{0em}`, second level
+    ///   headings by `{2em}` (nested once), third-level headings by `{4em}`
+    ///   (nested twice) and so on.
+    /// - [Function]($type/function): You can completely customize this setting
+    ///   with a function. That function receives the nesting level as a
+    ///   parameter (starting at 0 for top-level headings/elements) and can
+    ///   return a relative length or content making up the indent. For example,
+    ///   `{n => n * 2em}` would be equivalent to just specifiying `{2em}`,
+    ///   while `{n => [→ ] * n}` would indent with one arrow per nesting
+    ///   level.
     ///
+    /// *Migration hints:*  Specifying `{true}` (equivalent to `{auto}`) or
+    /// `{false}` (equivalent to `{none}`) for this option is deprecated and
+    /// will be removed in a future release.
     ///
     /// ```example
     /// #set heading(numbering: "1.a.")
     ///
-    /// #outline(title: "Contents (Automatic indentation)", indent: auto)
-    /// #outline(title: "Contents (Length indentation)", indent: 2em)
-    /// #outline(title: "Contents (Function indentation)", indent: n => [*!*] * n * n)
+    /// #outline(
+    ///   title: [Contents (Automatic)],
+    ///   indent: auto,
+    /// )
     ///
-    /// = About ACME Corp.
+    /// #outline(
+    ///   title: [Contents (Length)],
+    ///   indent: 2em,
+    /// )
+    ///
+    /// #outline(
+    ///   title: [Contents (Function)],
+    ///   indent: n => [→ ] * n,
+    /// )
     ///
+    /// = About ACME Corp.
     /// == History
+    /// === Origins
     /// #lorem(10)
     ///
     /// == Products