diff --git a/docs/src/getting_started.md b/docs/src/getting_started.md index d3d8ac7..ac5c336 100644 --- a/docs/src/getting_started.md +++ b/docs/src/getting_started.md @@ -23,7 +23,8 @@ 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(π) @@ -31,12 +32,7 @@ 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 $" ``` diff --git a/docs/src/index.md b/docs/src/index.md index 190beed..e157adf 100644 --- a/docs/src/index.md +++ b/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 diff --git a/docs/src/tutorials/interface.md b/docs/src/tutorials/interface.md index e06a566..0640e3a 100644 --- a/docs/src/tutorials/interface.md +++ b/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,14 +106,10 @@ 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\\\"]" @@ -121,7 +117,7 @@ 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 diff --git a/src/commands.jl b/src/commands.jl index 0afc1b3..e3bee26 100644 --- a/src/commands.jl +++ b/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,7 +91,7 @@ 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" @@ -99,16 +99,15 @@ 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 diff --git a/src/strings.jl b/src/strings.jl index ac0ad15..efe63c0 100644 --- a/src/strings.jl +++ b/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,6 +835,7 @@ 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)) @@ -844,7 +843,6 @@ function show(io::IOContext, ::MIME"text/typst", t::Typst) 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"