doc: Minor format and consistency improvements

11 files changed, 52 insertions, 46 deletions

diff --git a/doc/concepts/anonymous-targets.md b/doc/concepts/anonymous-targets.md
index 6692d0ae..0c27f234 100644
--- a/doc/concepts/anonymous-targets.md
+++ b/doc/concepts/anonymous-targets.md
@@ -113,7 +113,7 @@ in the same way. Intensionally equal artifacts create equal action
 graphs; here we can confidently say "equal" and not only isomorphic:
 due to our preliminary clean up, even the node names are equal. Making
 sure that equal actions produce bit-by-bit equal outputs is the realm of
-[reproducibe builds](https://reproducible-builds.org/). The tool can
+[reproducible builds](https://reproducible-builds.org/). The tool can
 support this by appropriate sandboxing, etc, but the rules still have to
 define actions that don't pick up non-input information like the
 current time, user id, readdir order, etc. Files that are bit-by-bit
@@ -293,7 +293,7 @@ map may now also have meaningful entries for the keys of the
 `"anonymous"` map. Each value in the map has to be itself a map,
 with entries `"target"`, `"provider"`, and `"rule_map"`.
 
-For `"target"`, a single string has to be specifed, and the
+For `"target"`, a single string has to be specified, and the
 value has to be a member of the `"target_fields"` list. For
 provider, a single string has to be specified as well. The idea
 is that the nodes are collected from that provider of the
diff --git a/doc/concepts/doc-strings.md b/doc/concepts/doc-strings.md
index a1a156ac..05de6c94 100644
--- a/doc/concepts/doc-strings.md
+++ b/doc/concepts/doc-strings.md
@@ -34,16 +34,16 @@ Rules
 
 Each rule is described as a JSON object with a fixed set of keys. So
 having fixed keys for documentation does not cause conflicts. More
-precisely, the keys `doc`, `field doc`, `config_doc`, `artifacts_doc`,
-`runfiles_doc`, and `provides_doc` are reserved for documentation. Here,
-`doc` has to be a list of strings describing the rule in general.
-`field doc` has to be a map from (some of) the field names to an array
+precisely, the keys `"doc"`, `"field_doc"`, `"config_doc"`, `"artifacts_doc"`,
+`"runfiles_doc"`, and `"provides_doc"` are reserved for documentation. Here,
+`"doc"` has to be a list of strings describing the rule in general.
+`"field_doc"` has to be a map from (some of) the field names to an array
 of strings, containing additional information on that particular field.
-`config_doc` has to be a map from (some of) the config variables to an
-array of strings describing the respective variable. `artifacts_doc` is
+`"config_doc"` has to be a map from (some of) the config variables to an
+array of strings describing the respective variable. `"artifacts_doc"` is
 an array of strings describing the artifacts produced by the rule.
-`runfiles_doc` is an array of strings describing the runfiles produced
-by this rule. Finally, `provides_doc` is a map describing (some of) the
+`"runfiles_doc"` is an array of strings describing the runfiles produced
+by this rule. Finally, `"provides_doc"` is a map describing (some of) the
 providers by that rule; as opposed to fields or config variables there
 is no authoritative list of providers given elsewhere in the rule, so it
 is up to the rule author to give an accurate documentation on the
@@ -115,9 +115,9 @@ Expressions
 -----------
 
 Expressions are also described by a JSON object with a fixed set of
-keys. Here we use the keys `doc` and `vars_doc` for documentation, where
-`doc` is an array of strings describing the expression as a whole and
-`vars_doc` is a map from (some of) the `vars` to an array of strings
+keys. Here we use the keys `"doc"` and `"vars_doc"` for documentation, where
+`"doc"` is an array of strings describing the expression as a whole and
+`"vars_doc"` is a map from (some of) the `"vars"` to an array of strings
 describing this variable.
 
 Export targets
@@ -126,9 +126,9 @@ Export targets
 As export targets play the role of interfaces between repositories, it
 is important that they be documented as well. Again, export targets are
 described as a JSON object with fixed set of keys amd we use the keys
-`doc` and `config_doc` for documentation. Here `doc` is an array of
-strings describing the targeted in general and `config_doc` is a map
-from (some of) the variables of the `flexible_config` to an array of
+`"doc"` and `"config_doc"` for documentation. Here `"doc"` is an array of
+strings describing the targeted in general and `"config_doc"` is a map
+from (some of) the variables of the `"flexible_config"` to an array of
 strings describing this parameter.
 
 Presentation of the documentation
@@ -145,7 +145,7 @@ human-readable form
 
  - the documentation for the rule
  - all the fields available for that rule together with
-    - their type (`string_field`, `target_field`, etc), and
+    - their type (`"string_fields"`, `"target_fields"`, etc), and
     - their documentation,
  - all the configuration variables of the rule with their documentation
    (if given), and
diff --git a/doc/concepts/expressions.md b/doc/concepts/expressions.md
index 9e8a8f36..b6aa0945 100644
--- a/doc/concepts/expressions.md
+++ b/doc/concepts/expressions.md
@@ -44,7 +44,7 @@ mechanism; the precise evaluation is as follows.
    themselves.
  - For lists, each entry is evaluated in the order they occur in the
    list; the result of the evaluation is the list of the results.
- - For JSON objects (wich can be understood as maps, or dicts), the key
+ - For JSON objects (which can be understood as maps, or dicts), the key
    `"type"` has to be present and has to be a literal string. That
    string determines the syntactical construct (sloppily also referred
    to as "function") the object represents, and the remaining
diff --git a/doc/concepts/multi-repo.md b/doc/concepts/multi-repo.md
index c465360e..e4dd1bd6 100644
--- a/doc/concepts/multi-repo.md
+++ b/doc/concepts/multi-repo.md
@@ -21,7 +21,7 @@ optional and the default is that the repository worked on has no
 external dependencies. Typically (but not necessarily), this
 repository-configuration file is located outside the referenced
 repositories and versioned separately or generated from such a file via
-`bin/just-mr.py`. It serves as meta-data for a group of repositories
+`just-mr`. It serves as meta-data for a group of repositories
 belonging together.
 
 This file contains one JSON object. For the key `"repositories"` the
diff --git a/doc/future-designs/computed-roots.md b/doc/future-designs/computed-roots.md
index 8bbff401..4d1960e7 100644
--- a/doc/future-designs/computed-roots.md
+++ b/doc/future-designs/computed-roots.md
@@ -4,7 +4,7 @@ Computed roots
 Status quo
 ----------
 
-As of version `1.0.0`, the `just` build tool requires a the repository
+As of version `1.0.0`, the `just` build tool requires the repository
 configuration, including all roots, to be specified ahead of time. This
 has a couple of consequences.
 
diff --git a/doc/specification/remote-protocol.md b/doc/specification/remote-protocol.md
index 1afd7e32..af10d2b8 100644
--- a/doc/specification/remote-protocol.md
+++ b/doc/specification/remote-protocol.md
@@ -140,6 +140,7 @@ message as it is done in the original protocol. The remote side promises
 that each blob and subtree contained in the root tree is available in
 the remote CAS. Such blobs and trees must be accessible, using the
 streaming interface, without specifying the size (since sizes are not
-stored in a git tree). Due to the Protobuf 3 specification, which is
-used in this remote execution API, not specifying the size means the
-default value 0 is used.
+stored in a git tree). Due to the [Protobuf 3
+specification](https://protobuf.dev/reference/protobuf/proto3-spec/), which is
+used in this remote execution API, not specifying the size means the default
+value `0` is used.
diff --git a/doc/tutorial/getting-started.md b/doc/tutorial/getting-started.md
index 36a57d26..e2dbbd4d 100644
--- a/doc/tutorial/getting-started.md
+++ b/doc/tutorial/getting-started.md
@@ -1,7 +1,7 @@
 Getting Started
 ===============
 
-In order to use *justbuild*, first make sure that `just`, `just-mr`, and
+In order to use *Justbuild*, first make sure that `just`, `just-mr`, and
 `just-import-git` are available in your `PATH`.
 
 Creating a new project
@@ -101,7 +101,7 @@ this can be used for both, interactively reading a text file, as well as
 for piping the artifact to another program.
 
 ``` sh
-$ just build greeter -Pout.txt
+$ just build greeter -P out.txt
 INFO: Requested target is [["@","","","greeter"],{}]
 INFO: Analysed target [["@","","","greeter"],{}]
 INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
diff --git a/doc/tutorial/hello-world.md b/doc/tutorial/hello-world.md
index 9af68f07..54ed7d72 100644
--- a/doc/tutorial/hello-world.md
+++ b/doc/tutorial/hello-world.md
@@ -115,7 +115,7 @@ command line:
 ``` sh
 $ just-mr build helloworld
 INFO: Requested target is [["@","tutorial","","helloworld"],{}]
-INFO: Analysed target [["@","tutorial","",helloworld"],{}]
+INFO: Analysed target [["@","tutorial","","helloworld"],{}]
 INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
 INFO: Discovered 2 actions, 1 trees, 0 blobs
 INFO: Building [["@","helloworld","","helloworld"],{}].
diff --git a/doc/tutorial/just-execute.org b/doc/tutorial/just-execute.org
index 5605dcd8..f43cb202 100644
--- a/doc/tutorial/just-execute.org
+++ b/doc/tutorial/just-execute.org
@@ -16,17 +16,18 @@ certainly not limited to)
 
 For the sake of completeness, these are the files used to compile the
 examples
-#+BEGIN_SRC bash
-$ tree latex-hello-world/
+#+BEGIN_SRC
 latex-hello-world/
-├── hello.tex
-├── repos.json
-└── TARGETS
++--hello.tex
++--repos.json
++--TARGETS
 #+END_SRC
 
 They read as follows
-#+BEGIN_SRC bash
-$ cat repos.json
+
+File ~repos.json~:
+#+SRCNAME: repos.json
+#+BEGIN_SRC js
 { "main": "tutorial"
 , "repositories":
   { "latex-rules":
@@ -45,8 +46,9 @@ $ cat repos.json
 }
 #+END_SRC
 
-#+BEGIN_SRC bash
-$ cat TARGETS
+File ~TARGETS~:
+#+SRCNAME: TARGETS
+#+BEGIN_SRC js
 { "tutorial":
   { "type": ["@", "latex-rules", "latex", "latexmk"]
   , "main": ["hello"]
@@ -55,8 +57,9 @@ $ cat TARGETS
 }
 #+END_SRC
 
-#+BEGIN_SRC bash
-$ cat hello.tex
+File ~hello.tex~:
+#+SRCNAME: hello.tex
+#+BEGIN_SRC tex
 \documentclass[a4paper]{article}
 
 \author{JustBuild developers}
@@ -76,7 +79,7 @@ In this first example, we simply call ~just execute~ and the
 environment of the caller is made available. We therefore recommend to
 have a dedicated non-priviledged ~build~ user to run the execution
 service. In the following, we will use ~%~ to indicate the prompt of
-the ~build~ user, ~$~ for a _normal_user_.
+the ~build~ user, ~$~ for a /normal/ user.
 
 To enable such a single-node execution service, it is sufficient to
 type on one shell (as ~build~ user)
@@ -85,7 +88,7 @@ type on one shell (as ~build~ user)
 #+END_SRC
 Where ~<N>~ is a port number which is supposed to be available.
 
-To use it, as a _normal_ user, on a different shell type
+To use it, as a /normal/ user, on a different shell type
 #+BEGIN_SRC bash
 $ just [...] -r localhost:<N> 
 #+END_SRC
@@ -148,7 +151,7 @@ $ cat /tmp/foo.json
 {"interface":"127.0.0.1","pid":7680,"port":44115}
 #+END_SRC
 
-Please note that the info file will _not be automatically deleted_
+Please note that the info file will /not be automatically deleted/
 when the user terminates the service. The user is responsible for
 eventually removing it from the file system.
 
@@ -171,7 +174,7 @@ $ just [...] --tls-ca-cert <path_to_CA_cert> --tls-client-cert <path_to_client_c
 
 ***** How to generate self-signed certificates
 
-This section does not pretend to be an exaustive guide to the
+This section does not pretend to be an exhaustive guide to the
 generation and management of certificates, which is well beyond the
 aim of this tutorial. We just want to provide a minimal reference for
 let users start using mTLS and having the benefits of mutual
@@ -188,7 +191,7 @@ As a first step, we need a Certification Authority certificate (~ca.crt~)
 
 If the clients will connect using the loopback device, i.e., the users
 are logged in the same machine where ~just execute~ will run, the
-_server certificates_ can be generate with the following instructions
+/server certificates/ can be generate with the following instructions
 #+BEGIN_SRC bash
 % openssl req -new -nodes -newkey rsa:4096 -keyout server.key -out server.csr -subj "/CN=localhost"
 % openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 0 -out server.crt
@@ -409,7 +412,7 @@ $ docker run --network host --name execute-latex --mount type=bind,source="${HOM
 *** Compile statically
 
 Since ~just~ and ~just-mr~ must also be available in the host
-environment, the best way to have ~just~ inside the enviroment is to
+environment, the best way to have ~just~ inside the environment is to
 compile a static binary, and copy it into the chroot environment.
 
 Please refer to the [[../../INSTALL.md][installation guide]] for details.
@@ -451,10 +454,10 @@ RUN apt install -y --no-install-recommends \
                     clang \
                     python3 \
                     git \
-		    patch \
+                    patch \
                     unzip \
                     wget \
-		    ca-certificates
+                    ca-certificates
 RUN git clone https://github.com/just-buildsystem/justbuild.git
 # use a well defined commit to foster reproducibility
 RUN git checkout 246e1b7f28f319e4be5bd24466494e6b5868ca6f
diff --git a/doc/tutorial/tests.md b/doc/tutorial/tests.md
index 138769b1..f4d8897c 100644
--- a/doc/tutorial/tests.md
+++ b/doc/tutorial/tests.md
@@ -93,7 +93,7 @@ be provided. By specifying the appropriate target in this module the
 default test runner can be overwritten by a different test runner fom
 the rule's workspace root. Moreover, all test targets share runner
 infrastructure from `shell/test`, e.g., summarizing multiple runs per
-test (to detect flakyness) if the configuration variable `RUNS_PER_TEST`
+test (to detect flakiness) if the configuration variable `RUNS_PER_TEST`
 is set.
 
 However, in our case, we want to use the default runner and therefore it
diff --git a/doc/tutorial/third-party-software.md b/doc/tutorial/third-party-software.md
index daaf5b2d..644b7b21 100644
--- a/doc/tutorial/third-party-software.md
+++ b/doc/tutorial/third-party-software.md
@@ -467,6 +467,8 @@ staging mechanism the logical repository it belongs to is rooted in the
 }
 ```
 
+---
+
 [^1]: Explicit `TREE` references are always a list of length 3, to
       distinguish them from target references of length 2 (module and
       target name). Furthermore, the second list element is always `null`