From 65270444b44ce14dd296d7ea89ef0ca0505a646d Mon Sep 17 00:00:00 2001 From: Jakob Peters Date: Fri, 8 Nov 2024 19:11:02 -0800 Subject: [PATCH] Fix and update documentation --- NEWS.md | 1 + docs/make.jl | 25 ++-- .../source/guides/package_interoperability.md | 9 +- docs/source/references/commands.md | 35 +---- docs/source/references/internals.md | 74 +++++------ docs/source/references/package_extensions.md | 4 +- docs/source/references/strings.md | 24 +--- docs/source/references/utilities.md | 13 ++ docs/source/tutorials/getting_started.md | 2 +- ext/LaTeXStringsExtension.jl | 6 +- ext/MarkdownExtension.jl | 6 +- src/commands/commands.jl | 71 +++++----- src/commands/typst_command.jl | 6 +- src/commands/typst_command_error.jl | 2 +- src/strings/show_typst.jl | 8 +- src/strings/strings.jl | 37 +++--- src/strings/types.jl | 123 ------------------ src/strings/typst.jl | 38 ++++++ src/strings/typst_string.jl | 19 ++- src/strings/typst_text.jl | 40 ++++++ src/utilities/context_error.jl | 2 +- src/utilities/mode.jl | 53 ++++++++ src/{strings => utilities}/typst_context.jl | 33 +++++ src/utilities/utilities.jl | 7 +- 24 files changed, 319 insertions(+), 319 deletions(-) create mode 100644 docs/source/references/utilities.md delete mode 100644 src/strings/types.jl create mode 100644 src/strings/typst.jl create mode 100644 src/strings/typst_text.jl create mode 100644 src/utilities/mode.jl rename src/{strings => utilities}/typst_context.jl (77%) diff --git a/NEWS.md b/NEWS.md index 6d01768..97c7d0e 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,6 +3,7 @@ ## v0.5.0 +- Improved documentation - `TypstError` renamed to `TypstCommandError` - `TypstContext` - `preamble` and `set_preamble` replaced by `context::TypstContext` and `set_context` diff --git a/docs/make.jl b/docs/make.jl index 26a1908..2575706 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -7,8 +7,7 @@ using .DocMeta: setdocmeta! using LaTeXStrings: LaTeXString using Luxor: Drawing, finish, julia_blue, julia_green, julia_purple, julia_red, rect, sethue using Markdown: MD -using Typstry: Strings, preamble -using .Strings: examples, _show_typst, enclose, join_with, typst_mime +using Typstry: _show_typst, enclose, examples, join_with, preamble, typst_mime using Typstry const assets = joinpath(@__DIR__, "source", "assets") @@ -52,7 +51,7 @@ finish() open(template; truncate = true) do file println(file, "\n#import table: cell, header\n\n#let template(document) = {") - for x in split(preamble, "\n") + for x in split(preamble(context), "\n") println(file, " ", x[2:end]) end @@ -114,7 +113,7 @@ for (package, examples) in append!([("Typstry", examples)], zip(extensions, _exa print(file, "\",", v isa Union{Vector, Matrix} ? "\n " : " ") join_with(file, modes, ", ") do file, mode - _show_typst(IOContext(file, :mode => code), String(TypstString(v; mode))) + _show_typst(file, String(TypstString(v; mode)); mode = code) print(file, ", [") enclose(_show_typst, file, TypstString(v; mode, depth = 2), ( if mode == code; ("#", "") @@ -132,16 +131,12 @@ for (package, examples) in append!([("Typstry", examples)], zip(extensions, _exa run(TypstCommand(["compile", "--font-path=" * julia_mono, "--format=svg", path])) end -makedocs(; modules, - format = Documenter.HTML(edit_link = "main"), - pages = [ - "Typstry.jl" => "index.md", - pages("tutorials", ["getting_started"]), - pages("guides", ["typst_formatting_examples", "the_julia_to_typst_interface", "package_interoperability"]), - pages("references", ["strings", "commands", "package_extensions", "internals"]) - ], - sitename = "Typstry.jl", - source = "source" -) +makedocs(; modules, format = Documenter.HTML(edit_link = "main"), pages = [ + "Typstry.jl" => "index.md", + pages("tutorials", ["getting_started"]), + pages("guides", [ + "typst_formatting_examples", "the_julia_to_typst_interface", "package_interoperability" + ]), pages("references", ["strings", "commands", "utilities", "package_extensions", "internals"]) +], sitename = "Typstry.jl", source = "source") deploydocs(; devurl = "development", repo = "github.com/jakobjpeters/Typstry.jl.git") diff --git a/docs/source/guides/package_interoperability.md b/docs/source/guides/package_interoperability.md index 641b069..bd31812 100644 --- a/docs/source/guides/package_interoperability.md +++ b/docs/source/guides/package_interoperability.md @@ -5,9 +5,12 @@ This guide illustrates how to use Typstry.jl in compatible notebooks and package ## Notebooks -IJulia.jl, Pluto.jl, and QuartoNotebookRunner.jl each [`render`](@ref) [`Typst`](@ref)s and [`TypstText`](@ref)s. -Pluto.jl and QuartoNotebookRunner.jl also `render` [`TypstString`](@ref)s, -whereas IJulia.jl will support them in its next feature release. +IJulia.jl, Pluto.jl, and QuartoNotebookRunner.jl each display +[`TypstString`](@ref)s, [`TypstText`](@ref)s, and [`Typst`](@ref)s using +`show` with the `application/pdf`, `image/png`, and `image/svg+xml` `MIME` types. + +!!! tip + Use [`set_context`](@ref) to customize the default formatting in these environments. ## Typst Packages diff --git a/docs/source/references/commands.md b/docs/source/references/commands.md index f1dcf31..d6f2b92 100644 --- a/docs/source/references/commands.md +++ b/docs/source/references/commands.md @@ -1,44 +1,13 @@ # Commands -```@eval -using Markdown, Typstry -Markdown.parse("This reference documents " * lowercasefirst(split(string(@doc Typstry.Commands), "\n")[5])) -``` - -## `Typstry` +This reference documents how to interact with the Typst compiler. ```@docs -TypstCommand TypstCommandError +TypstCommand @typst_cmd julia_mono -preamble render -set_preamble typst ``` - -## `Base` - -```@docs -== -addenv -detach -eltype -firstindex -getindex -hash -ignorestatus -iterate(::TypstCommand) -keys -lastindex -length -run -setcpuaffinity -setenv -show(::IO, ::MIME"text/plain", ::TypstCommand) -show(::IO, ::MIME"text/plain", ::TypstCommandError) -show(::IO, ::Union{MIME"application/pdf", MIME"image/png", MIME"image/svg+xml"}, ::Union{Typst, TypstString, TypstText}) -showerror(::IO, ::TypstCommandError) -``` diff --git a/docs/source/references/internals.md b/docs/source/references/internals.md index aaed83b..683b4ed 100644 --- a/docs/source/references/internals.md +++ b/docs/source/references/internals.md @@ -3,52 +3,50 @@ This reference documents non-public utilities. -```@docs -Typstry.compile_workload -Typstry.unwrap -``` - -## Strings +!!! info + A Dates.jl package extension would currently print warnings during precompilation. + See also the [Julia issue #52511](https://github.com/JuliaLang/julia/issues/52511) ```@docs -Typstry.Strings -Typstry.Strings.examples -Typstry.Strings.typst_mime -Typstry.Strings.backticks -Typstry.Strings.block -Typstry.Strings.code_mode -Typstry.Strings.depth -Typstry.Strings.enclose -Typstry.Strings.escape -Typstry.Strings.indent -Typstry.Strings.join_with -Typstry.Strings.math_mode -Typstry.Strings.math_pad -Typstry.Strings.mode -Typstry.Strings.parenthesize -Typstry.Strings.show_array -Typstry.Strings.show_parameters -Typstry.Strings.show_raw -Typstry.Strings.show_vector +Typstry.examples ``` -### Dates.jl - -!!! info - A Dates.jl package extension would currently print warnings during precompilation. - See also the [Julia issue #52511](https://github.com/JuliaLang/julia/issues/52511) +## Utilities.jl ```@docs -Typstry.Strings.date_time -Typstry.Strings.duration -Typstry.Strings.dates +Typstry.typst_mime +Typstry.apply +Typstry.compile_workload +Typstry.code_mode +Typstry.date_time +Typstry.dates +Typstry.default_context +Typstry.duration +Typstry.enclose +Typstry.escape +Typstry.indent +Typstry.format +Typstry.join_with +Typstry.math_mode +Typstry.math_pad +Typstry.merge_contexts! +Typstry.show_array +Typstry.show_parameters +Typstry.show_raw +Typstry.show_vector +Typstry.typst_context +Typstry.unwrap ``` -## Commands +## Strings ```@docs -Typstry.Commands -Typstry.Commands.default_preamble -Typstry.Commands.apply -Typstry.Commands.format +Typstry.backticks +Typstry.base_type +Typstry.block +Typstry.depth +Typstry.mode +Typstry.parenthesize +Typstry.preamble +Typstry.tab_size ``` diff --git a/docs/source/references/package_extensions.md b/docs/source/references/package_extensions.md index 9d43fae..635425a 100644 --- a/docs/source/references/package_extensions.md +++ b/docs/source/references/package_extensions.md @@ -7,11 +7,11 @@ This reference documents the lazily-loaded implementations of ## LaTeXStrings.jl ```@docs -show_typst(::Any, ::LaTeXStrings.LaTeXString) +show_typst(::Any, ::Any, ::LaTeXStrings.LaTeXString) ``` ## Markdown.jl ```@docs -show_typst(::Any, ::Markdown.MD) +show_typst(::Any, ::Any, ::Markdown.MD) ``` diff --git a/docs/source/references/strings.md b/docs/source/references/strings.md index e3cdd94..66b150f 100644 --- a/docs/source/references/strings.md +++ b/docs/source/references/strings.md @@ -1,27 +1,15 @@ # Strings -```@eval -using Markdown, Typstry -Markdown.parse("This reference documents " * lowercasefirst(split(string(@doc Typstry.Strings), "\n")[5])) -``` +This reference documents formatting Julia values into Typst source text. ```@docs -ContextError -Mode -Typst TypstString TypstText +Typst @typst_str -code -markup -math -context -show_typst(::Any, ::AbstractChar) -``` - -```@docs -show(::IO, ::MIME"text/plain", ::ContextError) -show(::IO, ::MIME"text/typst", ::Typst) -showerror(::IO, ::ContextError) +show_typst +show_typst(::Any, ::Any, ::TypstString) +show_typst(::Any, ::Any, ::TypstText) +show_typst(::Any, ::Any, ::Typst) ``` diff --git a/docs/source/references/utilities.md b/docs/source/references/utilities.md new file mode 100644 index 0000000..63ab75a --- /dev/null +++ b/docs/source/references/utilities.md @@ -0,0 +1,13 @@ + +# Utilities + +```@docs +Mode +code +markup +math +ContextError +TypstContext +context +set_context +``` diff --git a/docs/source/tutorials/getting_started.md b/docs/source/tutorials/getting_started.md index 85a8e8e..75f392d 100644 --- a/docs/source/tutorials/getting_started.md +++ b/docs/source/tutorials/getting_started.md @@ -40,7 +40,7 @@ typst"$ π approx 3.141592653589793 $" ## Commands -Use the Typst command-line interface by [`run`](@ref)ning a +Use the Typst command-line interface by `run`ning a [`TypstCommand`](@ref) created with its constructor or [`@typst_cmd`](@ref). ```jldoctest 1 diff --git a/ext/LaTeXStringsExtension.jl b/ext/LaTeXStringsExtension.jl index 607a3ac..ac34955 100644 --- a/ext/LaTeXStringsExtension.jl +++ b/ext/LaTeXStringsExtension.jl @@ -6,9 +6,11 @@ using LaTeXStrings: LaTeXString, @L_str using Typstry: compile_workload, show_raw """ - show_typst(io, ::LaTeXString) + show_typst(::IO, ::TypstContext, ::LaTeXString) -Print in Typst format for LaTeXStrings.jl. +Print a raw text block in Typst format. + +See also [`TypstContext`](@ref Typstry.TypstContext). | Type | Settings | Parameters | |:--------------|:-----------------------------------------|:-----------| diff --git a/ext/MarkdownExtension.jl b/ext/MarkdownExtension.jl index d1298af..50b773c 100644 --- a/ext/MarkdownExtension.jl +++ b/ext/MarkdownExtension.jl @@ -6,9 +6,11 @@ using Markdown: MD, @md_str using Typstry: compile_workload, show_raw """ - show_typst(io, ::Markdown.MD) + show_typst(::IO, ::TypstContext, ::Markdown.MD) -Print in Typst format for Markdown.jl. +Print a raw text block in Typst format. + +See also [`TypstContext`](@ref Typstry.TypstContext). | Type | Settings | Parameters | |:--------------|:-----------------------------------------|:-----------| diff --git a/src/commands/commands.jl b/src/commands/commands.jl index 7806795..ad811b4 100644 --- a/src/commands/commands.jl +++ b/src/commands/commands.jl @@ -8,8 +8,21 @@ include("typst_command_error.jl") A constant `String` file path to the [JuliaMono](https://github.com/cormullion/juliamono) typeface. -Use with a [`TypstCommand`](@ref) and one of [`addenv`](@ref), -[`setenv`](@ref), or the `font-path` Typst command-line option. +This typeface is available when using one of the following approaches: + +- `TypstCommand(["compile", "input.typ", "output.pdf", "--font-path=" * julia_mono)` +- `addenv(::TypstCommand,\u00A0"TYPST_FONT_PATHS"\u00A0=>\u00A0julia_mono)` +- `setenv(::TypstCommand,\u00A0"TYPST_FONT_PATHS"\u00A0=>\u00A0julia_mono)` +- `ENV["TYPST_FONT_PATHS"] = julia_mono` + +and when compiling documents with the following methods: + +- [`render`](@ref) +- [`typst`](@ref) +- `show` with the `application/pdf`, `image/png`, and `image/svg+xml` + `MIME` types and a `TypstString`, `TypstText`, and `Typst` value + +See also [`TypstCommand`](@ref). """ const julia_mono = artifact"JuliaMono" @@ -24,17 +37,18 @@ render!(tc) = merge_contexts!(tc, context) context = TypstContext() ) -Render to a document using -[`show(::IO,\u00A0::MIME"text/typst",\u00A0::Typst)`](@ref). +Render the `value` to a document. This first generates the `input` file containing -the [`preamble`](@ref) and formatted `value`. +the `preamble` and formatted `value`. Then it is compiled to the `output` document, whose format is inferred by its file extension to be `pdf`, `png`, or `svg`. The document may be automatically `open`ed by the default viewer. -The [`ignorestatus`](@ref) flag may be set. +The `ignorestatus` flag may be set. This supports using the [`julia_mono`](@ref) typeface. +See also [`TypstContext`](@ref). + # Examples ```jldoctest @@ -59,37 +73,6 @@ function render(value; ignorestatus)) end -""" - show(::IO, ::Union{ - MIME"application/pdf", MIME"image/png", MIME"image/svg+xml" - }, ::Union{Typst, TypstString, TypstText}) - -Print the Portable Document Format (PDF), Portable Network Graphics (PNG), -or Scalable Vector Graphics (SVG) format. - -The `preamble` keyword parameter used by [`render`](@ref) may be specified in an `IOContext`. -Environments, such as Pluto.jl notebooks, may use these methods to `display` values of type -[`Typst`](@ref), [`TypstString`](@ref), and [`TypstText`](@ref). -This supports using the [`julia_mono`](@ref) typeface. - -# Examples - -```jldoctest -julia> show(IOContext(devnull, :preamble => typst""), "image/svg+xml", Typst(1)) -``` -""" -function show(io::IO, m::Union{ - MIME"application/pdf", MIME"image/png", MIME"image/svg+xml" -}, t::Union{Typst, TypstString, TypstText}) - input = tempname() - output = input * "." * format(m) - - render(t; input, output, open = false, ignorestatus = false, context = typst_context(io)) - write(io, read(output)) - - nothing -end - """ typst(::AbstractString; catch_interrupt = true, ignorestatus = true) @@ -99,7 +82,7 @@ on spaces and does not provide any shell-style escape mechanism, so it will not work if there are, e.g., filenames with spaces. When `catch_interrupt` is true, CTRL-C quietly quits the command. -When [`ignorestatus`](@ref) is true, a Typst failure will not imply a julia error. +When `ignorestatus` is true, a Typst failure will not imply a julia error. If the `"TYPST_FONT_PATHS"` environment variable is not set, it is temporarily set to [`julia_mono`](@ref). @@ -115,3 +98,15 @@ function typst(parameters::AbstractString; catch_interrupt = true, ignorestatus end nothing end + +function show(io::IO, m::Union{ + MIME"application/pdf", MIME"image/png", MIME"image/svg+xml" +}, t::Union{Typst, TypstString, TypstText}) + input = tempname() + output = input * "." * format(m) + + render(t; input, output, open = false, ignorestatus = false, context = typst_context(io)) + write(io, read(output)) + + nothing +end diff --git a/src/commands/typst_command.jl b/src/commands/typst_command.jl index 10f15cd..8ae870e 100644 --- a/src/commands/typst_command.jl +++ b/src/commands/typst_command.jl @@ -14,7 +14,6 @@ However, the interface is undocumented, which may result in unexpected behavior. - `addenv(::TypstCommand,\u00A0env...;\u00A0::Bool\u00A0=\u00A0true)` - Can be used with [`julia_mono`](@ref) - - `addenv(::TypstCommand,\u00A0"TYPST_FONT_PATHS"\u00A0=>\u00A0julia_mono)` - `detach(::TypstCommand)` - `eltype(::Type{TypstCommand})` - `firstindex(::TypstCommand)` @@ -31,11 +30,10 @@ However, the interface is undocumented, which may result in unexpected behavior. - `run(::TypstCommand,\u00A0args...;\u00A0::Bool\u00A0=\u00A0true)` - Errors thrown by the Typst compiler will be printed to `stderr`. Then, a Julia [`TypstCommandError`](@ref) will be - thrown unless the [`ignorestatus`](@ref) flag is set. + thrown unless the `ignorestatus` flag is set. - `setcpuaffinity(::TypstCommand,\u00A0cpus)` - `setenv(::TypstString,\u00A0env...;\u00A0kwargs...)` - - Can be used with [`julia_mono`](@ref) - - `setenv(::TypstCommand,\u00A0"TYPST_FONT_PATHS"\u00A0=>\u00A0julia_mono)` + - Can be used with `julia_mono` - `show(::IO,\u00A0::MIME"text/plain",\u00A0::TypstCommand)` # Examples diff --git a/src/commands/typst_command_error.jl b/src/commands/typst_command_error.jl index ccc73a7..4b2b589 100644 --- a/src/commands/typst_command_error.jl +++ b/src/commands/typst_command_error.jl @@ -3,7 +3,7 @@ TypstCommandError <: Exception TypstCommandError(::TypstCommand) -An `Exception` indicating a failure to [`run`](@ref) a [`TypstCommand`](@ref). +An `Exception` indicating a Typst compiler error from a [`TypstCommand`](@ref). # Interface diff --git a/src/strings/show_typst.jl b/src/strings/show_typst.jl index d1ad3fb..b3417f3 100644 --- a/src/strings/show_typst.jl +++ b/src/strings/show_typst.jl @@ -57,7 +57,7 @@ end show_typst(io, tc, x::HTML) = show_raw((io, x) -> show(io, MIME"text/html"(), x), io, tc, x, "html") show_typst(io, tc, x::Irrational) = mode(tc) == code ? _show_typst(io, tc, Float64(x)) : - math_mode(print, io, tc, x) + math_mode((io, _, x) -> print(io, x), io, tc, x) function show_typst(io, tc, ::Nothing) code_mode(io, tc) print(io, "none") @@ -90,7 +90,6 @@ function show_typst(io, tc, x::Text) code_mode(io, tc) _show_typst(io, string(x)) end -show_typst(io, tc, x::TypstString) = print(io, x) function show_typst(io, tc, x::Unsigned) code_mode(io, tc) show(io, x) @@ -147,11 +146,6 @@ Some settings, such as `block`, correspond with a parameter but may also be used !!! tip Please create an issue or pull-request to implement new methods. -!!! info - Some types, particularly containers, may call - [`show(::IO,\u00A0::MIME"text/typst",\u00A0::Typst)`](@ref) - to format a value, which may use additional settings and parameters. - | Type | Settings | Parameters | |:----------------------------------------------------------|:-----------------------------------------|:--------------------------------------------------------| | `AbstractArray` | `:block`, `:depth`, `:mode`, `:tab_size` | `:delim`, `:gap` | diff --git a/src/strings/strings.jl b/src/strings/strings.jl index 89dc05f..0a5736d 100644 --- a/src/strings/strings.jl +++ b/src/strings/strings.jl @@ -1,33 +1,28 @@ -include("types.jl") -include("typst_context.jl") -include("typst_string.jl") include("show_typst.jl") +include("typst_text.jl") +include("typst.jl") +include("typst_string.jl") -""" - show(::IO, ::MIME"text/typst", ::Union{Typst, TypstString, TypstText}) - -Print in Typst format using [`show_typst`](@ref) and -formatting data specified by a [`TypstContext`](@ref). - -The formatting data is given by combining the [`context`](@ref), -the `TypstContext` constructor implemented for the given type, -and the `IOContext` key `:typst_context` such that each successive -context overwrites duplicate keys in previous contexts. +_show(io::IOContext, x) = _show_typst(io, typst_context(io), x) +_show(io::IO, x) = _show_typst(io, x) -See also [`TypstString`](@ref) and [`TypstText`](@ref). -""" -show(io::IO, ::MIME"text/typst", t::Union{Typst, TypstString, TypstText}) = - _show_typst(io, t) -show(io::IOContext, ::MIME"text/typst", t::Union{Typst, TypstString, TypstText}) = - _show_typst(io, typst_context(io), t) +show(io::IO, ::MIME"text/typst", x::Union{Typst, TypstString, TypstText}) = + _show(io, x) -function show(io::IO, x::T) where T <: Union{TypstText, Typst} - print(io, nameof(T), "(") +function show(io::IO, x::Union{TypstText, Typst}) + print(io, base_type(x), "(") show(io, x.value) print(io, ")") end +base_type(::TypstText) = TypstText +base_type(::Typst) = Typst + +@doc """ + base_type(x) +""" base_type + get!(context.context, :preamble, typst""" #set page(margin: 1em, height: auto, width: auto, fill: white) #set text(16pt, font: "JuliaMono") diff --git a/src/strings/types.jl b/src/strings/types.jl deleted file mode 100644 index 0ff8eae..0000000 --- a/src/strings/types.jl +++ /dev/null @@ -1,123 +0,0 @@ - -""" - TypstText{T} - TypstText(::Any) - -A wrapper whose [`show_typst`](@ref) method uses `print` on the wrapped value. - -# Interface - -- `show_typst(::IO,\u00A0::TypstContext,\u00A0::TypstText)` -- `show(::IO,\u00A0::Union{MIME"application/pdf",\u00A0MIME"image/png",\u00A0MIME"image/svg+xml"},\u00A0::TypstText)` -- `show(::IO,\u00A0::TypstText)` - -# Examples - -```jldoctest -julia> TypstText(1) -TypstText(1) - -julia> TypstText("a") -TypstText("a") -``` -""" -struct TypstText{T} - value::T -end - -""" - Typst{T} - Typst(::T) - -A wrapper used to pass values to [`show_typst`](@ref). - -# Interface - -- `show_typst(::IO,\u00A0::TypstContext,\u00A0::Typst)` -- `show(::IO,\u00A0::Union{MIME"application/pdf",\u00A0MIME"image/png",\u00A0MIME"image/svg+xml"},\u00A0::Typst)` -- `show(::IO,\u00A0::Typst)` - -# Examples - -```jldoctest -julia> Typst(1) -Typst(1) - -julia> Typst("a") -Typst("a") -``` -""" -struct Typst{T} - value::T -end - -""" - Mode - -An `Enum`erated type used to specify that the current Typst syntactical -context is [`code`](@ref), [`markup`](@ref), or [`math`](@ref). - -# Examples - -```jldoctest -julia> Mode -Enum Mode: -code = 0 -markup = 1 -math = 2 -``` -""" -@enum Mode code markup math - -@doc """ - code - -A Typst syntactical [`Mode`](@ref) prefixed by the number sign. - -# Examples - -```jldoctest -julia> code -code::Mode = 0 -``` -""" code - -@doc """ - markup - -A Typst syntactical [`Mode`](@ref) at the top-level of source text and enclosed within square brackets. - -```jldoctest -julia> markup -markup::Mode = 1 -``` -""" markup - -@doc """ - math - -A Typst syntactical [`Mode`](@ref) enclosed within dollar signs. - -```jldoctest -julia> math -math::Mode = 2 -``` -""" math - -""" - show_typst(::IO, ::TypstContext, ::TypstText) - -Call `print` the value wrapped in [`TypstText`](@ref). - -See also [`TypstContext`](@ref). -""" -show_typst(io, _, tt::TypstText) = print(io, tt.value) - -""" - show_typst(::IO, ::TypstContext, ::Typst) - -Call [`show_typst`](@ref) on the value wrapped in [`Typst`](@ref). - -See also [`TypstContext`](@ref). -""" -show_typst(io, tc, x::Typst) = _show_typst(io, tc, x.value) diff --git a/src/strings/typst.jl b/src/strings/typst.jl new file mode 100644 index 0000000..c4a7e8b --- /dev/null +++ b/src/strings/typst.jl @@ -0,0 +1,38 @@ + +""" + Typst{T} + Typst(::T) + +A wrapper used to pass values to [`show_typst`](@ref). + +# Interface + +- `show_typst(::IO,\u00A0::TypstContext,\u00A0::Typst)` +- `show(::IO,\u00A0::Union{MIME"application/pdf",\u00A0MIME"image/png",\u00A0MIME"image/svg+xml",\u00A0MIME"text/typst"},\u00A0::Typst)` + - Accepts a `IOContext(::IO,\u00A0:typst_context\u00A0=>\u00A0::TypstContext)` + - Supports the [`julia_mono`](@ref) typeface + - The generated Typst source text contains the context's `preamble` and the formatted value +- `show(::IO,\u00A0::Typst)` + +# Examples + +```jldoctest +julia> Typst(1) +Typst(1) + +julia> Typst("a") +Typst("a") +``` +""" +struct Typst{T} + value::T +end + +""" + show_typst(::IO, ::TypstContext, ::Typst) + +Call [`show_typst`](@ref) on the value wrapped in [`Typst`](@ref). + +See also [`TypstContext`](@ref). +""" +show_typst(io, tc, x::Typst) = _show_typst(io, tc, x.value) diff --git a/src/strings/typst_string.jl b/src/strings/typst_string.jl index 4199f9d..bad3ffe 100644 --- a/src/strings/typst_string.jl +++ b/src/strings/typst_string.jl @@ -6,9 +6,7 @@ Format the value as a Typst formatted string. -The [`TypstContext`](@ref) is passed to -`show(::IO,\u00A0::MIME"text/typst",\u00A0::Any)` -as the `IOContext` parameter `:typst_context`. +The [`TypstContext`](@ref) is combined with additional context and passed to [`show_typst`](@ref). # Interface @@ -27,9 +25,15 @@ However, the interface is undocumented, which may result in unexpected behavior. - This method patches incorrect output from the assumption in `repr` that the parameter is already in the requested `MIME` type when the `MIME` type satisfies `istextmime` and the parameter is an `AbstractString`. +- `show_typst(::IO,\u00A0::TypstContext,\u00A0::TypstString)` +- `show(::IO,\u00A0::MIME"text/typst",\u00A0::TypstString)` + - Accepts a `IOContext(::IO,\u00A0:typst_context\u00A0=>\u00A0::TypstContext)` - `show(::IO,\u00A0::Union{MIME"application/pdf",\u00A0MIME"image/png",\u00A0MIME"image/svg+xml"},\u00A0::TypstString)` + - Accepts a `IOContext(::IO,\u00A0:typst_context\u00A0=>\u00A0::TypstContext)` + - Supports the [`julia_mono`](@ref) typeface + - The generated Typst source text contains the context's `preamble` and the formatted value - `show(::IO,\u00A0::TypstString)` - - Print in [`@typst_str`](@ref) format if each character satisfies `isprint`. + - Prints in [`@typst_str`](@ref) format if each character satisfies `isprint`. Otherwise, print in [`TypstString`](@ref) format. # Examples @@ -69,7 +73,7 @@ Interpolation syntax may be escaped in the same manner as quotation marks. !!! tip Print directly to an `IO` using - [`show(::IO,\u00A0::MIME"text/typst",\u00A0::Typst)`](@ref). + `show(::IO,\u00A0::MIME"text/typst",\u00A0::Typst)`. See also the performance tip to [Avoid string interpolation for I/O] (https://docs.julialang.org/en/v1/manual/performance-tips/#Avoid-string-interpolation-for-I/O). @@ -119,6 +123,11 @@ macro typst_str(s::String) :(TypstString(TypstText($_s))) end +""" + show_typst(::IO, ::TypstContext, ::TypstString) +""" +show_typst(io, tc, x::TypstString) = print(io, x) + IOBuffer(ts::TypstString) = IOBuffer(ts.text) codeunit(ts::TypstString) = codeunit(ts.text) diff --git a/src/strings/typst_text.jl b/src/strings/typst_text.jl new file mode 100644 index 0000000..9dbbc6a --- /dev/null +++ b/src/strings/typst_text.jl @@ -0,0 +1,40 @@ + +""" + TypstText{T} + TypstText(::Any) + +A wrapper whose [`show_typst`](@ref) method uses `print` on the wrapped value. + +# Interface + +- `show_typst(::IO,\u00A0::TypstContext,\u00A0::TypstText)` +- `show(::IO,\u00A0::MIME"text/typst",\u00A0::TypstText)` + - Accepts `IOContext(::IO,\u00A0:typst_context\u00A0=>\u00A0::TypstContext)` +- `show(::IO,\u00A0::Union{MIME"application/pdf",\u00A0MIME"image/png",\u00A0MIME"image/svg+xml"},\u00A0::TypstText)` + - Accepts `IOContext(::IO,\u00A0:typst_context\u00A0=>\u00A0::TypstContext)` + - Supports the [`julia_mono`](@ref) typeface + - The generated Typst source text contains the context's `preamble` and the formatted value +- `show(::IO,\u00A0::TypstText)` + +# Examples + +```jldoctest +julia> TypstText(1) +TypstText(1) + +julia> TypstText("a") +TypstText("a") +``` +""" +struct TypstText{T} + value::T +end + +""" + show_typst(::IO, ::TypstContext, ::TypstText) + +Call `print` the value wrapped in [`TypstText`](@ref). + +See also [`TypstContext`](@ref). +""" +show_typst(io, _, tt::TypstText) = print(io, tt.value) diff --git a/src/utilities/context_error.jl b/src/utilities/context_error.jl index 558e97e..aa7e46e 100644 --- a/src/utilities/context_error.jl +++ b/src/utilities/context_error.jl @@ -3,7 +3,7 @@ ContextError <: Exception ContextError(::Type, ::Type, ::Symbol) -An `Exception` indicating that a [`context`](@ref) key returned a value of an incorrect type. +An `Exception` indicating that a context key returned a value of an incorrect type. # Interface diff --git a/src/utilities/mode.jl b/src/utilities/mode.jl new file mode 100644 index 0000000..771099d --- /dev/null +++ b/src/utilities/mode.jl @@ -0,0 +1,53 @@ + +""" + Mode + +An `Enum`erated type used to specify that the current Typst syntactical +context is [`code`](@ref), [`markup`](@ref), or [`math`](@ref). + +# Examples + +```jldoctest +julia> Mode +Enum Mode: +code = 0 +markup = 1 +math = 2 +``` +""" +@enum Mode code markup math + +@doc """ + code + +A Typst syntactical [`Mode`](@ref) prefixed by the number sign. + +# Examples + +```jldoctest +julia> code +code::Mode = 0 +``` +""" code + +@doc """ + markup + +A Typst syntactical [`Mode`](@ref) at the top-level of source text and enclosed within square brackets. + +```jldoctest +julia> markup +markup::Mode = 1 +``` +""" markup + +@doc """ + math + +A Typst syntactical [`Mode`](@ref) enclosed within dollar signs. + +```jldoctest +julia> math +math::Mode = 2 +``` +""" math diff --git a/src/strings/typst_context.jl b/src/utilities/typst_context.jl similarity index 77% rename from src/strings/typst_context.jl rename to src/utilities/typst_context.jl index 14d4c4a..bc3d792 100644 --- a/src/strings/typst_context.jl +++ b/src/utilities/typst_context.jl @@ -8,6 +8,30 @@ Provide formatting data for [`show_typst`](@ref). Implement a method of this constructor for a custom type to specify its custom settings and parameters. +Calls to [`show_typst`](@ref) from the following methods: + +- [`TypstString`](@ref) +- [`render`](@ref) +- `show_typst(::IO,\u00A0::TypstContext,\u00A0x)` +- `show` with the `application/pdf`, `image/png`, `image/svg+xml`, and `text/typst` + `MIME` types and a `TypstString`, `TypstText`, and `Typst` value + +specify the [`TypstContext`](@ref) by combining the following contexts: + +1. A default [`context`](@ref) +2. The context specified by [`set_context`](@ref), + which is combined with the `context` upon initialization +3. The `TypstContext` constructor implemented for the given type, + the context specified in the call by keyword parameters, + a given `TypstContext`, or the `IOContext` key `:typst_context`, + depending on the calling method +4. Any context specified by a recursive call in `show_typst` to format values, + such as elements from a container + +Duplicate keys are handled such that each successive context overwrites +those of previous contexts, prioritized in order as listed. +In other words, the default `context` has the lowest priority while +recursive calls to `show_typst` have the highest priority. # Interfaces This type implements the dictionary and iteration interfaces. @@ -63,6 +87,11 @@ const default_context = TypstContext(; tab_size = 2 ) +""" + merge_contexts!(tc, context) +""" +merge_contexts!(tc, context) = mergewith!((x, _) -> x, tc.context, context) + """ context @@ -118,5 +147,9 @@ the [`context`](@ref) is initialized to the given Specifying a key contained in the default settings will override it. If a `TypstContext` is not provided, the `context` is reset to the default settings. + +!!! tip + Use this function to customize the default formatting in environments that display values using + `show` with the `application/pdf`, `image/png`, and `image/svg+xml` `MIME` types. """ set_context diff --git a/src/utilities/utilities.jl b/src/utilities/utilities.jl index eff6d65..39385e0 100644 --- a/src/utilities/utilities.jl +++ b/src/utilities/utilities.jl @@ -1,5 +1,7 @@ include("context_error.jl") +include("mode.jl") +include("typst_context.jl") """ typst_mime @@ -198,11 +200,6 @@ math_pad(tc) = else block(tc) ? "\$ " : "\$" end -""" - merge_contexts(tc, context) -""" -merge_contexts!(tc, context) = mergewith!((x, _) -> x, tc.context, context) - """ show_array(io, x) """