Improve documentation

docs/src/getting_started.md

@@ -23,20 +23,16 @@ julia> show(IOContext(stdout, :mode => code), "text/typst", Typst(π))
 3.141592653589793
 ```
 
-Instead of printing, construct a [`TypstString`](@ref).
+Instead of printing, create a [`TypstString`](@ref) using its constructor or
+[`@typst_str`](@ref) with formatted interpolation.
 
 ```jldoctest 1
 julia> TypstString(π)
 typst"π"
 
 julia> TypstString(π; mode = code)
 typst"3.141592653589793"
-```
-
-Alternatively, use [`@typst_str`](@ref) to construct
-a `TypstString` with formatted interpolation.
 
-```jldoctest 1
 julia> typst"$ \(pi) approx \(pi; mode = code) $"
 typst"$ π approx 3.141592653589793 $"
 ```

docs/src/index.md

@@ -7,8 +7,14 @@ DocTestSetup = :(using Typstry)
 
 ## Introduction
 
-Typstry.jl is the interface to convert the computational power of Julia into
-beautifully formatted [Typst](https://github.com/typst/typst) documents.
+Typstry.jl is the interface to convert the computational power of Julia into beautifully formatted Typst documents.
+
+### What is Typst?
+
+Typst is an open-source and relatively new typesetting system (written in Rust 🚀),
+[designed to improve upon the performance and usability of LaTeX](https://typst.app/about).
+See also the Typst [repository](https://github.com/typst/typst) and
+[documentation](https://typst.app/docs) for examples and how to get started.
 
 ## Installation
 
@@ -52,10 +58,10 @@ typst`compile input.typ output.pdf`
 
 ### Strings
 
-- Convert Julia values to Typst format
+- Print Julia values in Typst format
     - Specify Julia settings and Typst parameters
     - Implement formatting for custom types
-- Create and manipulate Typst formatted strings
+- Construct Typst strings
     - Interpolate formatted values
     - Render in Pluto.jl notebooks
 

docs/src/tutorials/interface.md

@@ -69,7 +69,7 @@ reciprocal(3.1416)
 
 While implementing the interface only requires implementing two methods,
 it may be more challenging to determine how a Julia value should be
-represented in a Typst source file and its corresponding rendered document.
+represented in a Typst source file and its corresponding compiled document.
 Julia and Typst are distinct languages that differ in both syntax and semantics,
 so there may be multiple meaningful formats to choose from.
 
@@ -88,7 +88,7 @@ julia> println(TypstString(r"[a-z]"))
 #regex("[a-z]")
 ```
 
-### Choose the most meaningful and semantically rich representation
+### Choose the most semantically rich representation
 
 - This may vary across `Mode`s and domains
 - Both Julia and Typst support Unicode characters, except unknown variables in Typst's `code` mode
@@ -106,22 +106,18 @@ julia> println(TypstString(π; mode = markup))
 
 ### Consider both the Typst source text and rendered document formatting
 
-- A `String` is meaningful in different ways for each Typst `Mode`
 - A `Text` is documented to "render [its value] as plain text", and therefore corresponds to text in a rendered Typst document
 - A `TypstString` represents Typst source text, and is printed directly
 
 ```jldoctest 1
-julia> println(TypstString("[\"a\"]"))
-"[\\\"a\\\"]"
-
 julia> println(TypstString(text"[\"a\"]"))
 "[\\\"a\\\"]"
 
 julia> println(TypstString(typst"[\"a\"]"))
 ["a"]
 ```
 
-### Try to ensure that the formatting is valid Typst source text
+### Try to generate valid Typst source text
 
 - A `TypstString` represents Typst source text, which may be invalid
 - A `UnitRange{Int}` is formatted differently for each `Mode`, but is always valid
@@ -141,7 +137,7 @@ $vec(
 )$
 ```
 
-### Consider edge cases
+### Test for edge cases
 
 - `#1 / 2` is valid Typst source text, but is parsed partially in `code` mode as `(#1) / 2`
 - `1 / 2` may be ambiguous in a `math` mode expression

src/commands.jl

@@ -29,7 +29,7 @@ The Typst compiler.
 
 !!! info
     This type implements the `Cmd` interface.
-    However, the interface is unspecified and may result in unexpected behavior.
+    However, the interface is unspecified, which may result in unexpected behavior.
 
 # Examples
 ```jldoctest
@@ -57,7 +57,7 @@ TypstCommand(tc::TypstCommand, ignorestatus, flags, env, dir, cpus = nothing) =
     TypstError <: Exception
     TypstError(::TypstCommand)
 
-An `Exception` indicating an failure to [`run`](@ref) a [`TypstCommand`](@ref).
+An `Exception` indicating a failure to [`run`](@ref) a [`TypstCommand`](@ref).
 """
 struct TypstError <: Exception
     command::TypstCommand
@@ -69,7 +69,7 @@ end
 
 Construct a [`TypstCommand`](@ref) where each parameter is separated by a space.
 
-This does not support interpolation; use the `TypstCommand` constructor instead.
+This does not support interpolation; use the constructor instead.
 
 # Examples
 ```jldoctest
@@ -91,24 +91,23 @@ An constant artifact containing the
 [JuliaMono](https://github.com/cormullion/juliamono) typeface.
 
 Use with a [`TypstCommand`](@ref) and one of [`addenv`](@ref),
-[`setenv`](@ref), or the `font-path` command-line option.
+[`setenv`](@ref), or the `font-path` Typst command-line option.
 """
 const julia_mono = artifact"JuliaMono"
 
 """
     render(x;
         input = "input.typ",
         output = "output.pdf",
-        preamble = true,
         open = true,
+        preamble = true,
     context...)
 
 Render to a document using
-[`show(::IO, ::MIME"text/typst", ::Union{Typst, TypstString})`](@ref)
-with the `context`.
+[`show(::IO,\u00A0::MIME"text/typst",\u00A0::Typst)`](@ref).
 
 This generates two files: the `input` is the Typst
-source text and the `output` is the rendered document.
+source text and the `output` is the compiled document.
 The document format is inferred by the file extension of `output`,
 which may be `pdf`, `png`, or `svg`.
 The document may be automatically `open`ed by the default viewer.
@@ -126,8 +125,8 @@ julia> render(Any[true 1; 1.2 1 // 2]);
 function render(x;
     input = "input.typ",
     output = "output.pdf",
-    preamble = true,
     open = true,
+    preamble = true,
 context...)
     Base.open(input; truncate = true) do file
         preamble && println(file, Typstry.preamble)
@@ -151,7 +150,7 @@ See also [`TypstCommand`](@ref).
 julia> typst`help` == typst`help`
 true
 
-julia> typst`help` == ignorestatus(typst`help`)
+julia> TypstCommand(["help"]) == TypstCommand(["help"]; ignorestatus = true)
 false
 ```
 """
@@ -236,7 +235,10 @@ hash(tc::TypstCommand, h::UInt) =
 """
     ignorestatus(::TypstCommand)
 
-See also [`TypstCommand`](@ref).
+Return a [`TypstCommand`](@ref) that does not throw a
+[`TypstError`](@ref) if the Typst compiler throws an error.
+
+Errors thrown by the Typst compiler are printed to `stderr` regardless.
 
 # Examples
 ```jldoctest
@@ -315,10 +317,8 @@ length(tc::TypstCommand) = length(tc.parameters) + 1
 See also [`TypstCommand`](@ref).
 
 !!! info
-    Errors from the Typst compiler are printed to `stderr`.
-    If [`ignorestatus`](@ref) has been applied,
-    this will not throw an error in Julia.
-    Otherwise, the Typst error will be printed before the Julia error.
+    If the Typst compiler throws an error, it will be printed to `stderr`.
+    Then, a Julia [`TypstError`](@ref) will be thrown unless the [`ignorestatus`](@ref) flag is set.
 
 # Examples
 ```jldoctest

src/strings.jl

@@ -48,7 +48,7 @@ in an `IOContext`. See also [`show_typst`](@ref) for a list of supported types.
 
 !!! info
     This type implements the `String` interface.
-    However, the interface is unspecified and may result in unexpected behavior.
+    However, the interface is unspecified, which may result in unexpected behavior.
 
 # Examples
 ```jldoctest
@@ -484,8 +484,6 @@ such that the defaults may be overwritten.
 To be compatible with merging contexts and constructing an `IOContext`,
 methods must return an `AbstractDict{Symbol}`.
 
-See also [`TypstString`](@ref).
-
 | Setting         | Default                  | Type           | Description                                                                                                                                                                       |
 |:----------------|:-------------------------|:---------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `:block`        | `false`                  | `Bool`         | When `:mode => math`, specifies whether the enclosing dollar signs are padded with a space to render the element inline or its own block.                                         |
@@ -837,14 +835,14 @@ julia> show(IOContext(stdout, :mode => code), "text/typst", Typst("a"))
 "\\\"a\\\""
 ```
 """
+show(io::IO, m::MIME"text/typst", t::Typst) = show(IOContext(io), m, t)
 function show(io::IOContext, ::MIME"text/typst", t::Typst)
     for (k, v) in context(t)
         io = IOContext(io, k => get(io, k, v))
     end
 
     show_typst(io, t)
 end
-show(io::IO, m::MIME"text/typst", t::Typst) = show(IOContext(io), m, t)
 show(io::IO, ::MIME"text/typst", t::Union{TypstString, TypstText}) = show_typst(io, t)
 
 """
@@ -856,8 +854,8 @@ Print the Portable Document Format (PDF), Portable Network Graphics (PNG),
 or Scalable Vector Graphics (SVG) format using [`render`](@ref).
 
 !!! note
-    Environments such as Pluto.jl notebooks use this
-    function to `display` [`TypstString`](@ref)s.
+    Environments, such as Pluto.jl notebooks,
+    may use these methods to `display` a [`TypstString`](@ref).
 """
 function show(io::IO, m::Union{
     MIME"application/pdf", MIME"image/png", MIME"image/svg+xml"