diff --git a/docs/book/src/README.md b/docs/book/src/README.md index dc687c7..4ec76b9 100644 --- a/docs/book/src/README.md +++ b/docs/book/src/README.md @@ -17,7 +17,7 @@ This book contains a few sections aimed at answering the most common questions r - [Features](./quickstart/features.md) introduces various concepts to help you use `typst-test` effectively. - [Configuration](.quickstart/config.md) explains commonly used configuration keys. -After the quick start a few guides delve deeper into some advanced topics. +After the quick start, a few guides delve deeper into some advanced topics. - [Automation](./guides/automation.md) explains the ins and outs of hooks and how they can be used for testing typst preprocessors or formatters. - [Using Test Sets](./guides/test-sets.md) delves into the test set language and how it can be used to isolate tests and speed up your TDD workflow. - [Setting Up CI](./guides/ci.md) shows how to set up `typst-test` to continously test all changes to your package. @@ -26,5 +26,5 @@ The later sections of the book are a technical reference to `typst-test` and its - [Tests](./reference/tests.md) outlines which types of tests `typst-test` supports, how they can be customized and which features are offered within the test scripts. - [Test Set Language](./reference/test-set-dsl.md) defines the test set language and its built in test sets. - [Configuration Schema](./reference/config.md) lists all existing config options, their expected types and default values. -- [Command Line Tool](./reference/cli.md) goes over the `typst-test`s various sub commands, arguments and options. +- [Command Line Tool](./reference/cli.md) goes over `typst-test`s various sub commands, arguments and options. diff --git a/docs/book/src/quickstart/install.md b/docs/book/src/quickstart/install.md index 3be1d17..d1b2b4a 100644 --- a/docs/book/src/quickstart/install.md +++ b/docs/book/src/quickstart/install.md @@ -1,9 +1,9 @@ # Installation To install `typst-test` on your PC, you must, for the time being, compile it from source. -Once `typst-test` reaches 0.1.0 this restruction will be lifted and each release will provide precompiled binaries for major operating systems. +Once `typst-test` reaches 0.1.0, this restriction will be lifted and each release will provide precompiled binaries for major operating systems (Windows, Linux and macOS). ## Installation From Source -To install `typst-test` from source you must have a Rust toolchain (Rust **v1.80.0+**) and cargo installed. +To install `typst-test` from source, you must have a Rust toolchain (Rust **v1.79.0+**) and cargo installed. Run the following command to install the latest nightly version ```bash @@ -16,13 +16,13 @@ cargo install --locked --git https://github.com/tingerrr/typst-test --tag ci-sem ``` ## Required Libraries -### Openssl -Openssl (**v???**) is required to allow `typst-test` to download packages from the [Typst Universe](https://typst.app/universe) package registry. +### OpenSSL +OpenSSL (**v1.0.1** to **v3.x.x**) or LibreSSL (**v2.5** to **v3.7.x**) are required to allow `typst-test` to download packages from the [Typst Universe](https://typst.app/universe) package registry. -When installing from source the `vendor-openssl` feature can be used on operating systems other than Windows and macOS to statically vendor and statically link to openssl, avoiding the need for it on the operating system. +When installing from source the `vendor-openssl` feature can be used on operating systems other than Windows and macOS to statically vendor and statically link to OpenSSL, avoiding the need for it on the operating system.
-This is not yet possible, but will be once [#32](https://github.com/tingerrr/typst-test/issues/32) is resolved, in the meantime openssl may be linked ot dynamically as a transitive dependency. +This is not yet possible, but will be once [#32](https://github.com/tingerrr/typst-test/issues/32) is resolved, in the meantime OpenSSL may be linked to dynamically as a transitive dependency.
diff --git a/docs/book/src/quickstart/usage.md b/docs/book/src/quickstart/usage.md index 21ae058..2cffa03 100644 --- a/docs/book/src/quickstart/usage.md +++ b/docs/book/src/quickstart/usage.md @@ -1,9 +1,9 @@ # Usage `typst-test` is a command line program, it can be run by simply invoking it in your favorite shell and passing the appropriate arguments. -If you opened a shell in a folder `project` and `typst-test` is at `project/bin/typst-test`, then you can run it using `./project/bin/typst-test`. -Placing it directly in your project is most likely not what you will do or want to do. -You should install it to a directory which is contained in your `PATH`, allowing you to simply run it using `typst-test`. +If you open a shell in the folder `project` and `typst-test` is at `project/bin/typst-test`, then you can run it using `./project/bin/typst-test`. +Placing it directly in your project is most likely not what you will do, or want to do. +You should install it to a directory which is contained in your `PATH`, allowing you to simply run it using `typst-test` directly. How to add such folders to your `PATH` depends on your operating system, but if you installed `typst-test` using one of the recommended methods in [Installation](.install.md), then such a folder should be chosen for you.
@@ -28,7 +28,7 @@ You can also define an alias of the same name to make typing it easier. tt init ``` -This will create the default example to give you a graps at where tests are located and how they are structured. +This will create the default example to give you a grasp at where tests are located, and how they are structured. `typs-test` will look for the project root by checking for directories containing a `typst.toml` manifest file. This is because `typst-test` is primarily aimed at developers of packages, if you want to use a different project root, or don't have a `typst-manifest` you can provide the root directory using the `--root` like so. @@ -36,11 +36,11 @@ This is because `typst-test` is primarily aimed at developers of packages, if yo tt init --root ./path/to/root/ ``` -Keep in mind that you must pass this option for every command that operates on a project. +Keep in mind that you must pass this option to every command that operates on a project. Alternatively the `TYPST_ROOT` environment variable can be set to the project root. -Further examples assume the existence of a manifest or the `TYPST_ROOT` variable being set -If you're just following along and don't have a package to test this with, you can use a an empty project with the following manifest: +Further examples assume the existence of a manifest, or the `TYPST_ROOT` variable being set +If you're just following along and don't have a package to test this with, you can use an empty project with the following manifest: ```toml [package] @@ -70,7 +70,7 @@ Summary ``` Let's edit the test to actually do something, the default example test can be found in `/tests/example/` and simply contains `Hello World`. -Let's write something else in there and see what happens +Write something else in there and see what happens ```diff -Hello World +Typst is Great! @@ -88,12 +88,12 @@ Summary 0 / 1 passed. ``` -`typst-test` has compared the reference output from the original `Hello World` docuemnt to the new document and determined that they don't match. +`typst-test` has compared the reference output from the original `Hello World` document to the new document and determined that they don't match. It also told you where you can inspect the difference, the `/test/example` contains a `diff` directory. -You can take a look to see what changed by also looking at the `out` and `ref` directories, these contain the output of the current test and the expected reference output respectively. +You can take a look to see what changed, you can also take a look at the `out` and `ref` directories, these contain the output of the current test and the expected reference output respectively. Well, but this wasn't a mistake, this was a deliberate change. -So let's update the references to reflect that. +So, let's update the references to reflect that and try again. For this we use the appropriately named `update` command: ```bash @@ -111,11 +111,3 @@ Summary ``` and the test should once again pass. - -
- -Beware that `update` will by default update all test which aren't ignored, this may change before 0.1.0 is released. -Ensure you always have your references checked into your VCS to avoid losing them. -Check out the sections about test sets to learn more about how tests are selected. - -