clean up markdown in tutorial and concepts

... and ensure that pandoc processes them correctly. In particular,
add an empty line around itemize environments.

10 files changed, 23 insertions, 3 deletions

diff --git a/doc/concepts/alternative-mirrors.md b/doc/concepts/alternative-mirrors.md
index 4e934665..dc4579c7 100644
--- a/doc/concepts/alternative-mirrors.md
+++ b/doc/concepts/alternative-mirrors.md
@@ -49,6 +49,7 @@ has access to the respective project. In order to avoid polluting
 a multi-repository specification with the URLs of such restricted
 mirrors, the `.just-local` file was extended to support additional
 keys in its JSON object.
+
 - For the optional key `"local mirrors"`, if given, a JSON object
   is specified that maps primary URLs to a list of local (non-public)
   mirrors. Those mirrors are always tried first (in the given order)
diff --git a/doc/concepts/computed-roots.md b/doc/concepts/computed-roots.md
index 171c7648..7007eab4 100644
--- a/doc/concepts/computed-roots.md
+++ b/doc/concepts/computed-roots.md
@@ -136,9 +136,11 @@ of a `"computed"` repository is just forwarded as computed root.
 
 Due to the presence of `just serve`, roots can be absent. This
 affects computed roots in two ways,
+
  - roots, in particular the target roots, of the repository referred
    to can be absent, and
  - a computed root can be absent itself.
+
 The latter has to be supported, as dependencies that should be
 delegated to `just serve` might contain computed roots themselves.
 In this case, we consider it acceptable to have one round of talking
@@ -172,12 +174,14 @@ true}]` is the same computed root considered absent.
 
 If a computed root is absent then, in native mode, regardless of whether
 the base repository is absent or not,
+
  - serve will be asked for the result, and
  - from the result the tree identifier of the root will be computed
    in memory and the root set to that value, as absent.
 
 If a concrete computed root refers to a base repository with absent
 target root,
+
  - the client will ask serve about the flexible variables of the
    specified target, and
  - with this information will compute locally the cache key and
diff --git a/doc/concepts/expressions.md b/doc/concepts/expressions.md
index 74058f84..5d12d8d2 100644
--- a/doc/concepts/expressions.md
+++ b/doc/concepts/expressions.md
@@ -84,6 +84,7 @@ and `null` otherwise.
 The value is the value of the key `"$1"` uninterpreted but replacing
 all outermost maps having a key `"type"` with the value either
 `","` or `",@"` in the following way.
+
  - If the value for the key `"type"` is `","`, the value for the
    key `"$1"` (or `null` if there is no key `"$1"`) is evaluated
    and the map is replaced by the value of that evaluation.
@@ -94,6 +95,7 @@ all outermost maps having a key `"type"` with the value either
    that list (i.e., the list obtained by evaluating the value for
    `"$1"`) are inserted (not the list itself) into the surrounding
    list replacing that map.
+
 For example, ``{"type": "`", "$1": [1, 2, {"type": ",@", "$1": [3, 4]}]}``
 evaluates to `[1, 2, 3, 4]` while
 ``{"type": "`", "$1": [1, 2, {"type": ",", "$1": [3, 4]}]}``
diff --git a/doc/concepts/garbage.md b/doc/concepts/garbage.md
index ab0dba09..f6ba7149 100644
--- a/doc/concepts/garbage.md
+++ b/doc/concepts/garbage.md
@@ -113,6 +113,7 @@ The entries in the large-objects CAS are keyed by hash of the
 large object and the value of an entry is the concatenation of the
 hashes of the chunks the large object is composed of. An entry in
 a large-object CAS promises
+
 - that the chunks the large object is composed of are in the main
   CAS, more precisely `casf` in the same generation,
 - the concatenation of the specified chunks indeed gives the
@@ -129,6 +130,7 @@ can be replaced by a large-object entry themselves.
 
 Whenever an object is not found in the main CAS, the large-objects
 CAS is inspected. If found there, then, in this order,
+
 - if the entry is not already in the youngest generation, the chunks
   are promoted to the youngest generation,
 - the object itself is spliced on disk in a temproary file,
@@ -172,6 +174,7 @@ During garbage collection, while already holding the exclusive
 garbage-collection lock, the following compactification steps are
 performed on the youngest generation before doing the generation
 rotation.
+
 - For every entry in the large-objects CAS the corresponding entries
   in the main CAS are removed (for an entry in `cas-large-f` the
   entries in both, `casf` and `casx` are removed, as files and
@@ -181,6 +184,7 @@ rotation.
   added to the main CAS, the list of chunks the object is composed
   of is added to the large-objects CAS, and finally the object is
   removed from the main CAS.
+
 It should be noted that these steps do not modify the objects
 that can be obtained from that CAS generation. In particular, all
 invariants are kept.
diff --git a/doc/concepts/profiling.md b/doc/concepts/profiling.md
index 1f9c7925..10836c3a 100644
--- a/doc/concepts/profiling.md
+++ b/doc/concepts/profiling.md
@@ -97,6 +97,7 @@ information about that attempt. This also happens if no build was
 attempted despite being requested, e.g., due to failure in analysis.
 The file contains a single JSON object, with the following key (and
 more keys possibly added in the future).
+
  - The key `"exit code"` contains the exit value of the `just`
    process; this allows easy filtering on the build and test results.
  - The key `"target"` contains the target in full-qualified form.
@@ -150,6 +151,7 @@ The configuration file for `just-mr` has an entry `"invocation
 log"`. This entry, if given, is a JSON object; rc-file merging is
 done on the individual entries of the `"invocation log"` object.
 It supports the following keys.
+
  - `"directory"` A single location object specifying the directory
    under which the invocation logging will happen. If not given, no
    invocation logging will happen and the other keys are ignored.
@@ -165,6 +167,7 @@ It supports the following keys.
 
 If invocation logging is requested, `just-mr` will create for each invocation
 a directory `<prefix>/<project-id>/<YYYY-mm-DD-HH:MM>-<uuid>` where
+
  - `<prefix>` is the directory specified by the `"directory"`
    location object.
  - `<project-id>` is the value specified by the `"project id"`
@@ -178,6 +181,7 @@ a directory `<prefix>/<project-id>/<YYYY-mm-DD-HH:MM>-<uuid>` where
    unique id for that invocation (following RFC9562). The reason we
    prefix the UUID with a time stamp is allow a simple time-based
    collection and clean up of the log data.
+
 Inside this directory the requested files with the specified file
 names will be created, in the case of `"--profile"`, `"--dump-graph"`,
 and `"--dump-plain-graph"` by passing the appropriate options to
@@ -185,6 +189,7 @@ the invocation of `just`.
 
 The meta-data will be written just by `just-mr` itself, just before
 doing the `exec` call. The file contains a JSON object with keys
+
  - `"time"` The time stamp in seconds since the epoch as floating-point
    number, possibly rounded down to the nearest integer.
  - `"cmdline"` The command line, as vector of strings, that `just-mr`
diff --git a/doc/concepts/service-target-cache.md b/doc/concepts/service-target-cache.md
index 8821cfad..f7f14e1e 100644
--- a/doc/concepts/service-target-cache.md
+++ b/doc/concepts/service-target-cache.md
@@ -210,7 +210,7 @@ tree in the CAS of the associated remote-execution endpoint.
 For archives we typically require the `git` blob identifier to be
 given, thus the tree identifier corresponding to a distdir (i.e.,
 a list of distfiles) can always be computed without fetching the
-actual archives. 
+actual archives.
 
 In order to allow `just-mr` to set up a repository description that
 can build against an _absent_ distdir repository root, `just serve`
diff --git a/doc/concepts/symlinks.md b/doc/concepts/symlinks.md
index 9506cab0..d04076ee 100644
--- a/doc/concepts/symlinks.md
+++ b/doc/concepts/symlinks.md
@@ -65,7 +65,7 @@ symbolic links, e.g., shared libraries pointing to the specific version
 detours through `/etc/alternatives`.
 
 Bootstrapping "shopping list" option
----------------------------------------------------------
+------------------------------------
 
 In order to more easily support building the tool itself against
 pre-installed dependencies with the respective directories containing
@@ -77,7 +77,7 @@ clean directory serving as root; during this copying, symlinks are
 followed.
 
 Our treatment of symbolic links
-------------------------------------
+-------------------------------
 
 ### "Ignore-special" roots
 
diff --git a/doc/concepts/tree-overlay.md b/doc/concepts/tree-overlay.md
index 068ea5fb..1111e922 100644
--- a/doc/concepts/tree-overlay.md
+++ b/doc/concepts/tree-overlay.md
@@ -96,6 +96,7 @@ to the stages.
 
 The reason we require stages to be passed to these constructors
 rather than artifacts that happen to be trees is twofold.
+
 - We want to find malformed expressions already analysis time;
   therefore, we need to ensure not only that the arguments to the
   `"tree_overlays"` entry in the action graph are artifacts, but, in
diff --git a/doc/tutorial/computed.md b/doc/tutorial/computed.md
index 0ca6065d..ee9e94d8 100644
--- a/doc/tutorial/computed.md
+++ b/doc/tutorial/computed.md
@@ -177,6 +177,7 @@ INFO: Backing up artifacts of 1 export targets
 ```
 
 From that, we can, step by step, define the actual build description.
+
  - The tasks to generate the target files is a computed root of the
    `"src target tasks"` using the top-level target `["", ""]`. We
    call it `"src target tasks"`.
diff --git a/doc/tutorial/lint.md b/doc/tutorial/lint.md
index 7b488405..f7d99787 100644
--- a/doc/tutorial/lint.md
+++ b/doc/tutorial/lint.md
@@ -149,8 +149,10 @@ know the correct defines to be used.
 Of course, those abstract nodes are just an implementation detail
 and there is a rule to define linting for the collected sources.
 It takes two programs (targets consisting of a single artifact),
+
 - the `linter` for running the lint task on a single file, and
 - the `summarizer` for summarizing the lint results;
+
 additionally, arbitrary `config` data can be given to have config
 files available, but also to use a linter built from source.