docs: miscellaneous edits throughout for style and wording

README.md

@@ -25,7 +25,7 @@ binaries / packages from a simple recipe format. The recipe format is heavily
 inspired by `conda-build` and `boa`, and the output of a regular `rattler-build`
 run is a package that can be installed using `mamba`, `rattler` or `conda`.
 
-`rattler-build` does not have any dependencies on `conda-build` or `Python` and
+`rattler-build` does not have any dependencies on `conda-build` or Python and
 works as a standalone binary.
 
 ![](https://user-images.githubusercontent.com/885054/244683824-fd1b3896-84c7-498c-b406-40ab2a9e450c.svg)
@@ -70,7 +70,7 @@ self-contained.
   libraries and executables to make it relative
 * `patchelf` is required on Linux to rewrite the `rpath` and `runpath` of shared
   libraries and executables
-* `git` to checkout Git repositories (not implemented yet, but will require git
+* `git` to checkout Git repositories (not implemented yet, but will require `git`
   in the future)
 * `msvc` on Windows because we cannot ship the MSVC compiler on conda-forge
   (needs to be installed on the host machine)
@@ -85,9 +85,7 @@ here](https://prefix-dev.github.io/rattler-build).
 
 ### GitHub Action
 
-There is a GitHub Action for rattler-build.
-It can be used to install `rattler-build` in CI/CD workflows and run a build command.
-Please check out the [GitHub Action documentation](https://github.com/prefix-dev/rattler-build-action) for more information.
+There is a GitHub Action for `rattler-build`. It can be used to install `rattler-build` in CI/CD workflows and run a build command. Please check out the [GitHub Action documentation](https://github.com/prefix-dev/rattler-build-action) for more information.
 
 ### Usage
 
@@ -278,7 +276,7 @@ about:
 For this recipe, two additional script files (`build.sh` and `build.bat`) are
 needed.
 
-**build.sh**
+**`build.sh`**
 
 ```bash
 #!/bin/bash
@@ -306,7 +304,7 @@ make install
 rm -rf "${PREFIX}/share"
 ```
 
-**build.bat**
+**`build.bat`**
 
 ```cmd
 mkdir build

docs/automatic_linting.md

@@ -3,12 +3,12 @@
 The new recipe format comes with a strict JSON scheme. You can find the scheme
 [in this repository](https://github.com/prefix-dev/recipe-format).
 
-It's implemented with `pydantic` and renders to a JSON schema file. The [YAML
+It is implemented with `pydantic` and renders to a JSON schema file. The [YAML
 language server extension in
 VSCode](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)
 can recognize the scheme and give helpful hints during editing.
 
-With the YAML language server installed the automatic linting can be enabled by
+With the YAML language server installed, the automatic linting can be enabled by
 adding the following line to the top of the recipe file:
 
 ```yaml

docs/available_jinja.md

@@ -6,14 +6,14 @@
 
 ### The compiler function
 
-The compiler function can be used to put together a compiler that works for the current platform and the compilation "target_platform".
+The compiler function can be used to put together a compiler that works for the current platform and the compilation "`target_platform`".
 The syntax looks like: `${{ compiler('c') }}` where `'c'` signifies the programming language that is used.
 
 This function evaluates to `<compiler>_<target_platform> <compiler_version>`.
-For example, when compiling _on_ linux and to linux-64, this function evaluates to `gcc_linux-64`.
+For example, when compiling _on_ `linux` and _to_ `linux-64`, this function evaluates to `gcc_linux-64`.
 
 The values can be influenced by the `variant_configuration`.
-The `<lang>_compiler` and `<lang>_compiler_version` variables are the keys with influence, for example:
+The `<lang>_compiler` and `<lang>_compiler_version` variables are the keys with influence. See below for an example:
 
 ```yaml
 c_compiler:
@@ -22,21 +22,21 @@ c_compiler_version:
 - 9.0
 ```
 
-Would select the `clang` compiler in version `9.0`. Note that the final output will still contain the `target_platform`, so that the full compiler will read `clang_linux-64 9.0` when compiling with `--target-platform linux-64`.
+The variables shown above would select the `clang` compiler in version `9.0`. Note that the final output will still contain the `target_platform`, so that the full compiler will read `clang_linux-64 9.0` when compiling with `--target-platform linux-64`.
 
-## The `pin_subpackage` function
+### The `pin_subpackage` function
 
 - `${{ pin_subpackage("mypkg", min_pin="x.x", max_pin="x.x.x") }}` creates a pin to another output in the recipe.
 
-## The `pin_compatible` function
+### The `pin_compatible` function
 
 - `pin_compatible` pins a package in the run requirements based on the resolved package of the `host` or `build` section.
 
-## The `cdt` function
+### The `cdt` function
 
-- `${{ cdt("mypkg") }}` creates a cross dependency to another output in the recipe.
+- `${{ cdt("mypkg") }}` creates a cross-dependency to another output in the recipe.
 
-This function helps add Core Dependency Tree packages as dependencies by converting packages as required according to hard-coded logic.
+This function helps add Core Dependency Tree packages as dependencies by converting packages as required according to hard-coded logic. See below for an example of how this function can be used:
 
 ```yaml
 # on x86_64 system
@@ -45,25 +45,26 @@ cdt('package-name') # outputs: package-name-cos6-x86_64
 cdt('package-name') # outputs: package-name-cos6-aarch64
 ```
 
-## The `hash` variable
+### The `hash` variable
 
-- `${{ hash }}` this is the variant hash and is useful in the build string computation
+- `${{ hash }}` is the variant hash and is useful in the build string computation.
 
-## The `version_to_buildstring` function
-- `${{ python | version_to_buildstring }}` converts a version from the variant to a build string (removes `.` and takes only the first two elements of the version).
+### The `version_to_buildstring` function
+- `${{ python | version_to_buildstring }}` converts a version from the variant to a build string (it removes the `.` character and takes only the first two elements of the version).
 
-## The `env` object
+### The `env` object
 
 You can use the `env` object to retrieve environment variables and forward them to your build script. There are two ways to do this:
 
 - `${{ env.get("MY_ENV_VAR") }}` will return the value of the environment variable `MY_ENV_VAR` or throw an error if it is not set.
 - `${{ env.get_default("MY_ENV_VAR", "default_value") }}` will return the value of the environment variable `MY_ENV_VAR` or `"default_value"` if it is not set.
 
-You can also check for existence of an environment variable:
+You can also check for the existence of an environment variable:
 
 - `${{ env.exists("MY_ENV_VAR") }}` will return `true` if the environment variable `MY_ENV_VAR` is set and `false` otherwise.
 
 ## Default Jinja filters
 
-- default jinja filters are available: `lower`, `upper`, indexing into characters: `https://myurl.com/{{ name[0] }}/{{ name | lower }}_${{ version }}.tar.gz`.
-  A list of all the builtin filters can be found under: [Link](https://docs.rs/minijinja/latest/minijinja/filters/index.html#functions)
+The following Jinja filters are available: `lower`, `upper`, indexing into characters (e.g. `https://myurl.com/{{ name[0] }}/{{ name | lower }}_${{ version }}.tar.gz`).
+
+Navigate to the [Minijinja documentation](https://docs.rs/minijinja/latest/minijinja/filters/index.html#built-in-filters) for a list of all available built-in filters.

docs/build_options.md

@@ -1,4 +1,4 @@
-# Advanced Build Options
+# Advanced build options
 
 There are some specialized build options to control various features:
 
@@ -17,7 +17,7 @@ already in the environment as part of some other host dependency. This is normal
 "clobbering" and should be used with caution (since packages should not have any overlapping files).
 
 The `always_copy_files` option can be used to copy files instead of linking them.
-This is useful for files that might be modified inside the environment (for example configuration files).
+This is useful for files that might be modified inside the environment (e.g. configuration files).
 Normally, files are linked from a central cache into the environment to save space – that means
 that files modified in one environment will be modified in all environments. This is not always
 desirable, and in that case you can use the `always_copy_files` option.
@@ -140,15 +140,15 @@ build:
 
 ## Dynamic linking configuration
 
-After the package is build, rattler-build performs some "post-processing" on the
+After the package is built, rattler-build performs some "post-processing" on the
 binaries and libraries.
 
 This entails making the shared libraries relocatable and checking that all
 linked libraries are present in the run requirements. The following settings
 control this behavior.
 
 With the `rpath` option you can forcibly set the `rpath` of the shared
-libraries. The path is relative to the install prefix. Any rpath setting is
+libraries. The path is relative to the install prefix. Any `rpath` setting is
 ignored on Windows.
 
 The `rpath_allowlist` option can be used to allow the `rpath` to point to
@@ -160,7 +160,7 @@ If you want to stop `rattler-build` from relocating the binaries, you can set
 `binary_relocation` to `false`. If you want to only relocate some binaries, you
 can select the relevant ones with a glob pattern.
 
-To read more about rpaths and how rattler-build creates relocatable binary packages,
+To read more about `rpath`s and how rattler-build creates relocatable binary packages,
 see the [internals](internals.md) docs.
 
 If you link against some libraries (possibly even outside of the prefix, in a
@@ -169,11 +169,11 @@ against these and suppress any warnings. This list is pre-populated with a list
 of known system libraries on the different operating systems.
 
 As part of the post-processing, `rattler-build` checks for overlinking and
-overdepending. Overlinking is when a binary links against a library that is not
+overdepending. "Overlinking" is when a binary links against a library that is not
 specified in the run requirements. This is usually a mistake because the library
 would not be present in the environment when the package is installed.
 
-Conversely, overdepending is when a library is part of the run requirements, but
+Conversely, "overdepending" is when a library is part of the run requirements, but
 is not actually used by any of the binaries/libraries in the package.
 
 ```yaml title="recipe.yaml"

docs/build_script.md

@@ -47,7 +47,7 @@ noted, no variables are inherited from the shell environment in which you invoke
 : Represents the number of CPUs on the system.
 
 `SHLIB_EXT`
-: Denotes the shared library extension specific to the operating system (e.g., .so for Linux, .dylib for macOS, and .dll for Windows).
+: Denotes the shared library extension specific to the operating system (e.g. `.so` for Linux, `.dylib` for macOS, and `.dll` for Windows).
 
 `HTTP_PROXY`
 : Inherited from the user's shell environment, specifying the HTTP proxy settings.
@@ -80,10 +80,10 @@ noted, no variables are inherited from the shell environment in which you invoke
 : The version of the package currently under construction.
 
 `PKG_BUILD_STRING`
-: The complete build string of the package being built, including the hash (e.g., py311h21422ab_0).
+: The complete build string of the package being built, including the hash (e.g. py311h21422ab_0).
 
 `PKG_HASH`
-: Represents the hash of the package being built, excluding the leading 'h' (e.g., 21422ab). This is applicable from Conda-build 3.0 onwards.
+: Represents the hash of the package being built, excluding the leading 'h' (e.g. 21422ab). This is applicable from conda-build 3.0 onwards.
 
 `PYTHON`
 : The path to the Python executable in the host prefix. Python is installed in the host prefix only when it is listed as a host requirement.

docs/cli_usage.md

@@ -1,11 +1,10 @@
-# CLI Usage
+# CLI usage
 
 ## Shell Completions
 
-We support shell completions through clap-complete.
-You can generate them for your shell using the `completion` command.
+We support shell completions through [`clap_complete`](https://crates.io/crates/clap_complete). You can generate them for your shell using the `completion` command.
 
-You can add the completions to your shell by adding the following to your shell's configuration file.
+You can add the completions to your shell by adding the following to your shell's configuration file:
 
 ```sh
 # For bash (add this to ~/.bashrc)
@@ -16,8 +15,7 @@ eval "$(rattler-build completion --shell=zsh)"
 rattler-build completion --shell=fish | source
 ```
 
-Ensure that whereever you install the is pointed to by your FPATH (for zsh or equivalent in other shells).
-Now you can use TAB or your configured completion key. :3
+Ensure that wherever you install `rattler-build` is pointed to by your `FPATH` (for `zsh` or equivalent in other shells), after which point you can use TAB or any configured completion key of choice. 😄
 
 ```sh
 $ rattler-build <TAB>
@@ -42,17 +40,16 @@ rattler-build build --package-format conda:max --compression-threads 10 -r recip
 
 ## Logs
 
-Rattler-build knows 3 different log-styles: `fancy`, `plain` and `json`.
-You can configure them with the `--log-style=<style>` flag.
+`rattler-build` knows three different log styles: `fancy`, `plain`, and `json`.
+You can configure them with the `--log-style=<style>` flag:
 
 ```sh
 # default
 rattler-build build --log-style fancy -r recipe/recipe.yaml
 ```
 
-### Github integration
+### GitHub integration
 
-Rattler-build also has a github integration. With this integration, warnings are automatically
-emitted in the github actions log and a summary is generated that is posted to the Github Actions summary page.
+`rattler-build` also has a GitHub integration. With this integration, warnings are automatically emitted in the GitHub Actions log and a summary is generated and posted to the GitHub Actions summary page.
 
-To make use of the integration we recommend to use our Github action: [`rattler-build-action`](https://github.com/prefix-dev/rattler-build-action). To manually enable it, you can set the environment variable `RATTLER_BUILD_ENABLE_GITHUB_INTEGRATION=true`.
+To make use of this integration, we recommend using our custom GitHub action: [`rattler-build-action`](https://github.com/prefix-dev/rattler-build-action). To manually enable it, you can set the environment variable `RATTLER_BUILD_ENABLE_GITHUB_INTEGRATION=true`.

docs/compilers.md

@@ -27,25 +27,25 @@ c_compiler_version:
 ```
 
 When the template function is evaluated, it will look something like:
-`gcc_linux-64 9.3.0`. You can define your own compilers. For example, for `rust`
+`gcc_linux-64 9.3.0`. You can define your own compilers. For example, for Rust
 you can use `${{ compiler('rust') }}` and `rust_compiler_{version}` in your
 variant config.
 
-## Cross compilation
+## Cross-compilation
 
-Cross compilation is supported by rattler-build and the compiler template
+Cross-compilation is supported by `rattler-build` and the compiler template
 function is part of what makes it possible. When you want to cross-compile from
-`linux-64` to `linux-aarch64` (intel to ARM), you can pass `--target-platform
+`linux-64` to `linux-aarch64` (i.e. intel to ARM), you can pass `--target-platform
 linux-aarch64` to the `rattler-build` command. This will cause the compiler
 template function to select a compiler that is configured for `linux-aarch64`.
 The above example would resolve to `gcc_linux-aarch64 9.3.0`. Provided that the
 package is available for `linux-64` (your build platform), the compilation
 should succeed.
 
-The distinction between `build` and `host` section begins to make sense when
-thinking about cross compilation. The `build` enviromemnt is resolved to
+The distinction between the `build` and `host` sections begins to make sense when
+thinking about cross-compilation. The `build` enviromemnt is resolved to
 packages that need to _run_ at compilation time. For example, `cmake`, `gcc`,
-`autotools` are all tools that need to be executed. Therefore, the `build`
+and `autotools` are all tools that need to be executed. Therefore, the `build`
 environment resolves to packages for the `linux-64` architecture (in our
 example). On the other hand, the `host` packages resolve to `linux-aarch64` -
 those are packages that we want to link against.

docs/experimental_features.md

@@ -1,30 +1,27 @@
-# Experimental Features
+# Experimental features
 
 !!! warning
-    These are experimental features of rattler-build and may change or go away completely.
+    These are experimental features of `rattler-build` and may change or go away completely.
 
 
-Currently only `build` & `rebuild` command supports the following experimental features.
+Currently only the `build` and `rebuild` commands support the following experimental features.
 
-To enable them use the `--experimental` flag with the command.
+To enable them, use the `--experimental` flag with the command.
 Or, use the environment variable, `RATTLER_BUILD_EXPERIMENTAL=1`.
 
-Jinja functions
----------------
+## Jinja functions
 
 ### `load_from_file(<file_path>)`
 
-The jinja function `load_from_file` allows loading from files, specifically, it allows loading from `toml`, `json`
-and `yaml` to an object to allow to fetch things directly from it.
-While it loads all other files as strings.
+The Jinja function `load_from_file` allows loading from files; specifically, it allows loading from `toml`, `json`,
+and `yaml` file types to an object to allow it to fetch things directly from the file.
+It loads all other files as strings.
 
 #### Usage
 
-This is useful when you have the project description in a well defined project file, such as, `Cargo.toml`, `package.json`, `pyproject.toml`, `package.yaml`, or `stack.yaml`. And would like to keep the recipe as simple as possible, while not worrying about keeping changes in sync, perhaps using it with CI/CD.
+`load_from_file` is useful when there is a project description in a well-defined project file such as `Cargo.toml`, `package.json`, `pyproject.toml`, `package.yaml`, or `stack.yaml`. It enables the recipe to be preserved in as simple a state as possible, especially when there is no need to keep the changes in sync; some example use cases for this are with CI/CD infrastructure or when there is a well-defined output format.
 
-Or, from some other source that provides a well-defined output format.
-
-Example against `Cargo.toml` inside `rattler-build` github repository:
+Below is an example loading a `Cargo.toml` inside of the `rattler-build` GitHub repository:
 
 ``` yaml title="recipe.yaml"
 context:
@@ -60,11 +57,11 @@ about:
   license: ${{ load_from_file("Cargo.toml").package.license }}
 ```
 
-### Git functions
+### `git` functions
 
-Git functions are useful for getting the latest tag and commit hash.
+`git` functions are useful for getting the latest tag and commit hash.
 These can be used in the `context` section of the recipe, to fetch version information
-from the git repository.
+from a repository.
 
 ???+ example "Examples"
     ```python
@@ -80,8 +77,7 @@ from the git repository.
 
 #### Usage
 
-These can be useful for automating minor things inside the recipe itself.
-Such as if the current version is the latest version, if the current hash is the latest hash, etc.
+These can be useful for automating minor things inside of the recipe itself, such as if the current version is the latest version or if the current hash is the latest hash, etc.
 
 ``` yaml title="recipe.yaml"
 context:
@@ -97,5 +93,4 @@ source:
   tag: ${{ latest_tag }}
 ```
 
-Though it's important to understand currently we don't guarantee caching for repo fetch for git functions
-this may lead to some performance issues.
+There is currently no guarantee of caching for repo fetches when using `git` functions. This may lead to some performance issues.