docs: Copyedit readme and install documentation

INSTALL.md

@@ -18,7 +18,8 @@ obtain these.
 
 ### Obtaining the source
 
-Clone the [repository](https://codeberg.org/topola/topola):
+From your command line, clone the
+[repository](https://codeberg.org/topola/topola):
 
     git clone https://codeberg.org/topola/topola.git
 
@@ -30,7 +31,7 @@ Change your working directory to your clone of Topola's repository:
 
 ### Command-line application
 
-Topola has a command-line application written with the help of the
+Topola has a command-line application (CLI) written with the help of the
 [`clap`](https://docs.rs/clap/latest/clap/) library.
 
 #### Installation from source
@@ -44,18 +45,23 @@ application:
 
     cargo install --locked --path crates/topola-cli
 
-You can then invoke the application from your terminal as `topola`.
+You can then invoke the application from your terminal as `topola`. For example,
+
+    topola --help
+
+will display an explanation of the available command-line options and arguments.
 
 #### Debug build
 
-If you do not want to install new software on your system, or are interested in
+If you do not want to install new software on your system, or are interested
-debugging or developing Topola, you can build a debug executable of the Topola's
+in developing or debugging Topola, you need to build a debug executable of the
-command-line application inside your working directory by running
+Topola's command-line application inside your working directory by running
 
     cargo build -p topola-cli
 
-Once built, you can invoke the debug executable by replacing the `topola`
+Once built, you can invoke the debug executable by writing `cargo run -p
-command with `cargo run -p topola-cli -- `.
+topola-cli --` in the same place and with same arguments as you would write an
+installed `topola` command.
 
 #### Autorouting example
 
@@ -90,12 +96,13 @@ Topola has a graphical user interface (GUI) application written using the
 For displaying dialog boxes, Topola's GUI application uses the
 [Rusty File Dialogs](https://docs.rs/rfd/latest/rfd/) library.
 
-Due to technical constraints, these libraries have multiple runtime dependencies
+**_NOTE:_** Due to technical constraints, these libraries have multiple runtime dependencies
-that are not managed by Cargo, and as such, it is impossible to determine
+that are not managed by the Rust's package manager, Cargo, and as such, it is
-whether these dependencies have been satisfied during compilation, but only once
+impossible to determine whether these dependencies have been satisfied during
-the application has been launched. Because of that, Topola may crash on startup,
+compilation, but only once the application has been launched. Unfortunately,
-or have the file selection dialog not appear. If you encounter any problems,
+because of that, Topola may crash on startup or have file selection dialog not
-read the
+appear on some systems due to unsatisfied runtime dependencies. If you encounter
+any problems, read the
 [*Troubleshooting unmanaged runtime dependencies*](#troubleshooting-unmanaged-runtime-dependencies)
 subsection.
 
@@ -188,15 +195,16 @@ When trying to locate the source of a bug, it may be helpful to enable
 Wikipedia article needs improvement), which are nothing else but somewhat
 enchanced assertions.
 
-Unfortunately, the
+Regrettably, the [contracts](https://docs.rs/contracts/latest/contracts/)
-[contracts](https://docs.rs/contracts/latest/contracts/) library which we have
+library which we have been using enforces post-conditions using closures.
-been using enforces post-conditions via closures, which have deal-breaking
+Borrow semantics of these closures cause compile errors for some function
-limitations. To bypass these we have forked and modified it to use `try` blocks
+signatures, which is a deal-breaking limitation. Hence, to bypass this problem,
-instead. The fork is vendored in the [vendored/contracts/](vendored/contracts/)
+we maintain our own fork of this library to use `try` blocks instead. Our
-directory.
+fork's [repository](https://codeberg.org/topola/contracts-try) is available
+on Codeberg.
 
-However, `try` blocks are not present in stable Rust yet, so to use these you
+However, `try` blocks are not present in stable Rust yet, so to be able to
-need to set up your toolchain to use a nightly version of Rust.
+proceed you need to set up your toolchain to use a nightly version of Rust.
 
 #### Nightly Rust
 
@@ -211,12 +219,13 @@ You can go back to stable with
 #### Enabling contracts
 
 To enable contracts, simply add a `--no-default-features` switch. This switches
-off a default feature that prevents contracts from executing. For example, to
+off a default feature called `disable_contracts` that was expanding every
-build tests with contracts, simply run
+contract to a no-op during Rust's macro expansion. For instance, to build tests
+with contracts, simply run
 
     cargo test --no-default-features
 
-Of course, you can enable contracts for any build target. For instance, the
+Of course, you can enable contracts for any build target. For example, the
 following command will build the Topola's GUI application with debug profile and
 contracts enabled:
 

README.md

@@ -7,13 +7,7 @@ SPDX-License-Identifier: MIT
 # Topola
 
 [Topola](https://topola.dev) is a work-in-progress interactive
-topological router in Rust.
+topological router for printed circuit boards (PCBs) in Rust.
-
-The project is funded by the [NLnet Foundation](https://nlnet.nl/) from
-the [NGI0 Entrust](https://nlnet.nl/entrust/) fund.
-
-<img src="./assets/logos/nlnet/nlnet.png" alt="NLnet Foundation banner" width="200"/>
-<img src="./assets/logos/ngi0/entrust.svg" alt="NGI0 Entrust banner" width="200"/>
 
 ## Chat
 
@@ -49,7 +43,17 @@ Topola is licensed under the [MIT licence](LICENSES/MIT.txt). Files present in
 the `assets/` directory are dual-licensed as under MIT or
 [Creative Commons Attribution 4.0 International](LICENSES/CC-BY-4.0.txt)
 licence. The file `crates/planar-incr-embed/src/math.rs` is dual-licensed as under
-MIT or [Apache 2.0](LICENSES/Apache-2.0.txt) license.
+MIT or [Apache 2.0](LICENSES/Apache-2.0.txt) licence.
+
+## Acknowledgements
+
+This project is funded through the NGI0 Entrust Fund, a fund established by
+NLnet with financial support from the European Commission's Next Generation
+Internet programme, under the aegis of DG Communications Networks, Content and
+Technology under grant agreement No 101069594.
+
+<img src="./assets/logos/nlnet/nlnet.png" alt="NLnet Foundation banner" width="200"/>
+<img src="./assets/logos/ngi0/entrust.svg" alt="NGI0 Entrust banner" width="200"/>
 
 ## Gallery