Raise some headings up by a level

As well as making the spec more readable, 2nd-level (----) headings
show up in the sidebar generated by 'mkdocs', and are internal page
anchors that we can link to. This allows more linking to between
different sections of the spec.

Change-Id: I35d4cf5e86b01fde3195944875640669d18dbca8

1 files changed, 20 insertions, 17 deletions

diff --git a/spec.mdwn b/spec.mdwn
index 30366dc..248f826 100644
--- a/spec.mdwn
+++ b/spec.mdwn
@@ -59,12 +59,11 @@ integer.
 
 The integer specifies the version of the definitions format that this repo
 uses. A tool should refuse to process a version that it doesn't support, to
-avoid unpredictable errors. See the "Versioning" heading above for more detail
-on versions.
+avoid unpredictable errors. See also the [Versioning](#versioning) section.
 
 The top directory of the repo can also contain a file named `DEFAULTS`. This
 holds repo-wide 'build-system' and 'split-rules' information. See the
-'Defaults' section below.
+[defaults](#defaults) section below.
 
 To find all the Baserock definition files in the repo, tooling can recursively
 scan the contents of the repo for files matching the glob pattern "\*.morph".
@@ -90,13 +89,14 @@ For all definitions, use the following fields:
 * `kind`: the kind of thing being built; **required**
 * `description`: a comment to describe what the definition is for; optional
 
-### Build definitions: Chunks, Systems and Strata
+Build definitions: Chunks, Systems and Strata
+---------------------------------------------
 
 Within this document, consider 'building' to be the act of running a series of
 commands in a given 'environment', where the commands and how to build the
 environment are completely specified by the definitions and the build tool.
 
-#### Chunks
+### Chunks
 
 A 'chunk' definition describes an individual component, which can be built from
 a Git repository by executing the given sequence of commands.
@@ -130,7 +130,7 @@ chunk:
     - cd o && make install_root="$DESTDIR" install
 
 A chunk can optionally make use of a repo-wide build system defined in
-'DEFAULTS', by using the `build-system` field.  In this case, the
+['DEFAULTS'](#defaults), by using the `build-system` field.  In this case, the
 command sequences defined in DEFAULTS are used.
 
 Any predefined command sequence can be overridden by specifying a new value.
@@ -154,7 +154,7 @@ For example:
     build-commands:
     - make all
 
-If a chunk doesn't need to override anything from 'DEFAULTS', you can avoid
+If a chunk doesn't need to override anything from ['DEFAULTS'](#defaults), you can avoid
 having a chunk .morph file altogether, and just set 'build-system' when
 referring to the chunk from the stratum.
 
@@ -166,7 +166,7 @@ phases are often not safe when run in parallel; `morph` picks a default value
 based on the number of CPUs on the host system.
 
 Built chunks are split up into multiple artifacts. The default splitting rules
-for a chunk are defined in 'DEFAULTS'. You can use the `chunks` field of a
+for a chunk are defined in ['DEFAULTS'](#defaults). You can use the `chunks` field of a
 chunk to override these. The `chunks` field is a key/value map of lists of
 regular expressions; the key is the name of a binary chunk, the regexps match
 the pathnames that will be included in that chunk; the patterns match the
@@ -175,7 +175,7 @@ pathnames that get installed by `install-commands` (the whole path below
 single chunk gets created, named according to the definition, and containing
 all files.
 
-#### Strata
+### Strata
 
 A 'stratum' is a group of related chunks. A stratum can contain only chunks.
 Certain information about how to build a chunk is defined in the containing
@@ -215,7 +215,7 @@ The fields mean the following:
   of a workaround for the lack of distinction between build and runtime
   dependencies.
 
-#### Systems
+### Systems
 
 In the Baserock model, a 'system' is the top level entity that you actually
 build and execute. Systems contain one or more strata.
@@ -231,7 +231,7 @@ The fields mean the following:
     - `name`: name of the artifact when the stratum is build
     - `morph`: path to a stratum .morph file relative to the top of the containing repo
 
-#### Example stratum:
+### Example stratum:
 
     name: foundation
     kind: stratum
@@ -257,7 +257,7 @@ The fields mean the following:
       - fhs-dirs
       - linux-api-headers
 
-#### Example system:
+### Example system:
 
     name: base
     kind: system
@@ -265,7 +265,8 @@ The fields mean the following:
     - morph: foundation
     - morph: linux-stratum
 
-### Deployment definitions: Clusters
+Deployment definitions: Clusters
+--------------------------------
 
 For 'deployment', Baserock defines an API for running 'extensions'. The
 'cluster' and 'system' definitions together describe what extensions should be
@@ -345,7 +346,8 @@ Example:
                 cluster-foo-armv7-2:
                     HOSTNAME: cluster-foo-armv7-2
 
-### Repo URLs
+Repo URLs
+---------
 
 Git repository locations can (and should) be abbreviated using the 'repo-alias' feature of Baserock definitions. This is a kind of [Compact URI](http://www.w3.org/TR/2009/CR-curie-20090116/). It currently only affects the 'repo' fields in a stratum .morph file.
 
@@ -372,7 +374,8 @@ There are two repo aliases that *must* be defined:
 
 Baserock tools should allow changing these values. The main benefit of this compact URI scheme is that definitions are not tied to a specific Git server, or protocol. You can build against a mirror of the original Git server, or change the protocol that is used, just by altering the repo-alias configuration.
 
-### Defaults
+Defaults
+--------
 
 A definitions repository can contain a file named DEFAULTS. This file sets up
 repo-wide configuration.
@@ -381,7 +384,7 @@ The structure of the DEFAULTS file is described using [JSON-Schema] in
 the [spec.git] repo:
 <http://git.baserock.org/cgit/baserock/baserock/spec.git/tree/schemas/defaults.json-schema>
 
-#### Build systems
+### Build systems
 
 You can define common command sequences using the 'build-systems' key. These
 can then be referenced in chunk (and stratum) definitions, to avoid repeating
@@ -398,7 +401,7 @@ system:
         install-commands:
         - python setup.py install --prefix "$PREFIX" --root "$DESTDIR"
 
-#### Splitting rules
+### Splitting rules
 
 One 'source' in Baserock can produce multiple binary 'artifacts'. This allows
 you to separate programs, libraries, documentation, debugging information, and