Touch up docs

cli/src/main.rs

@@ -92,26 +92,19 @@ fn typst_version() -> &'static str {
 struct CompileSettings {
     /// The path to the input file.
     input: PathBuf,
-
     /// The path to the output file.
     output: PathBuf,
-
     /// Whether to watch the input files for changes.
     watch: bool,
-
     /// The root directory for absolute paths.
     root: Option<PathBuf>,
-
     /// The paths to search for fonts.
     font_paths: Vec<PathBuf>,
-
     /// The open command to use.
     open: Option<Option<String>>,
-
     /// The PPI to use for PNG export.
     ppi: Option<f32>,
-
+    /// In which format to emit diagnostics.
-    /// In which format to emit diagnostics
     diagnostic_format: DiagnosticFormat,
 }
 
@@ -173,7 +166,6 @@ impl CompileSettings {
 struct FontsSettings {
     /// The font paths
     font_paths: Vec<PathBuf>,
-
     /// Whether to include font variants
     variants: bool,
 }
@@ -505,7 +497,7 @@ struct SystemWorld {
     hashes: RefCell<HashMap<PathBuf, FileResult<PathHash>>>,
     paths: RefCell<HashMap<PathHash, PathSlot>>,
     sources: FrozenVec<Box<Source>>,
-    current_date: Cell<Option<Datetime>>,
+    today: Cell<Option<Datetime>>,
     main: SourceId,
 }
 
@@ -536,7 +528,7 @@ impl SystemWorld {
             hashes: RefCell::default(),
             paths: RefCell::default(),
             sources: FrozenVec::new(),
-            current_date: Cell::new(None),
+            today: Cell::new(None),
             main: SourceId::detached(),
         }
     }
@@ -599,20 +591,20 @@ impl World for SystemWorld {
     }
 
     fn today(&self, offset: Option<i64>) -> Option<Datetime> {
-        if self.current_date.get().is_none() {
+        if self.today.get().is_none() {
             let datetime = match offset {
                 None => chrono::Local::now().naive_local(),
                 Some(o) => (chrono::Utc::now() + chrono::Duration::hours(o)).naive_utc(),
             };
 
-            self.current_date.set(Some(Datetime::from_ymd(
+            self.today.set(Some(Datetime::from_ymd(
                 datetime.year(),
                 datetime.month().try_into().ok()?,
                 datetime.day().try_into().ok()?,
             )?))
         }
 
-        self.current_date.get()
+        self.today.get()
     }
 }
 
@@ -675,7 +667,7 @@ impl SystemWorld {
         self.sources.as_mut().clear();
         self.hashes.borrow_mut().clear();
         self.paths.borrow_mut().clear();
-        self.current_date.set(None);
+        self.today.set(None);
     }
 }
 

docs/src/reference/types.md

@@ -188,7 +188,9 @@ getting the current date with [`datetime.today`]($func/datetime.today).
 )
 
 #date.display() \
-#date.display("y:[year repr:last_two]")
+#date.display(
+  "y:[year repr:last_two]"
+)
 
 #let time = datetime(
   hour: 18,
@@ -197,20 +199,22 @@ getting the current date with [`datetime.today`]($func/datetime.today).
 )
 
 #time.display() \
-#time.display("h:[hour repr:12][period]")
+#time.display(
+  "h:[hour repr:12][period]"
+)
 ```
 
 ## Format
-You can specify a customized formatting using the `display` method.
+You can specify a customized formatting using the
-The format of a datetime is specified by providing
+[`display`]($type/datetime.display) method. The format of a datetime is
-_components_ with a specified number of _modifiers_. A component represents a
+specified by providing _components_ with a specified number of _modifiers_. A
-certain part of the datetime that you want to display, and with the help of
+component represents a certain part of the datetime that you want to display,
-modifiers you can define how you want to display that component. In order to
+and with the help of modifiers you can define how you want to display that
-display a component, you wrap the name of the component in square brackets
+component. In order to display a component, you wrap the name of the component
-(e.g. `[year]` will display the year). In order to add modifiers,
+in square brackets (e.g. `[[year]]` will display the year). In order to add
-you add a space after the component name followed by the name of the modifier,
+modifiers, you add a space after the component name followed by the name of the
-a colon and the value of the modifier (e.g. `[month repr:short]` will display
+modifier, a colon and the value of the modifier (e.g. `[[month repr:short]]`
-the short representation of the month).
+will display the short representation of the month).
 
 The possible combination of components and their respective modifiers is as
 follows:
@@ -262,7 +266,7 @@ follows:
     is padded.
 
 Keep in mind that not always all components can be used. For example, if
-you create a new datetime with `#datetime(year: 2023, month: 10, day: 13)`, it
+you create a new datetime with `{datetime(year: 2023, month: 10, day: 13)}`, it
 will be stored as a plain date internally, meaning that you cannot use
 components such as `hour` or `minute`, which would only work on datetimes
 that have a specified time.
@@ -271,47 +275,49 @@ that have a specified time.
 ### display()
 Displays the datetime in a certain way. Depending on whether you have defined
 just a date, a time or both, the default format will be different.
-If you specified a date, it will be `[year]-[month]-[day]`. If you specified a
+If you specified a date, it will be `[[year]-[month]-[day]]`. If you specified a
-time, it will be `[hour]:[minute]:[second]`. In the case of a datetime, it will
+time, it will be `[[hour]:[minute]:[second]]`. In the case of a datetime, it
-be `[year]-[month]-[day] [hour]:[minute]:[second]`.
+will be `[[year]-[month]-[day] [hour]:[minute]:[second]]`.
 
 - pattern: string (positional)
   The format used to display the datetime.
 - returns: string
 
 ### year()
-Returns the year of the datetime, if it exists. Otherwise, it returns `none`.
+Returns the year of the datetime, if it exists. Otherwise, it returns `{none}`.
 
 - returns: integer or none
 
 ### month()
-Returns the month of the datetime, if it exists. Otherwise, it returns `none`.
+Returns the month of the datetime, if it exists. Otherwise, it returns `{none}`.
 
 - returns: integer or none
 
 ### weekday()
 Returns the weekday of the datetime as a number starting with 1 from Monday, if
-it exists. Otherwise, it returns `none`.
+it exists. Otherwise, it returns `{none}`.
 
 - returns: integer or none
 
 ### day()
-Returns the day of the datetime, if it exists. Otherwise, it returns `none`.
+Returns the day of the datetime, if it exists. Otherwise, it returns `{none}`.
 
 - returns: integer or none
 
 ### hour()
-Returns the hour of the datetime, if it exists. Otherwise, it returns `none`.
+Returns the hour of the datetime, if it exists. Otherwise, it returns `{none}`.
 
 - returns: integer or none
 
 ### minute()
-Returns the minute of the datetime, if it exists. Otherwise, it returns `none`.
+Returns the minute of the datetime, if it exists. Otherwise, it returns
+`{none}`.
 
 - returns: integer or none
 
 ### second()
-Returns the second of the datetime, if it exists. Otherwise, it returns `none`.
+Returns the second of the datetime, if it exists. Otherwise, it returns
+`{none}`.
 
 - returns: integer or none
 
@@ -608,7 +614,10 @@ field does not exist or fails with an error if no default value was specified.
 Return the fields of this content.
 
 ```example
-#repr(rect(width: 10cm, height: 10cm).fields())
+#rect(
+  width: 10cm,
+  height: 10cm,
+).fields()
 ```
 
 ### location()

library/src/compute/calc.rs

@@ -143,7 +143,7 @@ pub fn pow(
 ///
 /// ## Example { #example }
 /// ```example
-/// #calc.exp(3)
+/// #calc.exp(1)
 /// ```
 ///
 /// Display: Exponential
@@ -479,7 +479,7 @@ pub fn log(
 ///
 /// ## Example { #example }
 /// ```example
-/// #calc.ln(100)
+/// #calc.ln(calc.e)
 /// ```
 ///
 /// Display: Natural Logarithm

library/src/compute/construct.rs

@@ -183,7 +183,8 @@ cast! {
 /// Create a new datetime.
 ///
 /// You can specify the [datetime]($type/datetime) using a year, month, day,
-/// hour, minute, and second.
+/// hour, minute, and second. You can also get the current date with
+/// [`datetime.today`]($func/datetime.today).
 ///
 /// ## Example
 /// ```example
@@ -564,7 +565,7 @@ pub fn str_to_unicode(
 /// #str.from-unicode(97)
 /// ```
 ///
-/// Display: Sting From Unicode
+/// Display: String From Unicode
 /// Category: construct
 #[func]
 pub fn str_from_unicode(

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}`,
+    /// How to indent the outline's entries.
-    /// 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.
     ///
-    /// If this option is set to `{auto}`, each entry (usually headings) will
+    /// - `{none}`: No indent
-    /// be indented enough to align with the last character of its parent's
+    /// - `{auto}`: Indents the numbering of the nested entry with the title of
-    /// numbering. For example, if the parent entry is "3. Top heading" and the
+    ///   its parent entry. This only has an effect if the entries are numbered
-    /// child entry is "3.1. Inner heading", the end result is that the child
+    ///   (e.g., via [heading numbering]($func/heading.numbering)).
-    /// entry's line will begin where the "3." from the parent ends (after the
+    /// - [Relative length]($type/relative): Indents the item by this length
-    /// last dot), but below. Consequently, if you specify `{auto}` indentation,
+    ///   multiplied by its nesting level. Specifying `{2em}`, for instance,
-    /// you will only see a visible effect if a
+    ///   would indent top-level headings (not nested) by `{0em}`, second level
-    /// [heading numbering]($func/heading.numbering) is set for your headings
+    ///   headings by `{2em}` (nested once), third-level headings by `{4em}`
-    /// (if using headings), or, in general, if your entries have some form of
+    ///   (nested twice) and so on.
-    /// automatic numbering (generated by Typst) enabled.
+    /// - [Function]($type/function): You can completely customize this setting
-    ///
+    ///   with a function. That function receives the nesting level as a
-    /// Note that specifying `{true}` (equivalent to `{auto}`) or `{false}`
+    ///   parameter (starting at 0 for top-level headings/elements) and can
-    /// (equivalent to `{none}`) for this option is deprecated and will be
+    ///   return a relative length or content making up the indent. For example,
-    /// removed in a future release. Please use `{none}` for no indentation
+    ///   `{n => n * 2em}` would be equivalent to just specifiying `{2em}`,
-    /// or `{auto}` for automatic indentation instead.
+    ///   while `{n => [→ ] * n}` would indent with one arrow per nesting
-    ///
+    ///   level.
-    /// 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}`.
     ///
+    /// *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(
-    /// #outline(title: "Contents (Length indentation)", indent: 2em)
+    ///   title: [Contents (Automatic)],
-    /// #outline(title: "Contents (Function indentation)", indent: n => [*!*] * n * n)
+    ///   indent: auto,
+    /// )
+    ///
+    /// #outline(
+    ///   title: [Contents (Length)],
+    ///   indent: 2em,
+    /// )
+    ///
+    /// #outline(
+    ///   title: [Contents (Function)],
+    ///   indent: n => [→ ] * n,
+    /// )
     ///
     /// = About ACME Corp.
-    ///
     /// == History
+    /// === Origins
     /// #lorem(10)
     ///
     /// == Products

src/syntax/kind.rs

@@ -234,7 +234,7 @@ pub enum SyntaxKind {
     WhileLoop,
     /// A for loop: `for x in y { z }`.
     ForLoop,
-    /// A module import: `import a, b, c from "utils.typ"`.
+    /// A module import: `import "utils.typ": a, b, c`.
     ModuleImport,
     /// Items to import from a module: `a, b, c`.
     ImportItems,