Topiary Book: Editorial sweep (#898)

* Easy/cheap changes for consistency

* Apparently links in PR descriptions don't work as expected :(

* Document C/C++ toolchain dependency

* Clean up relics

* Topiary Book style guide

* Edit wrt style guide

* Small tweaks to style guide

Author: Xophmeister

.github/pull_request_template.md

@@ -33,5 +33,5 @@ This is particularly important if this PR is preparing a release.
 
 Checklist before merging, wherever relevant:
 
-- [ ] [`CHANGELOG.md`](/CHANGELOG.md) updated
-- [ ] Documentation ([The Topiary Book](/docs/book), [`README.md`](/README.md), etc.) up-to-date
+- [ ] `CHANGELOG.md` updated
+- [ ] Documentation (The Topiary Book, `README.md`, etc.) up-to-date

docs/book/src/cli/configuration.md

@@ -5,12 +5,13 @@ relates to [Nickel](https://nickel-lang.org/), a configuration language
 created by Tweag. There are up to four sources where Topiary checks for
 such a file.
 
-## Configuration Sources
+## Configuration sources
 
-At build time the [`languages.ncl`](./languages.ncl) in the root of the
-Topiary repository is embedded into Topiary. This file is parsed at
-runtime. The purpose of this `languages.ncl` file is to provide sane
-defaults for users of Topiary (both the library and the CLI binary).
+At build time the [`languages.ncl`](https://github.com/tweag/topiary/blob/main/topiary-config/languages.ncl)
+in the root of the Topiary repository is embedded into Topiary. This
+file is parsed at runtime. The purpose of this `languages.ncl` file is
+to provide sane defaults for users of Topiary (both the library and the
+CLI binary).
 
 The next two are read by the Topiary binary at runtime and allow the
 user to configure Topiary to their needs. The first is intended to be
@@ -20,8 +21,8 @@ the OS:
 | OS      | Typical Configuration Path                                       |
 | :------ | :--------------------------------------------------------------- |
 | Unix    | `/home/alice/.config/topiary/languages.ncl`                      |
-| Windows | `C:\Users\Alice\AppData\Roaming\Topiary\config\languages.ncl`    |
 | macOS   | `/Users/Alice/Library/Application Support/Topiary/languages.ncl` |
+| Windows | `C:\Users\Alice\AppData\Roaming\Topiary\config\languages.ncl`    |
 
 This file is not automatically created by Topiary.
 
@@ -45,13 +46,10 @@ following order (highest to lowest):
 
 ### Configuration merging
 
-<!-- TODO: See issue #861 -->
-
 By default, Topiary only considers the configuration file with the
-[highest priority](../configuration.md). However, if
-the `-M` or `--merge-configuration` option is provided to the CLI, then
-all available configurations are merged together, as per the [Nickel
-specification](https://nickel-lang.org/user-manual/merging).
+highest priority. However, if the `-M`/`--merge-configuration` option is
+provided to the CLI, then all available configurations are merged
+together, as per the [Nickel specification](https://nickel-lang.org/user-manual/merging).
 
 In which case, if one of the sources listed above attempts to define a
 language configuration already present in the built-in configuration, or
@@ -89,6 +87,14 @@ To override only the indentation, use the following Nickel file:
 }
 ```
 
+<div class="warning">
+
+The merging semantics for Topiary's grammar configuration (see
+[below](#specifying-the-grammar)) is not yet fully defined; see issue
+[#861](https://github.com/tweag/topiary/issues/861).
+
+</div>
+
 ## Configuration options
 
 The configuration file contains a record of languages. That is, it

docs/book/src/cli/dialogue.md

@@ -26,13 +26,8 @@ In that case, you don't have to worry about making
 `TOPIARY_LANGUAGE_DIR` has been set at build time and is set at runtime
 as well, the runtime value takes precedence.
 
-<!----------------------------------------------------------------------
-TODO: Move CONTRIBUTING.md into the Topiary Book
-
-For a subsequent PR...
------------------------------------------------------------------------>
-See [`CONTRIBUTING.md`](https://github.com/tweag/topiary/blob/main/CONTRIBUTING.md)
-for details on setting up a development environment.
+See [the contributor's guide](../guides/contributing.html) for details
+on setting up a development environment.
 
 ## Logging
 

docs/book/src/cli/usage/format.md

@@ -55,8 +55,8 @@ the `--language` and, optionally, `--query` arguments, omitting any
 input files.
 
 Valid language identifiers, as specified with `--language`, are defined
-as part of your Topiary configuration. Please see the
-[configuration](../configuration.md) section for more details.
+as part of your Topiary configuration. See the [configuration](../configuration.md)
+chapter for more details.
 
 <div class="warning">
 

docs/book/src/cli/usage/index.md

@@ -29,8 +29,7 @@ Options:
 ```
 <!-- usage:end -->
 
-Please see the respective section for usage documentation on each
-subcommand:
+See the respective chapter for usage documentation on each subcommand:
 
 - [`format`](format.md)
 - [`visualise`](visualise.md)

docs/book/src/cli/usage/visualise.md

@@ -65,5 +65,5 @@ specify the `--language` and, optionally, `--query` arguments, omitting
 the input file. The visualisation output is written to standard out.
 
 Valid language identifiers, as specified with `--language`, are defined
-as part of your Topiary configuration. Please see the
-[configuration](../configuration.md) section for more details.
+as part of your Topiary configuration. See the [configuration](../configuration.md)
+chapter for more details.

docs/book/src/getting-started/configuration.md

@@ -1,8 +1,22 @@
 # Installation
 
 Topiary can be installed in a few different ways. For more information
-on these, please see the respective section:
+on these, see the respective chapter:
 
 - [Package managers](package-managers.md)
 - [Building from source](building-from-source.md)
 - [Using Nix](using-nix.md)
+
+## Dependencies
+
+The Topiary CLI will build Tree-sitter grammars on demand, optionally
+fetching them from a Git remote first. For this to work, your
+environment will need a C/C++ toolchain (i.e., compiler and linker)
+available. If this is available, it should "just work"; otherwise, refer
+to the [underlying mechanism's documentation](https://docs.rs/cc/latest/cc/#external-configuration-via-environment-variables)
+for configuration advice.
+
+Alternatively, the [Tree-sitter CLI](https://github.com/tree-sitter/tree-sitter/blob/master/cli/README.md)
+can be used to build Tree-sitter grammars outside of Topiary, which can
+then be loaded through [configuration](../../cli/configuration.md#specifying-the-grammar)
+from your local filesystem.

docs/book/src/getting-started/installation/index.md

@@ -9,7 +9,7 @@ The Topiary CLI, amongst other things, is available on
 [crates.io](https://crates.io/crates/topiary-cli):
 
 ```sh
-cargo install -p topiary-cli
+cargo install topiary-cli
 ```
 
 ## OPAM (OCaml Package Manager)
@@ -45,7 +45,7 @@ home.packages = with pkgs; [
 ];
 ```
 
-### Nix Install
+### Nix install
 
 ```sh
 # Using flakes:

docs/book/src/getting-started/installation/package-managers.md

@@ -98,7 +98,7 @@ define a formatting style for the language in question.
 <div class="warning">
 Topiary makes no assumption about a language's token separators. When
 it parses any input source into a collection of nodes, it will only
-apply formatting that has been explicitly defined with capture nodes, in
+apply formatting that has been explicitly defined with capture names, in
 a query file. This can result in any unspecified nodes losing their
 token separators (e.g., spacing) after formatting. That is, nodes can be
 "squashed" together, which can change (or even break) the code's

docs/book/src/getting-started/on-tree-sitter.md

@@ -200,6 +200,6 @@ format C code.
 
 You can now iterate on the formatting queries and the respective input
 and expected sample files to build your formatter, using the I/O and
-coverage tests to guide the process. Please also see the [following
+coverage tests to guide the process. Also see the [following
 chapter](suggested-workflow.md) on query development for more
 information.

docs/book/src/guides/adding-a-new-language.md

@@ -30,46 +30,46 @@ languages using a [simple DSL][tree-sitter:query]. This allows for the
 fast development of formatters, providing a [Tree-sitter
 grammar][tree-sitter:parsers] is defined for that language.
 
-## Design Principles
+## Design principles
 
 Topiary has been created with the following goals in mind:
 
-* Use [Tree-sitter] for parsing, to avoid writing yet another grammar
+- Use [Tree-sitter] for parsing, to avoid writing yet another grammar
   for a formatter.
 
-* Expect idempotency. That is, formatting of already-formatted code
+- Expect idempotency. That is, formatting of already-formatted code
   doesn't change anything.
 
-* For bundled formatting styles to meet the following constraints:
+- For bundled formatting styles to meet the following constraints:
 
-  * Be compatible with attested formatting styles used for that language
+  - Be compatible with attested formatting styles used for that language
     in the wild.
 
-  * Be faithful to the author's intent: if code has been written such
+  - Be faithful to the author's intent: if code has been written such
     that it spans multiple lines, that decision is preserved.
 
-  * Minimise changes between commits such that diffs focus mainly on the
+  - Minimise changes between commits such that diffs focus mainly on the
     code that's changed, rather than superficial artefacts. That is, a
     change on one line won't influence others, while the formatting
     won't force you to make later, cosmetic changes when you modify your
     code.
 
-  * Be well-tested and robust, so that the formatter can be trusted in
+  - Be well-tested and robust, so that the formatter can be trusted in
     large projects.
 
-* For end users -- i.e., not formatting style authors -- the formatter
+- For end users -- i.e., not formatting style authors -- the formatter
   should:
 
-  * Prescribe a formatting style that, while customisable, is uniform
+  - Prescribe a formatting style that, while customisable, is uniform
     and "good enough" for their codebase.
 
-  * Run efficiently.
+  - Run efficiently.
 
-  * Afford simple integration with other developer tools, such as
+  - Afford simple integration with other developer tools, such as
     editors and language servers.
 
 [gofmt]: https://pkg.go.dev/cmd/gofmt
 [gofmt:slides]: https://go.dev/talks/2015/gofmt-en.slide#1
 [tree-sitter]: https://tree-sitter.github.io/tree-sitter
-[tree-sitter:query]: https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries
-[tree-sitter:parsers]: https://tree-sitter.github.io/tree-sitter/#available-parsers
+[tree-sitter:query]: https://tree-sitter.github.io/tree-sitter/using-parsers/queries/index.html
+[tree-sitter:parsers]: https://github.com/tree-sitter/tree-sitter/wiki/List-of-parsers

docs/book/src/index.md

@@ -7,7 +7,7 @@ development and has diverged from newer releases of Topiary. The web
 playground is kept online, for demonstrative purposes, but newer
 features have **not been implemented**.
 
-Please see GitHub to [assess the divergence](https://github.com/tweag/topiary/compare/playground...main).
+See GitHub to [assess the divergence](https://github.com/tweag/topiary/compare/playground...main).
 
 </div>
 

docs/book/src/installation/index.md

@@ -9,7 +9,7 @@ strings (defined in the [language configuration](../../cli/configuration.md#inde
 ## `@append_indent_start` / `@prepend_indent_start`
 
 The matched nodes will trigger indentation before (or, respectively,
-after) them. This will only apply to lines following, until an
+after) them. This will only apply to the lines following, until an
 indentation end is signalled. If indentation is started and ended on the
 same line, nothing will happen. This is useful, because we get the
 correct behaviour whether a node is formatted as single-line or

docs/book/src/playground/web.md

@@ -15,8 +15,7 @@ recognised by Topiary to drive formatting.
 
 > **Note**\
 > This example is derived from the [Topiary announcement blog
-> post][tweag:topiary-announcement]. Please see the post for additional
-> detail.
+> post][tweag:topiary-announcement]; see the post for additional detail.
 
 ```scheme
 (

docs/book/src/reference/capture-names/indentation.md

@@ -122,9 +122,9 @@ These predicates allow the query to trigger only if the associated custom scope
 containing the matched nodes are is single-line (resp. multi-line).
 
 > **Note**\
-> There are non-scoped equivalents to these predicates; please see
-> [vertical spacing](vertical-spacing.md#testing-context-with-predicates)
-> for details.
+> There are non-scoped equivalents to these predicates; see [vertical
+> spacing](vertical-spacing.md#testing-context-with-predicates) for
+> details.
 
 ##### Example
 

docs/book/src/reference/capture-names/index.md

@@ -234,7 +234,7 @@ These predicates allow the query to trigger only if the matched nodes
 are in a single-line (or, respectively, multi-line) context.
 
 > **Note**\
-> There are scoped equivalents to these predicates; please see
+> There are scoped equivalents to these predicates; see
 > [scopes](scopes.md#testing-context-with-predicates) for details.
 
 ##### Example

docs/book/src/reference/capture-names/scopes.md

@@ -1,12 +1,7 @@
 # Language support
 
-<!-- Update this section as necessary on new developments/releases -->
-
 <!----------------------------------------------------------------------
-TODO Lay out expectations for contributed languages and what constitutes
-a language being "experimental" (or otherwise). See issue #876
-
-(I've made it a bit clearer here, but it could be much better...)
+Update these sections as necessary on new developments/releases
 ----------------------------------------------------------------------->
 
 Topiary ships with formatting support for a number of languages. The
@@ -30,23 +25,23 @@ stated design goals. They are exposed, in Topiary, through the
 `--language` command line flag, or language detection (based on file
 extension).
 
-* [Bash]
-* [JSON]
-* [Nickel]
-* [OCaml] (both implementations and interfaces)
-* [OCamllex]
-* [TOML]
-* [Tree Sitter Queries][tree-sitter-query]
+- [Bash]
+- [JSON]
+- [Nickel]
+- [OCaml] (both implementations and interfaces)
+- [OCamllex]
+- [TOML]
+- [Tree Sitter Queries][tree-sitter-query]
 
 ## Contributed
 
 These languages' formatting styles have been generously provided by
-external contributors. They are built in, by default, so are exposed in
-the same way as supported languages.
+external contributors. They are built in, by default -- unless marked as
+experimental -- so are exposed in the same way as supported languages.
 
-* [CSS], by [Eric Lavigne](https://github.com/lavigneer)
-* [OpenSCAD], by [Mikhail Katychev](https://github.com/mkatychev)
-* [SDML], by [Simon Johnston](https://github.com/johnstonskj)
+- [CSS], by [Eric Lavigne](https://github.com/lavigneer)
+- [OpenSCAD], by [Mikhail Katychev](https://github.com/mkatychev)
+- [SDML], by [Simon Johnston](https://github.com/johnstonskj)
 
 ## Experimental
 
@@ -57,7 +52,7 @@ feature flag (either `experimental`, for all of them, or by their
 individual name). Once included, they can be accessed in Topiary in the
 usual way.
 
-* [Rust]
+- [Rust]
 
 <!-- Links -->
 [bash]: https://www.gnu.org/software/bash

docs/book/src/reference/capture-names/vertical-spacing.md

@@ -5,8 +5,8 @@ documentation can be found on [docs.rs][topiary-docs]. Of main interest
 is the `formatter` function that performs the actual formatting. The
 example in the documentation of that function is kept up to date.
 
-For a more complete example, please see the [client-app example in the
-Topiary repository][client-app].
+For a more complete example, see the [client-app example in the Topiary
+repository][client-app].
 
 [client-app]: https://github.com/tweag/topiary/tree/main/examples/client-app
 [topiary-crate]: https://crates.io/crates/topiary-core