Skip to content

Commit

Permalink
fix(book): Correct small discrepancies
Browse files Browse the repository at this point in the history
- Fix various typos
- Improve overall phrasing
- Remove unecessary warning about `update` command
- Name the operating systems which will receive pre-built binaries
- Use the correct rust version
- Add required OpenSSL and LibreSSL versions
  • Loading branch information
tingerrr committed Jul 23, 2024
1 parent 55b5b1f commit 3b8b2ae
Show file tree
Hide file tree
Showing 3 changed files with 19 additions and 27 deletions.
4 changes: 2 additions & 2 deletions docs/book/src/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.

12 changes: 6 additions & 6 deletions docs/book/src/quickstart/install.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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.

<div class="warning">

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.

<div>
30 changes: 11 additions & 19 deletions docs/book/src/quickstart/usage.md
Original file line number Diff line number Diff line change
@@ -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.

<div class="warning">
Expand All @@ -28,19 +28,19 @@ 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.

```bash
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]
Expand Down Expand Up @@ -70,7 +70,7 @@ Summary
```

Let's edit the test to actually do something, the default example test can be found in `<project>/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!
Expand All @@ -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 `<project>/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
Expand All @@ -111,11 +111,3 @@ Summary
```

and the test should once again pass.

<div class="warning">

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.

</div>

0 comments on commit 3b8b2ae

Please sign in to comment.