From fec22822ea73efd8923ae7383d673c51b33508cb Mon Sep 17 00:00:00 2001 From: David Vogel Date: Sun, 12 Jan 2025 14:57:32 +0100 Subject: [PATCH] Update README.md --- README.md | 49 ++++---- documentation/images/readme-1.svg | 185 +++++++++++++++--------------- readme_test.go | 6 +- 3 files changed, 123 insertions(+), 117 deletions(-) diff --git a/README.md b/README.md index 7bcecfc..b535782 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,66 @@ # go-typst [![test](https://github.com/Dadido3/go-typst/actions/workflows/test.yml/badge.svg)](https://github.com/Dadido3/go-typst/actions/workflows/test.yml) -A library to generate documents and reports by utilizing the command line version of [typst]. +`go-typst` is a Go library that leverages the command-line interface of [Typst] to provide functions for the creation of documents and reports in various formats (PDF, SVG, PNG). +Its goal is to provide Go developers with a seamless, "Go-like" interface to Typst's powerful document generation capabilities. -This is basically a binding to typst-cli which exposes functions needed to compile documents into different formats like PDF, SVG or PNG. The goal is to make using typst as simple and "go like" as possible. +## Stability and Compatibility -This module, along with typst itself, is a work in progress. -The API may change, and compatibility with different typst versions are also not set in stone. -There is no way to prevent this as long as typst has breaking changes. -To mitigate problems arising from this, most of the functionality is unit tested against different typst releases. -The supported and tested versions right now are: +`go-typst` is a work in progress, and the API may change as Typst evolves. +Supported Typst versions are tested by unit tests to ensure compatibility: -- Typst 0.12.0 +- **Supported Version:** Typst 0.12.0 + +While breaking changes may occur, i aim to minimize disruptions. +Use at your own discretion for production systems. ## Features - PDF, SVG and PNG generation. -- All typst-cli parameters are [available as a struct](cli-options.go), which makes it easy to discover all available options. -- Encoder to convert go values into typst markup which can be injected into typst documents. This includes image.Image by using the [Image wrapper](image.go). -- Any stderr will be returned as go error value, including line number, column and file path of the error. +- All Typst parameters are discoverable and documented in [cli-options.go](cli-options.go). +- Go-to-Typst Object Encoder: Seamlessly inject any Go values (Including `image.Image` with a [wrapper](image.go)) into Typst documents via the provided encoder. +- Errors from Typst CLI are returned as structured Go error objects with detailed information, such as line numbers and file paths. - Uses stdio; No temporary files will be created. - Good unit test coverage. ## Installation 1. Use `go get github.com/Dadido3/go-typst` inside of your project to add this module to your project. -2. Install typst by following [the instructions in the typst repository]. +2. Install Typst by following [the instructions in the Typst repository]. ## Runtime requirements -You need to have [typst] installed on any machine that you want to run your go project on. -You can install it by following [the instructions in the typst repository]. +This module assumes that the Typst executable is accessible from your system's PATH. +Ensure that you have [Typst] installed on any machine that your project will be executed. +You can install it by following [the instructions in the Typst repository]. -Alternatively you can pack the typst executable with your application. In this case you have to set up the CLI object similar to this: +Alternatively you can pack the Typst executable with your application. +In this case you have to provide the path to the executable when setting up the `typst.CLI` object: ```go typstCLI := typst.CLI{ - ExecutablePath: "./typst", + ExecutablePath: "./typst", // Relative path to executable. } ``` > [!NOTE] -> Make sure to follow the typst license requirements when you pack and distribute the typst executable with your software. +> Make sure to follow the Typst license requirements when you pack and distribute the Typst executable with your software. ## Usage -Here we will create a simple PDF document by passing a reader with typst markup into `typstCLI.Compile` and then let it write the resulting PDF data into a file: +Here we will create a simple PDF document by passing a reader with Typst markup into `typstCLI.Compile` and then let it write the resulting PDF data into a file: ```go func main() { r := bytes.NewBufferString(`#set page(width: 100mm, height: auto, margin: 5mm) = go-typst -A library to generate documents and reports by utilizing the command line version of typst. +A library to generate documents and reports by utilizing the command line version of Typst. #footnote[https://typst.app/] == Features -- Encoder to convert go objects into typst objects which then can be injected into typst documents. -- Parsing of returned errors into go error objects. +- Encoder to convert Go objects into Typst objects which then can be injected into Typst documents. +- Parsing of returned errors into Go error objects. - Uses stdio; No temporary files need to be created. - Test coverage of most features.`) @@ -79,5 +82,5 @@ The resulting document will look like this: ![readme-1.svg](documentation/images/readme-1.svg) -[the instructions in the typst repository]: https://github.com/typst/typst?tab=readme-ov-file#installation -[typst]: https://typst.app/ +[the instructions in the Typst repository]: https://github.com/typst/typst?tab=readme-ov-file#installation +[Typst]: https://typst.app/ diff --git a/documentation/images/readme-1.svg b/documentation/images/readme-1.svg index b10055f..6b2fb72 100644 --- a/documentation/images/readme-1.svg +++ b/documentation/images/readme-1.svg @@ -96,15 +96,15 @@ - - - - - - + + + + + + - + @@ -153,76 +153,76 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -259,21 +259,21 @@ - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + @@ -490,6 +490,9 @@ + + + @@ -523,6 +526,9 @@ + + + @@ -544,9 +550,6 @@ - - - diff --git a/readme_test.go b/readme_test.go index f352232..c5dd754 100644 --- a/readme_test.go +++ b/readme_test.go @@ -12,13 +12,13 @@ func TestREADME1(t *testing.T) { r := bytes.NewBufferString(`#set page(width: 100mm, height: auto, margin: 5mm) = go-typst -A library to generate documents and reports by utilizing the command line version of typst. +A library to generate documents and reports by utilizing the command line version of Typst. #footnote[https://typst.app/] == Features -- Encoder to convert go objects into typst objects which then can be injected into typst documents. -- Parsing of returned errors into go error objects. +- Encoder to convert Go objects into Typst objects which then can be injected into Typst documents. +- Parsing of returned errors into Go error objects. - Uses stdio; No temporary files need to be created. - Test coverage of most features.`)